@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.
@@ -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, and Claude and Codex agent settings
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, and agent settings. Omit `--template` to select the current editing
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; each run starts a new thread on
424
- a new devbox. See [Automations](automations.md) for how they work.
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, `execution`, and `trigger` are required. Other keys
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 and uses box-hours. When retrying, reuse the same
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` is Codex-only and
1108
- changes the exact active turn. `queue` is the strict active-only form and
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. `threads result` returns the complete stored final response for one exact
1181
- terminal turn and automatically assembles its transport pages. Use it instead
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 the same thread fields as a listing and a `match` with the
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. Results retain that order even
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. Retrying with the same key and message recovers that outcome
1450
- without another delivery. Changing the recipient, message, attachments, or
1451
- idle-only policy under that key fails with `idempotency_key_reused`. Use a new
1452
- key for each distinct message. If delivery was skipped because the recipient
1453
- was busy, use a new key if you later decide to send it again.
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, ordinary `localhost` forwarding, Terminal, Files, and Git
4
- follow the selected runtime. If you select the Template box, they use the
5
- Template box. If you select a devbox thread, they use that devbox. Stable local
6
- URLs are the exception: an opted-in devbox keeps those URLs active after you
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 belong to the selected Template box
126
- or devbox; stable local URLs remain active for every opted-in devbox.
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 **Forwarding** switch in the Ports menu to release or restore all
141
- desktop-owned local ports quickly. Turning it off keeps the detected ports and
142
- saved configuration visible; the titlebar says **Ports off**.
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 awake, a port's local URL is released when its app stops,
149
- like an ordinary forward. The hostname and preference stay attached to that
150
- devbox when you select another thread and after you restart the desktop app,
151
- and its stable listeners remain active while it is unselected. Its active URLs
152
- also stay in place when the devbox sleeps.
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 the selected runtime. By default they do not
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 and restore ordinary forwarding. If another local
160
- process owns an exact port, boxes.dev reports the conflict instead of choosing
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
- The Ports button and menu cover only the selected Template box or devbox. The
178
- button shows that machine's active-link count, each detected port row offers
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 section beside **Project URLs**. That section appears
183
- while at least one link is active, names the machine that owns each link, and
184
- lets you open, copy, or stop sharing any link without switching machines; the
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. Ordinary localhost forwarding follows the selected
218
- machine. Stable local URLs remain active for every opted-in devbox. New projects
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 devbox + thread**, and additional threads on an
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