Claude Managed Agents

Claude Managed Agents let Anthropic run the agent loop for you - session state, event history, and a self-hosted work queue - while the actual code execution happens on infrastructure you control. This guide shows how to point that execution layer at Buddy Sandboxes, so every agent session runs in a clean, fully isolated cloud environment.

How the pieces fit together

The work is split between two parties:

• Anthropic owns the agent loop, session state, event history, and the self-hosted work queue.
• Buddy runs the execution layer: one orchestrator sandbox (the control plane) and one worker sandbox per session (cma-worker-<session>), created from a prebuilt snapshot and running the task through the ant beta:worker run CLI.

The orchestrator discovers work in one of two trigger modes:

• Webhook (default) - Anthropic sends session.status_run_started events to a public endpoint on the orchestrator. Requires a signing key.
• Polling - the orchestrator long-polls the work queue. No inbound endpoint or webhook secret needed.

What you need

• Claude Managed Agents access with a valid ANTHROPIC_API_KEY
• A Buddy workspace and project, plus a BUDDY_TOKEN scoped to SANDBOX_MANAGE
• Node 20 or later

Bootstrap

Clone the repo, drop in your credentials, and run the bootstrap:

cp .env.example .env
npm install
npm run bootstrap
$$$

The bootstrap script collects credentials, provisions the Claude self-hosted environment and agent, builds the base snapshot, and deploys the orchestrator. It pauses at the two steps that can only be done in the Console - generating the environment key and (in webhook mode) registering the webhook signing secret:

═══ cma-buddy-sandboxes · bootstrap ═══════════════════════════

Ctrl+C to abort · existing values are confirmed before overwrite.

┄┄ Credentials ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
»  ANTHROPIC_API_KEY
     ↳ Open: platform.claude.com/settings/keys
     ↳ Paste key: ········GAAA
»  BUDDY_REGION
     ↳ Choose: US
»  BUDDY_TOKEN
     ↳ Open: app.buddy.works/api-tokens/add
     ↳ Scope: SANDBOX_MANAGE
     ↳ Paste key: ········erk1
»  BUDDY_WORKSPACE
     ↳ Enter value: myplayground
»  BUDDY_PROJECT
     ↳ Enter value: sbs-2
»  TRIGGER_MODE
     ↳ Choose: webhook

┄┄ Provision & wire-up ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
✔  Claude self-hosted environment: env_••••••••••••••••
»  ANTHROPIC_ENVIRONMENT_KEY
     ↳ Open: platform.claude.com/workspaces/default/environments/env_••••••••••••••••
     ↳ Paste key: ········hAAA
✔  Claude agent: agent_••••••••••••••••
✔  Base snapshot: sn-••••••••••
✔  Deploy orchestrator
»  ANTHROPIC_WEBHOOK_SIGNING_KEY
     ↳ Open: platform.claude.com/settings/workspaces/default/webhooks
     ↳ Endpoint:  https://webhook-cma-orchestrator-sbs-2-myplayground.us-1.buddy.app/webhook
     ↳ Event:     session.status_run_started
     ↳ Paste signing secret: ········uaQ=
✔  Deploy orchestrator

✔  Setup complete
     ↳ Run session to test it:  npm run session

Run a session

With the orchestrator deployed, start an interactive session to prove it end to end:

npm run session
$

session: sesn_••••••••••••••••
Type a prompt and press Enter. Submit an empty line or `exit` to quit.

✔ you: who are you?

agent: I'm an AI assistant working in an agentic environment. I can help you with a wide
range of tasks — software engineering (fixing bugs, adding features, refactoring), research
and analysis, file operations, data processing, automation, and documentation.

I have access to tools for running shell commands, reading/writing/editing files, searching
code and the web, and delegating work to specialized subagents when useful. There's a
working sandbox at `/workspace`.

What would you like to do?

Behind the scenes, the orchestrator picked up the session, spun up a fresh cma-worker-<session> sandbox from the snapshot, and streamed the agent's turns back to you.

Credentials stay scoped

Workers never see your admin credentials. The only secret a worker sandbox receives is the scoped ANTHROPIC_ENVIRONMENT_KEY, passed as an encrypted variable. Your ANTHROPIC_API_KEY and BUDDY_TOKEN stay on the orchestrator and never reach the execution layer.

Configuration

A few environment variables let you tune behavior:

• TRIGGER_MODE - webhook (default) or polling.
• ANT_VERSION - the ant CLI release baked into the base snapshot.
• ANT_MAX_IDLE - worker idle timeout before it wraps up.
• WORKER_IDLE_TIMEOUT_SEC - how long Buddy keeps an idle worker sandbox running before auto-stopping it.
• MAX_IDLE_DAYS - how long a stopped worker survives before the janitor deletes it.
• JANITOR_SECONDS - how often the cleanup sweep runs.

Cleanup

When you're done, tear everything down:

npm run teardown
$

This destroys the orchestrator and any worker sandboxes. Snapshots are kept - delete them from Buddy manually if you no longer need them.

Learn more

• Run agents in a sandbox - the CLI-first way to drop any agent into an isolated Buddy Sandbox.
• Sandboxes documentation - lifecycle, endpoints, resources, and more.