Autopilot runs as Durable Objects

serverless-objects/autopilot runs Autopilot runs as Durable Objects. Each run is a RunObject that holds the run record and its state machine, tool-boundary events, usage budgets, durable wake timers and a Camouflage session log. A RunRegistry per workspace answers cross-run queries: list by status, and reconcile after a restart.

It ports the per-run part of Autopilot's RunStore and RunWakeScheduler to Durable Object SQLite, with the same statuses, transitions, budgets, lease and retry rules. A pending wake is a durable alarm, so it fires after the node restarts.

The module is pre-alpha and ships in the serverless-objects npm package.

#Use your own executor

import { RunObject, RunRegistry } from "serverless-objects/autopilot";

export { RunRegistry };

// Subclass to connect your executor. onWake runs when a wake timer fires.
export class Run extends RunObject {
  async onWake(event) {
    // Start or resume the executor for event.runId. Delivery is at least once:
    // be idempotent by event.timerId. Throwing retries with backoff.
  }
}

{
  "durable_objects": {
    "bindings": [
      { "name": "RUNS", "class_name": "Run" },
      { "name": "RUN_REGISTRY", "class_name": "RunRegistry" }
    ]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Run", "RunRegistry"] }]
}

To use other binding names, set the static registryBinding on your RunObject subclass and runBinding on a RunRegistry subclass.

const run = env.RUNS.getByName(runId);           // the object name is the run id
await run.create({ id: runId, workspace: "acme", cwd: "/workspace", task: "Fix the flaky test", maxCostUsd: 2 });
await run.transition("running");
await run.recordToolIntent("call-1", "bash", { command: "npm test" });   // stores a SHA-256 of the arguments
await run.recordToolResult("call-1", "bash", { ok: true, content: output }); // stores a hash and byte count
await run.recordCheckpoint();
await run.recordUsage({ promptTokens: 1200, completionTokens: 300, costUsd: 0.01 });
await run.scheduleTimer({ condition: "time", wakeAt: Date.now() + 60_000 });
await run.transition("waiting");

await env.RUN_REGISTRY.getByName("acme").list({ status: "waiting" });

Run statuses: queued, running, waiting, needs_input, completed, failed, cancelled, interrupted_unknown.

#Run Autopilot in a Hotcell cell

AutopilotCellRun is a RunObject that runs its task with Autopilot inside a Hotcell cell:

1. Create the cell with gateway egress, so the cell gets a short-lived token for model calls, never a provider key.
2. Install autopilot-ai in the cell and start its bridge.
3. Open a session and send the task as one prompt.
4. Follow the bridge's event cursor.

Control requests go through exec, so microVM cells without a network interface work too.

import { RunRegistry } from "serverless-objects/autopilot";
import { AutopilotCellRun } from "serverless-objects/autopilot/cell";

export { RunRegistry };
export class Run extends AutopilotCellRun {}

await env.RUNS.getByName(id).create({ id, workspace: "acme", cwd: "/workspace", task, maxCostUsd: 1 });
await env.RUNS.getByName(id).start({ model: "moonshotai/kimi-k2.6", egress: { spendCapUsd: 1, ttlMs: 3_600_000 } });

Set HOTCELL_ENDPOINT and HOTCELL_API_KEY in the Worker's vars and secrets.

#start() options

#Behavior

The cell is kept after the run so you can inspect its workspace. Destroy it through Hotcell when you're done.

#Redaction

The session log includes the task, assistant text, tool commands and up to 16,000 characters of each tool's output. Likely secrets are redacted before an event is stored:

• provider keys (sk-..., OpenRouter), GitHub and Slack tokens, AWS access key IDs, JWTs and PEM private keys;
• NAME=value and "name": "value" pairs whose name contains SECRET, TOKEN, PASSWORD or API_KEY.

The control log (stream=run) keeps only hashes. Redaction is pattern-based, so treat the session log as sensitive anyway.

#Run Autopilot in-process on the native engine

AutopilotNativeRun runs the task with Autopilot's SDK inside the object, on the native engine. Tools run on the host in the run's cwd, so use it only for trusted workspaces.

import { RunRegistry } from "serverless-objects/autopilot";
import { AutopilotNativeRun } from "serverless-objects/autopilot/native";

export { RunRegistry };
export class Run extends AutopilotNativeRun {}

npm install serverless-objects autopilot-ai
sobjects dev . --engine native

• Credentials: the session reads your Autopilot config (~/.config/kimiflare/config.json). An OPENROUTER_API_KEY binding overrides its key.
• Gating: before each mutating tool, the object checks allowedTools and the tool budget, so a call that would exceed a budget never runs.
• Pausing: a tripped budget pauses the run in needs_input. resume(budgets, { message }) continues the same session.
• Restarts: a turn cut off by a restart is reconciled when the object next loads, and start() continues the same session.
• Portability: sobjects build --strict reports such an app as native-only.

#RunObject methods

#RunRegistry methods

#Event streams

fetch() on a run object serves either log from a cursor: ?stream=session (the default) or ?stream=run, with &after=N.

• With Upgrade: websocket, it sends the backlog after N, then every new event as it is committed. Sockets use the hibernation API.
• A plain GET returns the same events as NDJSON.

The object assigns seq, session_id and timestamp_ms to each Camouflage event, so the log replays in order:

curl -s "https://agents.example.com/runs/run-42/stream" > run-42.ndjson
camouflage-validate run-42.ndjson
camouflage-tui --play run-42.ndjson

The object doesn't check event_type against Camouflage's schema. Run camouflage-validate in your tests.

#What has been tested

Unit tests run the SQL against node:sqlite, and the cell executor is tested against a fake bridge. A real run on celld 0.6.2 with Hotcell 0.1.19 (container driver), autopilot-ai 1.25.1 and moonshotai/kimi-k2.6 through the Hotcell gateway went from provision to completion in about 30 seconds. In a second run, the node was stopped for about 45 seconds during a tool call; after up, the object resumed from its saved cursor and the run completed.

The examples/autopilot-runs demo shows wake after restart, event streams and reconcile over HTTP. Full details are in the source doc.