Skip to main content

Claude Managed Agents

2 min read

Run Claude Managed Agents sessions in Upstash Box. Claude runs on Anthropic's side, and each session gets its own box where its bash commands and file edits run. Web search and web fetch still run on Anthropic's side.


1. Set up#

.env

Create a self-hosted environment:

setup.ts

Then open Managed Agents → Environments → upstash-box in the Claude Console, click Generate environment key, and add it to .env:

.env

2. Run the dispatcher#

The dispatcher picks up sessions and runs each one in its own box.

dispatcher.ts

3. Start a session#

Start a session on the upstash-box environment from the Claude Console, or from code:

session.ts

Claude's commands and file edits run in the session's box. Send another message to the same session and it continues in the same box, with the same files.


Customize the box#

Pass any Box.create option in getBox:

Values you pass in env are readable by the agent; use attachHeaders for credentials. Open a server the agent started with box.getPublicURL(3000), and delete a session's box with box.delete() when you are done. Pause or delete a box only when isWorkerRunning(box) is false. The worker exits about a minute after each turn.


Troubleshooting#

  • Session stays queued: the dispatcher is not running, or its environment ID and key don't match the session's environment.
  • This API key is not scoped to a workspace: create the API key inside a workspace.
  • Commands never run: check /workspace/home/worker.log in the session's box.