---
title: Configurazione dell'ambiente cloud
url: https://platform.claude.com/docs/it/managed-agents/environments
description: Personalizza le sandbox cloud per le tue sessioni.
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
---

Gli ambienti definiscono la configurazione della sandbox in cui viene eseguito il tuo agente. Crei un ambiente una sola volta, quindi fai riferimento al suo ID ogni volta che avvii una sessione. Più sessioni possono condividere lo stesso ambiente, ma ogni sessione ottiene la propria sandbox isolata (un nuovo container Linux).

Questa pagina tratta gli ambienti `type: cloud`. Per eseguire le sandbox sulla tua infrastruttura, consulta [Sandbox self-hosted](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes). Per scegliere tra le due opzioni, consulta [Scegliere un ambiente per l'agente](https://platform.claude.com/docs/it/managed-agents/choosing-an-environment).

## Crea un ambiente

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  curl -fsS 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" \
    --data '{
      "name": "python-dev",
      "config": {
        "type": "cloud",
        "networking": {"type": "limited", "allow_package_managers": true}
      }
    }'
  ```

  <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: python-dev
      config:
        type: cloud
        networking:
          type: limited
          allow_package_managers: true
      ```
    </File>

    [`ant apply`](https://platform.claude.com/docs/it/cli-sdks-libraries/cli/apply) crea l'ambiente a partire da `environment.yaml`, ne stampa l'ID e lo registra in `claude-lock.json`. Esegui il commit di `claude-lock.json` in modo che il successivo `ant apply` aggiorni questo ambiente invece di tentare di crearlo di nuovo.
  </CodeGroupItem>

  ```python Python
  environment = client.beta.environments.create(
      name="python-dev",
      config={
          "type": "cloud",
          "networking": {"type": "limited", "allow_package_managers": True},
      },
  )

  print(f"Environment ID: {environment.id}")
  ```

  ```typescript TypeScript
  const environment = await client.beta.environments.create({
    name: "python-dev",
    config: {
      type: "cloud",
      networking: { type: "limited", allow_package_managers: true }
    }
  });

  console.log(`Environment ID: ${environment.id}`);
  ```

  ```csharp C#
  var environment = await client.Beta.Environments.Create(new()
  {
      Name = "python-dev",
      Config = new BetaCloudConfigParams
      {
          Networking = new BetaLimitedNetworkParams
          {
              AllowPackageManagers = true,
          },
      },
  });

  Console.WriteLine($"Environment ID: {environment.ID}");
  ```

  ```go Go
  environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{
  	Name: "python-dev",
  	Config: anthropic.BetaEnvironmentNewParamsConfigUnion{
  		OfCloud: &anthropic.BetaCloudConfigParams{
  			Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{
  				OfLimited: &anthropic.BetaLimitedNetworkParams{
  					AllowPackageManagers: anthropic.Bool(true),
  				},
  			},
  		},
  	},
  })
  if err != nil {
  	panic(err)
  }

  fmt.Printf("Environment ID: %s\n", environment.ID)
  ```

  ```java Java
  var environment = client.beta().environments().create(EnvironmentCreateParams.builder()
      .name("python-dev")
      .config(BetaCloudConfigParams.builder()
          .networking(BetaLimitedNetworkParams.builder()
              .allowPackageManagers(true)
              .build())
          .build())
      .build());
  IO.println("Environment ID: " + environment.id());
  ```

  ```php PHP
  $environment = $client->beta->environments->create(
      name: 'python-dev',
      config: [
          'type' => 'cloud',
          'networking' => ['type' => 'limited', 'allow_package_managers' => true],
      ],
  );
  echo "Environment ID: {$environment->id}\n";
  ```

  ```ruby Ruby
  environment = client.beta.environments.create(
    name: "python-dev",
    config: {
      type: "cloud",
      networking: {type: "limited", allow_package_managers: true}
    }
  )

  puts "Environment ID: #{environment.id}"
  ```
</CodeGroup>

Usa un `name` (csharp, go: `Name`) univoco e descrittivo per poter distinguere gli ambienti. Questo esempio usa il [networking](https://platform.claude.com/docs/it/managed-agents/environments#networking) `limited` con i gestori di pacchetti consentiti, in modo che la sandbox possa raggiungere i registri dei pacchetti e gli host di codice. Per consentirle di raggiungere altri host, aggiungili a `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`).

## Usa l'ambiente in una sessione

Passa l'ID dell'ambiente come stringa quando [crei una sessione](https://platform.claude.com/docs/it/managed-agents/sessions).

<CodeGroup>
  ```bash cURL
  curl -fsS 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" \
    --data '{
      "agent": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  ant beta:sessions create --agent "$AGENT_ID" --environment-id "$ENVIRONMENT_ID"
  ```

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

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

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

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(agent.ID),
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  ```

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

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

  ```ruby Ruby
  session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id
  )
  ```
</CodeGroup>

## Opzioni di configurazione

### Pacchetti

Il campo `packages` (csharp, go: `Packages`) preinstalla i pacchetti nella sandbox prima dell'avvio dell'agente. I pacchetti vengono installati dai rispettivi gestori di pacchetti e memorizzati nella cache tra le sessioni che condividono lo stesso ambiente. Quando vengono specificati più gestori di pacchetti, vengono eseguiti in ordine alfabetico (apt, cargo, gem, go, npm, pip). Puoi facoltativamente fissare versioni specifiche. I pacchetti senza versione fissata installano la versione più recente. Se l'ambiente usa il [networking](https://platform.claude.com/docs/it/managed-agents/environments#networking) `limited`, imposta anche `allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`) in `networking` (csharp, go: `Networking`) su `true`; altrimenti la richiesta viene rifiutata con un errore 400.

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  curl -fsS 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" \
    --data '{
      "name": "data-analysis",
      "config": {
        "type": "cloud",
        "packages": {
          "pip": ["pandas", "numpy", "scikit-learn"],
          "npm": ["express"]
        },
        "networking": {"type": "limited", "allow_package_managers": true}
      }
    }'
  ```

  <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: data-analysis
      config:
        type: cloud
        packages:
          pip:
            - pandas
            - numpy
            - scikit-learn
          npm:
            - express
        networking:
          type: limited
          allow_package_managers: true
      ```
    </File>
  </CodeGroupItem>

  ```python Python
  environment = client.beta.environments.create(
      name="data-analysis",
      config={
          "type": "cloud",
          "packages": {
              "pip": ["pandas", "numpy", "scikit-learn"],
              "npm": ["express"],
          },
          "networking": {"type": "limited", "allow_package_managers": True},
      },
  )
  ```

  ```typescript TypeScript
  const environment = await client.beta.environments.create({
    name: "data-analysis",
    config: {
      type: "cloud",
      packages: {
        pip: ["pandas", "numpy", "scikit-learn"],
        npm: ["express"]
      },
      networking: { type: "limited", allow_package_managers: true }
    }
  });
  ```

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

  var environment = await client.Beta.Environments.Create(new()
  {
      Name = "data-analysis",
      Config = new BetaCloudConfigParams
      {
          Packages = new()
          {
              Pip = ["pandas", "numpy", "scikit-learn"],
              Npm = ["express"],
          },
          Networking = new BetaLimitedNetworkParams
          {
              AllowPackageManagers = true,
          },
      },
  });
  ```

  ```go Go
  environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{
  	Name: "data-analysis",
  	Config: anthropic.BetaEnvironmentNewParamsConfigUnion{
  		OfCloud: &anthropic.BetaCloudConfigParams{
  			Packages: anthropic.BetaPackagesParams{
  				Pip: []string{"pandas", "numpy", "scikit-learn"},
  				Npm: []string{"express"},
  			},
  			Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{
  				OfLimited: &anthropic.BetaLimitedNetworkParams{
  					AllowPackageManagers: anthropic.Bool(true),
  				},
  			},
  		},
  	},
  })
  if err != nil {
  	panic(err)
  }
  _ = environment
  ```

  ```java Java
  import com.anthropic.models.beta.environments.*;
  import java.util.List;

  var environment = client.beta().environments().create(EnvironmentCreateParams.builder()
      .name("data-analysis")
      .config(BetaCloudConfigParams.builder()
          .packages(BetaPackagesParams.builder()
              .pip(List.of("pandas", "numpy", "scikit-learn"))
              .npm(List.of("express"))
              .build())
          .networking(BetaLimitedNetworkParams.builder()
              .allowPackageManagers(true)
              .build())
          .build())
      .build());
  ```

  ```php PHP
  $environment = $client->beta->environments->create(
      name: 'data-analysis',
      config: [
          'type' => 'cloud',
          'packages' => [
              'pip' => ['pandas', 'numpy', 'scikit-learn'],
              'npm' => ['express'],
          ],
          'networking' => ['type' => 'limited', 'allow_package_managers' => true],
      ],
  );
  ```

  ```ruby Ruby
  environment = client.beta.environments.create(
    name: "data-analysis",
    config: {
      type: "cloud",
      packages: {
        pip: %w[pandas numpy scikit-learn],
        npm: %w[express]
      },
      networking: {type: "limited", allow_package_managers: true}
    }
  )
  ```
</CodeGroup>

Gestori di pacchetti supportati:

| Campo   | Gestore di pacchetti           | Esempio                                     |
| ------- | ------------------------------ | ------------------------------------------- |
| `apt`   | Pacchetti di sistema (apt-get) | `"graphviz"`                                |
| `cargo` | Rust (cargo)                   | `"hyperfine@1.18.0"`                        |
| `gem`   | Ruby (gem)                     | `"rails:7.1.0"`                             |
| `go`    | Moduli Go                      | `"golang.org/x/tools/cmd/goimports@latest"` |
| `npm`   | Node.js (npm)                  | `"express@4.18.0"`                          |
| `pip`   | Python (pip)                   | `"sqlalchemy==2.0.30"`                      |

### Networking

Il campo `networking` (csharp, go: `Networking`) controlla l'accesso di rete in uscita della sandbox.

Con il networking `limited`, `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) si applica anche agli strumenti `web_search` e `web_fetch`, che vengono eseguiti sui server di Anthropic. Una chiamata `web_fetch` per un URL su un host che non corrisponde a `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) restituisce un risultato di errore all'agente. `web_search` omette i risultati provenienti da host che non corrispondono a `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). `allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`) e `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) non aggiungono host per questi strumenti. Quando `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) non elenca alcun host, nessuna chiamata `web_fetch` o `web_search` restituisce una pagina o un risultato di ricerca. Un host che aggiungi a `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) per questi strumenti è accessibile anche alla sandbox. Il networking `unrestricted` e gli ambienti self-hosted non limitano questi strumenti. Per limitarli ulteriormente, imposta `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) o `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`) nella voce dello strumento nel toolset dell'agente. Consulta [Limitare i domini di web search e web fetch](https://platform.claude.com/docs/it/managed-agents/tools-web-restrictions).

| Modalità       | Descrizione                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limited`      | Limita l'accesso di rete della sandbox agli host in `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). Imposta `allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`) e `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) su `true` per consentire un accesso aggiuntivo. Usa questa modalità a meno che l'agente non debba raggiungere siti che non puoi elencare in anticipo. |
| `unrestricted` | Accesso di rete in uscita completo, ad eccezione di una blocklist di sicurezza generale. Prima di usarla, leggi [Rischi del networking senza restrizioni](https://platform.claude.com/docs/it/managed-agents/environments#risks-of-unrestricted-networking).                                                                                                                                                                                                                                                          |

<Note>
  Imposta `networking` (csharp, go: `Networking`) esplicitamente nelle richieste API; una richiesta di creazione che lo omette ottiene `unrestricted`. Il modulo della Claude Console per creare un ambiente parte con **Limited** selezionato e nient'altro consentito.
</Note>

L'esempio seguente crea un ambiente con networking `limited`:

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  curl -fsS 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": "api-access",
      "config": {
        "type": "cloud",
        "networking": {
          "type": "limited",
          "allowed_hosts": ["api.example.com"],
          "allow_mcp_servers": true,
          "allow_package_managers": true
        }
      }
    }'
  ```

  <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: api-access
      config:
        type: cloud
        networking:
          type: limited
          allowed_hosts:
            - api.example.com
          allow_mcp_servers: true
          allow_package_managers: true
      ```
    </File>
  </CodeGroupItem>

  ```python Python
  environment = client.beta.environments.create(
      name="api-access",
      config={
          "type": "cloud",
          "networking": {
              "type": "limited",
              "allowed_hosts": ["api.example.com"],
              "allow_mcp_servers": True,
              "allow_package_managers": True,
          },
      },
  )
  ```

  ```typescript TypeScript
  const environment = await client.beta.environments.create({
    name: "api-access",
    config: {
      type: "cloud",
      networking: {
        type: "limited",
        allowed_hosts: ["api.example.com"],
        allow_mcp_servers: true,
        allow_package_managers: true
      }
    }
  });
  ```

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

  var environment = await client.Beta.Environments.Create(new()
  {
      Name = "api-access",
      Config = new BetaCloudConfigParams
      {
          Networking = new BetaLimitedNetworkParams
          {
              AllowedHosts = ["api.example.com"],
              AllowMcpServers = true,
              AllowPackageManagers = true,
          },
      },
  });
  ```

  ```go Go
  environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{
  	Name: "api-access",
  	Config: anthropic.BetaEnvironmentNewParamsConfigUnion{
  		OfCloud: &anthropic.BetaCloudConfigParams{
  			Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{
  				OfLimited: &anthropic.BetaLimitedNetworkParams{
  					AllowedHosts:         []string{"api.example.com"},
  					AllowMCPServers:      anthropic.Bool(true),
  					AllowPackageManagers: anthropic.Bool(true),
  				},
  			},
  		},
  	},
  })
  if err != nil {
  	panic(err)
  }
  _ = environment
  ```

  ```java Java
  import com.anthropic.models.beta.environments.*;
  import java.util.List;

  var environment = client.beta().environments().create(EnvironmentCreateParams.builder()
      .name("api-access")
      .config(BetaCloudConfigParams.builder()
          .networking(BetaLimitedNetworkParams.builder()
              .allowedHosts(List.of("api.example.com"))
              .allowMcpServers(true)
              .allowPackageManagers(true)
              .build())
          .build())
      .build());
  ```

  ```php PHP
  $environment = $client->beta->environments->create(
      name: 'api-access',
      config: [
          'type' => 'cloud',
          'networking' => [
              'type' => 'limited',
              'allowed_hosts' => ['api.example.com'],
              'allow_mcp_servers' => true,
              'allow_package_managers' => true,
          ],
      ],
  );
  ```

  ```ruby Ruby
  environment = client.beta.environments.create(
    name: "api-access",
    config: {
      type: "cloud",
      networking: {
        type: "limited",
        allowed_hosts: %w[api.example.com],
        allow_mcp_servers: true,
        allow_package_managers: true
      }
    }
  )
  ```
</CodeGroup>

<Info>
  Usa il networking `limited` con un elenco `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) esplicito. Segui il principio del privilegio minimo concedendo solo l'accesso di rete minimo richiesto dal tuo agente e verifica regolarmente i domini consentiti.
</Info>

Con il networking `limited` e nessun altro campo impostato, nessun host è consentito. I file, i memory store e i repository GitHub che colleghi alla sessione restano disponibili. Quando una richiesta dalla sandbox sulla porta 80 o 443 viene rifiutata perché il suo host non è consentito, la risposta è un 403 che indica l'host bloccato.

Quando usi il networking `limited`:

* `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) specifica i domini che la sandbox può raggiungere. Specifica nomi host semplici o pattern con wildcard (come `*.example.com`). Non includere uno schema URL, una porta o un percorso. Un nome host semplice corrisponde esattamente a quell'host: `example.com` non corrisponde a `www.example.com`. `*.example.com` corrisponde a ogni sottodominio di `example.com`, ma non a `example.com` stesso.
* `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) consente l'accesso in uscita agli endpoint dei server MCP configurati sull'agente, oltre a quelli elencati nell'array `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). Il valore predefinito è `false`. Finché è `false`, la creazione della sessione fallisce con un errore 400 se l'agente dichiara un server MCP il cui host non è in `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). Lo stesso vale per [un agente a cui può delegare](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration). Per risolvere, aggiungi l'host a `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) oppure imposta `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) su `true`.
* `allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`) consente l'accesso in uscita a un insieme di registri di pacchetti pubblici e host di codice oltre a quelli elencati nell'array `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). Consulta [Host dei gestori di pacchetti](https://platform.claude.com/docs/it/managed-agents/environments#package-manager-hosts) per l'elenco. Il valore predefinito è `false`. Impostalo su `true` ogni volta che l'ambiente specifica `packages` (csharp, go: `Packages`); altrimenti la richiesta viene rifiutata con un errore 400, anche se gli host dei registri sono elencati in `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`).

#### Host dei gestori di pacchetti

Quando `allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`) è `true`, la sandbox può raggiungere i seguenti host oltre a quelli in `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). Anthropic gestisce questo elenco e può modificarlo.

| Ecosistema         | Host                                                                                                                                                                                       |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Hosting del codice | `github.com`, `api.github.com`, `codeload.github.com`, `raw.githubusercontent.com`, `objects.githubusercontent.com`, `release-assets.githubusercontent.com`, `gitlab.com`, `bitbucket.org` |
| Node.js            | `registry.npmjs.org`, `registry.yarnpkg.com`, `nodejs.org`                                                                                                                                 |
| Python             | `pypi.org`, `files.pythonhosted.org`                                                                                                                                                       |
| Rust               | `crates.io`, `index.crates.io`, `static.crates.io`, `static.rust-lang.org`                                                                                                                 |
| Go                 | `proxy.golang.org`, `sum.golang.org`                                                                                                                                                       |
| Java               | `repo1.maven.org`, `repo.maven.apache.org`, `services.gradle.org`, `plugins.gradle.org`, `plugins-artifacts.gradle.org`                                                                    |
| Ruby               | `rubygems.org`, `index.rubygems.org`                                                                                                                                                       |
| PHP                | `packagist.org`, `repo.packagist.org`                                                                                                                                                      |
| Ubuntu (apt)       | `archive.ubuntu.com`, `security.ubuntu.com`, `ppa.launchpad.net`                                                                                                                           |
| Container          | `registry-1.docker.io`, `auth.docker.io`, `production.cloudflare.docker.com`, `download.docker.com`, `ghcr.io`                                                                             |

<Warning>
  L'accesso di rete viene concesso per host, non per operazione. La sandbox può inviare qualsiasi richiesta a un host consentito, inclusi caricamenti come `git push` e la pubblicazione di pacchetti, con qualsiasi credenziale fornita dal comando. Se l'agente elabora input non attendibili (file del repository, contenuti web recuperati o output di strumenti di terze parti), una "prompt injection" (iniezione di prompt) riuscita potrebbe usare un host consentito per copiare file fuori dalla sandbox. Per ridurre questo rischio, imposta la [policy di autorizzazione](https://platform.claude.com/docs/it/managed-agents/permission-policies) dello strumento `bash` su `always_ask` o `auto`. Se l'ambiente non specifica `packages` (csharp, go: `Packages`), puoi invece lasciare `allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`) impostato su `false` ed elencare in `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) solo gli host di cui il tuo agente ha bisogno.
</Warning>

#### Rischi del networking senza restrizioni

Con il networking `unrestricted`, il codice nella sandbox può inviare richieste a qualsiasi host su internet, ad eccezione degli host presenti in una blocklist di sicurezza generale. Prima di scegliere questa modalità, considera cosa può fare l'agente con tale accesso:

* **L'agente può modificare elementi su siti esterni, non solo leggerli:** Lo strumento `bash` può inviare qualsiasi richiesta. L'agente può pubblicare dati, inviare moduli, chiamare API ed eseguire script che modificano dati su siti esterni. Anche una richiesta che si limita a recuperare un URL può modificare dati su alcuni siti.
* **Per impostazione predefinita nulla mette in pausa queste richieste:** La [policy di autorizzazione](https://platform.claude.com/docs/it/managed-agents/permission-policies) predefinita del toolset dell'agente è `always_allow`, quindi i comandi `bash` vengono eseguiti senza approvazione.
* **Qualsiasi cosa nella sandbox può uscirne:** Ciò include file, output degli strumenti e qualsiasi credenziale o segreto che inserisci nella sandbox.
* **I contenuti recuperati possono guidare l'agente:** Pagine web, risposte API e altri contenuti letti dall'agente possono contenere istruzioni (prompt injection) che cambiano ciò che fa successivamente.
* **L'agente agisce per tuo conto:** Le sue azioni possono violare i termini di servizio di un sito, oppure creare account e record su di esso.
* **Il comportamento del modello non è un controllo di sicurezza:** L'agente può agire su siti esterni in modi che non hai richiesto, incluso riprovare in modo diverso dopo che un sito ha bloccato una richiesta. Usa le impostazioni di rete e le policy di autorizzazione per limitare ciò che può fare.
* **La blocklist di sicurezza non è una allowlist:** Non limita quali altri siti l'agente raggiunge, né cosa l'agente fa su di essi.

Per ridurre questi rischi, usa il networking `limited` con un elenco esplicito di host. Il seguente valore di `networking` consente `api.example.com`, più gli [host dei gestori di pacchetti](https://platform.claude.com/docs/it/managed-agents/environments#package-manager-hosts) per un agente che installa pacchetti:

```json
{
  "type": "limited",
  "allowed_hosts": ["api.example.com"],
  "allow_package_managers": true
}
```

Un agente che usa solo gli strumenti `web_search` e `web_fetch` non ha bisogno del networking `unrestricted` se puoi elencare i siti di cui ha bisogno. Con il networking `limited`, `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) si applica anche a questi strumenti (consulta [Networking](https://platform.claude.com/docs/it/managed-agents/environments#networking)), quindi elenca quei siti in `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). Elencarli anche in `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) di `web_search` fa sì che la ricerca avvenga su quei siti. Un host che aggiungi a `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) è accessibile anche alla sandbox. Per limitare ulteriormente gli strumenti, consulta [Limitare i domini di web search e web fetch](https://platform.claude.com/docs/it/managed-agents/tools-web-restrictions).

Usa `unrestricted` solo quando l'agente deve raggiungere siti che non puoi elencare in anticipo. In tal caso, tieni segreti e file sensibili fuori dalla sandbox e fornisci all'agente solo le credenziali necessarie per l'attività. Valuta di impostare la policy di autorizzazione dello strumento `bash` su `always_ask` o `auto`, e [monitora gli eventi della sessione](https://platform.claude.com/docs/it/managed-agents/events-and-streaming).

## Ciclo di vita dell'ambiente

* Gli ambienti persistono finché non vengono esplicitamente archiviati o eliminati.
* Ogni sessione ottiene la propria istanza di sandbox, anche quando più sessioni fanno riferimento allo stesso ambiente. Le sessioni non condividono lo stato del filesystem.
* Gli ambienti non sono versionati. Se aggiorni un ambiente frequentemente, tieni un tuo registro delle modifiche in modo da poter sapere quale configurazione ha usato ciascuna sessione.

## Gestisci gli ambienti

<CodeGroup>
  ```bash cURL
  # Elenca gli ambienti
  curl -fsS 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"

  # Recupera un ambiente specifico
  curl -fsS "https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"

  # Archivia un ambiente (sola lettura, le sessioni esistenti continuano)
  curl -fsS -X POST "https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/archive" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"

  # Elimina un ambiente (solo se nessuna sessione vi fa riferimento)
  curl -fsS -X DELETE "https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

  ```bash CLI
  # Elenca gli ambienti
  ant beta:environments list

  # Recupera un ambiente specifico
  ant beta:environments retrieve --environment-id "$ENVIRONMENT_ID"

  # Archivia un ambiente (sola lettura, le sessioni esistenti continuano)
  ant beta:environments archive --environment-id "$ENVIRONMENT_ID"

  # Elimina un ambiente (solo se nessuna sessione vi fa riferimento)
  ant beta:environments delete --environment-id "$ENVIRONMENT_ID"
  ```

  ```python Python
  # Elenca gli ambienti
  environments = client.beta.environments.list()

  # Recupera un ambiente specifico
  env = client.beta.environments.retrieve(environment.id)

  # Archivia un ambiente (sola lettura, le sessioni esistenti continuano)
  client.beta.environments.archive(environment.id)

  # Elimina un ambiente (solo se nessuna sessione vi fa riferimento)
  client.beta.environments.delete(environment.id)
  ```

  ```typescript TypeScript
  // Elenca gli ambienti
  const environments = await client.beta.environments.list();

  // Recupera un ambiente specifico
  const env = await client.beta.environments.retrieve(environment.id);

  // Archivia un ambiente (sola lettura, le sessioni esistenti continuano)
  await client.beta.environments.archive(environment.id);

  // Elimina un ambiente (solo se nessuna sessione vi fa riferimento)
  await client.beta.environments.delete(environment.id);
  ```

  ```csharp C#
  // Elenca gli ambienti
  var environments = await client.Beta.Environments.List();

  // Recupera un ambiente specifico
  var env = await client.Beta.Environments.Retrieve(environment.ID);

  // Archivia un ambiente (sola lettura, le sessioni esistenti continuano)
  await client.Beta.Environments.Archive(environment.ID);

  // Elimina un ambiente (solo se nessuna sessione vi fa riferimento)
  await client.Beta.Environments.Delete(environment.ID);
  ```

  ```go Go
  // Elenca gli ambienti
  environments, err := client.Beta.Environments.List(ctx, anthropic.BetaEnvironmentListParams{})
  // ...

  // Recupera un ambiente specifico
  env, err := client.Beta.Environments.Get(ctx, environment.ID, anthropic.BetaEnvironmentGetParams{})
  // ...

  // Archivia un ambiente (sola lettura, le sessioni esistenti continuano)
  _, err = client.Beta.Environments.Archive(ctx, environment.ID, anthropic.BetaEnvironmentArchiveParams{})
  // ...

  // Elimina un ambiente (solo se nessuna sessione vi fa riferimento)
  _, err = client.Beta.Environments.Delete(ctx, environment.ID, anthropic.BetaEnvironmentDeleteParams{})
  ```

  ```java Java
  // Elenca gli ambienti
  var environments = client.beta().environments().list();
  // Recupera un ambiente specifico
  var env = client.beta().environments().retrieve(environment.id());
  // Archivia un ambiente (sola lettura, le sessioni esistenti continuano)
  client.beta().environments().archive(environment.id());
  // Elimina un ambiente (solo se nessuna sessione vi fa riferimento)
  client.beta().environments().delete(environment.id());
  ```

  ```php PHP
  // Elenca gli ambienti
  $environments = $client->beta->environments->list();
  // Recupera un ambiente specifico
  $env = $client->beta->environments->retrieve($environment->id);
  // Archivia un ambiente (sola lettura, le sessioni esistenti continuano)
  $client->beta->environments->archive($environment->id);
  // Elimina un ambiente (solo se nessuna sessione vi fa riferimento)
  $client->beta->environments->delete($environment->id);
  ```

  ```ruby Ruby
  # Elenca gli ambienti
  environments = client.beta.environments.list

  # Recupera un ambiente specifico
  env = client.beta.environments.retrieve(environment.id)

  # Archivia un ambiente (sola lettura, le sessioni esistenti continuano)
  client.beta.environments.archive(environment.id)

  # Elimina un ambiente (solo se nessuna sessione vi fa riferimento)
  client.beta.environments.delete(environment.id)
  ```
</CodeGroup>

## Runtime preinstallati

Le sandbox cloud includono fin da subito i runtime dei linguaggi più comuni, database e strumenti da riga di comando. Consulta il [Riferimento delle sandbox cloud](https://platform.claude.com/docs/it/managed-agents/cloud-sandboxes-reference) per l'elenco completo.

## Passaggi successivi

<CardGroup cols={2}>
  <Card title="Riferimento delle sandbox cloud" icon="book" href="https://platform.claude.com/docs/it/managed-agents/cloud-sandboxes-reference">
    Pacchetti preinstallati, database e utilità disponibili nelle sandbox cloud.
  </Card>

  <Card title="Avvia una sessione" icon="play" href="https://platform.claude.com/docs/it/managed-agents/sessions">
    Crea una sessione per eseguire il tuo agente e iniziare a svolgere attività.
  </Card>
</CardGroup>