@boxes-dev/dvb-runtime 1.0.1104 → 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.
@@ -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
@@ -906,6 +909,112 @@ When a user-required title change returns `title_editing_disabled`, request
906
909
  only `update-thread-titles` through the Agent permissions command above. Do not
907
910
  request it merely to perform an optional rename after unrelated work.
908
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
+
909
1018
  ## Pull Request Follow-ups
910
1019
 
911
1020
  boxes.dev can send a managed Codex or Claude thread a message when its pull
@@ -939,6 +1048,11 @@ The commands use the repository that contains the working directory. Pass
939
1048
  repositories and the project has more than one. They always act for the thread
940
1049
  that runs them.
941
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
+
942
1056
  `--triggers` takes a comma-separated list of `failed-checks`, `bot-reviews`,
943
1057
  `human-reviews`, and `conflicts`. Without it, `enable` turns on the project's
944
1058
  default follow-up events for a pull request that has no follow-ups and keeps
@@ -1361,12 +1475,20 @@ otherwise they are null. A later event can replace or clear them. `idle`
1361
1475
  describes activity, not successful completion. Muting does not hide this
1362
1476
  metadata.
1363
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
+
1364
1486
  `threads result` returns the complete stored final response for one
1365
1487
  exact terminal turn and automatically assembles its transport pages. Use it instead
1366
1488
  of asking the child to summarize a shortened `threads read` preview. When
1367
1489
  `threads wait` omits `--turn`, it snapshots the current active turn once. If
1368
1490
  there is no active turn, it returns `idle` with any available latest stop
1369
- 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
1370
1492
  its turn ID with the work you are checking. A completed wait includes that
1371
1493
  same complete response as `output.text`; Ctrl+C stops only the local wait.
1372
1494
  `threads events` emits durable lifecycle events with
@@ -1426,10 +1548,10 @@ Prompt files are limited to 32 KiB.
1426
1548
 
1427
1549
  Delegation does not grant destruction permission or access to unrelated
1428
1550
  threads. To clean up a devbox created this way, see
1429
- [Destroy And Archive Created Devboxes](#destroy-and-archive-created-devboxes).
1551
+ [Destroy And Archive Other Devboxes](#destroy-and-archive-other-devboxes).
1430
1552
  To archive finished threads started on the current devbox, see
1431
1553
  [Archive Created Threads On This Devbox](#archive-created-threads-on-this-devbox). Read-only thread and project discovery has its own permission below.
1432
- `dvb-onbox` does not expose arbitrary direct exec, services, or generic machine
1554
+ `dvb-onbox` does not expose arbitrary direct exec or generic machine
1433
1555
  management. The current-box public link commands above are its only port-control
1434
1556
  surface.
1435
1557
 
@@ -1509,6 +1631,8 @@ Scoped listings and status lookups include nullable `lastStopReason`,
1509
1631
  latest lifecycle event when it is terminal: `completed`, `interrupted`, or a
1510
1632
  failure category such as `usage_limit_exceeded`. An unclassified failure is
1511
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.
1512
1636
 
1513
1637
  To find idle threads stopped by exhausted usage or credits, run:
1514
1638
 
@@ -1832,9 +1956,8 @@ The project setting applies to existing and future devboxes without an
1832
1956
  individual override. After a `destruction_disabled` error, request
1833
1957
  `destroy-devbox`; the owner can choose **Allow** or **Always allow for project**.
1834
1958
  Either way, this permission lets agents destroy only their own ordinary devbox.
1835
- Template boxes and other devboxes cannot be targeted. To destroy devboxes that
1836
- agents on this box created, see
1837
- [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).
1838
1961
 
1839
1962
  Destruction permanently deletes the devbox's files and retains its thread
1840
1963
  history. It also stops automatic pull request follow-ups that the devbox's
@@ -1866,55 +1989,69 @@ dvb-onbox box cancel-destroy --json
1866
1989
  ```
1867
1990
 
1868
1991
  Any managed agent on the same devbox can cancel its pending request without
1869
- the destruction permission, including a request made by the box that created
1870
- 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`
1871
1993
  with a null `requestId` if there is nothing to cancel. Once archival has
1872
1994
  started, it returns `destruction_started`; it cannot undo that handoff.
1873
1995
 
1874
- ## Destroy And Archive Created Devboxes
1996
+ ## Destroy And Archive Other Devboxes
1875
1997
 
1876
- An agent on a Template box or devbox can request destruction of an ordinary
1877
- devbox that an agent on the same box created with
1878
- `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:
1879
2000
 
1880
2001
  ```bash
1881
2002
  dvb-onbox box destroy --devbox <devbox-id> --json
1882
2003
  ```
1883
2004
 
1884
- Use the `devboxId` returned by `threads start`. The separate **Destroy and
1885
- archive created devboxes** permission on the requesting box is off by default.
1886
- 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
1887
2020
  permissions for this project** in Project settings. After a
1888
- `destruction_disabled` error, request `destroy-created-devboxes`; the owner can
1889
- choose **Allow** or **Always allow for project**. This permission is
1890
- independent of **Create devboxes and threads** and of the created devbox's own
1891
- **Destroy and archive this devbox** permission, and any agent on the
1892
- requesting box can use it. Devboxes created by another box, devboxes where this
1893
- box only started a thread, devboxes created by a created devbox, devboxes
1894
- created by restoring an archived thread, and Template boxes return
1895
- `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).
1896
2031
 
1897
2032
  Run this only when the user's task calls for it, such as after the devbox's
1898
- 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.
1899
2035
  Destruction permanently deletes the devbox's files and retains its thread
1900
2036
  history. It also stops automatic pull request follow-ups that the devbox's
1901
2037
  threads handle until another thread turns them on.
1902
2038
 
1903
2039
  The request waits for every agent and queued message on that devbox to finish,
1904
2040
  and boxes.dev wakes a sleeping devbox to archive it. New work submitted to the
1905
- devbox before destruction starts cancels the request, as does turning off the
1906
- permission on the requesting box. A request that stays pending for 30 minutes
1907
- expires. If the devbox already has a pending request, including one it made for
1908
- itself, the command returns `already_requested` with that request's ID. Pending
1909
- requests are also cancelled if the requesting box is destroyed first, so a box
1910
- that will destroy itself should first wait until its created devboxes are
1911
- archived.
1912
-
1913
- `accepted` means only that the request was saved. `threads list
1914
- --include-archived` shows the devbox's thread as archived once its history is
1915
- saved and deletion of the machine has started; that does not prove the machine
1916
- is gone. Listing delegated threads still requires **Create devboxes and
1917
- 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**.
1918
2055
 
1919
2056
  To withdraw a pending request, run:
1920
2057
 
@@ -1922,15 +2059,16 @@ To withdraw a pending request, run:
1922
2059
  dvb-onbox box cancel-destroy --devbox <devbox-id> --json
1923
2060
  ```
1924
2061
 
1925
- Cancellation does not require a destroy permission and also withdraws a
1926
- request the devbox made for itself. It returns `cancelled`, or `not_pending`
1927
- with a null `requestId` if there is nothing to cancel. Once archival has
1928
- 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`.
1929
2067
 
1930
2068
  ### Archive Created Threads On This Devbox
1931
2069
 
1932
- **Destroy and archive created devboxes** also lets any agent on an ordinary
1933
- 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,
1934
2072
  such as a worker started with `threads start --target current-devbox`:
1935
2073
 
1936
2074
  ```bash
@@ -2031,8 +2169,8 @@ update; do not install workstation `dvb` or call backend services directly.
2031
2169
  ## Project URL Participation
2032
2170
 
2033
2171
  A Project URL is configured for the project and one expected HTTP port. Once
2034
- that application is listening on the current devbox, inspect the project's URLs
2035
- 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:
2036
2174
 
2037
2175
  ```bash
2038
2176
  dvb-onbox url list --json
@@ -2040,11 +2178,18 @@ dvb-onbox url show <name> --json
2040
2178
  dvb-onbox url claim <name> --if-free --json
2041
2179
  ```
2042
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
+
2043
2188
  `--if-free` is the safe startup default. Repeating it on the current holder is
2044
2189
  idempotent. It reports a conflict when another devbox holds the URL, even when
2045
2190
  that devbox's listener is temporarily unavailable; it never escalates to a
2046
2191
  takeover. Use `--take` only when the user or application deliberately intends
2047
- to move all newly authorized traffic to this devbox:
2192
+ to move all newly authorized traffic to this box:
2048
2193
 
2049
2194
  ```bash
2050
2195
  dvb-onbox url claim <name> --take --json
@@ -2060,19 +2205,30 @@ that makes the URL available to another devbox's `--if-free`:
2060
2205
  dvb-onbox url release <name> --json
2061
2206
  ```
2062
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
+
2063
2219
  For a Project URL with webhook-multicast delivery, subscribe the current
2064
- devbox after its configured HTTP listener starts:
2220
+ box after its configured HTTP listener starts:
2065
2221
 
2066
2222
  ```bash
2067
2223
  dvb-onbox url subscribe <name> --json
2068
2224
  dvb-onbox url unsubscribe <name> --json
2069
2225
  ```
2070
2226
 
2071
- Subscription is URL-wide: the devbox receives every request whose configured
2227
+ Subscription is URL-wide: the box receives every request whose configured
2072
2228
  method/path resolves to webhook multicast. Repeating subscribe or unsubscribe
2073
2229
  is idempotent. A subscription is temporary and expires when the listener
2074
- disappears, the devbox sleeps, its runtime is replaced, or it is destroyed.
2075
- 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
2076
2232
  routed claim and subscribe at the same time; each individual request still
2077
2233
  uses exactly one delivery behavior.
2078
2234
 
@@ -2083,9 +2239,10 @@ wakes. Listener failures therefore lose an already acknowledged webhook. Use
2083
2239
  routed delivery for verification challenges or any request that needs the
2084
2240
  application's status, headers, or response body.
2085
2241
 
2086
- Project URL traffic does not wake a sleeping devbox or keep it awake. The
2087
- commands require the URL's configured port to be allowed by the project port
2088
- 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
2089
2246
  participates; durable URL creation, delivery rules, port changes,
2090
2247
  disable/enable, replacement, and deletion remain project-level operations
2091
2248
  outside the box.
@@ -2119,9 +2276,12 @@ token grants only Project URL participation. An isolated container cannot call
2119
2276
  this host-native API in v1; it may still publish its application port onto host
2120
2277
  loopback and use a host-side participation wrapper.
2121
2278
 
2122
- That token file exists only on a boxes.dev devbox, so an application that also
2123
- runs elsewhere can check for it to decide whether to add the pinning step: when
2124
- 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.
2125
2285
 
2126
2286
  ## Team Template Commands
2127
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
@@ -221,7 +224,9 @@ edited copy to upload while leaving the laptop original untouched. Bash and
221
224
  Zsh startup files are optional individual choices; selected shell content is
222
225
  adapted for Linux without replacing the Template box's managed shell setup.
223
226
  Removing a file entry removes that explicit copy, but repository copying or
224
- 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.
225
230
 
226
231
  By default, agent setup creates a single-repository project. The coding agent
227
232
  suggests including other repositories only when it finds evidence that the
@@ -270,16 +275,25 @@ project's setup page. The page lists five stages: planning the setup with the
270
275
  coding agent, uploading the project files (with a percentage), creating the
271
276
  Template box, unpacking the files on the Template box, and starting setup on
272
277
  the Template box. While the agent plans, the page shows when it prepares the
273
- project, when the user needs to act, when the agent is fixing issues a check
274
- found, when a setup command fails, and when the setup plan is ready for
275
- approval. **Back** returns to the setup choices, and the page won't open on
276
- its own again for that project. In **New project**, the page only opens on its
277
- 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.
278
292
 
279
293
  Setups that a coding agent is running also appear under **Setups in
280
294
  progress** on the Project step and in the titlebar project selector, with
281
- their current status, such as **Plan ready for review** or **Waiting for
282
- 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
283
297
  open its setup page. Choosing a project folder that a coding agent is setting
284
298
  up also opens its setup page, because continuing in the desktop wizard would
285
299
  take over the agent's work. A setup stays listed until it finishes or is
@@ -844,10 +858,12 @@ are also imported.
844
858
  Untracked files can be customized. Common dependency, cache, and build
845
859
  directories (for example `.venv`, `node_modules`, `dist`, `build`, `__pycache__`)
846
860
  are excluded from the bundle by default so a large un-ignored directory does not
847
- bloat the upload. Disposable agent checkouts under `.claude/worktrees` and
848
- `.codex/worktrees` are also unchecked by default, while adjacent agent settings
849
- and other project files remain included. The bundle review notes what was
850
- 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
851
867
  browse the untracked files as a tree and check or uncheck individual files and
852
868
  directories, including all or selected worktrees from a directory that was
853
869
  excluded by default. Bulk actions cover include all, exclude all, and resetting
@@ -1004,8 +1020,8 @@ During provisioning, boxes.dev:
1004
1020
  - downloads and extracts the bundle onto the Template box;
1005
1021
  - starts the setup thread;
1006
1022
  - runs the setup plan;
1007
- - validates the configured services and creates the first snapshot after the
1008
- 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.
1009
1025
 
1010
1026
  The setup thread runs on the Template box. It places uploaded project files,
1011
1027
  approved external artifacts, and database dumps where the setup plan says they
@@ -1056,7 +1072,7 @@ The setup thread should include a short summary of what it completed, what it
1056
1072
  skipped, and any commands or follow-ups the user should handle manually. When
1057
1073
  the environment is ready to close out, the setup agent writes that durable
1058
1074
  summary and runs `dvb-onbox setup complete`. The command hands control back to
1059
- 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.
1060
1076
  The agent can then send its final response while the workbench shows
1061
1077
  **Finishing setup**. The setup banner disappears only after finalization
1062
1078
  actually completes.
@@ -72,8 +72,9 @@ temporary storage that only the user's account can use. boxes.dev deletes it
72
72
  once the Template box has copied the threads, or when the import fails or the
73
73
  upload goes unused.
74
74
 
75
- Untracked disposable agent checkouts under `.claude/worktrees` and
76
- `.codex/worktrees` are unchecked by default in the setup bundle review. Users
75
+ Untracked Git worktrees inside a repository, including disposable agent
76
+ checkouts under `.claude/worktrees` and `.codex/worktrees`, are unchecked by
77
+ default in the setup bundle review. Users
77
78
  can explicitly include all or selected worktrees when they need them; adjacent
78
79
  agent settings and unrelated project directories remain included.
79
80
 
@@ -293,10 +293,13 @@ Supported remote HTTP commands are another entry point to the same list. Running
293
293
  a command such as `codex mcp add <name> --url <url>` or `claude mcp add
294
294
  --transport http <name> <url>` in a Template box or devbox creates the central
295
295
  current-project connection. It does not create a separate machine-only copy.
296
- When the server uses OAuth, the command will try to open sign-in in your
297
- browser and will print a `dvb mcp authorize` command. If the browser doesn't
298
- open, run that command in a terminal on your own computer, not on the box. To enable both agents, run each agent's setup command with
299
- the same name, URL, and authentication details, including any API-key headers.
296
+ When the server uses OAuth, the command will print a boxes.dev sign-in link
297
+ and a `dvb mcp authorize` command, and it will try to open the link in your
298
+ browser. If the browser doesn't open, open the link yourself, or run that
299
+ command in a terminal on your own computer, not on the box. An agent that runs
300
+ the command for you will give you the link. To enable both agents, run each
301
+ agent's setup command with the same name, URL, and authentication details,
302
+ including any API-key headers.
300
303
  The second command will add its agent to the existing project connection;
301
304
  repeating either command will keep the existing connection and sign-in. OAuth
302
305
  still requires authorization for each agent. For an **All projects** connection
@@ -1097,6 +1100,16 @@ to finish or use the runtime controls if the whole runtime is stuck.
1097
1100
  The desktop thread list groups work by devboxes, automations, and, when the
1098
1101
  project has one, Template-box threads.
1099
1102
 
1103
+ On desktop, a devbox folder is a row with an open or closed folder icon, the
1104
+ folder's name, and its devbox count. A closed folder also shows the most
1105
+ urgent state among its threads, such as running, needs input, or unread. While
1106
+ the user scrolls through an open folder, its row stays pinned below the
1107
+ **Devboxes** heading until the next folder or the unfiled devboxes reach it.
1108
+ **Sidebar density**, under **Appearance and layout** in **Settings > General**,
1109
+ sets the thread list's spacing to **Comfortable** (the default), **Cozy**, or
1110
+ **Compact**. It is saved on that computer only, and **Restore appearance and
1111
+ layout defaults** returns it to Comfortable.
1112
+
1100
1113
  Thread sections include pinned and recent chats. On desktop, drag pinned
1101
1114
  threads or devboxes to rearrange them within their **Pinned** section. The order
1102
1115
  will sync across devices. A grouped devbox moves with its threads. Template