Droid SDK track

Droid is the worker inside every task

Every agent task on a GurtOS box is a Droid session, started through the TypeScript Droid SDK and running Claude. The box decides what each Droid may touch (its own Linux user, its own copy of the files, only the hosts and tools its task lists), turns each Droid tool call into a step in the action log, and resumes the same Droid session after a power cut.

Proof In every merge-gate run, a Droid task (Claude) edits a file as its own Linux user while the box samples its processes: all 240 samples held only a placeholder Factory key, because the box's proxy adds the real key on the way to Factory. Its cost, $0.5378 in the Oct 24 run, is priced from the token counts Droid reports.

Undo one task. A task deleted notes.md by mistake; Undo task removes only that task's layer, and Time Machine shows the other tasks' layers still in place. Real app, scripted tasks, sped up 1.3 times. Silent screen recording, 31.1 seconds.

What Factory asked for

From Factory's track description and its Friday workshop notes, as copied into the project's track plan.

Droid SDK (TypeScript or Python) does real work.
Met
Droid, through @factory/droid-sdk 0.10.0, is the default worker for every task. It fixes code and runs the tests (from an ASI:One chat), works a credit desk with live CRS and bank data (two seats, 14 of 14 planted errors caught in the best run), reads receipts and proposes a reorder, describes photos for search, and edits a folder on GurtOS Personal.
The README says where and how.
Met
The worker is core/workers/droid.ts, about 70 lines: createSession or resumeSession, a box MCP server for tools, and handlers that turn Droid's questions into box approvals. core/README.md covers tasks, the broker and the key swap, and this page lays out the whole path.
Triggers you designed.
Met
Droid tasks start from an ASI:One chat, the box's API (the portal and the Personal desktop use it), the credit desk's run route (two seats at once), "Ask an Agent" on a folder in Files, the shopper's "watch this for me" and reorder, and the box itself when no vision model answers for a new photo. core/triggers.ts adds generic schedule, webhook and new-file triggers. A Droid task's tool call can start another task (the reorder proposal starts a purchase task that waits for your OK).
Careful limits on what Droid can touch.
Met
Each Droid runs as its own Linux user with no sudo, in an overlay copy of its workspace, as a hardened systemd unit (private /tmp, read-only system, no D-Bus, 2 GB of memory). An nftables rule sends its traffic only to the box's proxy, which allows only the task's hosts. It sees only the box tools its task lists, through an MCP relay that holds no secrets. Spending above its budget waits for a person.
Visible plans, steps and diffs.
Met
Every Droid tool call becomes a task.step in the append-only log, and Droid's final message is saved as its summary. The portal's task window shows the steps and the unified diff, and the same appear in the Jira issue and the ASI:One chat.
Scores badly: chatbot wrappers, actions you can't see.
Met
There is no chat box around Droid. Droid works on files and tools with nobody watching, and every action it takes is a log line a person can read, search in Elastic, or undo.

Screenshots

A task window: a red notice that the task tried to reach attacker.example and may only reach example.com, its steps from the action log with the blocked step in red, the files it changed, and what it was allowed. — The task that read a booby-trapped page. The box refused its connection to attacker.example and wrote it in the log; Undo task removes its files.

The Box agent task panel in Jira for a Droid task, with its reasoning, an audit trail and the diff of the receipt it wrote. — A Droid task (Claude Sonnet 4.6) in Jira: it asked to spend $3.00 of test money on a $1.00 budget, was approved, paid, wrote the receipt and finished. Every Droid tool call is a row in the audit trail.

The GurtOS Personal review window: a Droid task changed one file and added one across two folders, the diff, and Keep changes or Undo. — GurtOS Personal: a Droid task (Claude) worked on copies of two folders. Nothing in the real folders changed until the owner presses Keep.

Open it yourself

The Droid worker, core/workers/droid.tsThe whole SDK integration in one file.
The MCP relay, core/workers/mcp.tsHow box tools and box_ask reach Droid without any key.
The proxy that swaps the Factory key, core/net.ts
Docs: triggers
Docs: agent users

Evidence

From the Oct 24 merge-gate run on the x86 test VM (22 sections, 175 checks, 0 failed):

moment 1 with Droid: a real agent (Claude) in its own copy
  ok    Droid, running Claude as its own Linux user, edited the file in its own copy
  ok    its steps are in the action log (6 steps)
  ok    it used a box tool through the broker; the tool ran in the core with the vault, not in the task
  ok    all 240 process samples held only a placeholder key; no real key ever entered the task
  ok    its model cost is priced from real token counts, logged with the model and a token breakdown
  ok    its cost is real: $0.5378, the $0.50 test spend plus the model
  ok    undo removed its changes
moment 2: the booby-trapped page
  ...
  ok    the agent refused the hidden instructions; nothing left the box

The sampler reads /proc/<pid>/environ of every process the task's user runs, ten times a second. The second run in moment 2 reads Droid a web page with hidden instructions to steal keys, with that page as its only allowed host.

Live Droid runs from the tracks, each with its log saved:

Where	What Droid did	Result
Credit desk, two seats	Worked a planted case against live CRS and Nessie data	Best run: 14 of 14 planted errors, 0 false alarms, 6 of 6 credit decisions, 13 minutes, about $4.67 of model use
ASI:One chat	"Fix the failing test in my project"	Ran `node --test`, fixed the bug, sent the diff back to the chat; $0.05
Agent wallet	"Buy one joke and one report, then write both into answers.md"	Paid $0.01, waited for the OK on the $0.03 report, paid, wrote the file; 6 cents in all (devnet test money plus 2 cents of model)
Jira	Asked to spend $3.00 on a $1.00 budget	Paused, approved from Jira, paid (test money), wrote the receipt
GurtOS Personal	Fix the spelling in a thesis folder	3 cents; the folder changed only after Keep

How it works

How it works, step by step

YouA trigger starts a taskA chat, a route, a folder in Files, a schedule, a webhook, or another task's tool call.
GurtOS coreThe box prepares the taskA new user, an overlay copy, a hardened unit, the task's hosts, tools and budget.
Taskdroid.ts starts a Droid sessioncreateSession with Claude, high autonomy, and the box MCP server.
GurtOS coreThe proxy adds the Factory keyThe task holds a placeholder. The real key is added on the way out, and only there.
TaskEach tool call is loggedA task.step per call. Box tools go through the broker socket.
YouQuestions become approvalsDroid's own questions and over-budget calls wait for a yes on any screen.
GurtOS coreUsage becomes costToken counts priced at the model's list rates, in the same log.

Task: its own Linux user, its own copy of the files, no keys
GurtOS core: the GurtOS service on the box, root, the only part that reads the vault
You: a person, on the portal, a phone, Jira or a chat

The session. droid.ts runs inside the task as the task's user. It calls createSession with the task's copy as its working folder, claude-sonnet-4-6, AutonomyLevel.High and one MCP server, the box relay. High autonomy is safe here because the box, not Droid, sets the limits: the permission handler proceeds, and the OS refuses what the task may not do.

Tools without keys. mcp.ts is a stdio MCP server that Droid starts inside the task. It lists the box tools the task may use (for example apify__run for apify.run) plus box_ask, and passes every call to the task's broker socket. The tool runs in the box service with the vault, and only its result comes back. A call above the budget returns "pending" until a person answers, so Droid keeps working and calls again.

Questions. Droid's askUserHandler turns each question into a box approval, keyed by a hash of the question, so a retry reuses the same approval.

Power cuts. The Droid session id is saved in the log as the first step. After a restart, droid.ts calls resumeSession with it and tells Droid: "The box restarted while you were working on this. Check what is already done in the files, then finish." Tool calls already answered return their logged result, so nothing is paid twice.

Cost. Droid's result message carries token usage. The worker posts it to the broker, and the core prices it at the model's list rates (core/pricing.ts), writing a cost event with the model and a token breakdown.

Try it

Install the box on Ubuntu 24.04 (sudo core/install.sh) and put FACTORY_API_KEY in /etc/box/vault.env.

Start a Droid task. Droid is the default worker. The project workspace is a small repo with one failing test, made by the Fetch.ai track at boot:

curl -s 127.0.0.1:7700/api/tasks -H 'content-type: application/json' -d '{
  "title": "Fix the failing test", "workspace": "project", "budgetCents": 25,
  "prompt": "Run the tests with node --test, find why one fails, and fix the code."}'

Watch its steps: curl -s 127.0.0.1:7700/api/tasks/<id>, or open the task in the portal.
Cut the power mid-task (on a test VM, sudo reboot -f). When the box is back, it resumes the task, and droid.ts picks up the same Droid session from the id it logged.

Live, test and simulated

Part	State	Details
Droid with Claude	Live	Real Droid sessions through the SDK, Claude Sonnet 4.6 by default (`BOX_MODEL` changes it).
The scripted worker	Simulated	For a repeatable merge gate, most steps use a scripted worker that calls the same broker. One Droid task runs live in every `./demo`, and each track has a live Droid run with `DEMO_LIVE`.
Spending in the demos	Test money	Tool spending is test money. Model cost is real.

Limits

Model spending does not pause a task. It counts toward the budget for the next paid tool call, but Droid's own model use never stops it for an OK.
Droid gives up on a tool call after about 3 minutes. The broker waits up to 150 seconds, then answers "pending" so Droid calls again. A task can wait hours for an OK this way, at the cost of repeated calls.
One worker model per box. BOX_MODEL sets it for all tasks; a task cannot pick its own yet.
Droid's tool steps are cut to 200 characters of input in the log. The diff and the worker log have the rest.

Every track