@boxes-dev/dvb-runtime 1.0.1098 → 1.0.1100
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/git-ssh.md +2 -2
- package/dist/bin/dvb.mjs +121 -72
- package/dist/bin/dvbd.mjs +6 -6
- package/dist/postgres-tools/SHA256SUMS +32 -8
- package/dist/postgres-tools/linux-arm64-el8/bin/pg_dump +0 -0
- package/dist/postgres-tools/linux-arm64-el8/bin/pg_restore +0 -0
- package/dist/postgres-tools/linux-arm64-el8/lib/libpq.so.5 +0 -0
- package/dist/postgres-tools/linux-arm64-el8/notices/PostgreSQL-COPYRIGHT.txt +23 -0
- package/dist/postgres-tools/linux-arm64-el9/bin/pg_dump +0 -0
- package/dist/postgres-tools/linux-arm64-el9/bin/pg_restore +0 -0
- package/dist/postgres-tools/linux-arm64-el9/lib/libpq.so.5 +0 -0
- package/dist/postgres-tools/linux-arm64-el9/notices/PostgreSQL-COPYRIGHT.txt +23 -0
- package/dist/postgres-tools/linux-arm64-ubuntu22.04/bin/pg_dump +0 -0
- package/dist/postgres-tools/linux-arm64-ubuntu22.04/bin/pg_restore +0 -0
- package/dist/postgres-tools/linux-arm64-ubuntu22.04/lib/libpq.so.5 +0 -0
- package/dist/postgres-tools/linux-x64-el8/bin/pg_dump +0 -0
- package/dist/postgres-tools/linux-x64-el8/bin/pg_restore +0 -0
- package/dist/postgres-tools/linux-x64-el8/lib/libpq.so.5 +0 -0
- package/dist/postgres-tools/linux-x64-el8/notices/PostgreSQL-COPYRIGHT.txt +23 -0
- package/dist/postgres-tools/linux-x64-el9/bin/pg_dump +0 -0
- package/dist/postgres-tools/linux-x64-el9/bin/pg_restore +0 -0
- package/dist/postgres-tools/linux-x64-el9/lib/libpq.so.5 +0 -0
- package/dist/postgres-tools/linux-x64-el9/notices/PostgreSQL-COPYRIGHT.txt +23 -0
- package/dist/postgres-tools/linux-x64-ubuntu22.04/bin/pg_dump +0 -0
- package/dist/postgres-tools/linux-x64-ubuntu22.04/bin/pg_restore +0 -0
- package/dist/postgres-tools/linux-x64-ubuntu22.04/lib/libpq.so.5 +0 -0
- package/dist/postgres-tools/linux-x64-ubuntu22.04/notices/PostgreSQL-and-Debian-copyright.txt +270 -0
- package/dist/postgres-tools/linux-x64-ubuntu24.04/notices/PostgreSQL-and-Debian-copyright.txt +270 -0
- package/dist/postgres-tools/release.json +306 -18
- package/dist/product-docs/references/agent-tools.md +6 -7
- package/dist/product-docs/references/automations.md +4 -4
- package/dist/product-docs/references/aws.md +17 -11
- package/dist/product-docs/references/billing-and-limits.md +26 -13
- package/dist/product-docs/references/cli.md +14 -15
- package/dist/product-docs/references/convex.md +92 -0
- package/dist/product-docs/references/core-concepts.md +35 -30
- package/dist/product-docs/references/desktop-workbench.md +62 -47
- package/dist/product-docs/references/files-git-and-review.md +14 -15
- package/dist/product-docs/references/fork-workflows.md +26 -25
- package/dist/product-docs/references/getting-started.md +11 -12
- package/dist/product-docs/references/glossary.md +46 -22
- package/dist/product-docs/references/google-cloud.md +13 -8
- package/dist/product-docs/references/index.md +20 -16
- package/dist/product-docs/references/linear.md +2 -2
- package/dist/product-docs/references/managed-environment-files.md +1 -1
- package/dist/product-docs/references/member-managed-files.md +4 -4
- package/dist/product-docs/references/mobile.md +18 -16
- package/dist/product-docs/references/onbox-agent-tools.md +63 -41
- package/dist/product-docs/references/ports-terminal-and-runtime.md +31 -28
- package/dist/product-docs/references/project-setup.md +15 -12
- package/dist/product-docs/references/security-and-data.md +23 -13
- package/dist/product-docs/references/slack.md +45 -7
- package/dist/product-docs/references/tailscale.md +2 -2
- package/dist/product-docs/references/team-template.md +26 -23
- package/dist/product-docs/references/template-box-environment.md +7 -3
- package/dist/product-docs/references/threads-and-agents.md +48 -24
- package/dist/product-docs/references/troubleshooting.md +24 -25
- package/package.json +2 -2
- /package/dist/postgres-tools/{linux-arm64 → linux-arm64-ubuntu22.04}/notices/PostgreSQL-and-Debian-copyright.txt +0 -0
- /package/dist/postgres-tools/{linux-arm64 → linux-arm64-ubuntu24.04}/bin/pg_dump +0 -0
- /package/dist/postgres-tools/{linux-arm64 → linux-arm64-ubuntu24.04}/bin/pg_restore +0 -0
- /package/dist/postgres-tools/{linux-arm64 → linux-arm64-ubuntu24.04}/lib/libpq.so.5 +0 -0
- /package/dist/postgres-tools/{linux-x64 → linux-arm64-ubuntu24.04}/notices/PostgreSQL-and-Debian-copyright.txt +0 -0
- /package/dist/postgres-tools/{linux-x64 → linux-x64-ubuntu24.04}/bin/pg_dump +0 -0
- /package/dist/postgres-tools/{linux-x64 → linux-x64-ubuntu24.04}/bin/pg_restore +0 -0
- /package/dist/postgres-tools/{linux-x64 → linux-x64-ubuntu24.04}/lib/libpq.so.5 +0 -0
|
@@ -165,7 +165,7 @@ contents. Timeout flags accept 1–120 seconds. Clear flags remove a script.
|
|
|
165
165
|
Always read first and use its revision. If the revision changed, read again and
|
|
166
166
|
reconcile the newer settings.
|
|
167
167
|
|
|
168
|
-
For an
|
|
168
|
+
For an independent project with a personal Template box, the agent can design one
|
|
169
169
|
maintenance script and its complete GitHub watch set together:
|
|
170
170
|
|
|
171
171
|
```bash
|
|
@@ -182,7 +182,7 @@ paths, whether each watch is enabled, and exact repository-relative files or
|
|
|
182
182
|
directories. Paths are not globs. Omitting an editable existing watch requires
|
|
183
183
|
`--confirm-watch-removals`. The command preserves the repeating schedule and
|
|
184
184
|
does not start a run; new or changed watches begin from a fresh default-branch
|
|
185
|
-
baseline.
|
|
185
|
+
baseline. Managed projects support lifecycle editing but return
|
|
186
186
|
`template_maintenance_unavailable` for maintenance because they have no
|
|
187
187
|
personal Template box.
|
|
188
188
|
|
|
@@ -243,7 +243,7 @@ Use:
|
|
|
243
243
|
dvb connect <devbox>
|
|
244
244
|
```
|
|
245
245
|
|
|
246
|
-
This opens or attaches to a persistent terminal session on the selected
|
|
246
|
+
This opens or attaches to a persistent terminal session on the selected box.
|
|
247
247
|
You can name sessions, reconnect to them later, or run one command:
|
|
248
248
|
|
|
249
249
|
```bash
|
|
@@ -273,8 +273,7 @@ dvb agents [project] [--json | --bell]
|
|
|
273
273
|
```
|
|
274
274
|
|
|
275
275
|
This opens a live terminal switchboard for existing agent threads on the
|
|
276
|
-
project's devboxes and, when it has one, its Template box. A
|
|
277
|
-
member project has only its Devboxes section and shows any recoverable setup
|
|
276
|
+
project's devboxes and, when it has one, its Template box. A managed project has only its Devboxes section and shows any recoverable setup
|
|
278
277
|
warning without inventing a Template target. If the project is omitted and more than one
|
|
279
278
|
is available, choose one from the prompt. If there are no projects yet, the CLI
|
|
280
279
|
points you to the coding-agent-led `dvb agent-init` flow or desktop setup.
|
|
@@ -323,8 +322,8 @@ Use `p` to pin or unpin an eligible Template-box thread or devbox anchor, `r`
|
|
|
323
322
|
to rename a thread, and `x` to archive or restore it. On a devbox group row,
|
|
324
323
|
`r` renames the devbox instead, and empty input returns the group to its first
|
|
325
324
|
thread's title. On an archived
|
|
326
|
-
cold-storage thread, `x` opens the available restore choice.
|
|
327
|
-
can use the current Template box or a new devbox;
|
|
325
|
+
cold-storage thread, `x` opens the available restore choice. Independent projects
|
|
326
|
+
can use the current Template box or a new devbox; managed projects
|
|
328
327
|
restore only to a new devbox. Empty rename input
|
|
329
328
|
returns the automatic title. Codex archive updates the saved native session
|
|
330
329
|
before the shared list; Claude archive changes the shared list without waking
|
|
@@ -332,8 +331,8 @@ its machine. If an action is not safe for the selected row, the switchboard
|
|
|
332
331
|
explains why.
|
|
333
332
|
|
|
334
333
|
Press `n` to start a thread on the selected item's machine. Select a thread on
|
|
335
|
-
the Template box or a devbox group/thread. In an
|
|
336
|
-
targets the Template box. A
|
|
334
|
+
the Template box or a devbox group/thread. In an independent empty project, `n`
|
|
335
|
+
targets the Template box. A managed project has no Template
|
|
337
336
|
target. Press `N` to start a thread on a new devbox created from the project's
|
|
338
337
|
current reusable source. The compact composer shows its target in the
|
|
339
338
|
border and the current agent settings on one status line. Press `Tab` (or
|
|
@@ -434,9 +433,9 @@ message there. If the project is omitted, the CLI auto-selects the only project
|
|
|
434
433
|
or shows the same project picker as `dvb agents`.
|
|
435
434
|
|
|
436
435
|
When starting a new thread without `--devbox`, the command creates a devbox from
|
|
437
|
-
the project's current reusable source. For an
|
|
436
|
+
the project's current reusable source. For an independent project, that is the
|
|
438
437
|
latest completed Template-box snapshot; if none exists, the command asks you to
|
|
439
|
-
take one without creating a thread or devbox. For a
|
|
438
|
+
take one without creating a thread or devbox. For a managed
|
|
440
439
|
project, it uses the current saved version and any prepared devbox. With
|
|
441
440
|
`--devbox`, it uses that existing devbox in the selected project; a reusable
|
|
442
441
|
source is not required and deleting the new thread never deletes that devbox.
|
|
@@ -573,7 +572,7 @@ Use:
|
|
|
573
572
|
dvb cp <local-path> <devbox>:<remote-path>
|
|
574
573
|
```
|
|
575
574
|
|
|
576
|
-
`dvb cp` copies local files or directories into the selected
|
|
575
|
+
`dvb cp` copies local files or directories into the selected box. Relative
|
|
577
576
|
remote paths resolve against the remote project working directory.
|
|
578
577
|
|
|
579
578
|
For full file browsing, downloads, inline review, and Git review, use the
|
|
@@ -666,7 +665,7 @@ for adding the pinning step to an application.
|
|
|
666
665
|
|
|
667
666
|
## Snapshots, Devbox Creation, Sleep, Wake, And Reset
|
|
668
667
|
|
|
669
|
-
For an
|
|
668
|
+
For an independent project's Template box, use:
|
|
670
669
|
|
|
671
670
|
```bash
|
|
672
671
|
dvb checkpoint <template-box>
|
|
@@ -674,7 +673,7 @@ dvb checkpoint <template-box>
|
|
|
674
673
|
|
|
675
674
|
to capture a new snapshot of the Template box.
|
|
676
675
|
|
|
677
|
-
|
|
676
|
+
Managed projects have no personal Template box, so checkpoint and
|
|
678
677
|
other Template-only commands are not available for them. Their team admins save
|
|
679
678
|
new versions through the Team Template editor.
|
|
680
679
|
|
|
@@ -710,7 +709,7 @@ later; destroy removes it.
|
|
|
710
709
|
|
|
711
710
|
## Services, IDE, SSH, And Mounts
|
|
712
711
|
|
|
713
|
-
`dvb services` manages user services running on the selected
|
|
712
|
+
`dvb services` manages user services running on the selected box. System
|
|
714
713
|
services owned by boxes.dev are hidden from normal service management.
|
|
715
714
|
|
|
716
715
|
`dvb ide` prepares and opens remote editor access. `dvb ssh proxy` supports the
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# Convex
|
|
2
|
+
|
|
3
|
+
Use this doc when a user asks how to connect Convex, how the Convex CLI gets
|
|
4
|
+
credentials on a box, which team a boxes.dev project can access, or why a
|
|
5
|
+
Convex command needs a new sign-in.
|
|
6
|
+
|
|
7
|
+
Each user can connect one Convex team to each boxes.dev project. The project's
|
|
8
|
+
Template box and devboxes receive expiring credentials for that team, with the
|
|
9
|
+
permissions Convex grants the connected user. Restricted project or deployment
|
|
10
|
+
access is not available in this version.
|
|
11
|
+
|
|
12
|
+
## Connect Convex
|
|
13
|
+
|
|
14
|
+
Open **Integrations → Convex** in the desktop app and choose **Connect
|
|
15
|
+
Convex**. Choose **Open Convex**, check that the one-time code matches, and
|
|
16
|
+
select **Confirm**. Convex describes this request as Convex CLI. Return to
|
|
17
|
+
boxes.dev, choose a team, and select **Connect team**.
|
|
18
|
+
|
|
19
|
+
This sign-in grants boxes.dev access to the user's Convex account. The personal
|
|
20
|
+
access token stays encrypted in boxes.dev; boxes receive only expiring tokens
|
|
21
|
+
for the chosen team. The connection belongs to this user and boxes.dev project,
|
|
22
|
+
so another project or teammate needs its own connection.
|
|
23
|
+
|
|
24
|
+
## CLI credentials and renewal
|
|
25
|
+
|
|
26
|
+
Use `boxes-convex` from the repository with the same arguments as `npx convex`,
|
|
27
|
+
for example `boxes-convex dev` or `boxes-convex run example:status`. The launcher
|
|
28
|
+
resolves the project's installed `convex` package; install that dependency
|
|
29
|
+
first. If the command is missing, update the box's software in boxes.dev.
|
|
30
|
+
|
|
31
|
+
For a fresh checkout without a selected deployment, run
|
|
32
|
+
`boxes-convex deployment select <deployment-name>` before `boxes-convex dev`.
|
|
33
|
+
Get the name from the user's Convex dashboard or existing project settings.
|
|
34
|
+
The CLI's interactive account/team discovery is PAT-only, so use the explicit
|
|
35
|
+
deployment selection. This sets the command target; the credential still
|
|
36
|
+
covers the chosen team. Do not create a separate personal login to configure
|
|
37
|
+
the checkout.
|
|
38
|
+
|
|
39
|
+
Convex CLI currently rejects team tokens during its personal account opt-in
|
|
40
|
+
check. The launcher skips only that unsupported check when its request uses
|
|
41
|
+
the current, unexpired managed team token. All deployment authorization and
|
|
42
|
+
other requests retain native behavior, including permission denials. It does
|
|
43
|
+
not modify project packages or the environment of other Node programs. Direct
|
|
44
|
+
`npx convex dev` can still fail; use the launcher for the managed team login.
|
|
45
|
+
|
|
46
|
+
boxes.dev writes the team token to the native `~/.convex/config.json` login
|
|
47
|
+
file. The launcher and other native CLI commands read that file. boxes.dev
|
|
48
|
+
does not install Convex or change the repository's deployment selection.
|
|
49
|
+
|
|
50
|
+
Team tokens expire after eight hours. boxes.dev renews them before expiry and
|
|
51
|
+
updates the managed file on running boxes; sleeping boxes pick up the current
|
|
52
|
+
credential after waking. New commands from terminals, Codex, and Claude use
|
|
53
|
+
the renewed token. For an ordinary managed `boxes-convex dev` watcher, the
|
|
54
|
+
launcher will briefly stop and restart Convex when replacement credentials
|
|
55
|
+
arrive. It keeps the same arguments, working directory, and terminal, including
|
|
56
|
+
`--prod` when the user selected it. Convex still controls production permissions.
|
|
57
|
+
|
|
58
|
+
Automatic restarts don't apply to personal or explicitly supplied credentials,
|
|
59
|
+
including deploy keys in project env files. They also don't apply to `--once`,
|
|
60
|
+
`--until-success`, `--configure`, `--run`, `--run-sh`, or `--start`, so renewal
|
|
61
|
+
won't repeat one-time work or startup hooks. Restart those commands manually
|
|
62
|
+
after an authentication error to read the renewed file. Do not start a
|
|
63
|
+
separate personal sign-in to repair a command that kept its old token.
|
|
64
|
+
|
|
65
|
+
An existing personal CLI login is preserved. Credentials supplied explicitly,
|
|
66
|
+
including `CONVEX_DEPLOY_KEY`, `CONVEX_DEPLOYMENT_TOKEN`, or
|
|
67
|
+
`CONVEX_OVERRIDE_ACCESS_TOKEN`, can take precedence over the managed login.
|
|
68
|
+
Check those settings if a command uses different permissions than expected.
|
|
69
|
+
|
|
70
|
+
Agents should not run `convex login` or `convex logout` unless the user asks.
|
|
71
|
+
`convex login` creates a separate login on that box, which boxes.dev preserves.
|
|
72
|
+
`convex logout` deletes the local file; while the integration is connected,
|
|
73
|
+
boxes.dev will restore its managed token. Remove the connection in Integrations
|
|
74
|
+
to stop using it.
|
|
75
|
+
|
|
76
|
+
## Reconnect or remove
|
|
77
|
+
|
|
78
|
+
When the saved sign-in expires, is revoked, or cannot issue team credentials,
|
|
79
|
+
the pane shows **Convex needs you to sign in again**. Choose **Reconnect**,
|
|
80
|
+
finish the new sign-in, and choose the team again. **Change team** in the
|
|
81
|
+
options menu starts the same sign-in and selection flow.
|
|
82
|
+
|
|
83
|
+
To disconnect, choose **Remove connection** in the options menu and confirm.
|
|
84
|
+
boxes.dev removes the credentials it wrote on running boxes, revokes the saved
|
|
85
|
+
sign-in and current team token, and stops renewing access. Previously issued
|
|
86
|
+
credentials may remain valid until their expiry. Sleeping boxes remove their
|
|
87
|
+
managed credentials after waking. Personal logins are left alone.
|
|
88
|
+
|
|
89
|
+
Convex permissions still determine access to development and production. This
|
|
90
|
+
integration does not add a production role or bypass Convex's permission checks.
|
|
91
|
+
An organization's sign-in policy may require signing in again through its
|
|
92
|
+
identity provider.
|
|
@@ -11,6 +11,10 @@ projects without personal Template boxes; those projects still own their
|
|
|
11
11
|
devboxes, threads, settings, and integrations. Set up another project when a
|
|
12
12
|
different codebase needs its own environment.
|
|
13
13
|
|
|
14
|
+
An **independent project** has its own Template box. A **managed project** uses
|
|
15
|
+
a Team Template and has no Template box of its own. Team members can own either
|
|
16
|
+
type. See `glossary.md` for older names and aliases.
|
|
17
|
+
|
|
14
18
|
## Team Template
|
|
15
19
|
|
|
16
20
|
A Team Template is one named, team-wide, versioned starting environment for new
|
|
@@ -18,15 +22,15 @@ projects. It is not a project's Template box. A team can have several Team
|
|
|
18
22
|
Templates for different project shapes. Each has its own release history and
|
|
19
23
|
editing lock. Team admins publish releases, and current team members can create
|
|
20
24
|
independent projects from a selected template's active saved version without
|
|
21
|
-
supplying a local repository. A Team Template can create an
|
|
22
|
-
with its own Template box or a
|
|
25
|
+
supplying a local repository. A Team Template can create an independent project
|
|
26
|
+
with its own Template box or a managed project whose future devboxes keep using
|
|
23
27
|
the Team Template's current saved files. See `team-template.md` for the editing,
|
|
24
28
|
saved-version, setup, Git access, and copied-data workflow.
|
|
25
29
|
|
|
26
30
|
## Template box
|
|
27
31
|
|
|
28
|
-
The Template box is the persistent base machine for an
|
|
29
|
-
the source that future devboxes start from.
|
|
32
|
+
The Template box is the persistent base machine for an independent project. It is
|
|
33
|
+
the source that future devboxes start from. Managed projects do
|
|
30
34
|
not have one.
|
|
31
35
|
|
|
32
36
|
Use the Template box for:
|
|
@@ -42,7 +46,7 @@ is intentionally part of the shared baseline.
|
|
|
42
46
|
## Devbox
|
|
43
47
|
|
|
44
48
|
A devbox is an isolated machine created from the project's reusable source: an
|
|
45
|
-
|
|
49
|
+
independent project's Template-box snapshot or a managed project's current Team
|
|
46
50
|
Template saved version. Each devbox has its own filesystem, services, memory,
|
|
47
51
|
local app state, terminal sessions, ports, and agent threads.
|
|
48
52
|
|
|
@@ -53,8 +57,8 @@ project uses, then sleep or destroy devboxes you no longer need.
|
|
|
53
57
|
|
|
54
58
|
## Thread
|
|
55
59
|
|
|
56
|
-
A thread is a conversation with a coding agent connected to a
|
|
57
|
-
boxes.dev, threads run on a devbox or, in an
|
|
60
|
+
A thread is a conversation with a coding agent connected to a box. In
|
|
61
|
+
boxes.dev, threads run on a devbox or, in an independent project, on the Template
|
|
58
62
|
box.
|
|
59
63
|
|
|
60
64
|
The agent is Codex or Claude, depending on what is enabled and authenticated.
|
|
@@ -62,26 +66,25 @@ In the desktop app, GUI and the CLI are two views of that same conversation,
|
|
|
62
66
|
not separate thread types. A thread may be user-started, setup-created, or
|
|
63
67
|
spawned by an automation or integration.
|
|
64
68
|
|
|
65
|
-
##
|
|
69
|
+
## Selected box
|
|
66
70
|
|
|
67
|
-
A
|
|
68
|
-
|
|
69
|
-
the app.
|
|
71
|
+
A box is a devbox or Template box. The selected box is the one currently chosen
|
|
72
|
+
in the desktop app.
|
|
70
73
|
|
|
71
|
-
The selected
|
|
72
|
-
status, wake/sleep controls, and
|
|
74
|
+
The selected box matters because terminals, forwarded ports, file views, git
|
|
75
|
+
status, wake/sleep controls, and box usage indicators follow it. If a user
|
|
73
76
|
selects a devbox, those tools operate on the devbox. If the user selects the
|
|
74
|
-
Template box, they operate on the Template box.
|
|
77
|
+
Template box, they operate on the Template box. Port forwarding follows
|
|
78
|
+
selection by default, but can stay on one box when pinned.
|
|
75
79
|
|
|
76
80
|
## Snapshot
|
|
77
81
|
|
|
78
|
-
A snapshot is a saved state of an
|
|
82
|
+
A snapshot is a saved state of an independent project's Template box that future
|
|
79
83
|
devboxes can start from. A snapshot preserves the saved filesystem, local
|
|
80
84
|
development data, and memory. Apps that run independently of agents and
|
|
81
85
|
terminals, such as Docker containers and system services, keep running on new
|
|
82
86
|
devboxes. Copied agents, terminals, and processes started from them do not
|
|
83
|
-
continue, and background services from setup start again. Team Template
|
|
84
|
-
member projects use the Team Template's current saved version instead; team
|
|
87
|
+
continue, and background services from setup start again. Managed projects use the Team Template's current saved version instead; team
|
|
85
88
|
admins update it from the Team Template editor.
|
|
86
89
|
|
|
87
90
|
Take a new snapshot after updating the Template box in a way future devboxes
|
|
@@ -94,7 +97,7 @@ From a Template box terminal or coding-agent session, run:
|
|
|
94
97
|
dvb-onbox snapshot
|
|
95
98
|
```
|
|
96
99
|
|
|
97
|
-
This does the same thing as **New snapshot** in the
|
|
100
|
+
This does the same thing as **New snapshot** in the box menu. The command
|
|
98
101
|
waits through the brief capture window and reports the new snapshot ID after
|
|
99
102
|
the machine reconnects. If Codex or Claude is running, boxes.dev will resume
|
|
100
103
|
that work only on the Template box; future devboxes will receive the saved
|
|
@@ -111,20 +114,22 @@ snapshot and then create the devbox.
|
|
|
111
114
|
|
|
112
115
|
## Checkpoint
|
|
113
116
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
+
The active workstation CLI command `dvb checkpoint <template-box>` takes a
|
|
118
|
+
Template box snapshot. From the Template box itself, use `dvb-onbox snapshot`.
|
|
119
|
+
Prefer snapshot when describing the saved state, and preserve checkpoint in
|
|
120
|
+
the exact CLI invocation. This alias does not refer to a separate product
|
|
121
|
+
feature.
|
|
117
122
|
|
|
118
123
|
## Awake, Sleeping, And Waking
|
|
119
124
|
|
|
120
|
-
Awake
|
|
121
|
-
Sleeping
|
|
122
|
-
instead of restarting it, but they do not run commands or consume awake
|
|
125
|
+
Awake boxes can run commands, serve ports, and accept live agent work.
|
|
126
|
+
Sleeping boxes retain their machine state in memory, like sleeping a laptop
|
|
127
|
+
instead of restarting it, but they do not run commands or consume awake box
|
|
123
128
|
capacity. Waking is the transition from sleeping back to running.
|
|
124
129
|
|
|
125
|
-
The desktop app shows
|
|
130
|
+
The desktop app shows box states such as Running, Connected, Sleeping,
|
|
126
131
|
Waking, Connecting, Upgrading, Snapshotting, and Disconnected depending on the
|
|
127
|
-
selected
|
|
132
|
+
selected box and current operation.
|
|
128
133
|
|
|
129
134
|
## Awake Devbox Limit
|
|
130
135
|
|
|
@@ -134,12 +139,12 @@ it can be woken when the awake devbox limit is reached.
|
|
|
134
139
|
|
|
135
140
|
## Template box Snapshots Versus Devbox Work
|
|
136
141
|
|
|
137
|
-
For an
|
|
138
|
-
For a
|
|
142
|
+
For an independent project, the Template box is the source of future devbox state.
|
|
143
|
+
For a managed project, the shared Team Template saved version is
|
|
139
144
|
the source. A devbox is where a specific task should happen. If useful setup
|
|
140
|
-
was discovered while working on an
|
|
145
|
+
was discovered while working on an independent-project devbox, apply that setup to
|
|
141
146
|
the Template box and take a new snapshot only when future devboxes should
|
|
142
|
-
inherit it. For a
|
|
147
|
+
inherit it. For a managed project, ask a team admin to update the Team Template
|
|
143
148
|
when the shared baseline should change.
|
|
144
149
|
|
|
145
150
|
Do not assume changes made on a devbox automatically update the Template box or
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
The desktop workbench is the main boxes.dev workspace. It is where you switch
|
|
4
4
|
projects, read and start agent threads, open files and Git, use the terminal,
|
|
5
5
|
use the shared Browser, open forwarded ports, and wake or sleep the selected
|
|
6
|
-
|
|
6
|
+
box.
|
|
7
7
|
|
|
8
8
|
## The Main Areas
|
|
9
9
|
|
|
@@ -21,7 +21,7 @@ The workbench has a few persistent areas:
|
|
|
21
21
|
thread is selected and hidden when the left pane
|
|
22
22
|
is too narrow to fit it. A thread inside a collapsed automation stays hidden
|
|
23
23
|
until you expand that automation. The
|
|
24
|
-
content pane's title bar starts with
|
|
24
|
+
content pane's title bar starts with box status, metrics, and ports when
|
|
25
25
|
a Template box or devbox is selected, and ends with the
|
|
26
26
|
Terminal/Files/Git/Review/Browser pane control as icon-only buttons that show
|
|
27
27
|
their names on hover; update notices appear in the middle when available.
|
|
@@ -59,8 +59,8 @@ The titlebar pane control switches the aux pane between Terminal, Files,
|
|
|
59
59
|
Git/Review, and Browser. The app menu can show or hide the Agent pane. At least
|
|
60
60
|
one main area stays visible. A new devbox starts with no aux pane open. The
|
|
61
61
|
Template box and each devbox then remember their last aux-pane choice
|
|
62
|
-
independently, so returning to a
|
|
63
|
-
can be resized. Showing Terminal reattaches the
|
|
62
|
+
independently, so returning to a box restores its previous pane. Pane widths
|
|
63
|
+
can be resized. Showing Terminal reattaches the box's open terminal
|
|
64
64
|
sessions, or starts one if it has none, and closing the last terminal tab
|
|
65
65
|
closes the pane.
|
|
66
66
|
|
|
@@ -199,9 +199,8 @@ Help:
|
|
|
199
199
|
|
|
200
200
|
- Show keyboard shortcuts: **Cmd+Shift+/** (Ctrl+Shift+/)
|
|
201
201
|
|
|
202
|
-
This opens
|
|
203
|
-
and every customizable shortcut with its current binding. **
|
|
204
|
-
Keyboard shortcuts** at the bottom of the sidebar opens the same dialog.
|
|
202
|
+
This opens Settings → Keyboard shortcuts, which lists the fixed history keys
|
|
203
|
+
and every customizable shortcut with its current binding. **Settings > Keyboard shortcuts** at the bottom of the sidebar opens the same dialog.
|
|
205
204
|
Controls that have a shortcut, such as the pane toggles in the titlebar, also
|
|
206
205
|
show their binding in the hover
|
|
207
206
|
tooltip. The dynamic thread-number shortcuts always follow sidebar order and
|
|
@@ -210,7 +209,7 @@ are not customizable.
|
|
|
210
209
|
### Customizing Shortcuts
|
|
211
210
|
|
|
212
211
|
Workbench shortcuts with a Rebind control can be changed. Open the dialog
|
|
213
|
-
(**Cmd+Shift+/**, **
|
|
212
|
+
(**Cmd+Shift+/**, **Settings > Keyboard shortcuts**, or **Customize** in
|
|
214
213
|
the search modal footer), then click Rebind on a shortcut and press the new
|
|
215
214
|
combo.
|
|
216
215
|
Bindings must include Cmd or Ctrl, cannot use Alt, and cannot collide with
|
|
@@ -223,7 +222,7 @@ row to return it to the default.
|
|
|
223
222
|
Use the project selector in the titlebar to switch between projects on the same
|
|
224
223
|
desktop app account. Threads and devboxes are shown for the selected project.
|
|
225
224
|
Most projects have one Template box. A project created through a Team
|
|
226
|
-
Template's **
|
|
225
|
+
Template's **managed projects** mode has no personal Template box and omits that
|
|
227
226
|
row without changing its normal thread and devbox workflow.
|
|
228
227
|
|
|
229
228
|
Use **New project...** in the project selector to add another project. On
|
|
@@ -254,34 +253,34 @@ through **New project...** instead of this admin-only management menu.
|
|
|
254
253
|
Project settings, integrations, automations, and a teammate's shared thread do
|
|
255
254
|
not select one of your Template boxes or devboxes. On those pages, machine
|
|
256
255
|
status and workspace tools are hidden and the workbench does not wake the
|
|
257
|
-
machine you last used. Return to one of your own
|
|
258
|
-
available, the Template box when you want
|
|
256
|
+
machine you last used. Return to one of your own threads connected to a box or, when
|
|
257
|
+
available, the Template box when you want box controls and Files,
|
|
259
258
|
Git/Review, Terminal, Browser, or Ports.
|
|
260
259
|
|
|
261
|
-
The app menu also includes **Project settings**, **
|
|
260
|
+
The app menu also includes **Project settings**, **Settings...**,
|
|
262
261
|
**Configure agents...**, **Sign Out**, update actions, and **Show Workbench**.
|
|
263
262
|
Configure agents can save multiple Codex and Claude accounts or API keys and
|
|
264
263
|
choose one active credential for each agent across all devboxes. The File menu
|
|
265
264
|
also includes **Delete This Project**.
|
|
266
265
|
|
|
267
|
-
##
|
|
266
|
+
## Box status
|
|
268
267
|
|
|
269
|
-
The
|
|
268
|
+
The box status control describes the selected box, which may be the
|
|
270
269
|
Template box or a devbox depending on the selected thread. It can show states
|
|
271
270
|
such as running, sleeping, waking, snapshotting, migration or repair needed, and
|
|
272
271
|
related errors.
|
|
273
272
|
|
|
274
|
-
Use the status control to wake or sleep the selected
|
|
273
|
+
Use the status control to wake or sleep the selected box when those actions
|
|
275
274
|
are available. Its auto-wake setting controls whether a sleeping Template box or
|
|
276
275
|
devbox wakes when you return to it; when auto-wake is off, use an explicit Wake
|
|
277
276
|
action instead.
|
|
278
277
|
|
|
279
278
|
Three small CPU, memory, and disk meters show live utilization for the selected
|
|
280
|
-
|
|
279
|
+
box. CPU and memory fill colors highlight elevated load. The disk meter
|
|
281
280
|
turns yellow below 2 GiB free and red below 1 GiB free. Hover the meters for
|
|
282
281
|
exact resource details, or click them to open an Activity Monitor-style view of
|
|
283
|
-
processes on the
|
|
284
|
-
|
|
282
|
+
processes on the box. Empty tracks remain visible while the selected
|
|
283
|
+
box has no live metrics.
|
|
285
284
|
|
|
286
285
|
## Project Settings
|
|
287
286
|
|
|
@@ -294,27 +293,43 @@ startup script, shared agent guidance, automatic waking of sleeping machines,
|
|
|
294
293
|
other new-devbox defaults, and the Claude and Codex settings kept on every box
|
|
295
294
|
(see `threads-and-agents.md`). Opening it does not select or wake a machine.
|
|
296
295
|
|
|
297
|
-
To change the automatic idle-sleep timeout, open **
|
|
298
|
-
→ Sleep timeout** and choose 5, 15, 30, or 60 minutes, or **Team default**.
|
|
299
|
-
Team admins can set the default in **Team
|
|
296
|
+
To change the automatic idle-sleep timeout, open **Settings
|
|
297
|
+
→ General → Sleep timeout** and choose 5, 15, 30, or 60 minutes, or **Team default**.
|
|
298
|
+
Team admins can set the default in **Settings → Team and members → Sleep timeout**; without
|
|
300
299
|
a custom setting it is five minutes. Your choice overrides the team default
|
|
301
|
-
for your Template boxes and devboxes, including
|
|
300
|
+
for your Template boxes and devboxes, including managed projects.
|
|
302
301
|
Changes apply to existing and new boxes. A running box may keep its current
|
|
303
302
|
sleep deadline until its next activity; saving will not wake a sleeping box.
|
|
304
303
|
Longer timeouts use more box-hours; active agents can still keep boxes awake.
|
|
305
304
|
|
|
306
|
-
Open the account menu
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
305
|
+
Open **Settings…** from the account menu, or press Cmd+, (Ctrl+,), for one
|
|
306
|
+
pane with a category sidebar. General, Notifications, Agents, Connections,
|
|
307
|
+
Browser, Terminal, Keyboard shortcuts, and Account contain personal and device
|
|
308
|
+
preferences. Labels distinguish **On this computer** and **Across devices**.
|
|
309
|
+
Team admins also see Team and members and Integrations; Billing & usage
|
|
310
|
+
retains its existing permissions. Opening Settings preserves the current
|
|
311
|
+
thread, draft, and terminal. Compound forms keep their own Save actions, and
|
|
312
|
+
leaving an edited form asks before discarding its changes.
|
|
313
|
+
|
|
314
|
+
**Related settings** links to the selected project's existing Project settings
|
|
315
|
+
and its associated Team Template, including an independent project's recorded
|
|
316
|
+
source. Without a project or source template, the links open the project list
|
|
317
|
+
or template collection. Back returns to the originating section. Opening a
|
|
318
|
+
link does not start an editing machine. At narrow widths, a section selector
|
|
319
|
+
replaces the sidebar and both links remain visible.
|
|
320
|
+
|
|
321
|
+
An older desktop client shows **Open desktop preferences** for settings whose
|
|
322
|
+
editor is unavailable in its bridge. Its native settings window remains
|
|
323
|
+
usable until the app is updated, and remains available while signed out.
|
|
324
|
+
The account menu retains account switching, notification pause, updates, and
|
|
325
|
+
log out; usage and Help stay beside it.
|
|
311
326
|
|
|
312
327
|
## Template box
|
|
313
328
|
|
|
314
329
|
For a project that has one, the Template box page is for the project's exact
|
|
315
330
|
Template machine. Use it to manage snapshots, repositories, maintenance, or
|
|
316
331
|
the machine itself; open its terminal, inspect files or Git, or check whether
|
|
317
|
-
it is awake.
|
|
332
|
+
it is awake. Managed projects omit the page and its thread,
|
|
318
333
|
snapshot, repository, terminal, and power controls.
|
|
319
334
|
|
|
320
335
|
Under **Project**, select the **Template box** row's title to open its page.
|
|
@@ -446,7 +461,7 @@ finished agents leave it after your next message. The inspector is read-only.
|
|
|
446
461
|
Older conversations may not have a subagent list.
|
|
447
462
|
|
|
448
463
|
To distinguish Claude and Codex threads at a glance, turn on **Show agent
|
|
449
|
-
logos** in **
|
|
464
|
+
logos** in **Settings > General**. The logos appear
|
|
450
465
|
at the right edge of thread rows and are off by default.
|
|
451
466
|
|
|
452
467
|
Thread rows can show unread or attention state. When a thread completes, fails,
|
|
@@ -469,8 +484,7 @@ finished turns don't notify you or mark it unread; requests for input still
|
|
|
469
484
|
do. **Mark unread** on a muted thread lasts until you open it or its next turn
|
|
470
485
|
finishes. **Unmute notifications** turns them back on.
|
|
471
486
|
|
|
472
|
-
Desktop completion notifications are controlled in **
|
|
473
|
-
Notifications**:
|
|
487
|
+
Desktop completion notifications are controlled in **Settings > Notifications**:
|
|
474
488
|
|
|
475
489
|
- **Never** turns banners and sounds off for completed replies, failures, and
|
|
476
490
|
requests for input.
|
|
@@ -483,7 +497,7 @@ Notifications**:
|
|
|
483
497
|
**Play notification sounds** is on by default. Turn it off to keep banners
|
|
484
498
|
without sound. Update the desktop app if this control is missing. Agent replies
|
|
485
499
|
do not ring the terminal bell or bounce the Dock icon; terminal bells have
|
|
486
|
-
their own settings under **
|
|
500
|
+
their own settings under **Settings > Terminal > Bell**.
|
|
487
501
|
|
|
488
502
|
Eligible controlled Codex completion notifications include the final-response
|
|
489
503
|
preview when it is available and a generic completion preview during recovery;
|
|
@@ -491,7 +505,7 @@ failures include a status preview. Selecting a notification opens its project
|
|
|
491
505
|
and thread. Delivery also depends on the operating system's notification
|
|
492
506
|
settings for boxes.dev.
|
|
493
507
|
|
|
494
|
-
**
|
|
508
|
+
**Settings → Notifications → Quiet hours** sets a daily interval shared with
|
|
495
509
|
mobile and your other computers. Each device uses its own timezone. Use the
|
|
496
510
|
account menu's **Pause notifications for 1 hour** to silence agent alerts on
|
|
497
511
|
every device for this account until the same end time; **Resume notifications**
|
|
@@ -573,11 +587,11 @@ own Find shortcut when focused.
|
|
|
573
587
|
## Files And Git
|
|
574
588
|
|
|
575
589
|
The Files and Git/Review segments in the titlebar open panes for the selected
|
|
576
|
-
|
|
590
|
+
box. Use Files to browse, search, upload, download, preview, and add
|
|
577
591
|
plain-file review comments. Use Git/Review to inspect repository status, diffs,
|
|
578
592
|
history, review comments, staging, and commits.
|
|
579
593
|
|
|
580
|
-
These panes route to the
|
|
594
|
+
These panes route to the box for the selected thread. If a devbox thread is
|
|
581
595
|
selected, Files and Git/Review inspect that devbox. If the Template box is
|
|
582
596
|
selected, they inspect the Template box.
|
|
583
597
|
|
|
@@ -585,15 +599,15 @@ See `files-git-and-review.md` for the detailed workflow.
|
|
|
585
599
|
|
|
586
600
|
## Browser
|
|
587
601
|
|
|
588
|
-
The Browser pane opens a Chromium session on the selected
|
|
602
|
+
The Browser pane opens a Chromium session on the selected box. It follows
|
|
589
603
|
the same selection model as Files, Git/Review, Terminal, and Ports: Template box
|
|
590
604
|
when the Template box is selected, the selected devbox when a devbox thread is
|
|
591
605
|
selected.
|
|
592
606
|
|
|
593
607
|
Browser tabs, cookies, local storage, downloads, uploads, and other profile
|
|
594
|
-
state live on that
|
|
608
|
+
state live on that box, so the user and agents can share the same web
|
|
595
609
|
session. The Browser pane supports ordinary page interaction, file chooser
|
|
596
|
-
prompts, downloads into the
|
|
610
|
+
prompts, downloads into the box, permission prompts, browser dialogs, and
|
|
597
611
|
profile reset. **Restart browser** asks for confirmation, then opens one blank
|
|
598
612
|
tab while preserving sign-ins and saved profile data. Check **Restore open
|
|
599
613
|
tabs** in that confirmation to reload the current tabs instead; the choice
|
|
@@ -618,7 +632,7 @@ If the stream can't connect after a second attempt, the pane shows
|
|
|
618
632
|
WebRTC streaming shows that it needs an update, and a page whose video stops
|
|
619
633
|
shows **Browser stopped updating** with **Try again**.
|
|
620
634
|
|
|
621
|
-
**
|
|
635
|
+
**Settings → Browser → Chrome window** shows the box's whole Chrome window in
|
|
622
636
|
Browser, with Chrome's own tabs, address bar, menus, and page dialogs in place
|
|
623
637
|
of the pane's address bar, navigation buttons, and tab strip. It is off by
|
|
624
638
|
default and saved to the account, and it applies to the desktop and mobile
|
|
@@ -653,9 +667,9 @@ can lose unsaved form entries. Agents use the shared browser skill's
|
|
|
653
667
|
`POST /.sprite/api/browser/restart` route; reading the browser's state alone
|
|
654
668
|
does not restart a disconnected browser.
|
|
655
669
|
|
|
656
|
-
The
|
|
670
|
+
The box has no security key or platform authenticator of its own. In the
|
|
657
671
|
desktop app, Browser-pane passkey forwarding is off by default and can be
|
|
658
|
-
enabled under **
|
|
672
|
+
enabled under **Settings > Browser > Allow sites to use a passkey
|
|
659
673
|
on this computer**. The first eligible passkey request can also ask whether to
|
|
660
674
|
enable forwarding and warns that a compromised sandbox could spoof the
|
|
661
675
|
requesting site shown in later passkey confirmation windows. Once enabled,
|
|
@@ -669,7 +683,7 @@ Coding agents cannot use passkeys or cause the confirmation window to open.
|
|
|
669
683
|
Passkey forwarding accepts only recent user input from the Browser pane. Ask
|
|
670
684
|
the user to complete the passkey flow themselves; the resulting Browser profile
|
|
671
685
|
session remains shared with the agent afterwards. If the user disabled passkey
|
|
672
|
-
forwarding, they can re-enable it under **
|
|
686
|
+
forwarding, they can re-enable it under **Settings > Browser**.
|
|
673
687
|
|
|
674
688
|
Users can also review specific page elements from the Browser. Select the
|
|
675
689
|
review control to enter a focused **Reviewing** mode, hover to preview a target,
|
|
@@ -696,7 +710,7 @@ element geometry.
|
|
|
696
710
|
## Ports
|
|
697
711
|
|
|
698
712
|
The ports control in the titlebar shows a singular or plural count of localhost
|
|
699
|
-
ports detected on the selected
|
|
713
|
+
ports detected on the selected box and forwarded to localhost on your
|
|
700
714
|
computer. You can open browser-friendly ports or copy the local target for other
|
|
701
715
|
tools, such as database clients.
|
|
702
716
|
|
|
@@ -704,7 +718,7 @@ See `ports-terminal-and-runtime.md` for details.
|
|
|
704
718
|
|
|
705
719
|
## Terminal
|
|
706
720
|
|
|
707
|
-
The terminal pane opens shell sessions on the selected
|
|
721
|
+
The terminal pane opens shell sessions on the selected box. It follows the
|
|
708
722
|
same selection model as Files, Git/Review, Browser, and Ports: Template box when
|
|
709
723
|
the Template box is selected, the selected devbox when a devbox thread is
|
|
710
724
|
selected.
|
|
@@ -714,13 +728,14 @@ terminal notification settings.
|
|
|
714
728
|
|
|
715
729
|
## Team Settings
|
|
716
730
|
|
|
717
|
-
Team admins can open **
|
|
731
|
+
Team admins can open **Settings → Team and members** from the account menu to review current
|
|
718
732
|
members and change another member between **Admin** and **Member**. An admin's
|
|
719
733
|
own role is read-only there, so another team admin must change it. Invitations
|
|
720
734
|
remain for new accounts; if an email is already on the team, manage that person
|
|
721
735
|
in the **Members** section instead.
|
|
722
736
|
|
|
723
|
-
|
|
737
|
+
**Settings → Integrations** shows **Static egress IP**, Tailscale, Slack,
|
|
738
|
+
and Linear. This optional feature gives the
|
|
724
739
|
team a stable public IPv4 to allowlist at an external database or service. It
|
|
725
740
|
is visible but off by default; use **Talk to us** to request enablement. Once
|
|
726
741
|
enabled, all team members can copy the current static IP and read the configured
|
|
@@ -733,7 +748,7 @@ periodic safety checks still recover a missed notification. Control-plane
|
|
|
733
748
|
authorization lasts at most ten minutes, and a destination's DNS expiry can
|
|
734
749
|
make the effective lease shorter. When the feature or its current policy is
|
|
735
750
|
unavailable and no valid lease is already applied, configured destinations fail
|
|
736
|
-
closed while unrelated
|
|
751
|
+
closed while unrelated box traffic continues normally. A temporary policy
|
|
737
752
|
or hostname refresh problem can preserve the exact already-applied path only
|
|
738
753
|
through its original lease deadline; it does not renew permission, and Team
|
|
739
754
|
Settings may still show temporary unavailability. Routine boxes.dev
|