@boxes-dev/dvb-runtime 1.0.1079 → 1.0.1080
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bin/dvb.mjs +1547 -218
- package/dist/bin/dvbd.mjs +6 -6
- package/dist/product-docs/references/agent-tools.md +6 -1
- package/dist/product-docs/references/automations.md +45 -1
- package/dist/product-docs/references/aws.md +5 -0
- package/dist/product-docs/references/cli.md +54 -0
- package/dist/product-docs/references/desktop-workbench.md +106 -32
- package/dist/product-docs/references/files-git-and-review.md +8 -1
- package/dist/product-docs/references/fork-workflows.md +2 -2
- package/dist/product-docs/references/google-cloud.md +142 -0
- package/dist/product-docs/references/index.md +12 -2
- package/dist/product-docs/references/mobile.md +139 -16
- package/dist/product-docs/references/onbox-agent-tools.md +165 -19
- package/dist/product-docs/references/ports-terminal-and-runtime.md +112 -27
- package/dist/product-docs/references/project-setup.md +1 -1
- package/dist/product-docs/references/security-and-data.md +20 -0
- package/dist/product-docs/references/team-template.md +45 -0
- package/dist/product-docs/references/threads-and-agents.md +100 -35
- package/dist/product-docs/references/troubleshooting.md +48 -7
- package/dist/product-docs/references/unattended-work.md +108 -0
- package/dist/product-docs/references/vercel.md +89 -0
- package/package.json +2 -2
|
@@ -235,7 +235,9 @@ dvb-onbox team-template settings get --template <team-template-id> --json
|
|
|
235
235
|
Project output includes Agent Guidance, prompt prefix, startup/teardown scripts
|
|
236
236
|
and timeouts, Git preferences, port forwarding, storage, environment metadata,
|
|
237
237
|
member-file requirements and supplied state, maintenance where applicable,
|
|
238
|
-
agent permission defaults
|
|
238
|
+
agent permission defaults (the values in effect, with
|
|
239
|
+
`permissionDefaultsLockedByTeamTemplate` true when a Team Template locks
|
|
240
|
+
them), and Claude and Codex agent settings
|
|
239
241
|
(`agentSettings`, plus the Team Template's read-only `teamAgentSettings` in a
|
|
240
242
|
member project). `effectiveGitAction` includes the account's default
|
|
241
243
|
when no project preference is set. `autoWake` reports the account-wide
|
|
@@ -252,7 +254,9 @@ Team Template output includes its identity, description, source/repositories,
|
|
|
252
254
|
machine size, active saved version, project defaults and save epochs, setup
|
|
253
255
|
instructions, integration requirements, member-project policy, cleanup,
|
|
254
256
|
maintenance and watches, Project URL/MCP definitions, environment definitions,
|
|
255
|
-
member-file requirements,
|
|
257
|
+
member-file requirements, agent settings, and `agentPermissions` (the saved
|
|
258
|
+
`policy` with `locked` and `values`, or null before an admin saves one, plus
|
|
259
|
+
`revision` and `memberProjectCount`). Omit `--template` to select the current editing
|
|
256
260
|
box's template or the project's source template. An explicit ID must belong to
|
|
257
261
|
the caller's team. Reading does not open or wake a template editing machine.
|
|
258
262
|
Environment/file metadata never includes saved secret values or file contents.
|
|
@@ -332,6 +336,15 @@ Team Template operations use these fields in addition to `section`:
|
|
|
332
336
|
| `environment_file` | `draft` for a Team Template environment file, as described below. |
|
|
333
337
|
| `environment_file_delete` | `contextId`, `expectedContextRevision`. |
|
|
334
338
|
| `agent_settings` | `agent` (`claude` or `codex`), `content`, `expectedRevision`, as described below. |
|
|
339
|
+
| `agent_permissions` | `expectedRevision` from `agentPermissions.revision`, `locked`, and complete `values` with every field from the read result. The first save with `locked: false` while `memberProjectCount` is above zero also needs `existingMembers`: `follow_team_template` or `keep_current`. |
|
|
340
|
+
|
|
341
|
+
Before a first `agent_permissions` save with existing member projects, ask
|
|
342
|
+
the user whether those projects should move to the new permissions
|
|
343
|
+
(`follow_team_template`) or keep their current ones as each member's own
|
|
344
|
+
choice (`keep_current`); without the field the save fails with
|
|
345
|
+
`team_template_agent_permissions_choice_required`. Changing `locked` to true
|
|
346
|
+
replaces every member's own project permissions, so confirm that with the user
|
|
347
|
+
first. See `team-template.md` for how the two modes behave.
|
|
335
348
|
|
|
336
349
|
An environment `draft` contains `contextId`, `expectedContextRevision`, `path`,
|
|
337
350
|
`displayOrder`, `adoptionRevision`, `adoptionSourceSha256`,
|
|
@@ -420,8 +433,10 @@ about a minute. After an uncertain response, run `list` before retrying.
|
|
|
420
433
|
## Automations
|
|
421
434
|
|
|
422
435
|
An agent can read and manage the current project's automations. Each
|
|
423
|
-
automation saves a prompt and agent settings
|
|
424
|
-
a new devbox
|
|
436
|
+
automation saves a prompt and agent settings. By default, each run starts a
|
|
437
|
+
new thread on a new devbox; Manual and Schedule automations can instead send
|
|
438
|
+
their prompt to an existing owned thread. See [Automations](automations.md)
|
|
439
|
+
for how they work.
|
|
425
440
|
|
|
426
441
|
Create an automation only when the user asks for recurring or unattended work.
|
|
427
442
|
Unless they asked for an automation by name, explain how one would run, offer
|
|
@@ -476,7 +491,8 @@ separate `--prompt-file`, not both. File paths can be relative or absolute.
|
|
|
476
491
|
}
|
|
477
492
|
```
|
|
478
493
|
|
|
479
|
-
- `name`, the prompt,
|
|
494
|
+
- `name`, the prompt, and `trigger` are required. `execution` is required for
|
|
495
|
+
new-thread runs; omit it when targeting an existing thread. Other keys
|
|
480
496
|
default to the desktop defaults: runs under the automation, successful runs
|
|
481
497
|
not marked read, completion notifications for every turn, no capacity
|
|
482
498
|
options, devbox cleanup **Never** with both
|
|
@@ -496,6 +512,18 @@ separate `--prompt-file`, not both. File paths can be relative or absolute.
|
|
|
496
512
|
Slack, and Linear triggers can be set up only in the desktop app.
|
|
497
513
|
- `threadPlacement`: `nested` (under the automation) or `main` (the main
|
|
498
514
|
thread list).
|
|
515
|
+
- `target`: `{"kind": "thread", "thread": "current"}` to continue the calling
|
|
516
|
+
thread, or replace `current` with another owned thread's ID in this project.
|
|
517
|
+
This is available for Manual and Schedule triggers. Omit it on creation for
|
|
518
|
+
new-thread runs; set it to `null` on update to return to new-thread runs.
|
|
519
|
+
Existing targets keep their current agent settings and location. Slack
|
|
520
|
+
outputs, devbox cleanup, capacity options, `threadPlacement`,
|
|
521
|
+
`markSuccessfulRunsRead`, and `completionNotifications` cannot be supplied
|
|
522
|
+
with an existing target. Include `execution` when clearing an existing
|
|
523
|
+
target, to choose settings for future new-thread runs. A scheduled
|
|
524
|
+
occurrence skips a target that is already busy; if work starts just after
|
|
525
|
+
that check, the prompt waits in the ordinary queue. Archived, deleted, or
|
|
526
|
+
inaccessible targets fail without creating a replacement thread.
|
|
499
527
|
- `markSuccessfulRunsRead`: `true` or `false`.
|
|
500
528
|
- `completionNotifications`: `all` (the default), `follow_ups_only` (no
|
|
501
529
|
notification when the automation's first turn finishes), or `none` (no
|
|
@@ -528,6 +556,12 @@ replaces that whole value. `"outputs": []` removes all destinations, and
|
|
|
528
556
|
`{"trigger": {"kind": "manual"}}` removes a schedule. `update` needs
|
|
529
557
|
`--spec-file`, `--prompt-file`, or both.
|
|
530
558
|
|
|
559
|
+
Changing to an existing-thread target removes saved Slack outputs. The saved
|
|
560
|
+
devbox cleanup policy still applies to earlier new-thread runs; it never
|
|
561
|
+
applies to the target's devbox. Read results retain `execution` and other
|
|
562
|
+
new-thread settings for compatibility, but those settings do not control
|
|
563
|
+
existing-thread runs.
|
|
564
|
+
|
|
531
565
|
If the automation changed after it was read, `update` fails with
|
|
532
566
|
`revision_conflict` and returns the current revision. Read it again, reconcile
|
|
533
567
|
the change with the user's request, and retry with the new revision.
|
|
@@ -549,7 +583,9 @@ Linear receiver.
|
|
|
549
583
|
automation. `pause` stops new triggered runs; runs already started
|
|
550
584
|
continue.
|
|
551
585
|
- `run` starts one run now, even while the automation is paused. It starts a
|
|
552
|
-
new devbox
|
|
586
|
+
new devbox by default, or sends to the saved existing-thread target. A
|
|
587
|
+
sleeping target devbox will wake for delivery; runs use normal box-hours.
|
|
588
|
+
When retrying, reuse the same
|
|
553
589
|
`--idempotency-key` to get the original run back. Errored automations and
|
|
554
590
|
default Slack and Linear receivers fail with `run_not_available`; launch
|
|
555
591
|
rejections fail with `run_rejected` and a `reasonCode`.
|
|
@@ -748,6 +784,10 @@ those configured separately. Other devboxes will keep their individual
|
|
|
748
784
|
permissions. The choice is personal to the owner's
|
|
749
785
|
project, including projects created from a Team Template; it will not change
|
|
750
786
|
teammates' permissions. Template-only permissions keep their existing scope.
|
|
787
|
+
In a Member project whose Team Template locks agent permissions, **Always
|
|
788
|
+
allow for project** is not offered; **Allow** still enables the permission on
|
|
789
|
+
the requesting box. See `team-template.md` for how a Team Template sets these
|
|
790
|
+
project permissions.
|
|
751
791
|
|
|
752
792
|
The **Agent permissions** switches show each box's effective on/off settings;
|
|
753
793
|
folder access shows its actual access level. Changing a control saves the
|
|
@@ -900,6 +940,47 @@ remote loads and connections from a visual, including this box's ports. If
|
|
|
900
940
|
`visuals` is missing from `dvb-onbox --help` or returns
|
|
901
941
|
`daemon_update_required`, the box has not received this capability yet.
|
|
902
942
|
|
|
943
|
+
## Inline Images And Videos
|
|
944
|
+
|
|
945
|
+
A managed Codex or Claude agent can present local images and video recordings
|
|
946
|
+
in its final answer as a gallery of previews. The `boxes-present-media` skill
|
|
947
|
+
has the presentation workflow; read it before presenting media.
|
|
948
|
+
|
|
949
|
+
```bash
|
|
950
|
+
dvb-onbox media publish ./before.png ./after.png ./recording.webm
|
|
951
|
+
dvb-onbox media publish --json ./before.png ./after.png
|
|
952
|
+
```
|
|
953
|
+
|
|
954
|
+
`publish` prepares a preview of each file, uploads the files, and prints one
|
|
955
|
+
Markdown link per file in the given order only after every upload succeeds.
|
|
956
|
+
Progress goes to stderr, and `--json` adds item metadata and the complete
|
|
957
|
+
Markdown. The gallery appears only when the links stand alone in a paragraph
|
|
958
|
+
of the final answer, one per line, with a blank line before and after it; a
|
|
959
|
+
blank line between links starts a separate gallery. A link's label can be
|
|
960
|
+
replaced with a short caption without square brackets, but each destination
|
|
961
|
+
must stay unchanged. Until the paragraph is complete, a streaming answer shows
|
|
962
|
+
ordinary links.
|
|
963
|
+
|
|
964
|
+
Images can be PNG, JPEG, WebP, or GIF files. Export SVG, HTML, or PDF content
|
|
965
|
+
to one of those first. Animated WebP files may fail to prepare, so export a
|
|
966
|
+
PNG or JPEG instead, and GIF previews are still images. Videos can be MP4,
|
|
967
|
+
MOV, WebM, MKV, or AVI files. Each video is converted to an H.264 MP4 with a
|
|
968
|
+
poster frame, and readers play and download that MP4, so keep the source file
|
|
969
|
+
when the user needs the original recording. Preparing a video can take up to
|
|
970
|
+
10 minutes per file. One command or gallery holds at most 20 files, with up to
|
|
971
|
+
25 MiB per image, 250 MiB per prepared video, 500 MiB of source files per
|
|
972
|
+
command, and 50 megapixels per image.
|
|
973
|
+
|
|
974
|
+
Each publish creates new files, so earlier answers never change and a retry
|
|
975
|
+
creates new links. Published files don't depend on the box and stay available
|
|
976
|
+
after it sleeps or is deleted. The command takes no owner or thread selector:
|
|
977
|
+
the current managed thread determines the owner. Publishing does not share the
|
|
978
|
+
thread; who can open a file follows its owner and thread sharing, and the links
|
|
979
|
+
are not public downloads. Images viewed through tools fold with a finished
|
|
980
|
+
turn's other activity, so publish the files the user should see. If `media` is
|
|
981
|
+
missing from `dvb-onbox --help` or returns `daemon_update_required`, the box
|
|
982
|
+
has not received this capability yet; give ordinary file links instead.
|
|
983
|
+
|
|
903
984
|
## Current-Box Public Links
|
|
904
985
|
|
|
905
986
|
An agent or shell script can create and remove an HTTPS public link for an
|
|
@@ -1104,8 +1185,12 @@ dvb-onbox threads send \
|
|
|
1104
1185
|
```
|
|
1105
1186
|
|
|
1106
1187
|
`next` starts a turn when the child is idle and otherwise queues behind its
|
|
1107
|
-
active turn. `idle` is the strict idle-only form. `steer`
|
|
1108
|
-
|
|
1188
|
+
active turn. `idle` is the strict idle-only form. `steer` adds instructions to
|
|
1189
|
+
the exact active Codex or Claude turn. Claude will read them at its next
|
|
1190
|
+
opportunity without interrupting a running tool. Claude steering requires an
|
|
1191
|
+
updated local boxes.dev service and a running managed session. Interactive
|
|
1192
|
+
terminal sessions can't be steered. Answer pending questions or approvals in
|
|
1193
|
+
boxes.dev before steering. `queue` is the strict active-only form and
|
|
1109
1194
|
enters Codex's persistent FIFO or Claude's next-message queue. `idle`, `steer`,
|
|
1110
1195
|
and `queue` do not adapt to another delivery mode. A Claude terminal that a
|
|
1111
1196
|
person is actively using stays out of bounds.
|
|
@@ -1123,7 +1208,9 @@ dvb-onbox threads interrupt \
|
|
|
1123
1208
|
Interrupt leaves queued follow-ups intact. Use one idempotency key for each
|
|
1124
1209
|
logical send or interrupt, and keep every argument identical on retry. If a
|
|
1125
1210
|
response is lost after dispatch, boxes.dev recovers the durable result without
|
|
1126
|
-
automatically sending the input again.
|
|
1211
|
+
automatically sending the input again. If a send or interrupt fails with
|
|
1212
|
+
`daemon_unavailable`, try again with a new idempotency key, because the old
|
|
1213
|
+
key will keep returning the same failure.
|
|
1127
1214
|
|
|
1128
1215
|
Mute or unmute the notifications of a child that this box created when the
|
|
1129
1216
|
user asks:
|
|
@@ -1177,8 +1264,10 @@ dvb-onbox threads events <delegated-thread-id> \
|
|
|
1177
1264
|
|
|
1178
1265
|
`threads list` uses the current source box's project automatically and never
|
|
1179
1266
|
shows other project threads, including children created by a different source
|
|
1180
|
-
box.
|
|
1181
|
-
|
|
1267
|
+
box. To find other threads in the project, use `threads list --scope project`
|
|
1268
|
+
from [Read Other Threads](#read-other-threads), which needs only **Read other
|
|
1269
|
+
threads**. `threads result` returns the complete stored final response for one
|
|
1270
|
+
exact terminal turn and automatically assembles its transport pages. Use it instead
|
|
1182
1271
|
of asking the child to summarize a shortened `threads read` preview. When
|
|
1183
1272
|
`threads wait` omits `--turn`, it snapshots the current active turn once. A
|
|
1184
1273
|
completed wait includes that same complete response as `output.text`; Ctrl+C
|
|
@@ -1187,6 +1276,12 @@ an opaque resume cursor on every JSONL row. With no turn, cursor, or
|
|
|
1187
1276
|
`--from-start`, it follows only events created after the command starts. An
|
|
1188
1277
|
exact-turn stream ends after needs-input or a terminal event.
|
|
1189
1278
|
|
|
1279
|
+
If an accepted child is later deleted, `threads list` retains its ID as a
|
|
1280
|
+
`failed` entry titled **Deleted delegated thread**. Reads and controls explain
|
|
1281
|
+
that it was deleted. Retrying its original start with the same idempotency key
|
|
1282
|
+
reports `child_thread_deleted` and keeps the original child ID; it does not
|
|
1283
|
+
create another thread or recover the deleted transcript.
|
|
1284
|
+
|
|
1190
1285
|
Use a message's `turnId` from `threads read`, or an active turn ID from
|
|
1191
1286
|
`threads list`, directly with `result`, `wait`, and `events`. These observations
|
|
1192
1287
|
also accept the transcript turn keys returned by older versions. For `steer`
|
|
@@ -1300,6 +1395,34 @@ order, with `status: "available"` and the usual `thread` metadata, or
|
|
|
1300
1395
|
that scope. Use `thread.status` for execution state. This lookup does not read
|
|
1301
1396
|
conversations or wake devboxes, and its states may lag live work.
|
|
1302
1397
|
|
|
1398
|
+
Scoped listings and status lookups include nullable `lastStopReason`,
|
|
1399
|
+
`lastStopAt` (Unix milliseconds), and `lastStopTurnId`. These describe the
|
|
1400
|
+
latest lifecycle event when it is terminal: `completed`, `interrupted`, or a
|
|
1401
|
+
failure category such as `usage_limit_exceeded`. An unclassified failure is
|
|
1402
|
+
`unknown`; missing events and newer nonterminal activity return null.
|
|
1403
|
+
|
|
1404
|
+
To find idle threads stopped by exhausted usage or credits, run:
|
|
1405
|
+
|
|
1406
|
+
```bash
|
|
1407
|
+
dvb-onbox threads list --scope project --stop-reason usage_limit_exceeded --all --json
|
|
1408
|
+
```
|
|
1409
|
+
|
|
1410
|
+
The filter excludes archived threads, active work, scheduled continuations,
|
|
1411
|
+
and threads with a newer completion, interruption, or turn start. The recorded
|
|
1412
|
+
usage-limit category also includes usage caps and Codex session budgets; it
|
|
1413
|
+
cannot establish that account credits alone caused the stop. Other supported
|
|
1414
|
+
reasons are `completed`, `interrupted`, `provider_stream_failure`,
|
|
1415
|
+
`provider_overloaded`, `provider_rate_limited`, `network_suspected`,
|
|
1416
|
+
`context_window_exceeded`, `auth`, `policy_blocked`, `codex_internal_error`,
|
|
1417
|
+
`request_rejected`, `codex_sandbox_error`, and `unknown`.
|
|
1418
|
+
|
|
1419
|
+
Review the matching threads before continuing them. With messaging permission,
|
|
1420
|
+
send a follow-up to the existing thread using `threads message --idle-only`,
|
|
1421
|
+
keeping its saved agent settings. Tell it to check its progress and any prior
|
|
1422
|
+
external actions before continuing; do not resend the original task as a new
|
|
1423
|
+
thread. Listing does not resume anything, and stored status can change before
|
|
1424
|
+
delivery.
|
|
1425
|
+
|
|
1303
1426
|
Listings, reads, and search results also report `devboxId` for your own
|
|
1304
1427
|
threads on a devbox. It is null for teammates' threads and for threads on the
|
|
1305
1428
|
Template box. With **Create devboxes and threads** enabled, pass it to
|
|
@@ -1367,7 +1490,7 @@ which need the same permission levels as listing them. Put a phrase in double
|
|
|
1367
1490
|
quotes to require those words together in that order.
|
|
1368
1491
|
|
|
1369
1492
|
Results list 10 threads by default, best match first; pass `-n` for 1 to 30.
|
|
1370
|
-
Each result has
|
|
1493
|
+
Each result has thread metadata and a `match` with the
|
|
1371
1494
|
role, message time, a highlighted `snippet`, and `readCursor`. To read the
|
|
1372
1495
|
conversation at the match, run `threads read` with the same scope, the
|
|
1373
1496
|
thread's `id`, and `readCursor` as `--cursor`: the page ends with the matching
|
|
@@ -1412,11 +1535,31 @@ The batch file is a JSON array of 1–100 objects, up to 3 MiB:
|
|
|
1412
1535
|
|
|
1413
1536
|
Each message needs a distinct key of 1–128 characters. The entire file is
|
|
1414
1537
|
validated before sending. Four deliveries run concurrently, launching in file
|
|
1415
|
-
order, so put higher-priority threads first.
|
|
1416
|
-
when deliveries finish in a different order. Each item succeeds or fails
|
|
1538
|
+
order, so put higher-priority threads first. JSON `results` retain that order
|
|
1539
|
+
even when deliveries finish in a different order. Each item succeeds or fails
|
|
1417
1540
|
independently; a failed item does not cancel the others. JSON output includes
|
|
1418
1541
|
`results`; the command exits unsuccessfully if any item fails.
|
|
1419
1542
|
|
|
1543
|
+
`--json` prints nothing until every item finishes, which can take several
|
|
1544
|
+
minutes for a large batch. To see each outcome as soon as it finishes, use
|
|
1545
|
+
`--jsonl` instead. It works only with `--batch-file`, can't be combined with
|
|
1546
|
+
`--json`, and prints one JSON object per line: a `result` line for each item in
|
|
1547
|
+
the order the items finish, then a final `summary` line with an overall `ok`.
|
|
1548
|
+
Without either flag, the command prints a line naming the recipient as each
|
|
1549
|
+
outcome finishes.
|
|
1550
|
+
|
|
1551
|
+
```text
|
|
1552
|
+
{"schemaVersion":2,"type":"result","index":1,"to":"<thread-id>","idempotencyKey":"keeper-2026-10-14-lane-2","ok":true,"requestId":"peer_…","threadId":"<thread-id>","agent":"codex","status":"skipped_busy"}
|
|
1553
|
+
{"schemaVersion":2,"type":"result","index":0,"to":"<thread-id>","idempotencyKey":"keeper-2026-10-14-lane-1","ok":true,"requestId":"peer_…","threadId":"<thread-id>","agent":"claude","status":"delivered"}
|
|
1554
|
+
{"schemaVersion":2,"type":"summary","ok":true}
|
|
1555
|
+
```
|
|
1556
|
+
|
|
1557
|
+
`index` is the item's zero-based position in the batch file, and the other
|
|
1558
|
+
fields match that item in `--json` `results`. If the output ends without a
|
|
1559
|
+
summary line, the command stopped early. Rerun the same file with the same
|
|
1560
|
+
`--idle-only` setting to finish the batch; items that were already sent will
|
|
1561
|
+
return their recorded outcome without another delivery.
|
|
1562
|
+
|
|
1420
1563
|
`--idle-only` checks the recipient after startup, immediately before native
|
|
1421
1564
|
delivery. It returns `delivered` for an accepted message or `skipped_busy`
|
|
1422
1565
|
without adding input when the agent is busy or awaiting an answer. Skips count
|
|
@@ -1446,11 +1589,14 @@ Attachments cannot be sent to a teammate's thread; send a link they can open
|
|
|
1446
1589
|
instead.
|
|
1447
1590
|
|
|
1448
1591
|
Keys reuse the same receipt on the same source machine, including across CLI
|
|
1449
|
-
invocations.
|
|
1450
|
-
|
|
1451
|
-
|
|
1452
|
-
|
|
1453
|
-
|
|
1592
|
+
invocations. After a retryable failure that confirms the message was not
|
|
1593
|
+
delivered, repeat the command with the same key and message to try delivery
|
|
1594
|
+
again. Successful sends, permanent failures, and uncertain delivery outcomes
|
|
1595
|
+
keep their recorded result; repeating the command does not send them again.
|
|
1596
|
+
Changing the recipient, message, attachments, or idle-only policy under that
|
|
1597
|
+
key fails with `idempotency_key_reused`. Use a new key for each distinct message.
|
|
1598
|
+
If delivery was skipped because the recipient was busy, use a new key if you
|
|
1599
|
+
later decide to send it again.
|
|
1454
1600
|
|
|
1455
1601
|
`--to` takes a boxes.dev thread ID, such as one named in a received message,
|
|
1456
1602
|
one returned by `dvb-onbox threads start`, or one from
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
# Ports, Terminal, And Runtime
|
|
2
2
|
|
|
3
|
-
The Ports menu,
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
select another thread.
|
|
3
|
+
The Ports menu, Terminal, Files, and Git follow the selected runtime. If you
|
|
4
|
+
select the Template box, they use the Template box. If you select a devbox
|
|
5
|
+
thread, they use that devbox. Ordinary `localhost` forwarding follows selection
|
|
6
|
+
by default, but you can keep it on one devbox while working elsewhere. Stable
|
|
7
|
+
local URLs also stay with each opted-in devbox after you select another thread.
|
|
8
8
|
|
|
9
9
|
## Runtime Status
|
|
10
10
|
|
|
@@ -31,6 +31,42 @@ that protection sooner. When the limit expires, normal idle sleep can resume;
|
|
|
31
31
|
the limit does not terminate the command. You can still sleep the machine
|
|
32
32
|
yourself.
|
|
33
33
|
|
|
34
|
+
### Scheduled checks and keep-awake requests
|
|
35
|
+
|
|
36
|
+
An agent can save one later check in its current thread, from one minute to
|
|
37
|
+
24 hours ahead. The box can sleep until then. At the requested time, boxes.dev
|
|
38
|
+
will try to wake it and start the saved prompt when the thread is idle,
|
|
39
|
+
behind any queued user messages. If the check cannot start within 30 minutes,
|
|
40
|
+
the thread will show a notice. Billing, awake-capacity and sign-in limits
|
|
41
|
+
still apply. Starting a check does not mean its work has finished.
|
|
42
|
+
|
|
43
|
+
For continuous local work, an agent can request that the box stay awake for
|
|
44
|
+
20 minutes by default, up to four hours. This uses box-hours at the current
|
|
45
|
+
size even while waiting; the thread shows the deadline and estimated usage.
|
|
46
|
+
Larger boxes use more box-hours. Frequent scheduled checks can also keep a
|
|
47
|
+
box awake continuously if each check and its normal idle timeout overlap.
|
|
48
|
+
|
|
49
|
+
The thread list shows a timer for a saved check or a power icon for a
|
|
50
|
+
keep-awake request. Open the thread to see the reason and time above the
|
|
51
|
+
composer. Choose **Cancel** to end that saved request; the control also works
|
|
52
|
+
while the box sleeps. Once a check is starting, use the ordinary **Stop**
|
|
53
|
+
control to interrupt its response. Stop alone does not cancel a future check
|
|
54
|
+
or keep-awake request. A pending Claude-native timer is shown read-only;
|
|
55
|
+
manage that timer through the thread's native controls.
|
|
56
|
+
|
|
57
|
+
Cancelling or reaching a keep-awake deadline releases that request's
|
|
58
|
+
protection. It does not kill a command or guarantee immediate sleep: other
|
|
59
|
+
work, another thread's request, automatic background protection and the normal
|
|
60
|
+
idle timeout still apply. Explicit sleep, reset or reboot ends keep-awake
|
|
61
|
+
requests. Scheduled checks remain after sleep or reboot and can wake the box
|
|
62
|
+
later; inspect the next check in the power menu before sleeping it. Archive
|
|
63
|
+
or delete a thread, or destroy its box, to cancel its pending requests.
|
|
64
|
+
New devboxes made from snapshots do not inherit these requests.
|
|
65
|
+
|
|
66
|
+
If delivery could not be confirmed, inspect the thread before trying again.
|
|
67
|
+
boxes.dev will not automatically resend an uncertain check. This helps avoid
|
|
68
|
+
repeating a deployment or similar operation after a lost response.
|
|
69
|
+
|
|
34
70
|
## Selected Runtime
|
|
35
71
|
|
|
36
72
|
Most runtime tools route to the selected thread:
|
|
@@ -122,8 +158,9 @@ service, exec fails explicitly and does not fall back to another transport.
|
|
|
122
158
|
|
|
123
159
|
Open Ports from the desktop titlebar. The menu shows the detected ports for the
|
|
124
160
|
selected Template box or devbox, whether each port is forwarded, and the reason
|
|
125
|
-
when it is not. Ordinary localhost forwards
|
|
126
|
-
|
|
161
|
+
when it is not. Ordinary localhost forwards follow selection unless you have
|
|
162
|
+
chosen to keep them on one box; stable local URLs remain active for every
|
|
163
|
+
opted-in devbox.
|
|
127
164
|
|
|
128
165
|
Each row shows the remote port and the local target. When boxes.dev can identify
|
|
129
166
|
the process, it may also show the process name, command, PID, or a service label
|
|
@@ -137,28 +174,65 @@ or generated `.localhost` URL. Custom hostnames that happen to resolve to the
|
|
|
137
174
|
same local port are rejected; use the URL shown in the Ports menu instead. TLS,
|
|
138
175
|
databases, SSH, and other non-HTTP forwarding continue as raw TCP connections.
|
|
139
176
|
|
|
140
|
-
Use the **
|
|
141
|
-
|
|
142
|
-
saved
|
|
177
|
+
Use the **Port forwarding** switch at the top of the Ports menu to stop or
|
|
178
|
+
resume ordinary localhost forwarding for that project. Turning it off will preserve detected
|
|
179
|
+
ports, saved rules, and your choice of localhost owner. Local URLs have their
|
|
180
|
+
own switch and remain available independently.
|
|
181
|
+
|
|
182
|
+
### Keep localhost on one devbox
|
|
183
|
+
|
|
184
|
+
To keep watching an app while you work in other threads, select its devbox,
|
|
185
|
+
open **Ports**, and choose the computer icon beside the **Port forwarding** switch, labeled
|
|
186
|
+
**Keep localhost on this devbox**. The icon will turn amber and gain a dot.
|
|
187
|
+
All of that devbox's eligible ports, including newly detected ports, will stay
|
|
188
|
+
on localhost when you select another thread, project, or new-thread draft.
|
|
189
|
+
The choice is saved for your account on this computer and survives desktop app
|
|
190
|
+
restarts. It can also target a Template box.
|
|
191
|
+
The devbox's right-click menu and the Template box's actions menu offer the
|
|
192
|
+
same keep and release actions.
|
|
193
|
+
|
|
194
|
+
An amber computer icon in the sidebar marks the chosen box. On another devbox,
|
|
195
|
+
the Ports menu still shows that devbox's ports, with an amber
|
|
196
|
+
**localhost is on {name}** pill explaining why ordinary forwarding is inactive.
|
|
197
|
+
Choose the name to return to the box using localhost. Choose the pill's **X**,
|
|
198
|
+
or the enabled computer icon on that box, to let localhost follow selection
|
|
199
|
+
again. Choosing the computer icon on a different box will move localhost there.
|
|
200
|
+
On a new-thread draft, **Ports** remains available to inspect or release the
|
|
201
|
+
chosen box.
|
|
202
|
+
|
|
203
|
+
Keeping localhost does not freeze a branch, start an app, or keep the box awake.
|
|
204
|
+
If it sleeps, select it and use the existing wake control. If it is removed or
|
|
205
|
+
becomes unavailable, localhost stays assigned until you release it or choose
|
|
206
|
+
another box. Other tools, including Terminal and Git, still follow selection.
|
|
207
|
+
|
|
208
|
+
Signing in to a Template box MCP temporarily forwards only its sign-in callback
|
|
209
|
+
port. Your app's other ports stay on the box you chose. If that callback port is
|
|
210
|
+
busy, the sign-in panel will explain the conflict instead of moving your app.
|
|
211
|
+
|
|
212
|
+
### Local URLs
|
|
143
213
|
|
|
144
214
|
Turn on **Local URLs** for a devbox to give it a stable generated
|
|
145
215
|
`<name>.localhost:<port>` URL for each detected HTTP app on an unprivileged
|
|
146
216
|
port. You can turn it on before any app is running; each HTTP port gets its
|
|
147
217
|
URL as its app starts, using the same hostname with its own port number.
|
|
148
|
-
While the devbox is
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
218
|
+
While the awake devbox is selected, a port's local URL is released when its app
|
|
219
|
+
stops. Existing addresses remain allocated while the devbox is unselected and
|
|
220
|
+
refresh when you return. If localhost is also kept on that devbox, newly
|
|
221
|
+
detected HTTP apps continue getting Local URLs while you work elsewhere. The
|
|
222
|
+
hostname and preference survive desktop app restarts. Its active URLs also
|
|
223
|
+
stay in place when the devbox sleeps.
|
|
153
224
|
|
|
154
225
|
Stable local URLs use plain HTTP and do not require an administrator prompt or
|
|
155
226
|
a local certificate. For their included ports, they replace the ordinary
|
|
156
|
-
`localhost` forwards that follow
|
|
227
|
+
`localhost` forwards that follow selection. If you also keep localhost on that
|
|
228
|
+
devbox, both addresses remain available. By default Local URLs do not
|
|
157
229
|
wake a sleeping devbox. Turn on **Wake on request** to opt in. Requests can
|
|
158
230
|
wake the devbox repeatedly and use box-hours. Turn **Local URLs** off to
|
|
159
|
-
release the stable URLs
|
|
160
|
-
|
|
161
|
-
a different port.
|
|
231
|
+
release the stable URLs. Ordinary forwarding will follow your localhost
|
|
232
|
+
selection or saved owner. If another local process owns an exact port,
|
|
233
|
+
boxes.dev reports the conflict instead of choosing a different port.
|
|
234
|
+
|
|
235
|
+
### Public app links
|
|
162
236
|
|
|
163
237
|
For a detected HTTP port, hover its row and choose the **Share publicly**
|
|
164
238
|
globe action to create an HTTPS public link for that exact port. Anyone with
|
|
@@ -171,17 +245,26 @@ active; Project URL traffic does not. Public links do not wake a sleeping
|
|
|
171
245
|
devbox: while the devbox sleeps, visitors see an unavailable page and the
|
|
172
246
|
Ports menu marks the link as paused.
|
|
173
247
|
|
|
248
|
+
Public links and Project URLs pass their public hostname to the app. If Vite
|
|
249
|
+
rejects those requests with "Blocked request. This host is not allowed", add
|
|
250
|
+
`'.onboxes.dev'` to the existing `server.allowedHosts` list in the Vite config
|
|
251
|
+
and restart the server if it does not restart on its own. The leading dot
|
|
252
|
+
matches every public link and Project URL, so sharing the port again does not
|
|
253
|
+
need another change. Do not set `allowedHosts: true`, which turns the check
|
|
254
|
+
off.
|
|
255
|
+
|
|
174
256
|
If recovery replaces the machine, boxes.dev will revoke its old public links.
|
|
175
257
|
Share the app again on the recovered machine to get a new URL.
|
|
176
258
|
|
|
177
|
-
|
|
178
|
-
button shows that
|
|
179
|
-
copy, open, and stop sharing, and the menu's **Public links** group keeps that
|
|
259
|
+
With a box selected, the Ports button and menu cover that Template box or
|
|
260
|
+
devbox. The button shows that box's active-link count, each detected port row
|
|
261
|
+
offers copy, open, and stop sharing, and the menu's **Public links** group keeps that
|
|
180
262
|
machine's links whose application is no longer detected visible and
|
|
181
263
|
individually stoppable. Every active link in the project lives in the
|
|
182
|
-
**Public links** sidebar
|
|
183
|
-
while at least one link is active
|
|
184
|
-
lets you open, copy, or stop sharing any link
|
|
264
|
+
**Public links** page, opened from the sidebar beside **Project URLs**. The
|
|
265
|
+
sidebar row appears while at least one link is active. The page names the
|
|
266
|
+
box that owns each link and lets you open, copy, or stop sharing any link
|
|
267
|
+
without switching boxes; the
|
|
185
268
|
Ports menu's **All public links…** entry jumps there. Choosing **Stop
|
|
186
269
|
sharing** stops that boxes.dev public URL and sharing the port again later
|
|
187
270
|
creates a new URL. It does not stop the application or change another network
|
|
@@ -211,11 +294,13 @@ returns. After the app returns, the public link can continue showing the
|
|
|
211
294
|
unavailable page for up to one minute while its availability refreshes; retry
|
|
212
295
|
the link after that interval.
|
|
213
296
|
|
|
297
|
+
### Project forwarding rules
|
|
298
|
+
|
|
214
299
|
Choose **Configure port forwarding…** for project-level rules. The same
|
|
215
300
|
configuration applies to every real machine in the project: the Template box
|
|
216
301
|
and devboxes in an ordinary project, or only assigned devboxes in a Team
|
|
217
|
-
Template member project.
|
|
218
|
-
|
|
302
|
+
Template member project. These rules also apply when you keep localhost on a
|
|
303
|
+
box. Stable local URLs remain active for every opted-in devbox. New projects
|
|
219
304
|
forward detected ports to the matching local port by default. Configuration can
|
|
220
305
|
change that default, allow or exclude individual ports and inclusive ranges,
|
|
221
306
|
and map remote ports or ranges to different local ports.
|
|
@@ -21,7 +21,7 @@ missing project dependencies, checks important app entrypoints, and writes a
|
|
|
21
21
|
setup summary or follow-up list when it finishes.
|
|
22
22
|
|
|
23
23
|
The setup thread's final reply explains what was validated and introduces the
|
|
24
|
-
Template box, snapshots, **New
|
|
24
|
+
Template box, snapshots, **New thread**, and additional threads on an
|
|
25
25
|
existing devbox. It also explains how to get started with Slack, Linear,
|
|
26
26
|
automations, and agent delegation and messaging. You can keep talking in that
|
|
27
27
|
thread for help with setup or using boxes.dev. The reply can arrive before
|
|
@@ -221,6 +221,26 @@ performs immediate AWS-side revocation. Use the organization's AWS controls
|
|
|
221
221
|
when that is required. See `aws.md` for setup, profile precedence, and current
|
|
222
222
|
container limits.
|
|
223
223
|
|
|
224
|
+
The Google Cloud integration stores the user's renewable Google sign-in
|
|
225
|
+
encrypted in boxes.dev and does not copy it onto Template boxes or devboxes.
|
|
226
|
+
When a tool on a connected box needs credentials, the local boxes.dev service
|
|
227
|
+
requests a short-lived Google access token for the project's selected Google
|
|
228
|
+
Cloud project and keeps it only in memory; no credentials file is written.
|
|
229
|
+
Removing Google Cloud from one project stops future tokens for that project.
|
|
230
|
+
Signing out of Google Cloud everywhere deletes the stored sign-in, disconnects
|
|
231
|
+
all of the user's boxes.dev projects, and asks Google to revoke boxes.dev's
|
|
232
|
+
access. Tokens a tool already holds can last until they expire, usually within
|
|
233
|
+
an hour. See `google-cloud.md` for setup, precedence, and current limits.
|
|
234
|
+
|
|
235
|
+
The Vercel integration stores the user's renewable Vercel CLI sign-in encrypted
|
|
236
|
+
in boxes.dev and does not copy it onto Template boxes or devboxes. The Vercel
|
|
237
|
+
CLI can't request credentials on demand, so boxes.dev writes a short-lived
|
|
238
|
+
Vercel access token to the CLI's own login file on each of the user's boxes and
|
|
239
|
+
replaces it before it expires. Anything running as the user on a box can read
|
|
240
|
+
that token. Disconnecting deletes the stored sign-in, ends it on Vercel, and
|
|
241
|
+
removes the file from each box. See `vercel.md` for setup, SAML teams, and
|
|
242
|
+
logout behavior.
|
|
243
|
+
|
|
224
244
|
Users can also link or unlink their own Slack and Linear identities from the
|
|
225
245
|
Account page when the team integration is installed.
|
|
226
246
|
|
|
@@ -300,6 +300,43 @@ The template's editing machine does not receive these settings. See
|
|
|
300
300
|
`threads-and-agents.md` for how boxes.dev writes the settings on each box, how
|
|
301
301
|
lists combine, and which keys are reserved.
|
|
302
302
|
|
|
303
|
+
## Team Agent Permissions
|
|
304
|
+
|
|
305
|
+
The **Agent permissions** card on the Team Template page sets the project
|
|
306
|
+
agent permissions for projects that use the template: creating devboxes and
|
|
307
|
+
threads, destroying devboxes, messaging other agents and teammates' agents,
|
|
308
|
+
updating thread titles, folder access, and reading other threads. Only team
|
|
309
|
+
admins can edit it. Until an admin saves it, each project keeps its own
|
|
310
|
+
permissions.
|
|
311
|
+
|
|
312
|
+
For managed projects, the admin chooses one of two modes:
|
|
313
|
+
|
|
314
|
+
- **Editable defaults:** each Member project follows the template's values
|
|
315
|
+
until the member changes a permission in Project settings. A permission the
|
|
316
|
+
member changed stays as they set it when the template changes. **Use Team
|
|
317
|
+
Template permissions** in Project settings returns every permission to the
|
|
318
|
+
template's values.
|
|
319
|
+
- **Locked:** every Member project uses the template's values, and members
|
|
320
|
+
can't change them in Project settings. Locking replaces any permissions
|
|
321
|
+
members chose themselves. Unlocking keeps everyone on the template's values
|
|
322
|
+
until a member changes one.
|
|
323
|
+
|
|
324
|
+
The first time an admin saves editable defaults for a template that already
|
|
325
|
+
has Member projects, boxes.dev asks whether those projects should move to the
|
|
326
|
+
template's values or keep their current permissions as the members' own
|
|
327
|
+
choices. Either way, new Member projects will follow the template.
|
|
328
|
+
|
|
329
|
+
In both modes, members can still change permissions on an individual box from
|
|
330
|
+
its thread header, and agents can still request permission for their own box.
|
|
331
|
+
While the template is locked, a permission request can't be approved for the
|
|
332
|
+
whole project. Independent projects copy the template's values when they are
|
|
333
|
+
created; their owners can change them afterward, and the lock doesn't apply.
|
|
334
|
+
|
|
335
|
+
An agent with Team Template access can read and change these permissions with
|
|
336
|
+
`dvb-onbox team-template settings` (the `agent_permissions` section in
|
|
337
|
+
`onbox-agent-tools.md`). Only a team admin can grant that access, and the
|
|
338
|
+
first-save and lock choices above still apply.
|
|
339
|
+
|
|
303
340
|
## Settings For New Projects
|
|
304
341
|
|
|
305
342
|
The **Settings for new projects** card controls everything else a new project
|
|
@@ -360,6 +397,14 @@ to establish its shared saved environment. A failure preserves the prior saved
|
|
|
360
397
|
version, discards any machine that may have been partly changed, and never
|
|
361
398
|
modifies an admin's editing session.
|
|
362
399
|
|
|
400
|
+
boxes.dev prepares a few devboxes for each member project ahead of time. For a
|
|
401
|
+
minute or two after a maintenance run makes a new saved version current, while
|
|
402
|
+
those are replaced, a new devbox can start from one prepared from the previous
|
|
403
|
+
saved version if the startup and teardown scripts and the box size have not
|
|
404
|
+
changed. That devbox keeps the previous version's files and repositories. A
|
|
405
|
+
version an admin saves from an editing session applies to every new devbox as
|
|
406
|
+
soon as it becomes current.
|
|
407
|
+
|
|
363
408
|
A maintenance trigger waits behind an active editing session and starts after
|
|
364
409
|
the session closes. Multiple triggers coalesce into the pending run. If the
|
|
365
410
|
script succeeds but saving fails, the detail page offers **Retry save** and
|