@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.
- package/dist/agent-init-guides/agent-config.md +34 -0
- package/dist/agent-init-guides/app.md +6 -5
- package/dist/agent-init-guides/flow.md +72 -12
- package/dist/agent-init-guides/git-ssh.md +9 -4
- package/dist/agent-init-guides/manifest.md +6 -0
- package/dist/agent-init-guides/recovery.md +22 -0
- package/dist/agent-init-guides/running.md +12 -0
- package/dist/agent-init-guides/untracked.md +2 -1
- package/dist/bin/dvb.mjs +1228 -1758
- package/dist/bin/dvbd.mjs +6 -6
- package/dist/product-docs/references/agent-tools.md +32 -5
- package/dist/product-docs/references/automations.md +18 -3
- package/dist/product-docs/references/cli.md +6 -4
- package/dist/product-docs/references/core-concepts.md +1 -1
- package/dist/product-docs/references/desktop-workbench.md +28 -3
- package/dist/product-docs/references/environment-setup-validation.md +22 -0
- package/dist/product-docs/references/files-git-and-review.md +32 -18
- package/dist/product-docs/references/fork-workflows.md +6 -3
- package/dist/product-docs/references/getting-started.md +2 -1
- package/dist/product-docs/references/index.md +2 -1
- package/dist/product-docs/references/linear.md +15 -0
- package/dist/product-docs/references/member-managed-files.md +2 -1
- package/dist/product-docs/references/mobile.md +63 -17
- package/dist/product-docs/references/onbox-agent-tools.md +224 -66
- package/dist/product-docs/references/ports-terminal-and-runtime.md +5 -3
- package/dist/product-docs/references/project-setup.md +67 -17
- package/dist/product-docs/references/security-and-data.md +3 -2
- package/dist/product-docs/references/slack.md +8 -5
- package/dist/product-docs/references/threads-and-agents.md +25 -8
- package/dist/product-docs/references/troubleshooting.md +7 -5
- package/dist/product-docs/references/unattended-work.md +5 -0
- package/dist/prompts/local-services-scan.md +3 -4
- 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**.
|
|
189
|
-
|
|
190
|
-
|
|
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
|
|
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**).
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
1838
|
-
|
|
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
|
|
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
|
|
1996
|
+
## Destroy And Archive Other Devboxes
|
|
1877
1997
|
|
|
1878
|
-
An agent on a Template box or devbox can request destruction of
|
|
1879
|
-
|
|
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
|
|
1887
|
-
|
|
1888
|
-
|
|
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
|
|
1891
|
-
|
|
1892
|
-
|
|
1893
|
-
**
|
|
1894
|
-
|
|
1895
|
-
|
|
1896
|
-
|
|
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
|
|
1908
|
-
|
|
1909
|
-
expires. If the devbox already has a
|
|
1910
|
-
|
|
1911
|
-
|
|
1912
|
-
|
|
1913
|
-
archived.
|
|
1914
|
-
|
|
1915
|
-
`accepted` means only that the request was saved.
|
|
1916
|
-
|
|
1917
|
-
|
|
1918
|
-
|
|
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
|
-
|
|
1928
|
-
|
|
1929
|
-
|
|
1930
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
2077
|
-
Subscribe again when a restarted application is ready. One
|
|
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
|
|
2089
|
-
|
|
2090
|
-
|
|
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
|
|
2125
|
-
runs elsewhere can check for it to decide whether to add
|
|
2126
|
-
the file is missing, run the ordinary OAuth flow
|
|
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
|
|
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,
|
|
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 **
|
|
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
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
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 **
|
|
258
|
-
|
|
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.
|
|
824
|
-
`.
|
|
825
|
-
|
|
826
|
-
|
|
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
|
-
-
|
|
984
|
-
|
|
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
|
|
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
|
|