Claude Managed Agents - Upstash Documentation

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

A Box API key from the Upstash Console.
An Anthropic API key from API keys, created inside a workspace.

.env

UPSTASH_BOX_API_KEY=box_xxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxx

npm install @upstash/box @anthropic-ai/sdk tsx

Create a self-hosted environment:

setup.ts

import Anthropic from "@anthropic-ai/sdk";
import { appendFileSync } from "node:fs";

const environment = await new Anthropic().beta.environments.create({
  name: "upstash-box",
  config: { type: "self_hosted" },
});

appendFileSync(".env", `ANTHROPIC_ENVIRONMENT_ID=${environment.id}\n`);

npx tsx --env-file=.env setup.ts

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

.env

ANTHROPIC_ENVIRONMENT_KEY=sk-ant-oat01-xxxxxxxxxxxx

2. Run the dispatcher

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

dispatcher.ts

import Anthropic from "@anthropic-ai/sdk";
import { Box } from "@upstash/box";

const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;

const anthropic = new Anthropic({ authToken: environmentKey });

const worker = `
import Anthropic from "@anthropic-ai/sdk";
import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments";

// Authenticates with ANTHROPIC_WORK_SECRET, a short-lived credential for this session only.
// The environment key never enters the box.
const client = new Anthropic({ authToken: "unused" });
await new EnvironmentWorker({ client, workdir: "/workspace/home" }).handleItem();
`;

const isWorkerRunning = async (box: Box) =>
  (await box.exec.command("pgrep -f '[w]orker.mjs' || true")).result.trim() !== "";

async function getBox(sessionId: string) {
  const boxes = await Box.list({ label: "claude-agent" });
  const existing = boxes.find((b) => b.name === sessionId);
  if (existing) return Box.get(existing.id);

  const box = await Box.create({ runtime: "node", name: sessionId, labels: ["claude-agent"] });
  await box.exec.command("npm install @anthropic-ai/sdk");
  await box.files.write({ path: "worker.mjs", content: worker });
  return box;
}

// The worker in the box completes each work item, so the poller must not stop it.
const queue = anthropic.beta.environments.work.poller({
  environmentId,
  environmentKey,
  autoStop: false,
  reclaimOlderThanMs: 30_000,
});

for await (const work of queue) {
  if (work.data.type !== "session") continue;

  const sessionId = work.data.id;
  const box = await getBox(sessionId);

  const env = {
    ANTHROPIC_ENVIRONMENT_ID: environmentId,
    ANTHROPIC_SESSION_ID: sessionId,
    ANTHROPIC_WORK_ID: work.id,
    ANTHROPIC_WORK_SECRET: work.secret ?? "",
  };

  const run = await box.exec.session({
    argv: ["bash", "-c", "setsid nohup node worker.mjs >> worker.log 2>&1 < /dev/null &"],
    env: Object.entries(env).map(([key, value]) => `${key}=${value}`),
  });
  await run.wait();
  run.close();

  await new Promise((resolve) => setTimeout(resolve, 3000));
  if (!(await isWorkerRunning(box))) console.error(`${sessionId}: worker exited, see worker.log`);
  else console.log(`${sessionId} -> ${box.id}`);
}

npx tsx --env-file=.env dispatcher.ts

3. Start a session

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

session.ts

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const agent = await client.beta.agents.create({
  name: "Coding Assistant",
  model: "claude-opus-5-5",
  system: "You work in /workspace/home.",
  tools: [{ type: "agent_toolset_20260401" }],
});

const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: process.env.ANTHROPIC_ENVIRONMENT_ID!,
});

const stream = await client.beta.sessions.events.stream(session.id);

await client.beta.sessions.events.send(session.id, {
  events: [
    {
      type: "user.message",
      content: [{ type: "text", text: "Write a Node script that prints the first 20 primes and run it." }],
    },
  ],
});

for await (const event of stream) {
  if (event.type === "agent.message") {
    for (const block of event.content) if (block.type === "text") console.log(block.text);
  }
  if (event.type === "session.status_idle" && event.stop_reason.type === "end_turn") break;
}

npx tsx --env-file=.env 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:

Box.create({
  runtime: "node",
  name: sessionId,
  labels: ["claude-agent"],
  // Added to matching requests by the network proxy, never visible inside the box
  attachHeaders: {
    "api.github.com": { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` },
  },
  // Only these domains are reachable
  networkPolicy: {
    mode: "custom",
    allowedDomains: ["api.anthropic.com", "registry.npmjs.org", "api.github.com"],
  },
});

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.

​1. Set up

​2. Run the dispatcher

​3. Start a session

​Customize the box

​Troubleshooting

1. Set up

2. Run the dispatcher

3. Start a session

Customize the box

Troubleshooting