---
title: Ejecutar un sandbox por sesión
url: https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-per-session
description: Da a cada sesión su propio sandbox autoalojado con el chart de Helm en Kubernetes, un script de lanzamiento o el sondeador del SDK.
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
  zdr:
    eligibility: not-eligible
    note: No es elegible para ZDR, excepto Managed Agents autoalojado. Las sesiones son recursos con estado; las transcripciones persisten hasta que las eliminas.
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: beta
    Claude Platform on AWS: beta
---

En el patrón de un sandbox por sesión, cada sesión se ejecuta en un “sandbox” (entorno aislado) nuevo, que puede tener su propio sistema de archivos, límites de recursos y controles de red. Para compararlo con los otros patrones, consulta [Elige un patrón de implementación](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-workers#choose-a-deployment-pattern).

Puedes configurarlo de tres maneras:

* **[Chart de Helm en Kubernetes](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-per-session#run-sandboxes-on-kubernetes):** El despachador de Anthropic reclama el trabajo e inicia un pod para cada sesión en tu clúster.
* **[Script de lanzamiento](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-with-a-spawn-script):** La CLI `ant` reclama el trabajo y llama a tu script, que lanza un sandbox en cualquier plataforma.
* **[Sondeador del SDK](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-from-the-sdk-poller):** Tu propio código reclama el trabajo y lanza el sandbox.

Las secciones posteriores a [Ejecuta sandboxes en Kubernetes](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-per-session#run-sandboxes-on-kubernetes) se aplican al script de lanzamiento y al sondeador del SDK.

## Ejecuta sandboxes en Kubernetes

Anthropic publica un chart de Helm, `cma-sandboxes`, y sus imágenes. El chart ejecuta un sandbox por sesión en tu propio clúster de Kubernetes. Su despachador sondea la cola de trabajo del entorno y le da a cada sesión un pod propio:

* **Aislamiento:** Cada pod se ejecuta bajo [gVisor](https://gvisor.dev/) detrás de las políticas de red del chart. Tiene su propio sistema de archivos y límites de recursos. Solo el despachador tiene la clave del entorno.
* **Afinidad de sesión:** Cada mensaje de una sesión va al sandbox de esa sesión. Después de que la sesión permanece inactiva durante 30 minutos (el valor predeterminado de la configuración `sandbox.idleTimeout` del chart), su pod se detiene. Su volumen `/workspace` permanece hasta que la sesión termina. El siguiente mensaje inicia un pod sobre el mismo volumen.
* **“Warm pool” (grupo precalentado):** Excepto en Google Kubernetes Engine (GKE), el chart mantiene dos pods listos para nuevas sesiones (el valor predeterminado de la configuración `sandbox.warmPoolSize` del chart).

Los pods de sandbox ejecutan el “worker” (proceso de trabajo) de la CLI `ant`. Admiten [almacenes de memoria](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-memory) con la configuración de sincronización predeterminada, y no admiten [herramientas personalizadas](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-custom-tools).

### Instala el chart

El chart se ejecuta en GKE, Amazon EKS y otros clústeres. Configura lo siguiente antes de instalarlo:

* **En el clúster:** El controlador de [Agent Sandbox](https://github.com/kubernetes-sigs/agent-sandbox) (en GKE, el complemento Agent Sandbox), nodos que ejecuten gVisor y un complemento de red que aplique NetworkPolicy.
* **En tu propio espacio de nombres:** Etiquetas del Pod Security Standard restringido, un Secret con el ID del entorno y la [clave del entorno](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes#run-your-first-session), y el certificado TLS del despachador.

La [guía de instalación en GitHub](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md) tiene los pasos de configuración para cada tipo de clúster. También cubre las actualizaciones y la rotación de claves.

Guarda tu configuración como `cma-values.yaml`. La instalación falla sin las tres configuraciones de este archivo:

<File filename="cma-values.yaml">
  ```yaml
  platform: gke             # or eks, or generic for any other cluster
  egress:
    # The chart already blocks the private ranges. List your other addresses
    # that sandboxes must not reach.
    clusterCIDRs:
      - 203.0.113.10/32     # your cluster's Kubernetes API endpoint
    cmaServer:
      public: true          # the Claude API has a public address
  ```
</File>

La guía de instalación enumera las configuraciones que dependen de tu clúster, como `gke.dns` en GKE Autopilot. También indica cuándo `egress.clusterIsPrivate: true` reemplaza a `egress.clusterCIDRs`.

Luego, instala el chart:

```bash
helm install cma \
  oci://us-docker.pkg.dev/anthropic-public-registry/sandboxes/charts/cma-sandboxes \
  --version 0.1.0 \
  --namespace cma \
  -f cma-values.yaml \
  --wait
```

Después de la instalación, ejecuta la comprobación previa que describe la guía de instalación.

<Warning>
  No elimines el chart solo con `helm uninstall`. Ese comando borra las políticas de red y deja los sandboxes de las sesiones ejecutándose sin ellas. Detén primero el despachador y elimina los sandboxes, en el orden que indica la [sección Removal de la guía de instalación](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#removal).
</Warning>

### Agrega herramientas a la imagen del sandbox

La imagen de sandbox publicada es Alpine Linux con `bash`, `curl`, `jq` y la CLI `ant`. El chart la ejecuta con un sistema de archivos raíz de solo lectura y como usuario no root, por lo que un agente no puede instalar paquetes durante una sesión.

Para darles más herramientas a tus agentes, como Python o Git, compila ambas imágenes desde el repositorio en la etiqueta de la versión. La [sección Install de la guía de instalación](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#install) tiene los comandos. Sube las imágenes a tu registro como `cma-dispatcher` y `cma-sandbox`, con la versión del chart como etiqueta. Luego, establece `image.registry` en ese registro. Si fijas digests de imagen, usa los digests de tus propias imágenes.

### Restringe el tráfico de salida de red

De forma predeterminada, las políticas de red del chart permiten que un sandbox acceda a la internet IPv4 pública. Bloquean los rangos de direcciones privadas, el servidor de metadatos de la nube y las direcciones de `egress.clusterCIDRs`. Un agente afectado por “prompt injection” (inyección de prompts) puede enviar lo que lee a cualquier dirección a la que su sandbox pueda acceder. [Network egress](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#network-egress) en la guía de instalación tiene los detalles.

* **GKE con Dataplane V2:** Establece `egress.mode: fqdnGke` para limitar las conexiones al puerto 443 de los hosts de `egress.fqdnGke.hosts`. Mantén `api.anthropic.com` en esa lista y agrega todos los hosts que necesiten los comandos de tus agentes. A diferencia del modo predeterminado, este modo no tiene una lista de rangos bloqueados. Permite cualquier dirección a la que resuelva el nombre de un host de la lista, así que incluye solo hosts cuyo DNS sea de tu confianza. Aun así, un sandbox puede enviar datos al exterior dentro de las consultas DNS.
* **Otros clústeres y GKE sin Dataplane V2:** El modo predeterminado es el único modo.
* **Todos los clústeres:** Las políticas de red no cubren los puertos en los que escuchan los propios nodos del clúster. Consulta [Node isolation you own](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#node-isolation-you-own) en la guía de instalación.

## Lanza sandboxes con un script de lanzamiento

Un sondeador en el host reclama el trabajo y llama a tu script una vez por cada elemento de trabajo. El script lanza un sandbox para esa única sesión.

<Steps>
  <Step title="Compila la imagen del sandbox">
    Instala `ant` y establece `ant beta:worker run` como punto de entrada. Cuando un sandbox se inicia, lee los detalles de la sesión desde variables de entorno, gestiona esa sesión y termina. La imagen base debe proporcionar `/bin/bash`; la compilación usa `curl` solo para descargar `ant`.

    <File filename="Dockerfile">
      ```dockerfile
      FROM your-base-image
      ARG ANT_VERSION=2.11.0
      ARG TARGETARCH
      RUN ARCH=$([ "$TARGETARCH" = "arm64" ] && echo arm64 || echo amd64) && \
          curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${ANT_VERSION}/ant_${ANT_VERSION}_linux_${ARCH}.tar.gz" \
            | tar -xz -C /usr/local/bin ant
      WORKDIR /workspace
      VOLUME /workspace
      ENTRYPOINT ["ant", "beta:worker", "run"]
      ```
    </File>
  </Step>

  <Step title="Escribe el script de lanzamiento">
    El script reenvía los detalles de la sesión a un sandbox nuevo. Requiere `jq` en el host del sondeador.

    <File filename="spawn.sh">
      ```bash
      #!/bin/bash
      # spawn.sh: se invoca una vez por cada elemento de trabajo reclamado
      # El elemento de trabajo reclamado llega como JSON por stdin.
      ANTHROPIC_WORK_SECRET="$(jq -r '.secret // empty')"
      export ANTHROPIC_WORK_SECRET
      mkdir -p "/host/outputs/$ANTHROPIC_SESSION_ID"
      exec docker run --rm \
        -e ANTHROPIC_SESSION_ID -e ANTHROPIC_ENVIRONMENT_KEY \
        -e ANTHROPIC_WORK_ID -e ANTHROPIC_ENVIRONMENT_ID -e ANTHROPIC_BASE_URL \
        -e ANTHROPIC_WORK_SECRET \
        -v "/host/outputs/$ANTHROPIC_SESSION_ID":/workspace \
        your-image
      ```
    </File>

    El sondeador establece `ANTHROPIC_WORK_ID`, `ANTHROPIC_ENVIRONMENT_ID`, `ANTHROPIC_SESSION_ID` y `ANTHROPIC_ENVIRONMENT_KEY`. `ANTHROPIC_BASE_URL` llega al script solo si la estableces en el host del sondeador. El script lee `ANTHROPIC_WORK_SECRET` del JSON del elemento de trabajo en la entrada estándar. Consulta [Variables de entorno](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-reference#environment-variables).

    `/host/outputs` es un directorio del host que tú eliges. Montarlo en `/workspace` te permite recuperar los entregables de la sesión después de que el sandbox termine. El montaje también recoge el árbol `skills/` descargado y cualquier archivo intermedio.
  </Step>

  <Step title="Inicia el sondeador">
    ```bash
    ant beta:worker poll --on-work ./spawn.sh
    ```
  </Step>
</Steps>

## Reenvía el secreto del elemento de trabajo

Cada elemento de trabajo reclamado puede llevar un `secret` (csharp, go: `Secret`) que Anthropic emite para esa sesión. El worker que ejecuta la sesión lo necesita para montar [almacenes de memoria](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-memory).

Un worker que reclama y ejecuta sesiones en un mismo proceso transmite el secreto por sí mismo. `EnvironmentWorker` con `run()` (go: `Run()`) es uno de esos workers, y `ant beta:worker poll` sin `--on-work` es otro. Cuando tu propio código se sitúa entre la reclamación y el worker, tú reenvías el secreto:

| Reclamas trabajo con                                                                                                    | El secreto llega como                                                                  | Pásalo al worker como                                                                                                                                                                           |
| ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ant beta:worker poll --on-work`                                                                                        | El campo `secret` del JSON del elemento de trabajo en la entrada estándar de tu script | `ANTHROPIC_WORK_SECRET` en el entorno del sandbox                                                                                                                                               |
| `work.poller()` (typescript: `new WorkPoller()`; go: `environments.NewWorkPoller()`) del SDK de Python, TypeScript o Go | El campo `secret` (go: `Secret`) de cada elemento de trabajo reclamado                 | `ANTHROPIC_WORK_SECRET` en el entorno del sandbox o el argumento `work_secret` (typescript: `workSecret`; go: `WorkSecret`) de `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) |

Pasa el secreto solo al sandbox que atiende esa sesión y nunca lo registres en los logs. Consulta [Modelo de seguridad](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-security) para ver cómo se relaciona con la clave del entorno.

## Lanza sandboxes desde el sondeador del SDK

Para reclamar trabajo desde tu propio código en lugar de `ant beta:worker poll --on-work`, usa el sondeador del SDK de Python, TypeScript o Go: `work.poller()` (typescript: `new WorkPoller()`; go: `environments.NewWorkPoller()`). Sondea la cola y te entrega cada sesión reclamada, y tú lanzas el sandbox:

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    Reclamar trabajo en un bucle y lanzar un sandbox para cada sesión requiere más lógica que un único comando de shell. Desde la shell, ejecuta `ant beta:worker poll --on-work` con un script de lanzamiento, como en [Lanza sandboxes con un script de lanzamiento](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-with-a-spawn-script).
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    Para reclamar trabajo desde la shell y lanzar un sandbox para cada sesión, ejecuta `ant beta:worker poll --on-work` con un script de lanzamiento. Consulta [Lanza sandboxes con un script de lanzamiento](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-with-a-spawn-script).
  </CodeGroupItem>

  ```python Python
  import asyncio
  import os

  from anthropic import AsyncAnthropic
  from anthropic.types.beta.environments import BetaSelfHostedWork

  SANDBOX_ENV = (
      "ANTHROPIC_ENVIRONMENT_ID",
      "ANTHROPIC_ENVIRONMENT_KEY",
      "ANTHROPIC_WORK_ID",
      "ANTHROPIC_SESSION_ID",
      "ANTHROPIC_WORK_SECRET",
      "ANTHROPIC_BASE_URL",  # forwarded only when set on this host
  )


  async def launch_container(work: BetaSelfHostedWork) -> None:
      print(f"claimed session {work.data.id}")
      # Reemplaza `docker run` con tu propio lanzador de sandboxes. Reenvía la clave del
      # entorno (nunca tu clave de API) y el secreto por sesión del elemento de trabajo: el worker
      # interno necesita el secreto para montar los almacenes de memoria de la sesión.
      env = os.environ | {
          "ANTHROPIC_WORK_ID": work.id,
          "ANTHROPIC_SESSION_ID": work.data.id,
          "ANTHROPIC_WORK_SECRET": work.secret or "",
      }
      forward = [arg for name in SANDBOX_ENV for arg in ("-e", name)]
      launcher = await asyncio.create_subprocess_exec(
          "docker", "run", "--rm", "--detach", *forward, "your-image", env=env
      )
      await launcher.wait()


  async def main() -> None:
      environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
      environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
      async with AsyncAnthropic(auth_token=environment_key) as client:
          async for work in client.beta.environments.work.poller(
              environment_id=environment_id,
              environment_key=environment_key,
              auto_stop=False,  # the launched sandbox owns the stop call
          ):
              await launch_container(work)


  asyncio.run(main())
  ```

  ```typescript TypeScript
  import { spawn } from "node:child_process";
  import { once } from "node:events";
  import Anthropic from "@anthropic-ai/sdk";
  import { WorkPoller } from "@anthropic-ai/sdk/helpers/beta/environments";
  import type { BetaSelfHostedWork } from "@anthropic-ai/sdk/resources/beta/environments";

  const SANDBOX_ENV = [
    "ANTHROPIC_ENVIRONMENT_ID",
    "ANTHROPIC_ENVIRONMENT_KEY",
    "ANTHROPIC_WORK_ID",
    "ANTHROPIC_SESSION_ID",
    "ANTHROPIC_WORK_SECRET",
    "ANTHROPIC_BASE_URL" // forwarded only when set on this host
  ];

  const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
  const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
  const client = new Anthropic({ authToken: environmentKey });

  async function launchContainer(work: BetaSelfHostedWork): Promise<void> {
    console.log(`claimed session ${work.data.id}`);
    // Reemplaza `docker run` con tu propio lanzador de sandboxes. Reenvía la clave
    // del entorno (nunca tu clave de API) y el secreto por sesión del elemento de trabajo: el worker
    // interno necesita el secreto para montar los almacenes de memoria de la sesión.
    const env = {
      ...process.env,
      ANTHROPIC_WORK_ID: work.id,
      ANTHROPIC_SESSION_ID: work.data.id,
      ANTHROPIC_WORK_SECRET: work.secret ?? ""
    };
    const forward = SANDBOX_ENV.flatMap((name) => ["-e", name]);
    const launcher = spawn("docker", ["run", "--rm", "--detach", ...forward, "your-image"], {
      env,
      stdio: "inherit"
    });
    await once(launcher, "close");
  }

  const poller = new WorkPoller({
    client,
    environmentId,
    environmentKey,
    autoStop: false // the launched sandbox owns the stop call
  });

  for await (const work of poller) {
    await launchContainer(work);
  }
  ```

  <CodeGroupItem language="C#">
    El SDK de C# no tiene una función auxiliar que sondee en busca de trabajo. Para reclamar trabajo desde tu propio código, llama a los [endpoints de Environments Work](https://platform.claude.com/docs/es/api/beta/environments/work) para sondear un elemento y confirmarlo.
  </CodeGroupItem>

  ```go Go
  package main

  import (
  	"context"
  	"fmt"
  	"log"
  	"os"
  	"os/exec"

  	"github.com/anthropics/anthropic-sdk-go/v2"
  	"github.com/anthropics/anthropic-sdk-go/v2/lib/environments"
  	"github.com/anthropics/anthropic-sdk-go/v2/option"
  	"github.com/anthropics/anthropic-sdk-go/v2/packages/param"
  )

  var sandboxEnv = []string{
  	"ANTHROPIC_ENVIRONMENT_ID",
  	"ANTHROPIC_ENVIRONMENT_KEY",
  	"ANTHROPIC_WORK_ID",
  	"ANTHROPIC_SESSION_ID",
  	"ANTHROPIC_WORK_SECRET",
  	"ANTHROPIC_BASE_URL", // forwarded only when set on this host
  }

  func launchContainer(ctx context.Context, work *anthropic.BetaSelfHostedWork) error {
  	fmt.Printf("claimed session %s\n", work.Data.ID)
  	// Reemplaza `docker run` con tu propio lanzador de sandbox. Reenvía la clave
  	// del entorno (nunca tu clave de API) y el secreto por sesión del elemento de trabajo: el worker
  	// interno necesita el secreto para montar los almacenes de memoria de la sesión.
  	args := []string{"run", "--rm", "--detach"}
  	for _, name := range sandboxEnv {
  		args = append(args, "-e", name)
  	}
  	launcher := exec.CommandContext(ctx, "docker", append(args, "your-image")...)
  	launcher.Env = append(os.Environ(),
  		"ANTHROPIC_WORK_ID="+work.ID,
  		"ANTHROPIC_SESSION_ID="+work.Data.ID,
  		"ANTHROPIC_WORK_SECRET="+work.Secret,
  	)
  	launcher.Stdout, launcher.Stderr = os.Stdout, os.Stderr
  	return launcher.Run()
  }

  func main() {
  	environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID")
  	environmentKey := os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")

  	client := anthropic.NewClient(option.WithAuthToken(environmentKey))

  	ctx := context.Background()

  	poller := environments.NewWorkPoller(ctx, client, environments.WorkPollerOptions{
  		EnvironmentID:  environmentID,
  		EnvironmentKey: environmentKey,
  		AutoStop:       param.NewOpt(false), // the launched sandbox owns the stop call
  	})
  	defer poller.Close()

  	for work, err := range poller.All() {
  		if err != nil {
  			log.Fatal(err)
  		}
  		if err := launchContainer(ctx, work); err != nil {
  			log.Fatal(err)
  		}
  	}
  }
  ```

  <CodeGroupItem language="Java">
    El SDK de Java no tiene una función auxiliar que sondee en busca de trabajo. Para reclamar trabajo desde tu propio código, llama a los [endpoints de Environments Work](https://platform.claude.com/docs/es/api/beta/environments/work) para sondear un elemento y confirmarlo.
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    El SDK de PHP no tiene una función auxiliar que sondee en busca de trabajo. Para reclamar trabajo desde tu propio código, llama a los [endpoints de Environments Work](https://platform.claude.com/docs/es/api/beta/environments/work) para sondear un elemento y confirmarlo.
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    El SDK de Ruby no tiene una función auxiliar que sondee en busca de trabajo. Para reclamar trabajo desde tu propio código, llama a los [endpoints de Environments Work](https://platform.claude.com/docs/es/api/beta/environments/work) para sondear un elemento y confirmarlo.
  </CodeGroupItem>
</CodeGroup>

## Ejecuta el worker del SDK dentro del sandbox

Reemplaza el punto de entrada `ant beta:worker run` por un punto de entrada del SDK cuando el sandbox deba [atender herramientas personalizadas](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-custom-tools) o usar una [configuración de sincronización de memoria no predeterminada](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-memory#configure-sync). El punto de entrada construye `EnvironmentWorker` y llama a `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`), que lee las mismas variables `ANTHROPIC_*` que reenvía el script de lanzamiento.

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    Un worker es un proceso de larga duración, no una única solicitud HTTP. Para atender herramientas personalizadas o cambiar la configuración de sincronización de memoria, usa `EnvironmentWorker` en el SDK de Python, TypeScript o Go.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    El worker de la CLI `ant` (`ant beta:worker run`) no puede atender herramientas personalizadas ni cambiar la configuración de sincronización de memoria. Para hacer cualquiera de las dos cosas, usa `EnvironmentWorker` en el SDK de Python, TypeScript o Go.
  </CodeGroupItem>

  ```python Python
  import asyncio
  import contextlib
  import os
  import signal
  from anthropic import AsyncAnthropic
  from anthropic.lib.environments import EnvironmentWorker


  async def main() -> None:
      async with AsyncAnthropic(
          auth_token=os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
      ) as client:
          worker = EnvironmentWorker(client, workdir="/workspace")
          # Sin argumentos, handle_item() lee las variables ANTHROPIC_* que el script de lanzamiento
          # reenvió, incluida ANTHROPIC_WORK_SECRET.
          task = asyncio.create_task(worker.handle_item())
          # Cancelar la tarea cuando se detiene el contenedor permite que el worker suba
          # los archivos de memoria modificados y elimine los directorios del almacén antes de salir.
          loop = asyncio.get_running_loop()
          for signum in (signal.SIGINT, signal.SIGTERM):
              loop.add_signal_handler(signum, task.cancel)
          with contextlib.suppress(asyncio.CancelledError):
              await task


  asyncio.run(main())
  ```

  ```typescript TypeScript
  import Anthropic from "@anthropic-ai/sdk";
  import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments";

  const client = new Anthropic({ authToken: process.env.ANTHROPIC_ENVIRONMENT_KEY });
  const controller = new AbortController();
  // Abortar cuando se detiene el contenedor permite que el worker suba los archivos de memoria
  // modificados y elimine los directorios del almacén antes de salir.
  process.once("SIGTERM", () => controller.abort());
  process.once("SIGINT", () => controller.abort());

  // Sin argumentos, handleItem() lee las variables ANTHROPIC_* que el script de lanzamiento
  // reenvió, incluida ANTHROPIC_WORK_SECRET.
  await new EnvironmentWorker({
    client,
    workdir: "/workspace",
    signal: controller.signal
  }).handleItem();
  ```

  <CodeGroupItem language="C#">
    El SDK de C# no tiene `EnvironmentWorker`.
  </CodeGroupItem>

  ```go Go
  package main

  import (
  	"context"
  	"log"
  	"os"
  	"os/signal"
  	"syscall"

  	"github.com/anthropics/anthropic-sdk-go/v2"
  	"github.com/anthropics/anthropic-sdk-go/v2/lib/environments"
  	"github.com/anthropics/anthropic-sdk-go/v2/option"
  )

  func main() {
  	// Cancelar el contexto cuando se detiene el contenedor permite al worker subir
  	// los archivos de memoria modificados y eliminar los directorios del almacén antes de salir.
  	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
  	defer stop()

  	client := anthropic.NewClient(option.WithAuthToken(os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")))
  	worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
  		Workdir: "/workspace",
  	})
  	// Con opciones de valor cero, HandleItem lee las variables ANTHROPIC_* que el script de lanzamiento
  	// reenvió, incluida ANTHROPIC_WORK_SECRET.
  	if err := worker.HandleItem(ctx, environments.HandleItemOptions{}); err != nil {
  		log.Fatalf("worker: %v", err)
  	}
  }
  ```

  <CodeGroupItem language="Java">
    El SDK de Java no tiene `EnvironmentWorker`.
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    El SDK de PHP no tiene `EnvironmentWorker`.
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    El SDK de Ruby no tiene `EnvironmentWorker`.
  </CodeGroupItem>
</CodeGroup>

## Prepara archivos para una sesión

Anthropic no monta archivos ni repositorios de GitHub en los sandboxes autoalojados. Para que los archivos específicos de una sesión estén disponibles:

1. Pasa referencias a archivos, como una ruta de S3 o un SHA de commit, en el campo `metadata` (csharp, go: `Metadata`) de la sesión.
2. En tu script de lanzamiento o en tu controlador de `--on-work`, recupera la sesión (`GET /v1/sessions/{session_id}`) y lee `metadata` (csharp, go: `Metadata`). El elemento de trabajo reclamado lleva el ID de la sesión, pero no los metadatos.
3. Prepara los archivos en el directorio de trabajo antes de que se ejecute cualquier herramienta.

El ejemplo de cURL lee un token de acceso de `ANTHROPIC_AUTH_TOKEN`. Para obtener uno, configura Workload Identity Federation con el alcance predeterminado `workspace:developer`, como se describe en [Configurar la federación](https://platform.claude.com/docs/es/manage-claude/workload-identity-federation#set-up-federation). Luego, intercambia el token de identidad de tu carga de trabajo por un token de acceso, como se muestra en [Autentícate desde tu carga de trabajo](https://platform.claude.com/docs/es/manage-claude/workload-identity-federation#authenticate-from-your-workload). Establece `ANTHROPIC_AUTH_TOKEN` solo en la shell donde ejecutes el ejemplo de cURL, porque tiene prioridad sobre tu configuración de federación. [Autenticación](https://platform.claude.com/docs/es/manage-claude/authentication) enumera las demás credenciales que acepta la API, como la clave de API de la guía de inicio rápido.

<CodeGroup>
  ```bash cURL
  curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
    -H "authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "agent": "agent_011CYm1BLqPXpQRk5khsSXrs",
      "environment_id": "env_01595EKxaaTTGwwY3kyXdtbs",
      "metadata": {"input_file": "s3://my-bucket/data.csv"}
    }'
  ```

  ```bash CLI
  ant beta:sessions create \
    --agent agent_011CYm1BLqPXpQRk5khsSXrs \
    --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
    --metadata '{"input_file": "s3://my-bucket/data.csv"}'
  ```

  ```python Python
  session = client.beta.sessions.create(
      agent=agent.id,
      environment_id=environment.id,
      metadata={"input_file": "s3://my-bucket/data.csv"},
  )
  ```

  ```typescript TypeScript
  const session = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id,
    metadata: { input_file: "s3://my-bucket/data.csv" }
  });
  ```

  ```csharp C#
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      Metadata = new Dictionary<string, string> { ["input_file"] = "s3://my-bucket/data.csv" },
  });
  ```

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent:         anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)},
  	EnvironmentID: environment.ID,
  	Metadata: map[string]string{
  		"input_file": "s3://my-bucket/data.csv",
  	},
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .metadata(SessionCreateParams.Metadata.builder()
          .putAdditionalProperty("input_file", JsonValue.from("s3://my-bucket/data.csv"))
          .build())
      .build());
  ```

  ```php PHP
  $session = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
      metadata: ['input_file' => 's3://my-bucket/data.csv'],
  );
  ```

  ```ruby Ruby
  session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id,
    metadata: {input_file: "s3://my-bucket/data.csv"}
  )
  ```
</CodeGroup>

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Supervisar y solucionar problemas de workers autoalojados" icon="lightning" href="https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-operations">
    Consulta la profundidad de la cola, detén sesiones y workers de forma limpia y corrige fallos comunes.
  </Card>
</CardGroup>
