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. That update restarts the local boxes.dev service for a few seconds, and dvb-onbox commands wait for it to come back. If a command reports that the local boxes.dev service isn't available, run it again in a minute.

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.

If creation fails, --wait exits with status 1 and shows the failure details. The JSON result keeps ok: true because the operation was retrieved; check data.operation.status to see whether creation succeeded. A status lookup of a failed operation still exits successfully.

When the operation has failed and failure.retryable is true, use a new idempotency key to try again. Reusing the old key will return the same failed operation. If the outcome is still unknown, keep the original key and read its status first.

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. Add --muted to start the thread with notifications muted. The result includes the operation ID and clientThreadId for subsequent commands. A Claude thread started this way will behave like one started in the desktop app, so you can reply to it from desktop or mobile.

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 starts a turn when the thread is idle and otherwise queues the follow-up behind the active turn. Choose when a follow-up should arrive with --delivery:

The result's disposition says whether the follow-up started, steered the active turn, or queued. A queued follow-up has no turn ID until it starts. Send never takes 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. It leaves queued follow-ups intact. Use desktop, mobile, or dvb agents to answer agent questions or take over a Claude terminal; these script commands don't support those actions.

Mute a thread

dvb threads mute --thread <client-thread-id> --json
dvb threads unmute --thread <client-thread-id> --json

A muted thread's finished turns don't notify you or mark it unread; requests for input still do. Repeating either command is safe.

Current-machine information and permissions

Run these commands inside the boxes.dev machine:

dvb-onbox box status --json
dvb-onbox whoami --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. whoami returns the ID, email, and name of the boxes.dev account that owns the machine. 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, destroy-created-devboxes, read-project-threads, read-user-threads, read-shared-threads, read-team-threads, edit-template-box, edit-team-template, edit-project-settings, edit-personal-environment, and edit-automations. 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 five 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 and Let one thread edit your automations. 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.

Send feedback to boxes.dev

An agent on the machine can send the boxes.dev team a feature request when a command or option it needed is missing, or a bug report when one behaved incorrectly:

dvb-onbox send-feedback "I needed to list the devboxes in a folder, but folders list shows only the folders."
dvb-onbox report-bug --stdin --json < report.txt

A report can be up to 32 KiB and needs no permission. It goes to the same queue as Send feedback in the desktop app and includes your boxes.dev account, the current machine and project, and the thread's ID. Agents send reports without asking first and mention them in their final response. They leave out confidential information, such as secrets, source code, personal data, and details of your work, unless you explicitly ask them to include it. IDs that help with debugging, such as thread or devbox IDs, can be included. If you'd rather an agent didn't send feedback, say so in your request.

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 \
  --muted --prompt-file <path> --idempotency-key <key> --json

Use options for current model IDs, reasoning efforts, and speeds before making an explicit selection. Add --model, optional supported --reasoning-effort, and optional --speed standard|fast|ultrafast with a speed the model lists; Claude's fast speed is fast mode. 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 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. The new conversation appears in your thread list like any other thread, and you can read and reply to it there.

Prefer --muted, as in the example above, for worker threads whose results the coordinating agent will review and include in its reply. You will still be notified if a worker needs your input. Omit --muted when you expect to review or continue the new thread yourself. Agents should follow any notification preference you give them.

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
dvb-onbox threads mute --thread <child-id> --json
dvb-onbox threads unmute --thread <child-id> --json

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

These commands can't take control of a Claude terminal that a person is using. 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. Add --all to a scoped thread listing to fetch every page in one command; it cannot be combined with --cursor. Project pages may repeat projects; deduplicate by project ID. Thread listings exclude archived threads unless you add --include-archived.

To read a thread, pass its id from a listing, a boxes.dev thread link, or the thread's Codex thread ID or Claude session ID. Listings and reads show that agent ID as nativeThreadId. If an agent ID matches more than one thread you can read, use the thread's id instead.

Listings, reads, and search results show the thread's last-reported execution status: draft, starting, idle, running, needs_input, failed, or archived, with nullable activeTurnId and activeTurnStatus fields. Check the thread's status before nudging an idle agent. A transcript marked ready means its messages can be read, even while the agent is working. Status reads do not wake machines or require delegation permission, but they can lag live work and do not guarantee that the agent will still be idle when a message arrives.

To check known threads together, put their listing id values in a JSON array in a file, then run:

dvb-onbox threads status --scope project --ids-file lanes.json --json

Supply 1 through 100 IDs in a file of at most 32 KiB. Results keep the file's order and include the usual thread metadata. An ID outside the selected scope or your access returns status: "unavailable" and thread: null. For an available thread, check thread.status for its last-reported execution state. The lookup uses the same read permissions and does not read conversations or wake devboxes.

Listings, reads, and search results also show devboxId for your own threads on a devbox. It is null for teammates' threads and for threads on the Template box. An agent with Create devboxes and threads can pass it to threads start --target devbox:<instance-id> to start another agent on that devbox's live files. For example, when Claude reaches a usage limit, a Codex thread started there can continue with the uncommitted work.

Copy thread ID in a teammate thread's … menu copies an ID that agents can read. A tsh_... ID from a share-link page needs --scope shared. A thr_... ID works with --scope shared if you opened that thread's share link, or with --scope team if your team settings allow reading it.

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.

Search your threads from an agent

An agent with This project or All my projects access can find your own threads by their titles or by what was said in them:

dvb-onbox threads search --scope user --query "flaky deploy" --json
dvb-onbox threads search --scope project --query '"setup script" timeout' -n 5 --json

Search covers the same titles and messages as searching your threads in the app, except Team Template editing threads. It lists 10 threads by default, best match first, so results don't fill the agent's context; -n allows up to 30. Each result that matched a message includes an excerpt of that message and a readCursor. Passing that value to threads read as --cursor, with the same scope and the thread's id, opens the conversation at the match. A result that matched only the thread's title has neither, so read that thread without --cursor.

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

dvb-onbox threads message --to <thread-id> --message "Review the endpoint." \
  --idempotency-key keeper-2026-10-14-lane-1 --idle-only --json

dvb-onbox threads message --batch-file /tmp/messages.json --idle-only --json

The batch file is a JSON array of 1–100 objects, up to 3 MiB:

[
  {"to": "<thread-id>", "message": "Review the endpoint.", "idempotencyKey": "keeper-2026-10-14-lane-1"}
]

Each message needs a distinct key of 1–128 characters. The whole file is validated before sending. Four deliveries run concurrently, starting in file order; put higher-priority threads first. JSON results stay in input order, and failures don't cancel other messages. The command exits unsuccessfully if any item fails.

--idle-only checks the recipient immediately before delivery, after any startup. An accepted message returns delivered; a busy agent or one awaiting an answer returns skipped_busy without added input. Skips count as successful outcomes. Thread status can lag the runtime, so use this flag when delivery must be limited to idle agents. Sleeping machines may wake before this check. The recipient service must support this mode; unsupported_capability means it couldn't enforce it and no message was delivered.

Retrying with the same key on the same source machine recovers the existing outcome without delivering twice. Reusing a key with a different recipient, message, or idle-only policy fails. Use a new key for each new nudge or cadence pass, including when reconsidering a busy skip.

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.

After work finishes, messages from other agents collapse with tool activity under Worked for…. Expand it to read them. Your messages and the agent's final answer stay visible.

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, recover with the same key if supplied; using a new key may send a second message. Without a supplied key, don't send again. Messages are limited to 4 KiB, and a Claude agent in a busy or user-controlled terminal can't receive them.

Sending can take a minute or more when the recipient's devbox has to wake or update first. A script that sends messages should allow at least four minutes per delivery; batches may need longer because each group can include slow wakes. If the script stops a send early, recover with the same key or treat the unkeyed message as possibly delivered. Batching cannot guarantee a five-minute cadence when machines must wake.

Publish interactive visuals

An agent on a boxes.dev machine can publish a self-contained HTML visual, such as a chart or a small simulation with controls, and show it in its final reply. Agents find the authoring steps in their boxes-inline-visualizations skill.

dvb-onbox visuals preview --file /tmp/visuals/latency/index.html \
  --output-dir /tmp/visuals/latency/preview --json
dvb-onbox visuals publish --file /tmp/visuals/latency/index.html \
  --title "Queue latency near capacity"
dvb-onbox visuals read --id <visual-id> \
  --output /tmp/visuals/latency/index.html --json

preview renders the visual on the machine and saves a screenshot, along with any console errors or blocked loads. publish combines the HTML file and its local scripts, stylesheets, and images into one document of at most 5 MiB and prints a Markdown link. The visual appears when that link is alone in its own paragraph of the final reply. Each publish creates a new visual, so earlier replies never change. To revise a visual you own, an agent runs read to save its HTML, edits it, and publishes it again.

A visual needs to contain everything it uses, because remote loads and requests, including requests to the machine's own ports, are blocked. Published visuals keep working while the machine sleeps.

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. To enable it across the project, turn on Destroy and archive under Agent permissions for this project in Project settings, or choose Always allow for project in the request. Existing and future devboxes will follow that setting unless configured separately. The permission is off by default, and the command can only destroy the agent's own ordinary 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.

Destroy devboxes the agent created

An agent on a Template box or devbox can delete a devbox that an agent on the same box created with dvb-onbox threads start --target new-devbox, using the devboxId that command returned:

dvb-onbox box destroy --devbox <devbox-id> --json

First enable Destroy and archive created devboxes under Agent permissions in that box's thread header, or approve the agent's destroy-created-devboxes permission request. To enable it across the project, turn it on under Agent permissions for this project in Project settings, or choose Always allow for project in the request. The permission is off by default. It doesn't depend on Create devboxes and threads or on the created devbox's own destroy permission. The command rejects the agent's own box, Template boxes, devboxes created by another box, and devboxes where the agent only started a thread.

The request works like a devbox's request to destroy itself: it waits for every agent and queued message on the devbox to finish, wakes a sleeping devbox to archive it, and expires after 30 minutes. New work on the devbox or turning off the permission cancels it. A successful response means the request was saved. When dvb-onbox threads list --include-archived shows the devbox's thread as archived, its history is saved and the machine is being deleted.

To cancel a pending request, run:

dvb-onbox box cancel-destroy --devbox <devbox-id> --json

Either box can cancel without a destroy permission. If the box that made the request is destroyed first, its pending requests are cancelled.

Read and edit project and Team Template settings

An agent can read settings from any box in your project without an editing grant:

dvb-onbox project settings get --json
dvb-onbox team-template settings get --json
dvb-onbox team-template settings get --template <team-template-id> --json

Project output includes guidance, lifecycle, Git, ports, storage, permission defaults, environment metadata, member-file supplied state, and Claude and Codex agent settings. autoWake reports the account-wide preference shown in Project settings, and effectiveGitAction includes the account default. Its origin records the source Team Template, saved version, and settings captured when the project was created, when that history is available. Compare these with the template's current defaults to trace inherited guidance. Changing template defaults won't replace an existing project's copy.

Team Template reads include its name, description, source, machine size, project defaults, setup instructions, integrations, member-project policy, cleanup, maintenance and watches, Project URL/MCP definitions, environment definitions, member-file requirements, and agent settings. An explicit template ID must belong to your team. These reads don't open or wake an editing machine and never include saved secret values or member-file contents.

To change settings, prepare a JSON operation in a regular file inside /home/boxes, no larger than 512 KiB. For example, copy the project's current Git settings and change the preference:

{
  "section": "git",
  "settings": { "preferredAction": "pull_request", "threadAttributionEnabled": false }
}

Then save it, passing the file's absolute path:

dvb-onbox project settings set --settings-file /home/boxes/settings-edit.json --json
dvb-onbox team-template settings set --settings-file /home/boxes/template-edit.json --json

Project writes need the thread's three-hour edit-project-settings permission; edit-template-box and edit-team-template also cover its own project settings. Team Template writes need a team admin with edit-team-template, or the existing authorized editing machine/association. No editing session is needed for settings saves from a project created from the template. Agent permission defaults remain user-only with every editing grant.

Each operation identifies one section. Project sections include lifecycle, git, ports, ports_enabled, storage, auto_wake, maintenance, maintenance_delete, maintenance_watches, member_files, environment_file, environment_file_delete, and agent_settings. Template sections include metadata, defaults, setup, integrations, member_projects, cleanup, maintenance, maintenance_delete, watch_save, watch_delete, agent_settings, and create/update/delete operations for URLs and MCPs, plus environment-file saves and deletions. Read before saving and preserve other fields within that section; pass the current revision or save epoch where required. After a conflict or uncertain result, read again and reconcile. The installed onbox-agent-tools reference lists each operation's exact fields.

An agent_settings save replaces the whole Claude or Codex document, so start from the current text and keep settings you didn't mean to change. boxes.dev will indent Claude JSON when it's saved. Codex TOML will be saved as written, so put one key per line for people who edit it in the desktop app. A value that would make the installed Claude Code or Codex reject its settings can't be saved. A value Claude Code would skip, or a key the agent doesn't recognize, will be saved with a warning in the JSON output. See Agent settings for how boxes apply it.

Use env set|remove for environment values and team-template member-files for requirement definitions. Publishing a filesystem version, snapshots, and account sign-in retain their existing workflows. An auto_wake edit takes enabled (boolean or null for the default) and affects your account across projects, just like the desktop control.

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. From an ordinary devbox, use project settings get|set with the appropriate thread editing permission instead.

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.

Manage automations

An agent can read and change its project's automations:

dvb-onbox automations options --json
dvb-onbox automations list --json
dvb-onbox automations get --automation <id> --json
dvb-onbox automations create --spec-file spec.json --prompt-file prompt.md --json
dvb-onbox automations update --automation <id> --spec-file changes.json \
  --if-revision <revision> --dry-run --json
dvb-onbox automations activate --automation <id> --json
dvb-onbox automations run --automation <id> --idempotency-key <key> --json
dvb-onbox automations runs --automation <id> --json

pause and delete also take --automation, and runs --run <run-id> shows the prompt and settings a run used. Reading needs no permission. Creating, changing, activating, pausing, running, and deleting need edit-automations for the agent's thread.

The spec is a JSON file with the automation's name, prompt, agent settings, and trigger: Manual, or an hourly, daily, weekly, or monthly schedule. It can also set thread placement, capacity behavior, devbox cleanup, and Slack output destinations. options lists the available models and reasoning levels. A new automation is saved paused.

An update changes only the keys in its file and needs the revision returned by get. If the automation changed since then, the update fails and returns the current revision. --dry-run shows the result and upcoming run times without saving. delete works only while the automation has no runs. A run's thread_ready status means its thread started, not that its work succeeded.

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

Agents can read member requirements without an editing grant. Admins can change them in the Team Template's editing machine or from a project created from it with the thread's edit-team-template permission:

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-project-settings or 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-project-settings, edit-personal-environment, or edit-team-template if you're a team admin. Listing needs no editing grant.

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.