@boxes-dev/dvb-runtime 1.0.1103 → 1.0.1105

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.
Files changed (33) hide show
  1. package/dist/agent-init-guides/agent-config.md +34 -0
  2. package/dist/agent-init-guides/app.md +6 -5
  3. package/dist/agent-init-guides/flow.md +72 -12
  4. package/dist/agent-init-guides/git-ssh.md +9 -4
  5. package/dist/agent-init-guides/manifest.md +6 -0
  6. package/dist/agent-init-guides/recovery.md +22 -0
  7. package/dist/agent-init-guides/running.md +12 -0
  8. package/dist/agent-init-guides/untracked.md +2 -1
  9. package/dist/bin/dvb.mjs +1228 -1758
  10. package/dist/bin/dvbd.mjs +6 -6
  11. package/dist/product-docs/references/agent-tools.md +32 -5
  12. package/dist/product-docs/references/automations.md +18 -3
  13. package/dist/product-docs/references/cli.md +6 -4
  14. package/dist/product-docs/references/core-concepts.md +1 -1
  15. package/dist/product-docs/references/desktop-workbench.md +28 -3
  16. package/dist/product-docs/references/environment-setup-validation.md +22 -0
  17. package/dist/product-docs/references/files-git-and-review.md +32 -18
  18. package/dist/product-docs/references/fork-workflows.md +6 -3
  19. package/dist/product-docs/references/getting-started.md +2 -1
  20. package/dist/product-docs/references/index.md +2 -1
  21. package/dist/product-docs/references/linear.md +15 -0
  22. package/dist/product-docs/references/member-managed-files.md +2 -1
  23. package/dist/product-docs/references/mobile.md +63 -17
  24. package/dist/product-docs/references/onbox-agent-tools.md +224 -66
  25. package/dist/product-docs/references/ports-terminal-and-runtime.md +5 -3
  26. package/dist/product-docs/references/project-setup.md +67 -17
  27. package/dist/product-docs/references/security-and-data.md +3 -2
  28. package/dist/product-docs/references/slack.md +8 -5
  29. package/dist/product-docs/references/threads-and-agents.md +25 -8
  30. package/dist/product-docs/references/troubleshooting.md +7 -5
  31. package/dist/product-docs/references/unattended-work.md +5 -0
  32. package/dist/prompts/local-services-scan.md +3 -4
  33. package/package.json +2 -2
@@ -185,9 +185,11 @@ response. If the user asks you not to send feedback, don't.
185
185
 
186
186
  Use the `boxes-agent-extensions` skill when a user asks to install, update, or
187
187
  remove a plugin or MCP. Supported remote HTTP MCPs belong in **Integrations →
188
- MCPs**. Codex-synced plugins use Codex's own trusted install flow. Local Codex
189
- plugins, Claude plugins, and unsupported/local MCPs belong on the Template box
190
- when they should become part of future devboxes.
188
+ MCPs**. You can add one from the box with the agent's native `codex mcp add`
189
+ or `claude mcp add` command, then give the user the printed sign-in link; the
190
+ skill covers the details. Codex-synced plugins use Codex's own trusted install
191
+ flow. Local Codex plugins, Claude plugins, and unsupported/local MCPs belong on
192
+ the Template box when they should become part of future devboxes.
191
193
 
192
194
  A managed project has no personal Template box. Native-only
193
195
  Plugins and unsupported/local MCPs installed on one of its devboxes stay on
@@ -788,7 +790,7 @@ The request values are `create-devboxes-and-threads`,
788
790
  `create-team-templates`, `update-thread-titles`,
789
791
  `move-devboxes-to-folders`, `create-devbox-folders`,
790
792
  `edit-devbox-lifecycle`, `edit-template-maintenance`, `destroy-devbox`,
791
- `destroy-created-devboxes`, `read-project-threads`, `read-user-threads`, `read-shared-threads`,
793
+ `destroy-created-devboxes`, `destroy-project-devboxes`, `read-project-threads`, `read-user-threads`, `read-shared-threads`,
792
794
  `read-team-threads`, `control-created-threads`, `control-project-threads`,
793
795
  `control-user-threads`, `message-agents`, `message-teammates-agents`, `edit-template-box`,
794
796
  `edit-team-template`, `edit-project-settings`, `edit-personal-environment`, and `edit-automations`.
@@ -845,7 +847,8 @@ the requesting box. See `team-template.md` for how a Team Template sets these
845
847
  project permissions.
846
848
 
847
849
  The **Agent permissions** switches show each box's effective on/off settings.
848
- **Read threads** and **Pause and resume agents** show a scope icon and chevron;
850
+ **Read threads**, **Pause and resume agents**, and **Destroy and archive
851
+ devboxes** show a scope icon and chevron;
849
852
  open the menu for labels and **Off**. Folder access shows its access level.
850
853
  Changing a control saves the
851
854
  choice for that box, independently of future project changes. Change shared
@@ -856,8 +859,7 @@ have permissions saved individually; turn those off in the box's Agent
856
859
  permissions control when needed. In the mobile app, the box's controls are in
857
860
  an open thread's **…** menu under **Agent permissions**, and the shared
858
861
  settings are under **Agent permissions** in the project's gear button
859
- (**Project settings**). **Message teammates' agents** is set only in the
860
- desktop app.
862
+ (**Project settings**).
861
863
 
862
864
  Run the request once and wait. `granted` and `already_granted` are successful;
863
865
  `denied`, `expired`, and `permission_request_pending` are non-successful
@@ -907,6 +909,112 @@ When a user-required title change returns `title_editing_disabled`, request
907
909
  only `update-thread-titles` through the Agent permissions command above. Do not
908
910
  request it merely to perform an optional rename after unrelated work.
909
911
 
912
+ ## User Presence
913
+
914
+ An agent can check whether the user who owns its thread has that thread open
915
+ in the boxes.dev desktop or mobile app:
916
+
917
+ ```bash
918
+ dvb-onbox threads presence
919
+ dvb-onbox threads presence --json
920
+ ```
921
+
922
+ The command reads recent reports from the desktop and mobile apps. It accepts
923
+ no thread ID, reports only on the owner of the current thread, and needs no
924
+ permission. With `--json`, it prints:
925
+
926
+ ```json
927
+ {
928
+ "schemaVersion": 1,
929
+ "ok": true,
930
+ "requestId": "…",
931
+ "desktopApp": {
932
+ "status": "focused_showing_something_else",
933
+ "computerInUse": true,
934
+ "thisThreadLastShownSecondsAgo": 140
935
+ },
936
+ "mobileApp": {
937
+ "status": "no_recent_report",
938
+ "thisThreadLastShownSecondsAgo": null
939
+ }
940
+ }
941
+ ```
942
+
943
+ `status` uses the same values for both apps and describes the last 45 seconds.
944
+ An app is focused when it's the window or app the user is using; a desktop
945
+ window behind other windows or a mobile app in the background isn't focused.
946
+
947
+ | `status` | Meaning |
948
+ | --- | --- |
949
+ | `focused_showing_this_thread` | The app is focused and shows the thread running this command. |
950
+ | `focused_showing_something_else` | The app is focused and shows another thread or screen. |
951
+ | `open_not_focused` | The app is open but not focused. |
952
+ | `no_recent_report` | The app hasn't reported in the last 45 seconds. It may be closed, or the device may be asleep, offline, or idle. |
953
+
954
+ The mobile app stops reporting once it's in the background, so its
955
+ `open_not_focused` lasts only about 45 seconds before it becomes
956
+ `no_recent_report`.
957
+
958
+ `thisThreadLastShownSecondsAgo` is how many seconds ago the app last showed
959
+ this thread, looking back 5 minutes. It's `0` while the status is
960
+ `focused_showing_this_thread`, and `null` when the app hasn't shown this thread
961
+ in the last 5 minutes. It counts only time while the app was focused, and it
962
+ can be up to 15 seconds older than the moment the user moved away.
963
+
964
+ `desktopApp.computerInUse` describes the computer running the desktop app:
965
+
966
+ | `computerInUse` | Meaning |
967
+ | --- | --- |
968
+ | `true` | Someone used the computer in the last 5 minutes, and the screen is unlocked. |
969
+ | `false` | The computer has had no keyboard or mouse input for 5 minutes, or the screen is locked. |
970
+ | `null` | Unknown, for example because the desktop app hasn't reported in the last 45 seconds or is an older version. |
971
+
972
+ `mobileApp` describes only the boxes.dev app. It doesn't say whether the phone
973
+ is nearby, unlocked, or usable.
974
+
975
+ `desktopApp.status` and `computerInUse` are independent: a window can show this
976
+ thread while nobody has touched the computer for 10 minutes. A desktop window
977
+ counts as showing the thread when the thread's conversation or agent terminal
978
+ is visible. Settings, project settings, a teammate's thread, the box terminal,
979
+ the IDE, or a full-window Files, Git, or Browser pane doesn't count.
980
+
981
+ Use presence to decide what to do next:
982
+
983
+ - Before a step that only works if the user acts soon, such as approving a
984
+ sign-in, entering a one-time code, or tapping a prompt, check presence. If
985
+ the mobile app isn't focused and the desktop app reports `no_recent_report`
986
+ or `computerInUse: false`, don't start the time-limited step. End your
987
+ response with what you need, so the user can act when they're back.
988
+ - When instructions differ by device, such as where to open a link, match the
989
+ focused app. If both are focused, give both.
990
+ - Only `focused_showing_this_thread` means this thread is on screen. With
991
+ `focused_showing_something_else`, the user has the app open but isn't
992
+ looking at this thread, so they may not see your message right away. Older
993
+ app versions don't report the open thread, so they show up as
994
+ `focused_showing_something_else` even on this thread, and their
995
+ `thisThreadLastShownSecondsAgo` is always `null`.
996
+ - A recent `thisThreadLastShownSecondsAgo` means the user was following this
997
+ thread a moment ago, for example before switching to check another thread.
998
+ - `no_recent_report` and `open_not_focused` don't prove that the user is away
999
+ or that their phone is out of reach.
1000
+ - Don't tell the user that a time-limited step is safe to retry unless you
1001
+ know it is.
1002
+ - Don't check repeatedly to wait for the user to come back. To check on work
1003
+ later, use the unattended work commands.
1004
+
1005
+ Failures exit with status 2. With `--json`, they print
1006
+ `{"schemaVersion": 1, "ok": false, "errorCode", "message", "retryable"}`;
1007
+ otherwise only the message is printed to stderr. These are the only error
1008
+ codes:
1009
+
1010
+ | `errorCode` | Meaning | `retryable` |
1011
+ | --- | --- | --- |
1012
+ | `invalid_request` | The command got an argument other than `--json`. | `false` |
1013
+ | `thread_context_unavailable` | The command isn't running inside a managed Codex or Claude thread on this box. | `false` |
1014
+ | `daemon_update_required` | The local boxes.dev service needs an update first. | `false` |
1015
+ | `unauthorized` | boxes.dev rejected this box's credentials. | `false` |
1016
+ | `service_unavailable` | Presence is temporarily unavailable. Wait a minute and try again. | `true` |
1017
+
910
1018
  ## Pull Request Follow-ups
911
1019
 
912
1020
  boxes.dev can send a managed Codex or Claude thread a message when its pull
@@ -940,6 +1048,11 @@ The commands use the repository that contains the working directory. Pass
940
1048
  repositories and the project has more than one. They always act for the thread
941
1049
  that runs them.
942
1050
 
1051
+ Follow-ups only work for the project's repositories and their worktrees. In a
1052
+ separate clone of another repository, the commands return `repo_required` and
1053
+ `gh pr create` prints nothing about follow-ups; check that clone's pull
1054
+ requests with `gh` instead.
1055
+
943
1056
  `--triggers` takes a comma-separated list of `failed-checks`, `bot-reviews`,
944
1057
  `human-reviews`, and `conflicts`. Without it, `enable` turns on the project's
945
1058
  default follow-up events for a pull request that has no follow-ups and keeps
@@ -1362,12 +1475,20 @@ otherwise they are null. A later event can replace or clear them. `idle`
1362
1475
  describes activity, not successful completion. Muting does not hide this
1363
1476
  metadata.
1364
1477
 
1478
+ When an accepted child fails to start, list and read results include
1479
+ `startupFailure`, with a `reason` category such as `startup_timeout` and a
1480
+ `message` that explains the cause and what to do next. Otherwise
1481
+ `startupFailure` is null. A `threads wait` without `--turn` reports that child
1482
+ as `failed` with the same message, and `threads send` returns
1483
+ `thread_not_ready` with it. Retrying the start with its original idempotency
1484
+ key returns the same failure, so use a new key to try again.
1485
+
1365
1486
  `threads result` returns the complete stored final response for one
1366
1487
  exact terminal turn and automatically assembles its transport pages. Use it instead
1367
1488
  of asking the child to summarize a shortened `threads read` preview. When
1368
1489
  `threads wait` omits `--turn`, it snapshots the current active turn once. If
1369
1490
  there is no active turn, it returns `idle` with any available latest stop
1370
- metadata as context. That stop can belong to an earlier assignment, so compare
1491
+ metadata as context, or `failed` if the child failed to start. That stop can belong to an earlier assignment, so compare
1371
1492
  its turn ID with the work you are checking. A completed wait includes that
1372
1493
  same complete response as `output.text`; Ctrl+C stops only the local wait.
1373
1494
  `threads events` emits durable lifecycle events with
@@ -1427,10 +1548,10 @@ Prompt files are limited to 32 KiB.
1427
1548
 
1428
1549
  Delegation does not grant destruction permission or access to unrelated
1429
1550
  threads. To clean up a devbox created this way, see
1430
- [Destroy And Archive Created Devboxes](#destroy-and-archive-created-devboxes).
1551
+ [Destroy And Archive Other Devboxes](#destroy-and-archive-other-devboxes).
1431
1552
  To archive finished threads started on the current devbox, see
1432
1553
  [Archive Created Threads On This Devbox](#archive-created-threads-on-this-devbox). Read-only thread and project discovery has its own permission below.
1433
- `dvb-onbox` does not expose arbitrary direct exec, services, or generic machine
1554
+ `dvb-onbox` does not expose arbitrary direct exec or generic machine
1434
1555
  management. The current-box public link commands above are its only port-control
1435
1556
  surface.
1436
1557
 
@@ -1510,6 +1631,8 @@ Scoped listings and status lookups include nullable `lastStopReason`,
1510
1631
  latest lifecycle event when it is terminal: `completed`, `interrupted`, or a
1511
1632
  failure category such as `usage_limit_exceeded`. An unclassified failure is
1512
1633
  `unknown`; missing events and newer nonterminal activity return null.
1634
+ Listings, status lookups, and reads also include a nullable `startupFailure`
1635
+ when the thread's latest startup attempt failed.
1513
1636
 
1514
1637
  To find idle threads stopped by exhausted usage or credits, run:
1515
1638
 
@@ -1774,8 +1897,7 @@ An agent can also message a teammate's Codex or Claude thread in any of the
1774
1897
  teammate's projects. This needs **Message teammates' agents** on both
1775
1898
  devboxes: the one sending and the recipient thread's current devbox. It is
1776
1899
  separate from **Message other agents**, off by default, and set by each person
1777
- in the desktop app for their own projects and boxes, like the other Agent
1778
- permissions.
1900
+ for their own projects and boxes, like the other Agent permissions.
1779
1901
 
1780
1902
  Use the same command. `--to` takes the thread ID named in a received message,
1781
1903
  or a `thr_` ID from **Copy thread ID** or `dvb-onbox threads list --scope team`.
@@ -1803,7 +1925,7 @@ recipient's side wakes until the message is allowed, and the waking and model
1803
1925
  usage count against the recipient's account. **Always allow** covers one
1804
1926
  sending thread and one receiving thread, including that pair's messages
1805
1927
  already waiting; the recipient can remove it under **Always allowed in this
1806
- thread** in that thread's Agent permissions in the desktop app.
1928
+ thread** in that thread's Agent permissions, on desktop and mobile.
1807
1929
 
1808
1930
  The receiving agent sees a first line naming the teammate: "Sent by <name>, a
1809
1931
  teammate of your user. Your user allowed this message to reach you." Treat the
@@ -1834,9 +1956,8 @@ The project setting applies to existing and future devboxes without an
1834
1956
  individual override. After a `destruction_disabled` error, request
1835
1957
  `destroy-devbox`; the owner can choose **Allow** or **Always allow for project**.
1836
1958
  Either way, this permission lets agents destroy only their own ordinary devbox.
1837
- Template boxes and other devboxes cannot be targeted. To destroy devboxes that
1838
- agents on this box created, see
1839
- [Destroy And Archive Created Devboxes](#destroy-and-archive-created-devboxes).
1959
+ To destroy the user's other devboxes, see
1960
+ [Destroy And Archive Other Devboxes](#destroy-and-archive-other-devboxes).
1840
1961
 
1841
1962
  Destruction permanently deletes the devbox's files and retains its thread
1842
1963
  history. It also stops automatic pull request follow-ups that the devbox's
@@ -1868,55 +1989,69 @@ dvb-onbox box cancel-destroy --json
1868
1989
  ```
1869
1990
 
1870
1991
  Any managed agent on the same devbox can cancel its pending request without
1871
- the destruction permission, including a request made by the box that created
1872
- the devbox. The command returns `cancelled`, or `not_pending`
1992
+ the destruction permission, including a request made from another box. The command returns `cancelled`, or `not_pending`
1873
1993
  with a null `requestId` if there is nothing to cancel. Once archival has
1874
1994
  started, it returns `destruction_started`; it cannot undo that handoff.
1875
1995
 
1876
- ## Destroy And Archive Created Devboxes
1996
+ ## Destroy And Archive Other Devboxes
1877
1997
 
1878
- An agent on a Template box or devbox can request destruction of an ordinary
1879
- devbox that an agent on the same box created with
1880
- `dvb-onbox threads start --target new-devbox`:
1998
+ An agent on a Template box or devbox can request destruction of another of the
1999
+ user's ordinary devboxes in the same project:
1881
2000
 
1882
2001
  ```bash
1883
2002
  dvb-onbox box destroy --devbox <devbox-id> --json
1884
2003
  ```
1885
2004
 
1886
- Use the `devboxId` returned by `threads start`. The separate **Destroy and
1887
- archive created devboxes** permission on the requesting box is off by default.
1888
- Enable it in the thread header's **Agent permissions**, or under **Agent
2005
+ Run it once for each devbox. Use the `devboxId` returned by `threads start`, or
2006
+ the `devboxId` that a `--scope project` thread listing reports for the user's
2007
+ own threads.
2008
+
2009
+ The requesting box's **Destroy and archive devboxes** permission decides which
2010
+ devboxes it can target. It is off by default and has two levels:
2011
+
2012
+ - **Created from this devbox** covers devboxes that an agent on the requesting
2013
+ box created with `dvb-onbox threads start --target new-devbox`. Devboxes
2014
+ where this box only started a thread, devboxes created by a created devbox,
2015
+ and devboxes created by restoring an archived thread are not included.
2016
+ - **In this project** covers all of the user's other ordinary devboxes in the
2017
+ project, including devboxes the user created.
2018
+
2019
+ Set it in the thread header's **Agent permissions**, or under **Agent
1889
2020
  permissions for this project** in Project settings. After a
1890
- `destruction_disabled` error, request `destroy-created-devboxes`; the owner can
1891
- choose **Allow** or **Always allow for project**. This permission is
1892
- independent of **Create devboxes and threads** and of the created devbox's own
1893
- **Destroy and archive this devbox** permission, and any agent on the
1894
- requesting box can use it. Devboxes created by another box, devboxes where this
1895
- box only started a thread, devboxes created by a created devbox, devboxes
1896
- created by restoring an archived thread, and Template boxes return
1897
- `devbox_not_found`.
2021
+ `destruction_disabled` error, request the permission the error names:
2022
+ `destroy-created-devboxes` for a devbox this box created, or
2023
+ `destroy-project-devboxes` for any other devbox. The owner can choose
2024
+ **Allow** or **Always allow for project**. This permission is independent of
2025
+ **Create devboxes and threads** and of the target devbox's own **Destroy and
2026
+ archive this devbox** permission, and any agent on the requesting box can use
2027
+ it. Template boxes, teammates' devboxes, and devboxes in other projects return
2028
+ `devbox_not_found`. Passing the current devbox's own ID returns
2029
+ `invalid_request`; see
2030
+ [Destroy And Archive The Current Devbox](#destroy-and-archive-the-current-devbox).
1898
2031
 
1899
2032
  Run this only when the user's task calls for it, such as after the devbox's
1900
- work has merged or has otherwise been preserved outside the machine.
2033
+ work has merged or has otherwise been preserved outside the machine. If it's
2034
+ unclear which devboxes the user means, ask before requesting destruction.
1901
2035
  Destruction permanently deletes the devbox's files and retains its thread
1902
2036
  history. It also stops automatic pull request follow-ups that the devbox's
1903
2037
  threads handle until another thread turns them on.
1904
2038
 
1905
2039
  The request waits for every agent and queued message on that devbox to finish,
1906
2040
  and boxes.dev wakes a sleeping devbox to archive it. New work submitted to the
1907
- devbox before destruction starts cancels the request, as does turning off the
1908
- permission on the requesting box. A request that stays pending for 30 minutes
1909
- expires. If the devbox already has a pending request, including one it made for
1910
- itself, the command returns `already_requested` with that request's ID. Pending
1911
- requests are also cancelled if the requesting box is destroyed first, so a box
1912
- that will destroy itself should first wait until its created devboxes are
1913
- archived.
1914
-
1915
- `accepted` means only that the request was saved. `threads list
1916
- --include-archived` shows the devbox's thread as archived once its history is
1917
- saved and deletion of the machine has started; that does not prove the machine
1918
- is gone. Listing delegated threads still requires **Create devboxes and
1919
- threads**.
2041
+ devbox before destruction starts cancels the request, as does turning off or
2042
+ narrowing the requesting box's permission so it no longer covers the devbox. A
2043
+ request that stays pending for 30 minutes expires. If the devbox already has a
2044
+ pending request, including one it made for itself, the command returns
2045
+ `already_requested` with that request's ID. Pending requests are also cancelled
2046
+ if the requesting box is destroyed first, so a box that will destroy itself
2047
+ should first wait until the other devboxes are archived.
2048
+
2049
+ `accepted` means only that the request was saved. Once a devbox's history is
2050
+ saved and deletion of the machine has started, its threads appear as archived
2051
+ in `threads list --include-archived` for devboxes this box created, or in a
2052
+ `--scope project` listing with `--include-archived`. That does not prove the
2053
+ machine is gone. Listing delegated threads requires **Create devboxes and
2054
+ threads**, and project listings require **Read threads**.
1920
2055
 
1921
2056
  To withdraw a pending request, run:
1922
2057
 
@@ -1924,15 +2059,16 @@ To withdraw a pending request, run:
1924
2059
  dvb-onbox box cancel-destroy --devbox <devbox-id> --json
1925
2060
  ```
1926
2061
 
1927
- Cancellation does not require a destroy permission and also withdraws a
1928
- request the devbox made for itself. It returns `cancelled`, or `not_pending`
1929
- with a null `requestId` if there is nothing to cancel. Once archival has
1930
- started, it returns `destruction_started`.
2062
+ Any agent on a box in the same project can cancel a pending request for one of
2063
+ the user's devboxes there. Cancellation does not require a destroy permission
2064
+ and also withdraws a request the devbox made for itself. It returns
2065
+ `cancelled`, or `not_pending` with a null `requestId` if there is nothing to
2066
+ cancel. Once archival has started, it returns `destruction_started`.
1931
2067
 
1932
2068
  ### Archive Created Threads On This Devbox
1933
2069
 
1934
- **Destroy and archive created devboxes** also lets any agent on an ordinary
1935
- devbox archive worker threads created there by agents on that same devbox,
2070
+ Either level of **Destroy and archive devboxes** also lets any agent on an
2071
+ ordinary devbox archive worker threads created there by agents on that same devbox,
1936
2072
  such as a worker started with `threads start --target current-devbox`:
1937
2073
 
1938
2074
  ```bash
@@ -2033,8 +2169,8 @@ update; do not install workstation `dvb` or call backend services directly.
2033
2169
  ## Project URL Participation
2034
2170
 
2035
2171
  A Project URL is configured for the project and one expected HTTP port. Once
2036
- that application is listening on the current devbox, inspect the project's URLs
2037
- and claim one without needing a project selector:
2172
+ that application is listening on the current devbox or Template box, inspect
2173
+ the project's URLs and claim one without needing a project selector:
2038
2174
 
2039
2175
  ```bash
2040
2176
  dvb-onbox url list --json
@@ -2042,11 +2178,18 @@ dvb-onbox url show <name> --json
2042
2178
  dvb-onbox url claim <name> --if-free --json
2043
2179
  ```
2044
2180
 
2181
+ These commands work on the project's devboxes and its Template box. A Team
2182
+ Template editing box isn't part of a project, so they report
2183
+ `project_box_required` there. In JSON output, `claimHolder.kind` is relative to
2184
+ the calling box: `this_devbox` means the current box, including the Template
2185
+ box, and `another_devbox` means any other box. `holderBoxKind` reports whether
2186
+ the holder is the `template_box` or a `devbox`.
2187
+
2045
2188
  `--if-free` is the safe startup default. Repeating it on the current holder is
2046
2189
  idempotent. It reports a conflict when another devbox holds the URL, even when
2047
2190
  that devbox's listener is temporarily unavailable; it never escalates to a
2048
2191
  takeover. Use `--take` only when the user or application deliberately intends
2049
- to move all newly authorized traffic to this devbox:
2192
+ to move all newly authorized traffic to this box:
2050
2193
 
2051
2194
  ```bash
2052
2195
  dvb-onbox url claim <name> --take --json
@@ -2062,19 +2205,30 @@ that makes the URL available to another devbox's `--if-free`:
2062
2205
  dvb-onbox url release <name> --json
2063
2206
  ```
2064
2207
 
2208
+ On the Template box, claim a URL only to test the app during setup or
2209
+ maintenance. A Template box claim never blocks a devbox: a devbox's
2210
+ `--if-free` claim takes the URL over, which will interrupt a test still running
2211
+ on the Template box. If a devbox already holds the URL, ask the user before
2212
+ using `--take`, because it will move that devbox's traffic to the Template box.
2213
+ Release the claim when testing is done. Otherwise, once the Template box
2214
+ sleeps, the project's Project URLs list will show the URL as not handling
2215
+ requests until a devbox claims it. `url browser-link` reports
2216
+ `devbox_required` on the Template box, because devboxes made from its snapshot
2217
+ would copy the browser's pin; test through the claim instead.
2218
+
2065
2219
  For a Project URL with webhook-multicast delivery, subscribe the current
2066
- devbox after its configured HTTP listener starts:
2220
+ box after its configured HTTP listener starts:
2067
2221
 
2068
2222
  ```bash
2069
2223
  dvb-onbox url subscribe <name> --json
2070
2224
  dvb-onbox url unsubscribe <name> --json
2071
2225
  ```
2072
2226
 
2073
- Subscription is URL-wide: the devbox receives every request whose configured
2227
+ Subscription is URL-wide: the box receives every request whose configured
2074
2228
  method/path resolves to webhook multicast. Repeating subscribe or unsubscribe
2075
2229
  is idempotent. A subscription is temporary and expires when the listener
2076
- disappears, the devbox sleeps, its runtime is replaced, or it is destroyed.
2077
- Subscribe again when a restarted application is ready. One devbox may hold the
2230
+ disappears, the box sleeps, its runtime is replaced, or it is destroyed.
2231
+ Subscribe again when a restarted application is ready. One box may hold the
2078
2232
  routed claim and subscribe at the same time; each individual request still
2079
2233
  uses exactly one delivery behavior.
2080
2234
 
@@ -2085,9 +2239,10 @@ wakes. Listener failures therefore lose an already acknowledged webhook. Use
2085
2239
  routed delivery for verification challenges or any request that needs the
2086
2240
  application's status, headers, or response body.
2087
2241
 
2088
- Project URL traffic does not wake a sleeping devbox or keep it awake. The
2089
- commands require the URL's configured port to be allowed by the project port
2090
- policy and to have a detected HTTP listener. They configure only which devbox
2242
+ Project URL traffic does not wake a sleeping box or keep it awake. `list` and
2243
+ `show` work without a running app. `claim`, `subscribe`, and `browser-link`
2244
+ require the URL's configured port to be allowed by the project port policy and
2245
+ to have a detected HTTP listener. The commands configure only which box
2091
2246
  participates; durable URL creation, delivery rules, port changes,
2092
2247
  disable/enable, replacement, and deletion remain project-level operations
2093
2248
  outside the box.
@@ -2121,9 +2276,12 @@ token grants only Project URL participation. An isolated container cannot call
2121
2276
  this host-native API in v1; it may still publish its application port onto host
2122
2277
  loopback and use a host-side participation wrapper.
2123
2278
 
2124
- That token file exists only on a boxes.dev devbox, so an application that also
2125
- runs elsewhere can check for it to decide whether to add the pinning step: when
2126
- the file is missing, run the ordinary OAuth flow unchanged.
2279
+ That token file exists only on a boxes.dev devbox or Template box, so an
2280
+ application that also runs elsewhere can check for it to decide whether to add
2281
+ the pinning step: when the file is missing, run the ordinary OAuth flow
2282
+ unchanged. On the Template box, the browser-link call returns HTTP 422 with
2283
+ `devbox_required`; the application should treat that the same way and continue
2284
+ with the ordinary flow.
2127
2285
 
2128
2286
  ## Team Template Commands
2129
2287
 
@@ -362,8 +362,10 @@ to recover. Reduce memory use before retrying the interrupted work.
362
362
  ## Reset
363
363
 
364
364
  The desktop app menu has **Machine > Reset (stop processes)…** when the selected
365
- managed box is running. Reset kills shells, agent sessions, background
366
- commands, and user services, while preserving files and keeping the box running.
365
+ managed box is running. Reset kills shells, agent sessions, and background
366
+ commands while preserving files and keeping the box running. Services that
367
+ always restart, such as systemd units with `Restart=always` or containers with
368
+ an `always` restart policy, start again.
367
369
 
368
370
  If a devbox thread is selected, reset targets that devbox. In an independent
369
371
  project, selecting the Template box targets it instead. A project with no
@@ -386,7 +388,7 @@ saved memory. The normal **Wake** control remains available to retry waking.
386
388
 
387
389
  Reboot preserves files saved to disk, including project files and git state;
388
390
  changes still held only in memory may be lost. Every process, shell, terminal attachment, agent
389
- session, background command, user service, and network connection stops. After
391
+ session, background command, and network connection stops. After
390
392
  the machine starts, boxes.dev waits for a fresh boxes.dev service heartbeat
391
393
  before reporting success. Existing terminals and agent sessions do not resume;
392
394
  reconnect or start new ones.
@@ -124,7 +124,7 @@ HTTPS push/pull access without registering an SSH key. This is the default for
124
124
  a fresh GitHub-origin setup even when GitHub still needs to be connected or its
125
125
  access needs to be updated. If boxes.dev can't access the account that owns a
126
126
  repository yet, setup shows **Connect your GitHub repositories**. For the
127
- user's own personal account, its **Connect on GitHub** button opens GitHub with
127
+ user's own personal account, its **Continue on GitHub** button opens GitHub with
128
128
  that account already selected and **All repositories** chosen. For an
129
129
  organization, it opens GitHub's account list and asks the user to choose the
130
130
  organization; GitHub lists only organizations the user belongs to. If an
@@ -132,7 +132,10 @@ organization requires an owner's approval, GitHub sends the member's request to
132
132
  an organization owner. Setup also offers a request message to send to an owner,
133
133
  for members waiting on approval and for users who aren't in the organization.
134
134
  If the repository belongs to another person's personal account, setup names the
135
- owner and provides instructions to send them.
135
+ owner and provides instructions to send them. The same step offers **Use SSH
136
+ instead** for users who can't get App access: SSH covers pull and push with a
137
+ key on the user's GitHub account, while automatic pull request updates and
138
+ follow-ups still need App access.
136
139
  If GitHub requires an access update, setup keeps automatic access selected and
137
140
  shows the affected **Update GitHub access** link or links; setup cannot continue
138
141
  until the update is accepted. The user can instead choose **Use an SSH key for
@@ -182,6 +185,30 @@ untracked files, Git access, agent config, and so on) — and reviews it with
182
185
  the user. The manifest lives outside the repo, so setup leaves no changes in
183
186
  the project folder, and the user can read or edit it directly at any time.
184
187
 
188
+ The agent should recommend the smallest box size that fits one coding agent,
189
+ one running instance of the app, and its required services. A marketing site
190
+ or modest app is a candidate for 4 vCPU / 8 GB; a larger recommendation should
191
+ have a workload reason. Review the box-hour multiplier as well as CPU and
192
+ memory before choosing. Larger sizes consume included box-hours and prepaid
193
+ credits faster while awake, even when their extra capacity is idle. The size
194
+ applies to the Template box and future devboxes and cannot be changed after
195
+ initialization. See Billing And Limits for current multipliers.
196
+
197
+ Agent-driven setup can select individual Claude and Codex skill folders,
198
+ including their linked support files. `dvb agent-init detect agent-config`
199
+ lists individual skill ids and sizes, and its `--json` output includes source
200
+ paths and exact byte counts. The manifest's `agentConfig.include` selects those
201
+ ids. Existing `claude:skills` and `codex:skills` entries still select whole
202
+ folders; remove the corresponding whole-folder entry when choosing a subset.
203
+ The local originals remain unchanged.
204
+
205
+ Global agent configuration is optional. The local agent should recommend a
206
+ selection based on usefulness to this project and the user's development
207
+ workflow, estimate its upload size, and explain the largest categories. Testing and
208
+ browser skills can be worth including even when the app does not require
209
+ them. Review large or uncertain choices with the agent before approving the
210
+ import; a small upload is not the only goal.
211
+
185
212
  The local agent can record its verified current agent and model in optional
186
213
  `agents.setup: { backend: codex, model: gpt-6.1-sol }` (use `claude` for Claude
187
214
  Code). Remote setup prefers that agent when selected and connected, and that
@@ -197,7 +224,9 @@ edited copy to upload while leaving the laptop original untouched. Bash and
197
224
  Zsh startup files are optional individual choices; selected shell content is
198
225
  adapted for Linux without replacing the Template box's managed shell setup.
199
226
  Removing a file entry removes that explicit copy, but repository copying or
200
- the separate untracked-file selection may still include the file.
227
+ the separate untracked-file selection may still include the file. The default
228
+ untracked-file selection leaves out Git worktrees inside a repository; their
229
+ branches still upload with the repository's local branches.
201
230
 
202
231
  By default, agent setup creates a single-repository project. The coding agent
203
232
  suggests including other repositories only when it finds evidence that the
@@ -246,16 +275,25 @@ project's setup page. The page lists five stages: planning the setup with the
246
275
  coding agent, uploading the project files (with a percentage), creating the
247
276
  Template box, unpacking the files on the Template box, and starting setup on
248
277
  the Template box. While the agent plans, the page shows when it prepares the
249
- project, when the user needs to act, when the agent is fixing issues a check
250
- found, when a setup command fails, and when the setup plan is ready for
251
- approval. **Back** returns to the setup choices, and the page won't open on
252
- its own again for that project. In **New project**, the page only opens on its
253
- own for a setup started after the wizard opened.
278
+ project, when the user needs to act, when a check found issues in the plan,
279
+ when a setup command fails, and when the setup plan is ready for approval.
280
+ The planning stage spins only while the agent prepares the project. When setup
281
+ can't continue until the user checks the coding agent, such as for a check
282
+ that found issues or a plan ready for approval, the stage stops spinning and
283
+ says what it's waiting for. **Back** returns to the setup choices, and the
284
+ page won't open on its own again for that project. In **New project**, the
285
+ page only opens on its own for a setup started after the wizard opened.
286
+
287
+ When the desktop app opens for the first time after a coding agent has started
288
+ setting up a project, it skips the Account step unless GitHub still needs to be
289
+ connected, and skips the Agents step once a coding agent is connected. It then
290
+ opens that project's setup page, or the setup thread if that has started.
291
+ **Back** still returns to the skipped steps.
254
292
 
255
293
  Setups that a coding agent is running also appear under **Setups in
256
294
  progress** on the Project step and in the titlebar project selector, with
257
- their current status, such as **Plan ready for review** or **Waiting for
258
- you**. Choose **View setup**, or the setup's entry in the project selector, to
295
+ their current status, such as **Preparing** or **Waiting for your
296
+ approval**. Choose **View setup**, or the setup's entry in the project selector, to
259
297
  open its setup page. Choosing a project folder that a coding agent is setting
260
298
  up also opens its setup page, because continuing in the desktop wizard would
261
299
  take over the agent's work. A setup stays listed until it finishes or is
@@ -820,10 +858,12 @@ are also imported.
820
858
  Untracked files can be customized. Common dependency, cache, and build
821
859
  directories (for example `.venv`, `node_modules`, `dist`, `build`, `__pycache__`)
822
860
  are excluded from the bundle by default so a large un-ignored directory does not
823
- bloat the upload. Disposable agent checkouts under `.claude/worktrees` and
824
- `.codex/worktrees` are also unchecked by default, while adjacent agent settings
825
- and other project files remain included. The bundle review notes what was
826
- excluded, and a **Customize** button opens a file picker where the user can
861
+ bloat the upload. Git worktrees inside a repository, including disposable agent
862
+ checkouts under `.claude/worktrees` and `.codex/worktrees`, are also unchecked
863
+ by default; their branches still upload with the repository's Git history.
864
+ Adjacent agent settings and other project files remain included. The bundle
865
+ review notes what was excluded, and a **Customize** button opens a file picker
866
+ where the user can
827
867
  browse the untracked files as a tree and check or uncheck individual files and
828
868
  directories, including all or selected worktrees from a directory that was
829
869
  excluded by default. Bulk actions cover include all, exclude all, and resetting
@@ -980,8 +1020,8 @@ During provisioning, boxes.dev:
980
1020
  - downloads and extracts the bundle onto the Template box;
981
1021
  - starts the setup thread;
982
1022
  - runs the setup plan;
983
- - validates the configured services and creates the first snapshot after the
984
- setup thread explicitly hands the completed work back to boxes.dev.
1023
+ - creates the first snapshot after the setup thread explicitly hands the
1024
+ completed work back to boxes.dev.
985
1025
 
986
1026
  The setup thread runs on the Template box. It places uploaded project files,
987
1027
  approved external artifacts, and database dumps where the setup plan says they
@@ -1032,7 +1072,7 @@ The setup thread should include a short summary of what it completed, what it
1032
1072
  skipped, and any commands or follow-ups the user should handle manually. When
1033
1073
  the environment is ready to close out, the setup agent writes that durable
1034
1074
  summary and runs `dvb-onbox setup complete`. The command hands control back to
1035
- boxes.dev; it does not skip service validation, cleanup, or the final snapshot.
1075
+ boxes.dev; it does not skip cleanup or the final snapshot.
1036
1076
  The agent can then send its final response while the workbench shows
1037
1077
  **Finishing setup**. The setup banner disappears only after finalization
1038
1078
  actually completes.
@@ -1098,6 +1138,16 @@ Common recovery paths:
1098
1138
  - Setup state is no longer useful: delete setup state and start over.
1099
1139
 
1100
1140
  Starting over removes the incomplete setup state created by that setup attempt.
1141
+
1142
+ For an agent-driven setup with an unnecessarily large import, the local agent
1143
+ can stop its active upload command and, with approval, run
1144
+ `dvb agent-init destroy --yes` from the project folder. This removes the
1145
+ incomplete Template box and setup progress but keeps the agent's manifest and
1146
+ local project files. The agent can revise that manifest, check it again, and
1147
+ show the smaller import and box-size cost before requesting launch approval.
1148
+ A completed project needs a separate recreation decision; do not reset it as
1149
+ an incomplete setup.
1150
+
1101
1151
  If setup says the Template box did not respond in time, resume setup to
1102
1152
  continue.
1103
1153