# Claude Managed Agents

Self-host Claude Managed Agents on Buddy Sandboxes - Anthropic owns the agent loop, Buddy runs the execution layer with an orchestrator and one isolated worker sandbox per session.

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](/docs/ai-agents/sandboxes.md), so every agent session runs in a clean, fully isolated cloud environment.

<Hint type="info">
The reference implementation lives at [github.com/buddy/claude-managed-agents](https://github.com/buddy/claude-managed-agents) - clone it and you're a few commands away from a working setup.
</Hint>

## 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:

```bash
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:

```text
═══ 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:

```bash
npm run session
```

```text
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:

```bash
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](/docs/ai-agents/sandboxes.md) - the CLI-first way to drop any agent into an isolated Buddy Sandbox.
- [Sandboxes documentation](/docs/sandboxes.md) - lifecycle, endpoints, resources, and more.


---
Original source: https://buddy.works/docs/ai-agents/claude-managed-agents