Agent command reference

You can ask a coding agent to create a devbox, run tests, or start another agent thread. The commands below also support scripts that need explicit targets and JSON results. For an interactive terminal or thread picker, start with Install and use the CLI.

Choose the correct command

Do not install or run workstation dvb inside a boxes.dev machine. It can destabilize or permanently break that environment; boxes.dev is not responsible for recovering a machine knowingly modified this way. Use the dvb-onbox commands already installed there.

From your computer, start by finding the project and machine, then create a devbox or run a command or start an agent thread. An agent already on a devbox can delegate a task without looking up a project.

For exact options supported by the installed release, use command help. Local agents can also read bundled product references without sign-in or network access:

dvb agent-docs
dvb agent-docs agent-tools
dvb agent-docs onbox-agent-tools

Agents on a devbox already have these references. If an on-box command is missing from dvb-onbox --help, wait for the machine's normal boxes.dev update; installing dvb won't add the missing capability safely.

Use dvb-onbox help on a managed machine to inspect its available agent commands. Select the image to enlarge it.

Workstation inventory and JSON

Run these commands on your computer before choosing targets for a script:

dvb projects list --json
dvb devboxes list --project <project-fingerprint> --json
dvb threads list --project <project-fingerprint> --include-archived --json

Inventory does not wake machines or mark conversations read. Use the returned project fingerprint, machine instanceId, and thread clientThreadId in later commands. Devbox inventory is complete in one response and doesn't accept --all. For threads, follow pagination.nextCursor with --cursor, or use --all when you need every matching thread.

Handle results and retries

Agent commands return versioned results:

{
  "schemaVersion": 1,
  "ok": true,
  "requestId": "request-id",
  "data": {},
  "nextActions": []
}

Failures use ok: false, a stable error code, message, and retryable flag. Follow applicable nextActions. Treat unknown versions or events as unsupported. JSONL streams can end with a failure object.

For operations requiring --idempotency-key, generate one unique key for each intended action and keep it until you know the outcome. Any unique, stable value works. With Node.js installed, one way to generate a key in a shell on your computer is:

idempotency_key="$(node -p 'require("node:crypto").randomUUID()')"

Use that value for <key> when performing that action. If a request times out or loses its response, inspect the original operation and retry with the same key and identical arguments. A new key can create another devbox, thread, or message.

Create a devbox or run a command

Create a machine without starting an agent

dvb devboxes create --project <fingerprint> --idempotency-key <key> --wait --json
dvb devboxes status --operation <operation-id> --json

Creation makes an environment without a thread. With --wait, the result contains the final operation and generated machine name/ID. Omit it for an asynchronous operation and use status. After you start its first thread, the devbox will appear in the normal desktop and mobile thread groups. New devboxes use the latest Template box snapshot or current saved Team Template version.

Run tests or another one-off command

dvb exec --project <fingerprint> --target <instance-id> --cwd project \
  --timeout 2m --json -- npm test

Exec uses literal arguments after --; use an explicit shell for pipelines. --cwd accepts project or an absolute remote path, not project/subfolder. Use --stdin for input. Results separate stdout/stderr, exit code, duration, timeout/cancellation, and truncation. A nonzero remote exit also becomes the local exit code. The command will wake a sleeping target; Ctrl+C will cancel only that command. An older devbox version can report unsupported_capability; let the devbox update before retrying.

Sleep, wake, or destroy that devbox

dvb devboxes sleep --project <fingerprint> --target <instance-id> --json
dvb devboxes wake --project <fingerprint> --target <instance-id> --json
dvb devboxes destroy --project <fingerprint> --target <instance-id> --yes --json

These operations reject Template boxes. This destroy form supports only devboxes without threads; use desktop or the interactive switchboard to destroy and archive a devbox with threads. Destruction is permanent. Commit and push code or download useful files before running it. A successful sleep or wake result reports the resulting state; another inventory read isn't required.

Workstation thread operations

Start a task

dvb threads start --project <fingerprint> --target new-devbox --agent codex \
  --prompt-file <path> --idempotency-key <key> --json

Start accepts codex or claude and targets template, new-devbox, or devbox:<instance-id>. A Team Template member project has no template target. Supply exactly one of --prompt, --prompt-file, or --stdin. The result includes the operation ID and clientThreadId for subsequent commands.

Read progress and wait for a response

dvb threads read <client-thread-id> --json
dvb threads wait --thread <client-thread-id> --turn <active-turn-id> --timeout 30m --json
dvb threads events --thread <client-thread-id> --turn <active-turn-id> --jsonl

Read returns bounded user, assistant, and notice text, without reasoning or tool activity, and does not wake a machine or mark it viewed. The default is 20 recent turns; use --turns to change the window or follow the returned cursor for older turns.

Take the <active-turn-id> from the activeTurnId field in a threads list row. Every message returned by read carries its turnId. Wait observes one exact turn. Omitting --turn selects the active turn once and returns idle if none exists. It won't follow later turns automatically. Timeout, needs-input, failure, interruption, and completion have distinct results. Ctrl+C stops observation without interrupting remote work.

Events carry resume cursors; continue with --cursor <cursor>. An exact-turn stream ends when the agent needs input or the turn ends. Without a turn or cursor, it follows new events; use --from-start to include earlier ones. Current Codex and Claude threads support transcript reads. The retired Claude CLI thread type reports unsupported_agent.

Read also accepts a permanent /thread/ URL or thr_… ID for a teammate when current sharing allows it. The URL grants no access and does not enable writes. If your access depends on a /t/ share invitation, open that link first, then use the permanent thread link in the CLI. The CLI doesn't accept /t/ links.

Send a follow-up or interrupt work

dvb threads send --thread <client-thread-id> --prompt-file <path> \
  --idempotency-key <key> --json
dvb threads interrupt --thread <client-thread-id> --turn <active-turn-id> \
  --idempotency-key <key> --json

Workstation send requires an idle thread. It returns thread_busy during active work and doesn't queue, steer, or take control from a person's Claude terminal. An indeterminate result may have reached the agent; inspect the original operation before retrying.

Interrupt requires the exact active turn ID and won't stop a newer turn that replaced it. Use desktop, mobile, or dvb agents to answer agent questions or take over a Claude terminal; these script commands don't support those actions.

Current-machine information and permissions

Run these commands inside the boxes.dev machine:

dvb-onbox box status --json
dvb-onbox threads get-title --json
dvb-onbox threads set-title --title "Review the signup flow" --json
dvb-onbox threads get-link --json
dvb-onbox threads get-link --for-commit

Box status distinguishes a Template box, devbox, and Team Template editing box. Current title/link commands take no thread selector. Titles must be nonempty and at most 120 Unicode characters. Agents should ask before replacing a title you wrote. --for-commit returns a URL only when Add thread links to commits is enabled; it does not share a private conversation.

Allow an agent to perform a disabled action

If an action you've requested is disabled, the agent can ask for its permission:

dvb-onbox permissions request --permission create-devboxes-and-threads --json

Other values are create-team-templates, update-thread-titles, move-devboxes-to-folders, create-devbox-folders, edit-devbox-lifecycle, edit-template-maintenance, destroy-devbox, read-project-threads, read-user-threads, read-shared-threads, read-team-threads, edit-template-box, edit-team-template, and edit-personal-environment. The request waits up to ten minutes for Allow or Deny. Allow changes the persistent permission for all agents on that source box until disabled; it is not a one-use grant. The last three values are different: Allow for 3 hours grants them only to the requesting thread, and they expire after 3 hours. See Let one thread edit your Template. The agent must retry the original operation after approval, keeping its original idempotency key. After Deny or expiry, the agent must continue without that operation and must not repeat the permission request in the same task.

Delegate from a devbox

An agent on a devbox can start a second Codex or Claude conversation for a specific task. These dvb-onbox commands require Create devboxes and threads on the source machine and use its project automatically.

Choose the agent and machine

dvb-onbox threads options --agent codex --json
dvb-onbox threads options --agent claude --json
dvb-onbox threads start --target current-devbox --agent claude \
  --prompt-file <path> --idempotency-key <key> --json

Use options for current model IDs, reasoning efforts, and Codex speeds before making an explicit selection. Add --model, optional supported --reasoning-effort, and Codex-only --speed standard|fast. Reasoning and speed require an explicit model. An explicit --model without --reasoning-effort uses that model's reported default effort; omit the reasoning flag for a model whose effort list is empty. An explicit Codex model without speed uses Standard. Without any of these options, the child uses the source machine's saved defaults for that agent, or the catalog default if none exist. Prompt files are limited to 32 KiB.

Choose a target based on which files the new agent needs:

A Template box can initiate delegation but cannot be its destination.

Send instructions and collect the result

dvb-onbox threads list --json
dvb-onbox threads read --thread <child-id> --turns 20 --json
dvb-onbox threads send --thread <child-id> --prompt-file <path> \
  --delivery next --idempotency-key <key> --json
dvb-onbox threads interrupt --thread <child-id> --turn <active-turn-id> \
  --idempotency-key <key> --json
dvb-onbox threads wait <child-id> --turn <turn-id> --timeout 30m --json
dvb-onbox threads result <child-id> --turn <turn-id> --json
dvb-onbox threads events <child-id> --turn <turn-id> --jsonl

These commands can reach only children created by the current source box. Choose when a follow-up should arrive with --delivery:

queue also reaches a delegated Claude first turn that is still running in its unattended native terminal. A native terminal actively controlled by a person stays out of bounds; these commands can't take control from it. Interrupt leaves queued follow-ups intact.

Read can lag live progress and shorten long messages. Use result for the complete final response of one exact turn. Take the child's active turn ID from threads list, or a message's turnId from threads read, and use it with wait, result, and events. A child that is still starting can have no active turn yet. Keep observing until the turn starts or startup fails; an idle observation during startup does not establish that the task finished. Starting a child does not deliver its result to an idle parent automatically: keep the coordinating thread active, wait for each required turn, and review its complete result before finishing.

Read other threads

Enable Read other threads in Agent permissions to let agents read beyond their delegated children. The permission applies to all agents on the source box and is off by default.

dvb-onbox threads access --json
dvb-onbox threads list --scope project --json
dvb-onbox threads projects --scope user --json
dvb-onbox threads list --scope user --project <project-id> --json
dvb-onbox threads list --scope shared --json
dvb-onbox threads list --scope team --owner <owner-id> --json
dvb-onbox threads read --scope shared --thread <thread-id-or-share-link> --json

project selects your current project; user selects all your projects. shared includes teammate threads whose share link you previously opened and which still grant access, even if you removed them from Shared with me. It does not discover unopened links or count pins as shares. An agent given an exact invitation link can read it without adding it to your shared list.

team selects teammates' threads, excluding your own, under current team settings. Shared links only disables general discovery; Thread titles permits metadata; All threads permits conversations. Existing shares can also grant conversation access under Thread titles. Private and revoked threads remain unavailable. access explains the current limits.

Use returned IDs for --project and --owner filters. Project filters apply to user, shared, and team scopes; owner filters apply to shared and team. Each page examines up to 50 candidate records, so filtering may produce fewer results or an empty page. Pass pagination.nextCursor as --cursor for more results until pagination.complete is true. Scoped commands do not accept --all. Project pages may repeat projects; deduplicate by project ID. Thread listings exclude archived threads unless you add --include-archived.

Reads use stored visible conversation messages, may lag ongoing work, and may shorten long messages. They do not expose full tool logs, wake boxes, mark threads read, or grant control. Use the returned transcript cursor to read older messages. Commands without a scope keep their existing delegated-child behavior.

Message other agents

Enable Message other agents in Agent permissions to let agents on a machine send short messages to your other agents in the same project and receive their messages. The permission is off by default, and both machines need it.

dvb-onbox threads message --to <thread-id> \
  --message "The endpoint now returns 422 for invalid widgets." --json

A message will start an idle agent and wake its devbox if it's asleep. The recipient sees it as a message from another agent, with the sender's thread and the command for replying; it can't answer a permission prompt for you. In the recipient's thread, the message is labeled with the kind of agent that sent it, such as From a Codex agent or From another Claude agent. Select View thread to open the sender's thread. In the desktop app, hover over it to see that thread's title and which machine it runs on.

Claude also has a built-in messaging tool that reaches other Claude sessions on the same machine. Messages sent that way are labeled From a Claude agent on this box and have no thread link. boxes.dev guides agents to use dvb-onbox threads message instead, since Claude's tool can't reach Codex or other machines and may hold a message until the recipient's user approves it. delivered means the recipient accepted the message, not that it has read or answered it. Replies arrive later as messages in the sender's thread. If the result is operation_indeterminate, don't send the message again, because it may already have arrived. Messages are limited to 4 KiB, and a Claude agent in a busy or user-controlled terminal can't receive them.

Destroy and archive the agent's devbox

An agent on an ordinary devbox can run:

dvb-onbox box destroy --json

First enable Destroy and archive this devbox under Agent permissions in the thread header, or approve the agent's destroy-devbox permission request. This permission is off by default and applies only to that devbox. The command cannot target a Template box or another devbox.

Destruction permanently deletes files. Preserve useful work outside the devbox first. The command accepts the request so the agent can send its final reply. It always waits for every agent and queued message to finish; no --when-idle flag is needed. Then boxes.dev archives the thread history, runs teardown, and deletes the machine.

Submitting new work before destruction starts cancels the request. Turning off the permission also cancels a pending request, and a request expires if the devbox does not become idle within 30 minutes. Once destruction starts, the devbox cannot accept new messages.

To cancel while the request is still pending, an agent on that devbox can run:

dvb-onbox box cancel-destroy --json

Cancellation does not require the destroy permission. If nothing is pending, the command succeeds without changing anything. Once destruction has started, it is too late to cancel.

Configure lifecycle and maintenance

Use these commands to change what runs when devboxes start or are destroyed, or to keep a Template box up to date. For the settings themselves, see Startup, teardown, and maintenance.

On your computer, use dvb projects lifecycle get|set --project <fingerprint> or dvb projects maintenance get|apply --project <fingerprint>. Inside the machine, use dvb-onbox project lifecycle get|set and dvb-onbox project maintenance get|apply, without a project flag.

On-box lifecycle commands require the project's personal Template box and Edit devbox lifecycle. On-box maintenance requires Edit template maintenance on a personal Template box, or an authorized Team Template editing session. An ordinary devbox can't change these settings.

Read settings first and pass --if-revision <revision> on writes.

• For lifecycle, pass local script files with --startup-script-file and --teardown-script-file. Each has an independent 1–120 second timeout; explicit clear flags remove scripts.
• For maintenance, pass --script-file, --timeout-seconds (1–480), and a complete --watches-file. Version-1 watches use . or direct-child repository paths and exact files/directories, not globs. Omitting editable watches requires --confirm-watch-removals.

Maintenance writes preserve the repeating schedule. New, changed, or re-enabled watches get a fresh baseline; unchanged watches keep theirs. Saving these settings won't start maintenance immediately.

After a revision conflict, read again and reconcile. Member projects support their own lifecycle defaults but have no personal Template maintenance. Inside a Team Template editor, on-box maintenance edits that template's policy; its repeating schedule stays editable under Template environment → Maintenance in the desktop app. Because on-box lifecycle commands require an ordinary personal Template box, configure a Team Template's lifecycle defaults in its editor under When a new devbox is created, including its When a devbox is destroyed section.

Organize devboxes and share ports

Move a devbox into a folder

dvb-onbox devboxes folders list --json
dvb-onbox devboxes folders get --devbox current --json
dvb-onbox devboxes folders create --name "Review" --when-to-use-file <path> \
  --idempotency-key <key> --json
dvb-onbox devboxes folders move --devbox current --folder <folder-id> \
  --expected-revision <revision> --idempotency-key <key> --json

Use an existing suitable folder first. --clear removes membership. Moves can target the current devbox or one directly created by the source thread, not arbitrary siblings. Read again after folder_revision_conflict; agents cannot edit, reorder, or delete folders through these commands.

Give someone a public app link

dvb-onbox ports share --port <port>, ports list-public, and ports stop-sharing --port <port> act only on the current machine's detected, eligible HTTP ports. Sharing makes the app accessible without sign-in. Share only apps intended for public access, never databases, credential tools, or private administration pages. Repeated share returns its existing active URL. Run stop-sharing when finished; stopping the app doesn't revoke the URL. For claims, subscriptions, routing rules, browser affinity, and the local app API, see Project URLs.

Setup, snapshots, and Team Templates

Finish project setup or save a snapshot

dvb-onbox setup status and setup complete support the managed setup thread. Completion requires finished validation and the requested nonempty .devbox/setup.todo summary; acceptance starts final cleanup/snapshot work. dvb-onbox snapshot works only on the Template box after the environment is ready and you have requested a new source for future devboxes. It can pause and resume the requesting agent during capture; new devboxes do not continue its process.

Change the Template box from a devbox

After you allow edit-template-box for a devbox thread, its agent can change the project's Template box and snapshot it:

dvb-onbox template-box exec --cwd /home/boxes/example -- direnv allow
dvb-onbox template-box run --script-file <path> --idempotency-key <key> --json
dvb-onbox template-box snapshot --json

These commands will wake a sleeping Template box. exec has the same limits as Team Template exec. run sends a script file of up to 3 MiB, runs for up to 20 minutes, and returns up to 4 MiB per output stream. snapshot waits for the new snapshot that future devboxes will use.

Change the files Team Template members must provide

Admins can manage member requirements in the Team Template's editing machine:

dvb-onbox team-template member-files list --json
dvb-onbox team-template member-files add --root home --path .config/example.json \
  --instructions "Upload your personal configuration file." --json
dvb-onbox team-template member-files update --file <id> --if-revision <revision> \
  --instructions "Upload your current personal configuration." --json
dvb-onbox team-template member-files remove --file <id> --if-revision <revision> --json

From a personal Template box with access to that editing session, add --template <team-template-id> to select the associated Team Template.

Requirements support Home/Project relative destinations and optional display order. List first for IDs/revisions. A changed requirement takes effect without saving a filesystem version, and a missing required file can block a member's next startup. A destination change requires member approval; instructions-only changes do not. These commands never read or upload members' file contents.

Change environment variables

An agent can list, set, and remove the current project's managed environment variables. List output never includes values:

dvb-onbox env list --json
dvb-onbox env set --file .env.local --name API_BASE_URL --value https://api.example.test
printf %s "$TOKEN" | dvb-onbox env set --file .env.local --name API_TOKEN --value-stdin
dvb-onbox env remove --file .env.local --name API_TOKEN

In a project with its own Template box, these commands change the project's variables; an agent on a devbox needs edit-template-box for its thread. In a Team Template project, they change your own variables and your values for the team's Member variables; the agent needs edit-personal-environment, or edit-team-template if you're a team admin.

Team admins can define the Team Template's variables with dvb-onbox team-template env, from its editing machine or from a member devbox with edit-team-template:

dvb-onbox team-template env set --file sandbox/.env.local --name LOG_LEVEL --value debug
dvb-onbox team-template env set --file sandbox/.env.local --name OPENAI_API_KEY \
  --member --instructions "Create a key at platform.openai.com."

--member asks each member for their own value, required unless you add --optional. Changes reach existing machines within about a minute, without a new Team Template version.

Create a Team Template with an agent

If you're a team admin, an agent on your personal Template box can create a Team Template from clean GitHub clones. Your GitHub connection and the GitHub App installation must cover each repository with write access.

1. Ask the agent to run dvb-onbox team-template create inspect. This reports repositories, access, available devbox sizes, comparable settings, and the required permission.
2. Review the agent's version-1 JSON spec. It identifies source and remote commits, repository destinations, configuration, cleanup, and member policy. Keep source keys from inspect and exclude personal credentials and values. Review the selected size and any higher billing rate; the size cannot change after creation.
3. Have the agent run dvb-onbox team-template create check --spec-file <path>. It will validate the spec and return a checked hash.
4. After you confirm the plan, the agent can run dvb-onbox team-template create with --spec-file, --checked-hash, and a stable --idempotency-key.

Creation adds the Team Template definition. Next, prepare its editing machine with a separate key; edit-box create will also connect the current thread and its Template box to that editing session:

dvb-onbox team-template edit-box create --template <team-template-id> \
  --idempotency-key <key> --json
dvb-onbox team-template edit-box status --edit-box <edit-box-id> --json

Use the returned editBox.id to run a setup script or save the result:

dvb-onbox team-template edit-box run --edit-box <edit-box-id> \
  --script-file <path> --idempotency-key <key> --json
dvb-onbox team-template edit-box save --edit-box <edit-box-id> \
  --idempotency-key <key> --json

Use a different key for each action. run accepts up to 3 MiB of script input, a timeout up to 20 minutes, and 4 MiB per output stream. To abandon an unsaved draft created this way, use dvb-onbox team-template edit-box discard with --edit-box and its own --idempotency-key.

Review settings with dvb-onbox team-template show --template <team-template-id>. To change them, check the revised whole spec and apply it with dvb-onbox team-template configure, passing --template, --spec-file, --checked-hash, and a new --idempotency-key. The cleanup script stays fixed at its creation value. If you enabled member-project creation, it will become available only after an eligible first save. The installed onbox-agent-tools reference contains the complete spec and maintenance-policy fields.

Work on an existing Team Template editing machine

In the desktop app, open the Team Template and choose Take control, then start Codex or Claude with the editor's new-thread control. The thread runs directly on the editing machine, so ordinary shell commands read and change the current checkout, and dvb-onbox box status --json reports team_template_edit_box.

An ordinary project's Template box can also reach an editing checkout when it has an active editing association. In the agent-led creation flow above, team-template edit-box create establishes that association; the commands below use it but do not create it. On this path, ordinary shell commands still operate on the source project's files — only these commands act on the Team Template:

dvb-onbox team-template list --json
dvb-onbox team-template exec --template <id> -- git status --short
dvb-onbox team-template push --template <id> \
  --source <absolute-path> --destination <absolute-path>

The association covers every process on the associated source box. It ends when the template is saved or discarded, the agent session is stopped, or the editing session otherwise closes; the source thread then stays in its project but can no longer list or reach that checkout. For an existing Team Template without an association, start a thread in its editor instead.

Exec is limited to 120 seconds and 1 MiB per output stream, without stdin. Push accepts one regular file up to 100 MiB, with both absolute paths below /home/boxes; existing files require --overwrite. After an uncertain command result, inspect the destination before repeating work.

Edit a Team Template from a member devbox

If you're a team admin working in a Team Template project, you can let an agent on your devbox change the Team Template. After you allow edit-team-template for its thread, the agent will connect to the Team Template's editing session, starting one if needed, and use the commands above:

dvb-onbox team-template edit-box open --idempotency-key <key> --json
dvb-onbox team-template exec --template <id> -- git status --short
dvb-onbox team-template edit-box save --edit-box <edit-box-id> \
  --idempotency-key <key> --json

open fails while another admin is editing the Team Template. Saving will publish a new version for your team and end the agent's access to that editing session; access also ends when the 3-hour grant expires.

Custom command policies

To control which commands Codex or Claude may run, read the README on an updated machine in /etc/boxes/agents/codex/ or /etc/boxes/agents/claude/. These directories contain inactive starter files and examples. Untouched files retain the normal full-access behavior; updates preserve your edits.

Codex uses native config.toml, hooks.json, and rules files. Claude uses native settings.json. Both support synchronous PreToolUse and PostToolUse command hooks; supported Codex versions also accept PermissionRequest hooks. Authentication, agent homes, sandbox settings, and required boxes.dev hooks are managed separately and are not customization points here.

Codex approvals

For Codex to ask about commands outside an allowlist, mark the project untrusted and leave approval_policy unset. on-request by itself does not ask about every unmatched command. Untrusted projects skip repository-local Codex configuration, so place this policy in the machine directory. Personal rules and remembered approvals still participate. This mode also asks about ordinary patch edits; the machine README documents a PermissionRequest hook for approving selected edit paths.

Claude approvals

For Claude manual approvals, set permissions.defaultMode to default. An explicit machine mode applies when a process starts, including a resumed thread, and can override a previously chosen thread mode.

Activate and recover policy changes

Finish active work, then reboot the devbox to activate configuration across both agents. Reboot stops workloads and preserves files. Pause or Reset alone does not guarantee activation. For a Team Template, save and close, then take control again.

Repair invalid settings through Terminal and retry the affected agent. Remove overrides and reboot to return to the ordinary configuration; Claude needs an explicit bypassPermissions mode if you want to replace a saved manual mode with approval bypass. Script edits take effect on their next execution.

A hook error or timeout is not guaranteed to deny an action. Use the native agent's explicit deny response for a refusal. Save a Team Template version to distribute policies to future member devboxes; existing machines need their own update. Read the machine README before relying on a policy on an older machine.