---
title: Sandbox self-hosted
url: https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes
description: Esegui le sessioni di Claude Managed Agents in sandbox self-hosted, mantenendo l'esecuzione degli strumenti, i file e il traffico di rete in uscita nella tua infrastruttura.
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
---

Le "self-hosted sandboxes" (sandbox self-hosted) spostano l'esecuzione degli strumenti dell'agente dalle sandbox cloud gestite da Anthropic a un'infrastruttura che controlli tu, mentre Anthropic continua a eseguire l'agente. Per capire cosa significa e decidere se è adatto al tuo agente, consulta [Scegliere un ambiente per l'agente](https://platform.claude.com/docs/it/managed-agents/choosing-an-environment).

## Come funziona

Un ambiente `self_hosted` funge da coda di lavoro. Esegui un **environment worker** (worker dell'ambiente), un processo sulla tua infrastruttura che serve quella coda:

1. Crei una [sessione](https://platform.claude.com/docs/it/managed-agents/sessions) che ha come destinazione l'ambiente. Anthropic accoda la sessione come elemento di lavoro.
2. Il tuo worker prende in carico l'elemento di lavoro e scarica le [skill](https://platform.claude.com/docs/it/managed-agents/skills) dell'agente e i [memory store](https://platform.claude.com/docs/it/managed-agents/memory) della sessione.
3. Claude viene eseguito dal lato di Anthropic e richiede chiamate agli strumenti. Il tuo worker esegue ogni chiamata localmente e invia il risultato.

Gli input e gli output degli strumenti continuano a fluire verso il "control plane" (piano di controllo) di Anthropic, in modo che il modello possa vedere i risultati e determinare cosa fare dopo. Anthropic archivia le skill e i memory store. La tua sandbox ne conserva una copia per la sessione. Consulta [Modello di sicurezza](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-security) per il confine completo del flusso di dati.

Le sandbox self-hosted supportano ogni modello Claude disponibile in Managed Agents. Il modello è configurato sull'agente, non sull'ambiente.

La CLI `ant` e gli SDK Python, TypeScript e Go includono worker predefiniti. Anche provider di sandbox come Cloudflare, Daytona e Modal pubblicano le proprie [guide per piattaforma](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes#platform-guides).

## Guida rapida

Questa guida rapida esegue un worker sempre attivo con la CLI `ant`, gli invia una sessione e conferma che le chiamate agli strumenti dell'agente sono state eseguite sul tuo host.

### Prerequisiti

* **Un agente:** Se non ne hai uno, completa prima [Inizia con Claude Managed Agents](https://platform.claude.com/docs/it/managed-agents/quickstart) e annota l'ID dell'agente.
* **Un host Linux:** L'host necessita di `/bin/bash` esattamente in quel percorso. Il worker necessita solo di HTTPS in uscita.
* **Una chiave API Claude:** La usi dalla tua macchina per creare sessioni e leggere le statistiche della coda. Tienila lontana dall'host del worker, dove le chiamate agli strumenti dell'agente potrebbero leggerla.
* **La CLI `ant` o l'SDK sulla tua macchina:** I passaggi relativi a statistiche e sessioni in questa guida rapida vengono eseguiti lì, non sull'host del worker. Installa la CLI nello stesso modo in cui lo fa il [passaggio di installazione](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes#run-your-first-session) per il worker, oppure installa l'[SDK](https://platform.claude.com/docs/it/cli-sdks-libraries/overview).

<Note>
  Su [Claude Platform on AWS](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws), il worker si autentica con AWS IAM (SigV4) o con una [chiave API generata nella AWS Console](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws#api-key-authentication), non con una chiave dell'ambiente. Associa la policy gestita [`AnthropicSelfHostedEnvironmentAccess`](https://platform.claude.com/docs/it/api/claude-platform-on-aws-iam-actions#managed-policies) al principal IAM con cui viene eseguito il tuo worker. Le chiavi dell'ambiente generate nella Claude Console non funzionano con l'endpoint di Claude Platform on AWS.
</Note>

### Esegui la tua prima sessione

<Steps>
  <Step title="Crea un ambiente self-hosted">
    Nella Claude Console, vai alla pagina [Environments](https://platform.claude.com/environments) (`platform.claude.com/environments`), fai clic su **Create environment** e in **Hosting** seleziona **Self-hosted**.

    Oppure tramite l'API:

    <CodeGroup defaultLanguage="CLI">
      ```bash cURL
      curl -sS --fail-with-body https://api.anthropic.com/v1/environments \
        -H "x-api-key: $ANTHROPIC_API_KEY" \
        -H "anthropic-version: 2023-06-01" \
        -H "anthropic-beta: managed-agents-2026-04-01" \
        -H "content-type: application/json" \
        -d '{
          "name": "self-hosted",
          "config": {"type": "self_hosted"}
        }'
      ```

      <CodeGroupItem>
        ```bash CLI
        ant apply environment.yaml
        ```

        <File filename="environment.yaml">
          ```yaml
          # yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
          name: self-hosted
          config:
            type: self_hosted
          ```
        </File>
      </CodeGroupItem>

      ```python Python
      client = anthropic.Anthropic()

      environment = client.beta.environments.create(
          name="self-hosted", config={"type": "self_hosted"}
      )
      print(environment.id)
      ```

      ```typescript TypeScript
      const client = new Anthropic();

      const environment = await client.beta.environments.create({
        name: "self-hosted",
        config: { type: "self_hosted" }
      });
      console.log(environment.id);
      ```

      ```csharp C#
      using Anthropic.Models.Beta.Environments;

      var client = new AnthropicClient();

      var environment = await client.Beta.Environments.Create(
          new EnvironmentCreateParams
          {
              Name = "self-hosted",
              Config = new BetaSelfHostedConfigParams(),
          }
      );
      Console.WriteLine(environment.ID);
      ```

      ```go Go
      client := anthropic.NewClient()

      environment, err := client.Beta.Environments.New(context.Background(), anthropic.BetaEnvironmentNewParams{
      	Name: "self-hosted",
      	Config: anthropic.BetaEnvironmentNewParamsConfigUnion{
      		OfSelfHosted: &anthropic.BetaSelfHostedConfigParams{},
      	},
      })
      if err != nil {
      	panic(err)
      }
      fmt.Println(environment.ID)
      ```

      ```java Java
      import com.anthropic.models.beta.environments.BetaSelfHostedConfigParams;
      import com.anthropic.models.beta.environments.EnvironmentCreateParams;

      void main() {
          var client = AnthropicOkHttpClient.fromEnv();

          var environment = client.beta().environments().create(
              EnvironmentCreateParams.builder()
                  .name("self-hosted")
                  .config(BetaSelfHostedConfigParams.builder().build())
                  .build()
          );
          IO.println(environment.id());
      }
      ```

      ```php PHP
      $client = new \Anthropic\Client();

      $environment = $client->beta->environments->create(
          name: 'self-hosted',
          config: ['type' => 'self_hosted'],
      );
      echo $environment->id, PHP_EOL;
      ```

      ```ruby Ruby
      client = Anthropic::Client.new

      environment = client.beta.environments.create(
        name: "self-hosted",
        config: {type: :self_hosted}
      )
      puts environment.id
      ```
    </CodeGroup>
  </Step>

  <Step title="Genera una chiave dell'ambiente">
    Nella Console, apri l'ambiente e fai clic su **Generate environment key**. La chiave dell'ambiente autentica il worker presso la sua coda. Puoi generarne una solo nella Console, anche per un ambiente che hai creato tramite l'API.

    Esporta l'ID dell'ambiente e la chiave sull'host del worker:

    ```bash
    export ANTHROPIC_ENVIRONMENT_KEY="sk-ant-oat01-..."
    export ANTHROPIC_ENVIRONMENT_ID="env_..."
    ```
  </Step>

  <Step title="Installa la CLI ant">
    Esegui questo sull'host del worker.

    <Tabs>
      <Tab title="curl (Linux/WSL)">
        Per gli ambienti Linux, scarica direttamente il binario della release.

        ```bash
        VERSION=1.42.0
        OS=$(uname -s | tr '[:upper:]' '[:lower:]')
        case $(uname -m) in
          x86_64) ARCH=amd64 ;;
          aarch64) ARCH=arm64 ;;
        esac
        curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_${OS}_${ARCH}.tar.gz" \
          | sudo tar -xz -C /usr/local/bin ant
        ```

        Puoi trovare tutte le release nella [pagina delle release su GitHub](https://github.com/anthropics/anthropic-cli/releases).
      </Tab>

      <Tab title="Homebrew (macOS)">
        ```bash
        brew install anthropics/tap/ant
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Avvia il worker">
    Crea la directory di lavoro, quindi avvia il worker. `--workdir` usa per impostazione predefinita la directory corrente, quindi passa `/workspace` per corrispondere al valore predefinito del sistema.

    ```bash
    sudo mkdir -p /workspace && sudo chown "$USER" /workspace
    ant beta:worker poll --workdir /workspace
    ```

    Il worker legge le due variabili che hai esportato ed esegue il polling finché non lo arresti.
  </Step>

  <Step title="Verifica che il worker sia connesso">
    Sulla tua macchina, imposta `ANTHROPIC_API_KEY` sulla tua chiave API Claude (non sulla chiave dell'ambiente) e `ANTHROPIC_ENVIRONMENT_ID` (python, ruby: `environment_id`; typescript, java, csharp: `environmentId`; go: `environmentID`; php: `$environmentId`) sull'ID dell'ambiente. Conferma che `workers_polling` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) sia almeno 1:

    <CodeGroup>
      ```bash cURL
      curl -sS --fail-with-body "https://api.anthropic.com/v1/environments/$ANTHROPIC_ENVIRONMENT_ID/work/stats" \
        -H "x-api-key: $ANTHROPIC_API_KEY" \
        -H "anthropic-version: 2023-06-01" \
        -H "anthropic-beta: managed-agents-2026-04-01"
      ```

      ```bash CLI
      ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID"
      ```

      ```python Python
      client = anthropic.Anthropic()

      stats = client.beta.environments.work.stats(environment_id)
      print(f"workers_polling={stats.workers_polling}")
      ```

      ```typescript TypeScript
      const client = new Anthropic();

      const stats = await client.beta.environments.work.stats(environmentId);

      console.log(`workers_polling=${stats.workers_polling}`);
      ```

      ```csharp C#
      var client = new AnthropicClient();

      var stats = await client.Beta.Environments.Work.Stats(environmentId);

      Console.WriteLine($"workers_polling={stats.WorkersPolling}");
      ```

      ```go Go
      client := anthropic.NewClient()

      stats, err := client.Beta.Environments.Work.Stats(
      	context.Background(),
      	environmentID,
      	anthropic.BetaEnvironmentWorkStatsParams{},
      )
      if err != nil {
      	panic(err)
      }

      fmt.Printf("workers_polling=%d\n", stats.WorkersPolling)
      ```

      ```java Java
      var client = AnthropicOkHttpClient.fromEnv();

      var stats = client.beta().environments().work().stats(environmentId);

      IO.println("workers_polling=" + stats.workersPolling().orElse(null));
      ```

      ```php PHP
      $client = new Client();

      $stats = $client->beta->environments->work->stats($environmentId);

      printf("workers_polling=%d\n", $stats->workersPolling);
      ```

      ```ruby Ruby
      client = Anthropic::Client.new

      stats = client.beta.environments.work.stats(environment_id)

      puts "workers_polling=#{stats.workers_polling}"
      ```
    </CodeGroup>

    Se `workers_polling` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) rimane a 0, consulta [Risoluzione dei problemi](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-operations#troubleshooting).
  </Step>

  <Step title="Avvia una sessione">
    Imposta `AGENT_ID` (python, ruby: `agent_id`; typescript, java, csharp: `agentId`; go: `agentID`; php: `$agentId`) sull'ID del tuo agente. Crea una sessione che ha come destinazione l'ambiente, quindi inviale un'attività:

    <CodeGroup>
      ```bash cURL
      SESSION_ID=$(curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
        -H "x-api-key: $ANTHROPIC_API_KEY" \
        -H "anthropic-version: 2023-06-01" \
        -H "anthropic-beta: managed-agents-2026-04-01" \
        -H "content-type: application/json" \
        -d '{
          "agent": "'"$AGENT_ID"'",
          "environment_id": "'"$ANTHROPIC_ENVIRONMENT_ID"'"
        }' | jq -er '.id'
      )

      curl -sS --fail-with-body "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
        -H "x-api-key: $ANTHROPIC_API_KEY" \
        -H "anthropic-version: 2023-06-01" \
        -H "anthropic-beta: managed-agents-2026-04-01" \
        -H "content-type: application/json" \
        -d '{
          "events": [
            {
              "type": "user.message",
              "content": [
                {
                  "type": "text",
                  "text": "Write the output of \"uname -a\" to hello.txt in your working directory."
                }
              ]
            }
          ]
        }'
      ```

      ```bash CLI
      SESSION_ID=$(ant beta:sessions create \
        --agent "$AGENT_ID" \
        --environment-id "$ANTHROPIC_ENVIRONMENT_ID" \
        --transform id --raw-output)

      ant beta:sessions:events send --session-id "$SESSION_ID" <<'YAML'
      events:
        - type: user.message
          content:
            - type: text
              text: Write the output of "uname -a" to hello.txt in your working directory.
      YAML
      ```

      ```python Python
      session = client.beta.sessions.create(
          agent=agent_id,
          environment_id=environment_id,
      )

      client.beta.sessions.events.send(
          session.id,
          events=[
              {
                  "type": "user.message",
                  "content": [
                      {
                          "type": "text",
                          "text": 'Write the output of "uname -a" to hello.txt in your working directory.',
                      },
                  ],
              },
          ],
      )
      ```

      ```typescript TypeScript
      const session = await client.beta.sessions.create({
        agent: agentId,
        environment_id: environmentId
      });

      await client.beta.sessions.events.send(session.id, {
        events: [
          {
            type: "user.message",
            content: [
              {
                type: "text",
                text: 'Write the output of "uname -a" to hello.txt in your working directory.'
              }
            ]
          }
        ]
      });
      ```

      ```csharp C#
      var session = await client.Beta.Sessions.Create(new()
      {
          Agent = agentId,
          EnvironmentID = environmentId,
      });

      await client.Beta.Sessions.Events.Send(session.ID, new()
      {
          Events =
          [
              new BetaManagedAgentsUserMessageEventParams
              {
                  Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
                  Content =
                  [
                      new BetaManagedAgentsTextBlock
                      {
                          Type = BetaManagedAgentsTextBlockType.Text,
                          Text = "Write the output of \"uname -a\" to hello.txt in your working directory.",
                      },
                  ],
              },
          ],
      });
      ```

      ```go Go
      session, err := client.Beta.Sessions.New(context.Background(), anthropic.BetaSessionNewParams{
      	Agent:         anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agentID)},
      	EnvironmentID: environmentID,
      })
      if err != nil {
      	panic(err)
      }

      _, err = client.Beta.Sessions.Events.Send(context.Background(), session.ID, anthropic.BetaSessionEventSendParams{
      	Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
      		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
      			Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
      			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
      				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
      					Type: anthropic.BetaManagedAgentsTextBlockTypeText,
      					Text: "Write the output of \"uname -a\" to hello.txt in your working directory.",
      				},
      			}},
      		},
      	}},
      })
      if err != nil {
      	panic(err)
      }
      ```

      ```java Java
      var session = client.beta().sessions().create(SessionCreateParams.builder()
          .agent(agentId)
          .environmentId(environmentId)
          .build());

      client.beta().sessions().events().send(
          session.id(),
          EventSendParams.builder()
              .addEvent(BetaManagedAgentsUserMessageEventParams.builder()
                  .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
                  .addTextContent("Write the output of \"uname -a\" to hello.txt in your working directory.")
                  .build())
              .build());
      ```

      ```php PHP
      $session = $client->beta->sessions->create(
          agent: $agentId,
          environmentID: $environmentId,
      );

      $client->beta->sessions->events->send(
          $session->id,
          events: [
              [
                  'type' => 'user.message',
                  'content' => [['type' => 'text', 'text' => 'Write the output of "uname -a" to hello.txt in your working directory.']],
              ],
          ],
      );
      ```

      ```ruby Ruby
      session = client.beta.sessions.create(
        agent: agent_id,
        environment_id: environment_id
      )

      client.beta.sessions.events.send_(
        session.id,
        events: [
          {
            type: :"user.message",
            content: [{type: :text, text: 'Write the output of "uname -a" to hello.txt in your working directory.'}]
          }
        ]
      )
      ```
    </CodeGroup>

    La sessione attende nella coda dell'ambiente finché un worker non la prende in carico. Se nessun worker è connesso, la sessione rimane in coda anziché fallire.
  </Step>

  <Step title="Conferma che gli strumenti siano stati eseguiti sul tuo host">
    Sull'host del worker, leggi il file scritto dall'agente:

    ```bash
    cat /workspace/hello.txt
    ```

    Il file descrive il kernel del tuo host, quindi le chiamate agli strumenti dell'agente sono state eseguite lì. Per seguire il lavoro dell'agente mentre avviene, consulta [Flusso di eventi della sessione](https://platform.claude.com/docs/it/managed-agents/events-and-streaming).
  </Step>
</Steps>

## Risorse della sessione

Le sandbox self-hosted supportano solo risorse `memory_store`. Una sessione su un ambiente self-hosted che include una risorsa `file` o `github_repository` viene rifiutata con un errore 400:

```text wrap
Environment env_... is a self-hosted environment. `resources` are not supported with self-hosted environments.
```

I [deployment](https://platform.claude.com/docs/it/managed-agents/scheduled-deployments) che hanno come destinazione un ambiente self-hosted seguono la stessa regola. Per fornire a una sessione i propri file di input, consulta [Preparare i file per una sessione](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-workers#stage-files-for-a-session).

## Sandbox self-hosted e tunnel MCP

Il self-hosting controlla *dove viene eseguito il codice dell'agente*. I [tunnel MCP](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/overview) controllano *come Anthropic raggiunge i server MCP nella tua rete*. I due sono indipendenti:

* Una sessione nelle sandbox cloud di Anthropic può raggiungere server MCP privati tramite un tunnel. Ad esempio, un server MCP privato potrebbe trovarsi davanti a un database o a un'API interna dietro il tuo firewall.
* Una sessione self-hosted può usare server MCP tramite tunnel o pubblici.

Usali entrambi quando vuoi che l'esecuzione e l'accesso agli strumenti rimangano all'interno del tuo perimetro. Per evitare il tunnel, [incapsula il server MCP come strumenti personalizzati](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-custom-tools#wrap-an-mcp-server-as-custom-tools) serviti dal tuo worker.

## Guide per piattaforma

Queste pagine descrivono come creare un worker su qualsiasi piattaforma di sandboxing. Sono disponibili anche guide specifiche per piattaforma:

* [AWS Lambda MicroVMs](https://docs.aws.amazon.com/lambda/latest/dg/microvms-integrations-claude-managed-agents.html)
* [Blaxel](https://docs.blaxel.ai/Tutorials/Claude-Managed-Agents)
* [Cloudflare](https://developers.cloudflare.com/sandbox/claude-managed-agents/)
* [Daytona](https://www.daytona.io/docs/en/guides/claude/claude-managed-agents)
* [E2B](https://e2b.dev/docs/agents/claude-managed-agents)
* [Fly.io](https://docs.sprites.dev/integrations/claude-managed-agents/)
* [GKE Agent Sandbox](https://github.com/GoogleCloudPlatform/kubernetes-engine-samples/tree/main/ai-ml/anthropic-agent-sandbox)
* [Modal](https://github.com/modal-labs/claude-managed-agents-modal-sandbox)
* [Namespace](https://namespace.so/docs/integrations/claude)
* [Superserve](https://docs.superserve.ai/integrations/managed-agents/claude-managed-agents)
* [Vercel](https://vercel.com/kb/guide/run-claude-managed-agent-tools-with-vercel-sandbox)

## Passaggi successivi

<CardGroup cols={2}>
  <Card title="Distribuisci i worker" icon="play" href="https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-workers">
    Esegui il worker dell'SDK, attiva i worker dai webhook o assegna a ogni sessione la propria sandbox.
  </Card>

  <Card title="Memory store" icon="brain" href="https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-memory">
    Prepara l'host, configura la sincronizzazione e gestisci gli store di sola lettura e i conflitti.
  </Card>

  <Card title="Strumenti personalizzati e server MCP" icon="tool" href="https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-custom-tools">
    Servi i tuoi strumenti dal worker, inclusi gli strumenti di un server MCP all'interno della tua rete.
  </Card>

  <Card title="Monitoraggio e risoluzione dei problemi" icon="lightning" href="https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-operations">
    Leggi la profondità della coda, arresta sessioni e worker in modo pulito e risolvi i problemi comuni.
  </Card>

  <Card title="Riferimento del worker" icon="book" href="https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-reference">
    Flag della CLI, variabili d'ambiente, percorsi del filesystem e opzioni degli helper dell'SDK.
  </Card>

  <Card title="Modello di sicurezza" icon="lock" href="https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-security">
    Modello di responsabilità condivisa per gli ambienti sandbox self-hosted.
  </Card>
</CardGroup>