Self-hosted sandboxes

1. Create a self-hosted environment

   In the Console: Workspace > Environments > New > Self-hosted

   Or through the API:

   cURLcURLPythonTypescriptCsharpGoJavaPhpRuby

   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"}
     }'
   

   ant beta:environments create \
     --name self-hosted \
     --config '{"type": "self_hosted"}'
   

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

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

   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);
   

   package main
   
   import (
   	"context"
   	"fmt"
   
   	"github.com/anthropics/anthropic-sdk-go"
   )
   
   func main() {
   	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)
   }
   

   import com.anthropic.models.beta.environments.BetaSelfHostedConfigParams;
   import com.anthropic.models.beta.environments.EnvironmentCreateParams;
   
   var client = AnthropicOkHttpClient.fromEnv();
   
   var environment = client.beta().environments().create(
       EnvironmentCreateParams.builder()
           .name("self-hosted")
           .config(BetaSelfHostedConfigParams.builder().build())
           .build()
   );
   IO.println(environment.id());
   

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

   client = Anthropic::Client.new
   
   environment = client.beta.environments.create(
     name: "self-hosted",
     config: {type: :self_hosted}
   )
   puts environment.id
   

2. Set your environment key

   In the Console, open the environment and click Generate environment key. Then export the environment ID and key on the worker host:

   export ANTHROPIC_ENVIRONMENT_KEY="sk-ant-oat01-..."
   export ANTHROPIC_ENVIRONMENT_ID="env_..."
   

3. Run the worker

   EnvironmentWorker claims sessions assigned to the environment, downloads skills, executes tool calls in the working directory, and posts results back. Authenticate with the environment key you generated in Step 2.

   ℹ️

   Note

   Skills can include executables that the agent may run directly. The SDK automatically marks downloaded skill files as executable in the sandbox. If you implement skills download manually, you are responsible for setting executable permissions.

   PythonTypescriptCsharpGoJavaPhpRuby

   import asyncio
   import os
   from anthropic import AsyncAnthropic
   from anthropic.lib.environments import EnvironmentWorker
   
   
   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:
           await EnvironmentWorker(
               client,
               environment_id=environment_id,
               environment_key=environment_key,
               workdir="/workspace",
           ).run()
   
   
   asyncio.run(main())
   

   import Anthropic from "@anthropic-ai/sdk";
   import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments";
   
   const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
   const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
   const client = new Anthropic({ authToken: environmentKey });
   const ctrl = new AbortController();
   process.once("SIGTERM", () => ctrl.abort());
   
   await new EnvironmentWorker({
     client,
     environmentId,
     environmentKey,
     workdir: "/workspace",
     signal: ctrl.signal
   }).run();
   

   // EnvironmentWorker is not currently available in the C# SDK. See the Always-on (ant CLI) tab above.
   

   package main
   
   import (
   	"context"
   	"log"
   	"os"
   	"os/signal"
   	"syscall"
   
   	"github.com/anthropics/anthropic-sdk-go"
   	"github.com/anthropics/anthropic-sdk-go/lib/environments"
   	"github.com/anthropics/anthropic-sdk-go/option"
   )
   
   func main() {
   	environmentKey := os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")
   	environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID")
   
   	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
   	defer stop()
   
   	client := anthropic.NewClient(option.WithAuthToken(environmentKey))
   
   	worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
   		EnvironmentID:  environmentID,
   		EnvironmentKey: environmentKey,
   		Workdir:        "/workspace",
   	})
   	if err := worker.Run(ctx); err != nil {
   		log.Fatalf("worker: %v", err)
   	}
   }
   
   

   // EnvironmentWorker is not currently available in the Java SDK. See the Always-on (ant CLI) tab above.
   

   // EnvironmentWorker is not currently available in the PHP SDK. See the Always-on (ant CLI) tab above.
   

   # EnvironmentWorker is not currently available in the Ruby SDK. See the Always-on (ant CLI) tab above.
   

1. Subscribe to session webhooks

   In the Console, define a webhook endpoint that listens for session.status_run_started events. For more details, see the webhooks documentation.

2. Create a self-hosted environment

   In the Console: Workspace > Environments > New > Self-hosted

   Or through the API:

   cURLcURLPythonTypescriptCsharpGoJavaPhpRuby

   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"}
     }'
   

   ant beta:environments create \
     --name self-hosted \
     --config '{"type": "self_hosted"}'
   

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

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

   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);
   

   package main
   
   import (
   	"context"
   	"fmt"
   
   	"github.com/anthropics/anthropic-sdk-go"
   )
   
   func main() {
   	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)
   }
   

   import com.anthropic.models.beta.environments.BetaSelfHostedConfigParams;
   import com.anthropic.models.beta.environments.EnvironmentCreateParams;
   
   var client = AnthropicOkHttpClient.fromEnv();
   
   var environment = client.beta().environments().create(
       EnvironmentCreateParams.builder()
           .name("self-hosted")
           .config(BetaSelfHostedConfigParams.builder().build())
           .build()
   );
   IO.println(environment.id());
   

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

   client = Anthropic::Client.new
   
   environment = client.beta.environments.create(
     name: "self-hosted",
     config: {type: :self_hosted}
   )
   puts environment.id
   

3. Set your credentials

   In the Console, open the environment and click Generate environment key. Export all three on your handler host:

   export ANTHROPIC_ENVIRONMENT_KEY="sk-ant-oat01-..."
   export ANTHROPIC_ENVIRONMENT_ID="env_..."
   export ANTHROPIC_WEBHOOK_SIGNING_KEY="whsec_..."
   

4. Implement the webhook handler

   EnvironmentWorker claims the session, downloads skills, executes tool calls in the working directory, posts results back, and exits. Invoke it when session.status_run_started fires.

   ℹ️

   Note

   Skills can include executables that the agent may run directly. The SDK automatically marks downloaded skill files as executable in the sandbox. If you implement skills download manually, you are responsible for setting executable permissions.

   PythonTypescriptCsharpGoJavaPhpRuby

   import os
   import anthropic
   
   environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
   environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
   client = anthropic.AsyncAnthropic(
       auth_token=environment_key,
   )
   
   
   async def handle(raw: bytes, headers: dict[str, str]) -> dict:
       event = client.beta.webhooks.unwrap(raw.decode(), headers=headers)
       if event.data.type != "session.status_run_started":
           return {"status": "ignored"}
       async for work in client.beta.environments.work.poller(
           environment_id=environment_id,
           environment_key=environment_key,
           block_ms=None,
           reclaim_older_than_ms=2000,
           drain=True,
           auto_stop=False,
       ):
           await client.beta.environments.work.worker(workdir="/workspace").handle_item(
               work_id=work.id,
               environment_id=environment_id,
               session_id=work.data.id,
               environment_key=environment_key,
           )
       return {"status": "ok"}
   

   import Anthropic from "@anthropic-ai/sdk";
   
   const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
   const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
   const client = new Anthropic({
     authToken: environmentKey
   });
   
   export async function handle(req: Request): Promise<Response> {
     const body = await req.text();
     let event;
     try {
       event = client.beta.webhooks.unwrap(body, { headers: Object.fromEntries(req.headers) });
     } catch {
       return new Response("signature verification failed", { status: 401 });
     }
     if (event.data.type !== "session.status_run_started") {
       return Response.json({ status: "ignored" });
     }
   
     for await (const work of client.beta.environments.work.poller({
       environmentId,
       environmentKey,
       blockMs: null,
       reclaimOlderThanMs: 2000,
       drain: true,
       autoStop: false
     })) {
       await client.beta.environments.work.worker({ workdir: "/workspace" }).handleItem({
         workId: work.id,
         environmentId,
         sessionId: work.data.id,
         environmentKey
       });
     }
     return Response.json({ status: "ok" });
   }
   

   // EnvironmentWorker is not currently available in the C# SDK.
   // To handle work items directly, see the Environments Work endpoints linked in the intro.
   

   package main
   
   import (
   	"context"
   	"encoding/json"
   	"io"
   	"log/slog"
   	"net/http"
   	"os"
   
   	"github.com/anthropics/anthropic-sdk-go"
   	"github.com/anthropics/anthropic-sdk-go/lib/environments"
   	"github.com/anthropics/anthropic-sdk-go/option"
   )
   
   var (
   	environmentKey = os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")
   	environmentID  = os.Getenv("ANTHROPIC_ENVIRONMENT_ID")
   	client         = anthropic.NewClient(
   		option.WithAuthToken(environmentKey),
   		option.WithWebhookKey(os.Getenv("ANTHROPIC_WEBHOOK_SIGNING_KEY")),
   	)
   	worker = environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
   		Workdir: "/workspace",
   	})
   )
   
   func handle(w http.ResponseWriter, r *http.Request) {
   	body, err := io.ReadAll(r.Body)
   	if err != nil {
   		http.Error(w, "bad request", http.StatusBadRequest)
   		return
   	}
   	event, err := client.Beta.Webhooks.Unwrap(body, r.Header)
   	if err != nil {
   		http.Error(w, "signature verification failed", http.StatusUnauthorized)
   		return
   	}
   	if event.Data.Type != "session.status_run_started" {
   		json.NewEncoder(w).Encode(map[string]string{"status": "ignored"})
   		return
   	}
   
   	// The Go SDK does not provide a RunOne convenience: claim the item with
   	// WorkPoller, then run it with HandleItem.
   	// Detach from r.Context(): the session can outlive the webhook delivery timeout.
   	ctx := context.Background()
   	poller := environments.NewWorkPoller(ctx, client, environments.WorkPollerOptions{
   		EnvironmentID:  environmentID,
   		EnvironmentKey: environmentKey,
   		Drain:          true,
   	})
   	defer poller.Close()
   	if poller.Next() {
   		item := poller.Current()
   		if err := worker.HandleItem(ctx, environments.HandleItemOptions{
   			WorkID:         item.ID,
   			EnvironmentID:  item.EnvironmentID,
   			SessionID:      item.Data.ID,
   			EnvironmentKey: environmentKey,
   		}); err != nil {
   			slog.Error("handle work item", "work_id", item.ID, "err", err)
   			http.Error(w, "internal error", http.StatusInternalServerError)
   			return
   		}
   	}
   	if err := poller.Err(); err != nil {
   		slog.Error("poll work queue", "err", err)
   		http.Error(w, "internal error", http.StatusInternalServerError)
   		return
   	}
   	json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
   }
   
   func main() {
   	http.HandleFunc("POST /webhook", handle)
   	if err := http.ListenAndServe(":8080", nil); err != nil {
   		slog.Error("http server", "err", err)
   		os.Exit(1)
   	}
   }
   
   

   // EnvironmentWorker is not currently available in the Java SDK.
   // To handle work items directly, see the Environments Work endpoints linked in the intro.
   

   // EnvironmentWorker is not currently available in the PHP SDK.
   // To handle work items directly, see the Environments Work endpoints linked in the intro.
   

   # EnvironmentWorker is not currently available in the Ruby SDK.
   # To handle work items directly, see the Environments Work endpoints linked in the intro.
   

The SDK provides three helpers at different levels:

• EnvironmentWorker: the out-of-the-box worker. Handles polling, setup, and execution end to end.
  • .run(): runs indefinitely, picking up sessions as they arrive. Exits cleanly on SIGTERM.
  • .handle_item(): picks up one pending session, handles it, and exits.
• work.poller(): polls the work queue on your behalf and gives you each claimed session. Use this when you want to decide what happens per session, for example launching a container rather than running tools in-process.
  • drain: whether to stop polling once the queue is empty rather than waiting for new work.
  • block_ms: how long to wait for work to arrive before returning, in milliseconds. Must be between 1 and 999. Set to None for a non-blocking check.
  • reclaim_older_than_ms: re-claim work items leased to a worker that has stopped responding.
  • auto_stop: whether to post a stop signal on the work item after the iterator exits.
• tool_runner(): runs tool calls for a single session. Use when you've already claimed the work and only need the execution layer.

EnvironmentWorker covers most use cases. Use the work poller directly when you want to launch your own per-session process, for example spinning up a container for each claimed session:

# The poll endpoint requires the environment key (Bearer auth), not your
# API key. Use one of the SDK options below.

# The poll endpoint requires the environment key (Bearer auth), not your
# API key. Use one of the SDK options below.

import asyncio
import os

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


async def launch_container(work: BetaSelfHostedWork) -> None:
    # Replace with your own per-session sandbox launcher. Pass
    # ANTHROPIC_ENVIRONMENT_KEY into the launched container, never
    # your API key.
    print(f"claimed session {work.data.id}")


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 container owns the stop call
        ):
            await launch_container(work)


asyncio.run(main())

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 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> {
  // Replace with your own per-session sandbox launcher. Pass
  // ANTHROPIC_ENVIRONMENT_KEY into the launched container, never
  // your API key.
  console.log(`claimed session ${work.data.id}`);
}

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

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

// Work polling is not currently available in the C# SDK.

package main

import (
	"context"
	"fmt"
	"log"
	"os"

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

func launchContainer(work *anthropic.BetaSelfHostedWork) {
	// Replace with your own per-session sandbox launcher. The Go poller
	// calls work.Stop when this function returns (it has no auto-stop
	// opt-out), so block here until the session completes rather than
	// detaching as the Python and TypeScript tabs do.
	fmt.Printf("claimed session %s\n", work.Data.ID)
}

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,
	})
	defer poller.Close()

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

// Work polling is not currently available in the Java SDK.

// Work polling is not currently available in the PHP SDK.

# Work polling is not currently available in the Ruby SDK.

AgentToolContext is the execution context for tool calls, defining the working directory, path policy, and optionally downloads the session's skills when entered as a context manager. beta_agent_toolset_20260401(env) takes an AgentToolContext and returns the standard tool implementations (bash, read, write, edit, glob, grep).

With EnvironmentWorker: both are managed automatically. Pass a tools factory to customize the tool list:

EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])

With work.poller() / tool_runner(): set up AgentToolContext and beta_agent_toolset_20260401(env) yourself before running tools:

from anthropic.lib.tools.agent_toolset import (
    AgentToolContext,
    beta_agent_toolset_20260401,
)

async with AgentToolContext(
    workdir="/workspace", client=client, session_id=work.data.id
) as env:
    # skills downloaded to /workspace/skills/<name>/
    tools = beta_agent_toolset_20260401(env)

import {
  setupSkills,
  betaAgentToolset20260401
} from "@anthropic-ai/sdk/tools/agent-toolset/node";

const ctx = { workdir: "/workspace", client, sessionId: work.data.id };
await setupSkills(ctx);
const tools = betaAgentToolset20260401(ctx);

// AgentToolContext is not currently available in the C# SDK.

env := &agenttoolset.AgentToolContext{Workdir: "/workspace"}
if err := env.SetupSkills(ctx, client, work.Data.ID); err != nil {
	panic(err)
}
// skills downloaded to /workspace/skills/<name>/
tools := agenttoolset.BetaAgentToolset20260401(env)

// AgentToolContext is not currently available in the Java SDK.

// AgentToolContext is not currently available in the PHP SDK.

# AgentToolContext is not currently available in the Ruby SDK.