@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.
- package/dist/agent-init-guides/app.md +6 -5
- package/dist/agent-init-guides/flow.md +36 -12
- package/dist/agent-init-guides/git-ssh.md +9 -4
- package/dist/agent-init-guides/untracked.md +2 -1
- package/dist/bin/dvb.mjs +1216 -1829
- package/dist/bin/dvbd.mjs +6 -6
- package/dist/product-docs/references/agent-tools.md +32 -5
- 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 +22 -3
- package/dist/product-docs/references/environment-setup-validation.md +22 -0
- package/dist/product-docs/references/files-git-and-review.md +29 -16
- package/dist/product-docs/references/fork-workflows.md +3 -2
- 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/mobile.md +6 -1
- package/dist/product-docs/references/onbox-agent-tools.md +221 -61
- package/dist/product-docs/references/ports-terminal-and-runtime.md +5 -3
- package/dist/product-docs/references/project-setup.md +33 -17
- package/dist/product-docs/references/security-and-data.md +3 -2
- package/dist/product-docs/references/threads-and-agents.md +17 -4
- package/dist/product-docs/references/troubleshooting.md +7 -5
- 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
|
|
@@ -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
|
|
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
|
|
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
|
-
|
|
1836
|
-
|
|
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
|
|
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
|
|
1996
|
+
## Destroy And Archive Other Devboxes
|
|
1875
1997
|
|
|
1876
|
-
An agent on a Template box or devbox can request destruction of
|
|
1877
|
-
|
|
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
|
|
1885
|
-
|
|
1886
|
-
|
|
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
|
|
1889
|
-
|
|
1890
|
-
|
|
1891
|
-
**
|
|
1892
|
-
|
|
1893
|
-
|
|
1894
|
-
|
|
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
|
|
1906
|
-
|
|
1907
|
-
expires. If the devbox already has a
|
|
1908
|
-
|
|
1909
|
-
|
|
1910
|
-
|
|
1911
|
-
archived.
|
|
1912
|
-
|
|
1913
|
-
`accepted` means only that the request was saved.
|
|
1914
|
-
|
|
1915
|
-
|
|
1916
|
-
|
|
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
|
-
|
|
1926
|
-
|
|
1927
|
-
|
|
1928
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
2075
|
-
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
|
|
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
|
|
2087
|
-
|
|
2088
|
-
|
|
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
|
|
2123
|
-
runs elsewhere can check for it to decide whether to add
|
|
2124
|
-
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.
|
|
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
|
|
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
|
|
@@ -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
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
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 **
|
|
282
|
-
|
|
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.
|
|
848
|
-
`.
|
|
849
|
-
|
|
850
|
-
|
|
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
|
-
-
|
|
1008
|
-
|
|
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
|
|
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
|
|
76
|
-
`.
|
|
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
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
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
|