worker

Orb on Durable Objects and Celld

The Worker host runs the full Orb runtime inside a Cloudflare Durable Object. The same bundle and the same wrangler.jsonc also run on a self-hosted Celld cell. It is a runtime, not a thin client: the agent loop, tools, session journal and provider calls all run in the object.

What runs where

client ──HTTPS/WSS──▶ Worker (dist/worker.mjs default export)
                        │  checks the bearer token, then routes /agents/<name>/…
                        ▼  env.ORB_AGENT.idFromName(<name>)
                      Durable Object OrbAgent (one per agent name)
                        │  first event: open its Orb in the isolate's runtime
                        ▼  (orb.wasm, cmd/orb-worker, instantiated once per isolate)
                      Go runtime: one platforms/worker.Instance per object
                        host.Host{FS, Store, Env}  ◀──▶  ctx.storage (SQLite-backed)
                        agent session + agent/rpc  ──▶  provider APIs via fetch

• Bundle. make -f platforms/worker/worker.mk worker-build writes .tools/worker/dist/worker.mjs and .tools/worker/dist/orb.wasm. worker.mjs is Go's wasm_exec.js followed by deploy/worker.mjs, so the bundle is one JavaScript module plus a Wasm module. no_bundle: true means neither Wrangler nor Celld runs a bundler, and Celld does not need esbuild.
• Objects. Each agent name gets its own Durable Object, with its own storage, session and Go instance. The name must match [A-Za-z0-9._~-]{1,128}. Use one name per conversation or per long-lived agent instance. idFromName is deterministic, so the same name always reaches the same object. On Celld, the id also depends on the Worker name: renaming the Worker there moves every name to a new, empty object.
• Lifecycle. An object opens its Orb on its first event after a start, eviction or hibernation. Opening restores the files and documents from storage and resumes the current session. There is no in-memory state that storage does not also hold. The objects of an isolate share one Go runtime: only the first pays for instantiating it and its one-time setup, and each object adds a few megabytes rather than a runtime's worth. An object disposes of its Orb once it is collected, and a runtime that stops, as a panic does, stops its objects until their next event.

Capability profile

The object does not load context files, skills or prompt templates. The resource loader reads the process file system, and that is not yet served through the FS port.

Bridge peer

Each object is a full Bridge peer (platforms/worker/peer). Its identity (an Ed25519 key), grants, pairings and operation receipts live in Store documents under /bridge/, so they survive restarts. The object's own Orb is enrolled once, under an alias derived from the object name, and is attached as its orb.instance/1 service whenever the peer is open.

• Inbound streams. /agents/<name>/bridge accepts a WebSocket that carries Bridge's pinned TLS 1.3 stream, as orb bridge run --web-listen does. The route needs no ORB_TOKEN: a remote Orb never has it, and Bridge authenticates the peer inside the stream. The socket is accepted, not hibernatable. The TLS session lives in the Go runtime, which hibernation would discard while the socket stayed open, and the open socket keeps the object resident. An object without a Bridge identity answers 404 without booting. A browser Origin must be listed in ORB_BRIDGE_ORIGINS.
• Outbound calls. The object cannot dial (tailcat is native-only, and a Worker has no listener of its own). It reaches another peer over a channel that peer opened: a laptop Orb that joined keeps its channel, and the object's agent calls it with bridge_call. That tool is active only when plugins.bridge-agent-calls is on in the object's settings. Each call also needs the object's own instance grant for the destination, and a grant on the destination for the object's instance subject.
• Plugins. The object's settings turn on titles, tasks, questions (answered by the app or peer driving the object) and memtree (experimental, docs/plugins.md): with memtree, every prompt starts from a fixed-size view of the whole conversation, and its summaries live in the session journal in object storage.
• Admin. POST /agents/<name>/bridge/admin with {"method", "params"}, behind ORB_TOKEN, runs the owner methods of orb bridge: status, instances, peers, grants, invite, approve, block, grant, revoke, scope, group, assign, takeover, trust (a full controller grant) and remote. self returns the peer ID, instance ID and stream URL. invite advertises wss://<host>/agents/<name>/bridge, or the same path on ORB_PUBLIC_ORIGIN when a proxy fronts the Worker. join, publish and the service lifecycle are refused, because the object cannot dial.

Pairing a laptop Orb with an object:

curl -s -X POST https://<host>/agents/demo/bridge/admin -H "Authorization: Bearer $ORB_TOKEN" \
  -d '{"method":"invite"}' > invitation.json
orb bridge pair join < invitation.json          # prints the claim, with the laptop's peer ID
curl -s -X POST https://<host>/agents/demo/bridge/admin -H "Authorization: Bearer $ORB_TOKEN" \
  -d '{"method":"approve","params":{"invitation_id":"<id>","claimant":"<laptop peer ID>"}}'
orb bridge trust <object peer ID>               # optional: the object may list and call this laptop
orb bridge remote <object peer ID> instances.list < /dev/null

Deploy

Cloudflare, with Wrangler credentials from npx wrangler login or CLOUDFLARE_API_TOKEN:

make -f platforms/worker/worker.mk worker-deploy        # builds .tools/worker, then wrangler deploy

Celld, with a fleet bucket:

make -f platforms/worker/worker.mk worker-build && .tools/bin/celld deploy .tools/worker --bucket s3://my-cells-bucket

The installed cf CLI (0.4) delegates cf dev and cf deploy to Wrangler only through the experimental cloudflare.config.ts, which Celld cannot read. The targets therefore call the Wrangler version pinned in deploy/package.json, which shares wrangler.jsonc with Celld.

Local servers read .tools/worker/.dev.vars (dotenv format, never committed):

make -f platforms/worker/worker.mk worker-dev           # workerd via wrangler dev, http://127.0.0.1:8787
make -f platforms/worker/worker.mk worker-celld-dev     # Celld, http://127.0.0.1:9876 (installs celld into .tools)

Secrets and configuration

On Cloudflare, set secrets with cd .tools/worker && npx wrangler secret put ORB_TOKEN and do the same for each provider key. Celld has no secret store: celld dev reads .dev.vars, and a fleet takes string vars from the deployed config. Keep that config out of git. A client can change the model of a session with the RPC set_model command.

Endpoint contract

Every /agents/<name>/… route except the Bridge stream requires Authorization: Bearer <ORB_TOKEN>. A missing or wrong token gets 401.

Frames are the kernel RPC frames of orb --mode rpc (agent/rpc), byte for byte. A transport failure, such as a runtime that failed to boot, arrives as {"type":"worker_error","error":"…"}. That frame is specific to this host and is not part of the kernel.

curl -N https://orb-agent.<account>.workers.dev/agents/demo/rpc \
  -H "Authorization: Bearer $ORB_TOKEN" --data-binary @- <<'EOF'
{"id":"1","type":"prompt","message":"Create notes/todo.md with three items"}
EOF

Limits

• Size. With the Bridge peer, orb.wasm is 27.9 MB raw and 7.0 MB gzip, about 30% under the 10 MB compressed limit of the paid plan. The free plan allows 3 MB, so it cannot host Orb.
• Memory. Cloudflare gives each isolate 128 MB. The isolate's objects share one runtime, whose Wasm linear memory is about 21 MB with one object after a tool-using turn and grows by about 1.7 MB per further object, mostly Go heap (89 MB for 40 objects under Node). Linear memory only grows, so this figure is also the peak.
• Time. In local workerd a boot takes 0.3–1.7 s, and the first frame after a restart arrives in 0.25–0.75 s. Celld's first activation of a cell also compiles the module, which takes about 2.8 s in its isolate log. The Durable Object CPU limit is 30 s per event by default.
• Timers. After each provider request, Go's js/wasm scheduler leaves a JavaScript timer pending for up to httpIdleTimeoutMs (5 minutes by default). A pending timer keeps the object out of hibernation until it fires.
• Runs. One run per object at a time. A prompt sent while a run streams needs streamingBehavior, as in RPC mode.
• Celld. performance.now() stays fixed while JavaScript runs, so bootMs reads 0. Celld's process global is partial, and the shim fills in the members Go needs.

Delete

• Cloudflare. cd .tools/worker && npx wrangler delete --name orb-agent removes the Worker. To erase stored objects first, deploy a migration with "deleted_classes": ["OrbAgent"].
• Celld. Locally, celld dev --clean discards .tools/worker/.celld/dev. For a fleet, remove the deployment's prefix from the bucket.

Tests and gates