Workers

Ultron shell

The shell is a worker that fronts a managed container running the vendored claude-code CLI. Each session gets its own Durable Object plus container instance with its own /work directory. Work is snapshotted to object storage between calls so a session survives container cold-boots.

Updated today

Overview

At a glance

Worker: ultron-shell
Container: Managed container, standard-4 (8GB disk, 2 vCPU, 12GB RAM), max 200 instances
Durable Object: UltronShell (SQLite-backed)
Queue: ultron-shell-runs (producer + consumer in same worker)
Workflow: RunGoalWorkflow for multi-step durable goals
R2 buckets: ultron-shell-snapshots, ultron-design-assets, ultron-shell-events
Default LLM backend: Kimi via a bridge worker
Alternate backend: Real Anthropic when payload sets backend: "claude"

The shell replaces the previous per-user sandbox. Where the old sandbox was always-on and held a desktop session, the shell is request-scoped, queue-driven, and survives via snapshots rather than always-running compute. The agent CLI inside the container drives Kimi (or Anthropic) and exposes a single HTTP surface to callers.

Worker shape

What the worker contains.

wrangler.toml (key bindings)toml

1name = "ultron-shell"

2main = "src/index.ts"

4[[containers]]

5class_name = "UltronShell"

6image = "./Dockerfile"

7max_instances = 200

8instance_type = "standard-4"

10[[durable_objects.bindings]]

11class_name = "UltronShell"

12name = "ULTRON_SHELL"

14[[r2_buckets]]

15binding = "WORK_R2" # /work snapshots

16binding = "DESIGN_ASSETS" # 71 brand DNA docs

17binding = "EVENTS_R2" # event log

19[[queues.producers]]

20binding = "RUN_QUEUE"

21queue = "ultron-shell-runs"

23[[queues.consumers]]

24queue = "ultron-shell-runs"

25max_batch_size = 1

26max_batch_timeout = 5

27max_retries = 2

28dead_letter_queue = "ultron-shell-runs-dlq"

30[[workflows]]

31binding = "RUN_GOAL_WORKFLOW"

HTTP endpoints

All POSTs, all auth-gated against UC_KEY.

Method + path	Body	Returns
GET /health	-	Container health + CLI version
POST /exec	cmd, cwd?, timeout_ms?	Stdout / stderr / exit_code from a bash command in the container
POST /write	path, content	Writes a file in the container
POST /read	path	Reads a file
POST /list	path	Lists a directory
POST /seed	files: { path: content, ... }	Writes many files in one round trip
POST /run-claude	prompt, allowed_tools?, system?, model?, timeout_ms?, backend?	Invokes the agent CLI in non-interactive mode and returns the final text
POST /snapshot	-	Tars /work, uploads to R2 at snapshots/<session>.tar.gz
POST /restore	-	Pulls snapshots/<session>.tar.gz from R2 and unpacks into /work
POST /jobs	type, payload	Enqueues onto RUN_QUEUE. Returns a job id immediately.

Note

Containers are keyed by ?session=<id> (default primary). Each session is a separate DO + container instance with its own /work directory.

Async job pipeline

POST /jobs enqueues, the queue consumer drives the container.

src/index.ts (queue handler concept)ts

1// Producer

2async fetch(req, env) {

3 if (url.pathname === '/jobs') {

4 const job: RunJobMsg = await req.json()

5 job.jobId = crypto.randomUUID()

6 job.enqueuedAt = Date.now()

7 await env.RUN_QUEUE.send(job)

8 return Response.json({ ok: true, jobId: job.jobId })

9 }

10}

12// Consumer (same worker)

13async queue(batch, env) {

14 for (const msg of batch.messages) {

15 const job = msg.body as RunJobMsg

16 const stub = env.ULTRON_SHELL.idFromName(job.session)

17 const obj = env.ULTRON_SHELL.get(stub)

18 await obj.fetch(internalDriverUrl(job)) // DO drives the container

19 msg.ack()

20 }

21}

The queue decouples the long /run-claude and /run-goal paths from the worker's subrequest budget. A producer POST returns within milliseconds with a job id; the consumer in the same worker drains the queue and drives the container for as long as the work takes. Final state is delivered via an optional callback webhook configured per job.

RunGoalWorkflow

Durable multi-step orchestration. Survives worker restarts.

For work that needs cooldowns, retries with backoff, or multi-day execution, the shell exposes RunGoalWorkflow. A workflow instance can sleep between steps, and each step is checkpointed so the workflow resumes cleanly after a worker restart.

RunGoalWorkflow sketchts

1export class RunGoalWorkflow extends WorkflowEntrypoint<Env, RunGoalParams> {

2 async run(event, step) {

3 const { goal, session, maxAttempts } = event.payload

5 for (let attempt = 1; attempt <= maxAttempts; attempt++) {

6 const ok = await step.do(`attempt-${attempt}`, async () => {

7 const r = await runOnce(this.env, session, goal)

8 return r.ok

9 })

10 if (ok) return { ok: true, attempt }

11 // Cooldown grows with attempts

12 await step.sleep(`cooldown-${attempt}`, '15 minutes')

13 }

14 return { ok: false }

15 }

16}

Session and snapshots

How /work survives between calls.

A fresh container has an empty /work directory. The DO tracks startedAt (set in onStart) and restoredAt (set after a successful restore). Before forwarding any state-touching request, the DO checks whether restoredAt < startedAt and an R2 snapshot exists; if so it pulls /work back from R2 transparently before forwarding. Auto-snapshot fires (via ctx.waitUntil) after every successful /run-claude so each iteration is durable.

Note

A periodic in-container snapshotter also fires every 60s (configurable) to catch mid-run state, dedupes if a previous snap is still running, skips if /work is empty or no session is known. Fixes the "container migrated mid-run, the post-migration auto-snap was empty so the work was lost" case.

Inference backends

Two backends, switchable per request.

Backend	When	Env
Kimi via bridge (default)	All standard runs. Cheap, fast, good for code.	ANTHROPIC_BASE_URL, ANTHROPIC_MODEL
Real Anthropic	Set backend: 'claude' in /run-claude payload. Used for tasks that need stronger reasoning.	ANTHROPIC_BASE_URL_CLAUDE, ANTHROPIC_MODEL_CLAUDE, ANTHROPIC_API_KEY_CLAUDE

Bundled tools

Binaries the shell ships alongside the CLI in /tools-bin.

Binary	What it does
ultron-screenshot	Grab a screenshot of a running browser or page in the container.
brave-search	Web search through an external provider. The shell's search shortcut.
ultron-deploy	Deploy a built project to a hosted preview URL.
ultron-render	Trigger the carousel renderer for a brief.
lookup-design-dna	Open the design assets R2 bucket and surface relevant brand DNA docs.

File map

cf-workers/ultron-shell

wrangler.tomlcontainer, DO, queue, workflow, R2 bindings

Dockerfilecontainer image with vendored CLI + tools

server.mjsin-container HTTP wrapper around the CLI

src

index.tsworker entry; DO, queue consumer, RunGoalWorkflow

tools-bin

ultron-screenshot

brave-search

ultron-deploy

ultron-render

lookup-design-dna

skills

ULTRON_OPERATING_PRINCIPLES.md

claude-code

...vendored CLI sources