orchestrator

Managed Agents Worker Orchestrator

Start and manage an Anthropic Managed Agents self-hosted environment worker from your app or CLI.

This is the simplest E2B shape: your host process starts one E2B sandbox from the managed-agents template, launches Anthropic's EnvironmentWorker.run() inside it, then creates Managed Agents sessions that route tool calls to that worker.

flowchart LR
    app["App or CLI"] --> session["Managed Agents session"]
    session --> env["Anthropic self-hosted environment"]
    worker["E2B worker sandbox"] --> env
    worker --> tools["bash/read/write/edit/glob/grep"]
    tools --> workdir["/mnt/session"]

Loading

Setup

Run these commands from this directory. The Python package and .env live one level up.

uv sync --project ..
cp ../.env.template ../.env

Fill in .env:

Variable	Notes
E2B_API_KEY	Required to start worker sandboxes.
E2B_ACCESS_TOKEN	Required to build the E2B template.
ANTHROPIC_API_KEY	Used to create environments, agents, and sessions.
ANTHROPIC_ENVIRONMENT_ID	Printed by create-environment.
ANTHROPIC_ENVIRONMENT_KEY	Generated from the Anthropic Environments workspace. See Anthropic's environment docs.
ANTHROPIC_AGENT_ID	Printed by create-agent.

Create Anthropic Resources

For the Anthropic concepts behind these commands, see the Managed Agents docs for environments and agents.

make create-environment NAME=my-e2b-env

Save the printed ANTHROPIC_ENVIRONMENT_ID, open the printed URL in the Anthropic Environments workspace, and generate ANTHROPIC_ENVIRONMENT_KEY for the self-hosted environment.

make create-agent NAME=my-e2b-agent

Save the printed ANTHROPIC_AGENT_ID.

Build the E2B Template

make build-template

This bakes the Python package, Anthropic SDK, FastAPI/Uvicorn webhook dependencies, shell tools, and /mnt/session workdir into the anthropic-managed-agents E2B template.

Start a Worker

make start-worker

The command prints E2B_WORKER_SANDBOX_ID and stores that value on the Anthropic environment metadata as e2b_worker_sandbox_id. That gives another process a lookup path from ANTHROPIC_ENVIRONMENT_ID to the active E2B sandbox:

make show-environment

Stop that sandbox later with:

make stop-worker SANDBOX_ID="<sandbox-id>"

If the stopped sandbox ID matches e2b_worker_sandbox_id, the stop command clears that metadata key.

Send a Session Message

With the worker running:

make send

Expected event stream signals:

UserToolResultEvent ... text='/mnt/session'
UserToolResultEvent ... text='hello from E2B'
SessionStatusIdleEvent ... stop_reason=EndTurn

To upload a local file into the running E2B worker sandbox:

make upload-file \
  SANDBOX_ID="<sandbox-id>" \
  FILE=/tmp/example-input.txt \
  REMOTE_PATH=/mnt/session/uploads/example-input.txt

Then ask the agent to read /mnt/session/uploads/example-input.txt. Anthropic session resources are not supported for self-hosted environments, so this example uploads files through E2B.

Notes

• This is a simple worker demo, not per-session isolation.
• One worker sandbox can service the self-hosted environment. Start more workers for more capacity.
• Persistent state is scoped to the worker sandbox. Files under /mnt/session can be shared by any session that worker claims.
• Tool calls execute inside the E2B sandbox under /mnt/session.
• Secrets and Anthropic resource IDs stay runtime-only in ../.env; they are not baked into the E2B template.

Use ../app-webhooks/ with APP_SANDBOX_ROUTING_SCOPE=session when each Managed Agents session needs its own sandbox and follow-up state.

For a concrete event-by-event walkthrough, see ../EXAMPLE_USAGE.md. For a complete code-level implementation, see IMPLEMENTATION.md.