How to Add a Custom Agent

Custom agents let you bring your own agent process to an Upstash Box. The box still provides the same sandbox, filesystem, shell, git, logs, streaming, and console experience, but your code decides how to call the model and how to produce output.

Use a custom agent when the built-in Claude Code, Codex, OpenCode, or Cursor agents do not fit your workflow.

Create a Custom Agent Box#

Create the box with agent.harness: Agent.Custom and provide a customHarness command. The command runs inside the box for every box.agent.run() or box.agent.stream() call.

Agent Contract#

For each run, Box executes your command and appends these arguments:

-p "<prompt>" --model "<model>" --stream --session "<session-id>"

--session is only included when a prior session exists.

Your process must write Server-Sent Events to stdout using the box-sse-v1 protocol:

event: textdata: {"text":"Hello"}event: donedata: {"output":"Hello","input_tokens":10,"output_tokens":4,"total_cost_usd":0.0001,"session_id":"session-1"}

Supported event names:

SDK Helper#

If your custom agent process can import @upstash/box, use runCustomHarness() to parse Box arguments and emit the protocol events:

Minimal Anthropic Agent#

This custom agent calls Anthropic directly and streams text back through Box.

const args = process.argv.slice(2)function readArg(name, fallback = "") {  const index = args.indexOf(name)  return index >= 0 ? args[index + 1] ?? fallback : fallback}function emit(event, data) {  process.stdout.write(`event: ${event}\n`)  process.stdout.write(`data: ${JSON.stringify(data)}\n\n`)}const prompt = readArg("-p")const model = readArg("--model", "claude-haiku-4-5-20251001")const sessionId = readArg("--session") || crypto.randomUUID()try {  emit("tool", {    name: "anthropic_messages",    input: { model },  })  const response = await fetch("https://api.anthropic.com/v1/messages", {    method: "POST",    headers: {      "content-type": "application/json",      "x-api-key": process.env.ANTHROPIC_API_KEY,      "anthropic-version": "2023-06-01",    },    body: JSON.stringify({      model,      max_tokens: 1024,      messages: [{ role: "user", content: prompt }],    }),  })  const body = await response.json()  if (!response.ok) {    throw new Error(body.error?.message ?? `Anthropic request failed: ${response.status}`)  }  const output = body.content    ?.filter((part) => part.type === "text")    .map((part) => part.text)    .join("") ?? ""  emit("text", { text: output })  emit("done", {    output,    input_tokens: body.usage?.input_tokens ?? 0,    output_tokens: body.usage?.output_tokens ?? 0,    session_id: sessionId,  })} catch (error) {  emit("error", {    error: error instanceof Error ? error.message : String(error),    session_id: sessionId,  })  process.exitCode = 1}

Write the custom agent into the box before the first run:

Update an Existing Custom Agent#

You can update the custom agent command for an existing custom box:

This only works for boxes created with agent.harness: Agent.Custom.

Custom Harness Examples#

Ready-to-run examples for popular open-source agents:

• Pi — multi-provider coding agent
• Gemini — Google Gemini via @google/genai
• Aider — git-aware code editor
• Goose — autonomous coding agent
• CrewAI — multi-agent orchestration framework
• Pydantic AI — type-safe agent framework

Notes#

• Custom agents do not use managed provider keys.
• Pass secrets through env on Box.create() or configure them inside the box.
• The command must be a binary name from PATH or an absolute path under /workspace/home/ or /home/boxuser/.
• The command runs as boxuser inside the existing box sandbox.