Every boxd tool is a method of the boxd.machines.tools RPC, so a script calls it with no model, as a session and the
agent it names. A script's grant is a rule in config: only a resolved allow runs, an ask is refused because no one
can answer it, and a deny runs nothing.
The session is created for the script with an agent (opencode api post /api/session -d '{"title":"…","agent":"build","location":{"directory":"/path/to/project"}}', with data.id kept). The body is
{"input":{"sessionID":"<id>","input":{…}}}; both keys are required, and no other key is allowed. Give the project as the session's location: a session made without one belongs to the service's default location, where the project's agents may not exist, and each call then fails Agent not found.
opencode api post /api/rpc/boxd.machines.tools/boxd_job -H "x-opencode-directory:$PWD" -d '{"input":{"sessionID":"<id>","input":{"workId":"review-api"}}}'describe takes no input, or a session, and lists every method with its class and — given a session — the permission the
call would get:
opencode api post /api/rpc/boxd.machines.tools/describe -H "x-opencode-directory:$PWD" -d '{"input":{"sessionID":"<id>"}}'A plugin-owned method's result is the method's output object, as describe gives its schema: for boxd, the JSON the
tool itself returns, with a state on every answer. text is what the model path would show.
boxd_status answers for the whole fleet in one call: counts by phase, each region's machine headroom, the works that
need a decision (attention, worst first, at most limit, with more for the rest), repeated causes folded into
groups, and the cost and cleanup blocks. It never wakes a machine and never reads an idle guest. Its cursor,
passed back as since, answers only the works that changed since; a cursor older than the kept event log answers the
full view with cursorExpired: true, so a gap is never mistaken for "nothing changed".
opencode api post /api/rpc/boxd.machines.tools/boxd_status -H "x-opencode-directory:$PWD" \
-d '{"input":{"sessionID":"<id>","input":{"since":1842,"limit":50}}}'A script's own session gets no notices: notices go to the coordinator that last drove a work from the model path. A
script names one with notify on boxd_submit (a session id, or false to clear it), and a submit without notify
leaves an earlier subscription in place.
boxd_ensure, boxd_submit, boxd_job, boxd_harvest, boxd_sleep, boxd_resume and boxd_drop take
works: [...], 1 to 300 items, and answer { state, counts, results } with one result per item in input order. state
is done, partial, failed or cancelled. A list call has a bound: an item still creating or starting when it
runs out answers that state, and an item that never started answers cancelled with started: false; both carry the
same next, which only waits and converges. Use one list call rather than many single calls at once.
opencode api post /api/rpc/boxd.machines.tools/boxd_ensure -H "x-opencode-directory:$PWD" \
-d '{"input":{"sessionID":"<id>","input":{"works":[{"workId":"api-a","repo":"https://github.com/o/a"},{"workId":"api-b","repo":"https://github.com/o/b"}]}}}'
opencode api post /api/rpc/boxd.machines.tools/boxd_job -H "x-opencode-directory:$PWD" \
-d '{"input":{"sessionID":"<id>","input":{"works":["api-a","api-b"]}}}'boxd_sleep, boxd_harvest and boxd_drop also take select instead of works, resolved against a fresh listing and
the ledger; dryRun: true lists the matches and changes nothing:
opencode api post /api/rpc/boxd.machines.tools/boxd_sleep -H "x-opencode-directory:$PWD" \
-d '{"input":{"sessionID":"<id>","input":{"select":"finished","dryRun":true}}}'| Method | Class | Runs when |
|---|---|---|
boxd_status |
read | allowed |
boxd_job |
read | allowed |
boxd_read |
read | allowed |
boxd_ensure |
write | the agent or session allows boxd_ensure |
boxd_submit |
write | the agent or session allows boxd_submit |
boxd_harvest |
export | the agent or session allows boxd_harvest (it writes this laptop) |
boxd_sleep |
write | the agent or session allows boxd_sleep |
boxd_resume |
write | the agent or session allows boxd_resume |
boxd_reassign |
write | the agent or session allows boxd_reassign |
boxd_golden |
write | the agent or session allows boxd_golden |
boxd_exec |
write | the agent or session allows boxd_exec |
boxd_drop |
destructive | the agent or session allows boxd_drop |
events_list |
read | allowed (its action is boxd_events_list) |
probe |
read | allowed (its action is boxd_probe) |
A class is the worst thing the method does; it never decides whether a call runs. The rules do.
events_list and probe are the boxd.works source's methods (source contract, package.json's sources), for a
collector such as Memory's. They read this laptop's ledger only: no boxd call, no machine woken, no lock taken.
opencode api post /api/rpc/boxd.machines.tools/probe -H "x-opencode-directory:$PWD" -d '{"input":{"sessionID":"<id>","input":{}}}'
opencode api post /api/rpc/boxd.machines.tools/events_list -H "x-opencode-directory:$PWD" \
-d '{"input":{"sessionID":"<id>","input":{"since":"2026-11-01T00:00:00Z","limit":100}}}'- The account and owner. The account is this computer's host name, as a slug, and the owner its OS user,
{ "id": "os-user:<user>@<computer>", "label": "<user> on <computer>" }. A read that names another account isACCOUNT_MISMATCH. - An event is one line of the ledger's
events.jsonl:external_id<work id>:<seq>,kindx-boxd/work,occurred_atthe change's time,threadboxd-work:<work id>, atitlein the plugin's own words, such asWork fix-auth: its run failed (RUN_FAILED), andlabelsphase:<phase>,outcome:<outcome>,code:<code>,asleep-by:<who>andneeds:<form or permission>where they apply. It has notext,actorsorurl. An event whose title holds a secret (a work id shaped like a key) is listed inrefused[]with reasonsecret, never sent. - The cursor is the log's sequence number, bound to the plugin, the source and the account. The ledger keeps at
least the last 5 MiB of events: a cursor older than the oldest kept event, or one from another ledger, answers the
oldest kept events with
gap: { "reason": "expired", "since": <the time the cursor covered> }, once, and a first read whosesinceis older than the oldest kept event answers the same. Without a cursor orsince, a read starts 24 hours ago. - While the v0 import runs, or after it failed, there is no ledger to read:
events_listanswersUNAVAILABLEwith the import's progress, and never starts the import itself. A ledger that cannot be read isUNAVAILABLEtoo. - Refusals carry the source contract's codes:
INPUT_INVALID,SOURCE_UNKNOWN(any source butworks),ACCOUNT_MISMATCH,CURSOR_INVALIDandUNAVAILABLE, each asCODE: what happened. Next step: ….
boxd_submit takes files to copy data to the machine, and boxd_harvest takes files to copy results back. A path is
relative to the work tree; a laptop path must be inside the project or a folder in allowedRoots, and a symlink is never
followed. The caps are 8 MiB a file and 32 MiB a call, and the ledger records each file's name, size and sha256, never
its content.
A worked example: summarise the bookmarks a previous step saved, and bring the summary back.
# 1. One work, with the laptop folder it belongs to. It answers when the guest's OpenCode is up.
opencode api post /api/rpc/boxd.machines.tools/boxd_ensure -H "x-opencode-directory:$PWD" \
-d '{"input":{"sessionID":"<id>","input":{"workId":"bookmarks"}}}'
# 2. The data in, then the prompt. The model reads data/bookmarks.json, not a pasted list.
opencode api post /api/rpc/boxd.machines.tools/boxd_submit -H "x-opencode-directory:$PWD" \
-d '{"input":{"sessionID":"<id>","input":{"workId":"bookmarks","text":"Read data/bookmarks.json and write SUMMARY.md: one line per site, grouped by topic.","files":[{"from":"bookmarks.json","to":"data/bookmarks.json"}]}}}'
# 3. Later: the outcome, then the transcript and the summary, then the machine down.
opencode api post /api/rpc/boxd.machines.tools/boxd_job -H "x-opencode-directory:$PWD" \
-d '{"input":{"sessionID":"<id>","input":{"workId":"bookmarks"}}}'
opencode api post /api/rpc/boxd.machines.tools/boxd_harvest -H "x-opencode-directory:$PWD" \
-d '{"input":{"sessionID":"<id>","input":{"workId":"bookmarks","files":["SUMMARY.md"]}}}'
opencode api post /api/rpc/boxd.machines.tools/boxd_drop -H "x-opencode-directory:$PWD" \
-d '{"input":{"sessionID":"<id>","input":{"workId":"bookmarks"}}}'boxd_job answers state: "idle" with outcome: "completed" when the model finished. The harvest makes the work
saved: "fresh", and the drop succeeds because SUMMARY.md came back at the digest the guest still has; a file that
was never harvested keeps the refusal (UNTRACKED).
Two more reads help a script without a harvest:
opencode api post /api/rpc/boxd.machines.tools/boxd_read -H "x-opencode-directory:$PWD" \
-d '{"input":{"sessionID":"<id>","input":{"workId":"bookmarks","path":"SUMMARY.md"}}}'
opencode api post /api/rpc/boxd.machines.tools/boxd_exec -H "x-opencode-directory:$PWD" \
-d '{"input":{"sessionID":"<id>","input":{"workId":"bookmarks","command":["git","status","--short"],"timeout":30}}}'boxd_exec is a change, because a command can do anything; each argument reaches the remote shell exactly as given.
When the work's machine runs out of room, boxd_reassign moves an unstarted work's machine to a new id, and
boxd_golden builds or prunes the golden images:
opencode api post /api/rpc/boxd.machines.tools/boxd_reassign -H "x-opencode-directory:$PWD" \
-d '{"input":{"sessionID":"<id>","input":{"from":"spare-1","to":"bookmarks-2"}}}'
opencode api post /api/rpc/boxd.machines.tools/boxd_golden -H "x-opencode-directory:$PWD" \
-d '{"input":{"sessionID":"<id>","input":{"region":"nyc","size":"4x16"}}}'If the host asks for permission to touch a folder outside the project, allow it with the external_directory rule as
well as the path rule:
A refusal that names permission.rejected: external_directory is fixed by that rule, and by naming the folder in the
plugin's allowedRoots option.
To let one agent run a script that harvests, give that agent its own rule:
{ "agents": { "harvester": { "permissions": [{ "action": "boxd_harvest", "resource": "*", "effect": "allow" }] } } }Every tool is allowed by default (the plugin's access option is "all"), and a script gets the same default: the
tools RPC resolves a rule before dispatch, and the default allow is that rule, so a script can call every method. To
restrict a script, set access to "ask-changes" (an ask is refused, because no one can answer it) or
"read-only", or give the script's agent its own deny rule — the script's grant is a rule in config.
Run the command in the project whose agent you mean, and send the call to that location explicitly:
opencode api post /api/rpc/<id>/<method> -H "x-opencode-directory:$PWD" -d '{…}'Without it the call goes to the service's default location and fails rpc.unavailable if the plugin is not loaded
there. The HTTP equivalents are the location[directory] query parameter and the same header. describe reports the
location that answered and a locationHint.
A location unloads after OpenCode's idle timeout. If a scheduled script gets rpc.unavailable from a location that was
loaded before, send the call again once: the request loads the location. Jobs keeps its own location loaded.
A call the RPC refuses before the method runs is the RPC error failed, with data: { code, next }:
| Code | When | What to do |
|---|---|---|
PERMISSION_DENIED |
the rule resolves to ask, or a deny hides the method | add an allow rule for the action to the session's agent or to the session |
SESSION_UNKNOWN |
OpenCode does not know the session in this location | create the session in the location you mean, and pass its id |
SESSION_AGENT_REQUIRED |
the session names no agent | create a session that names an agent |
TOOL_UNAVAILABLE |
OpenCode does not list the method's tool now | call describe to see the methods there are |
A method that ran and refused answers with its output, not an RPC error, in the same shape as a success: { "state": "<state>", "error": "<code>", "message": "<what happened>", "next": "<the one next call>" }, with workId, machine
and region when the call named a valid work, and the facts its code carries: field (NAME_INVALID), paths,
count and kind (UNTRACKED), limit per region (MACHINE_LIMIT), progress (LEDGER_IMPORTING), uncertain
(CANCELLED), and today, daily and currency (BUDGET_REACHED). state is refused, failed, unreachable,
busy, starting, gone, asleep or cancelled, so a loop reads state on every answer. The codes a script meets
most:
| Code | When | What to do |
|---|---|---|
LEDGER_IMPORTING |
the import of earlier works is not complete yet | the same call again in a few seconds |
NOT_OURS |
no open work has that id, or its name now points at another machine | boxd_ensure for an unknown id; otherwise look at the machines the message names |
MACHINE_LIMIT |
no region has room | the other region when it has room, or free machines with boxd_drop or boxd_reassign |
SESSION_BUSY |
the session is running and the call needs it idle | wait for the notice or boxd_status, or mode: "interrupt" |
NOT_SAVED |
drop without a fresh harvest, or the guest moved on since it | boxd_harvest, then drop again |
RUN_FAILED, GUEST_AUTH_FAILED |
the session's last run failed | read lastText; fix the credential for an auth failure; then boxd_submit again |
BUDGET_REACHED |
the daily budget is reached with action: "refuse" |
sleep and drop finished works, or raise the budget |
Every other code the plugin raises is in docs/configuration.md, with its one next step.
Known limit: a saved "Always allow" answer from an earlier session is not part of the agent and session rules, so it does not authorize an ad hoc script. A script's grant is a rule in config.
{ "permissions": [ { "action": "external_directory", "resource": "/srv/work/*", "effect": "allow" }, { "action": "read", "resource": "/srv/work/**", "effect": "allow" }, { "action": "edit", "resource": "/srv/work/**", "effect": "allow" } ] }