@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.
Files changed (66) hide show
  1. package/dist/agent-init-guides/git-ssh.md +2 -2
  2. package/dist/bin/dvb.mjs +121 -72
  3. package/dist/bin/dvbd.mjs +6 -6
  4. package/dist/postgres-tools/SHA256SUMS +32 -8
  5. package/dist/postgres-tools/linux-arm64-el8/bin/pg_dump +0 -0
  6. package/dist/postgres-tools/linux-arm64-el8/bin/pg_restore +0 -0
  7. package/dist/postgres-tools/linux-arm64-el8/lib/libpq.so.5 +0 -0
  8. package/dist/postgres-tools/linux-arm64-el8/notices/PostgreSQL-COPYRIGHT.txt +23 -0
  9. package/dist/postgres-tools/linux-arm64-el9/bin/pg_dump +0 -0
  10. package/dist/postgres-tools/linux-arm64-el9/bin/pg_restore +0 -0
  11. package/dist/postgres-tools/linux-arm64-el9/lib/libpq.so.5 +0 -0
  12. package/dist/postgres-tools/linux-arm64-el9/notices/PostgreSQL-COPYRIGHT.txt +23 -0
  13. package/dist/postgres-tools/linux-arm64-ubuntu22.04/bin/pg_dump +0 -0
  14. package/dist/postgres-tools/linux-arm64-ubuntu22.04/bin/pg_restore +0 -0
  15. package/dist/postgres-tools/linux-arm64-ubuntu22.04/lib/libpq.so.5 +0 -0
  16. package/dist/postgres-tools/linux-x64-el8/bin/pg_dump +0 -0
  17. package/dist/postgres-tools/linux-x64-el8/bin/pg_restore +0 -0
  18. package/dist/postgres-tools/linux-x64-el8/lib/libpq.so.5 +0 -0
  19. package/dist/postgres-tools/linux-x64-el8/notices/PostgreSQL-COPYRIGHT.txt +23 -0
  20. package/dist/postgres-tools/linux-x64-el9/bin/pg_dump +0 -0
  21. package/dist/postgres-tools/linux-x64-el9/bin/pg_restore +0 -0
  22. package/dist/postgres-tools/linux-x64-el9/lib/libpq.so.5 +0 -0
  23. package/dist/postgres-tools/linux-x64-el9/notices/PostgreSQL-COPYRIGHT.txt +23 -0
  24. package/dist/postgres-tools/linux-x64-ubuntu22.04/bin/pg_dump +0 -0
  25. package/dist/postgres-tools/linux-x64-ubuntu22.04/bin/pg_restore +0 -0
  26. package/dist/postgres-tools/linux-x64-ubuntu22.04/lib/libpq.so.5 +0 -0
  27. package/dist/postgres-tools/linux-x64-ubuntu22.04/notices/PostgreSQL-and-Debian-copyright.txt +270 -0
  28. package/dist/postgres-tools/linux-x64-ubuntu24.04/notices/PostgreSQL-and-Debian-copyright.txt +270 -0
  29. package/dist/postgres-tools/release.json +306 -18
  30. package/dist/product-docs/references/agent-tools.md +6 -7
  31. package/dist/product-docs/references/automations.md +4 -4
  32. package/dist/product-docs/references/aws.md +17 -11
  33. package/dist/product-docs/references/billing-and-limits.md +26 -13
  34. package/dist/product-docs/references/cli.md +14 -15
  35. package/dist/product-docs/references/convex.md +92 -0
  36. package/dist/product-docs/references/core-concepts.md +35 -30
  37. package/dist/product-docs/references/desktop-workbench.md +62 -47
  38. package/dist/product-docs/references/files-git-and-review.md +14 -15
  39. package/dist/product-docs/references/fork-workflows.md +26 -25
  40. package/dist/product-docs/references/getting-started.md +11 -12
  41. package/dist/product-docs/references/glossary.md +46 -22
  42. package/dist/product-docs/references/google-cloud.md +13 -8
  43. package/dist/product-docs/references/index.md +20 -16
  44. package/dist/product-docs/references/linear.md +2 -2
  45. package/dist/product-docs/references/managed-environment-files.md +1 -1
  46. package/dist/product-docs/references/member-managed-files.md +4 -4
  47. package/dist/product-docs/references/mobile.md +18 -16
  48. package/dist/product-docs/references/onbox-agent-tools.md +63 -41
  49. package/dist/product-docs/references/ports-terminal-and-runtime.md +31 -28
  50. package/dist/product-docs/references/project-setup.md +15 -12
  51. package/dist/product-docs/references/security-and-data.md +23 -13
  52. package/dist/product-docs/references/slack.md +45 -7
  53. package/dist/product-docs/references/tailscale.md +2 -2
  54. package/dist/product-docs/references/team-template.md +26 -23
  55. package/dist/product-docs/references/template-box-environment.md +7 -3
  56. package/dist/product-docs/references/threads-and-agents.md +48 -24
  57. package/dist/product-docs/references/troubleshooting.md +24 -25
  58. package/package.json +2 -2
  59. /package/dist/postgres-tools/{linux-arm64 → linux-arm64-ubuntu22.04}/notices/PostgreSQL-and-Debian-copyright.txt +0 -0
  60. /package/dist/postgres-tools/{linux-arm64 → linux-arm64-ubuntu24.04}/bin/pg_dump +0 -0
  61. /package/dist/postgres-tools/{linux-arm64 → linux-arm64-ubuntu24.04}/bin/pg_restore +0 -0
  62. /package/dist/postgres-tools/{linux-arm64 → linux-arm64-ubuntu24.04}/lib/libpq.so.5 +0 -0
  63. /package/dist/postgres-tools/{linux-x64 → linux-arm64-ubuntu24.04}/notices/PostgreSQL-and-Debian-copyright.txt +0 -0
  64. /package/dist/postgres-tools/{linux-x64 → linux-x64-ubuntu24.04}/bin/pg_dump +0 -0
  65. /package/dist/postgres-tools/{linux-x64 → linux-x64-ubuntu24.04}/bin/pg_restore +0 -0
  66. /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 ordinary project with a personal Template box, the agent can design one
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. Team Template member projects support lifecycle editing but return
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 machine.
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 Team Template
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. Ordinary projects
327
- can use the current Template box or a new devbox; Team Template member projects
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 ordinary empty project, `n`
336
- targets the Template box. A Team Template member project has no Template
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 ordinary project, that is the
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 Team Template member
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 machine. Relative
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 ordinary project's Template box, use:
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
- Team Template member projects have no personal Template box, so checkpoint and
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 machine. System
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 ordinary project
22
- with its own Template box or a member project whose future devboxes keep using
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 ordinary project. It is
29
- the source that future devboxes start from. Team Template member projects do
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
- ordinary project's Template-box snapshot or a member project's current Team
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 runtime. In
57
- boxes.dev, threads run on a devbox or, in an ordinary project, on the Template
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
- ## Runtime
69
+ ## Selected box
66
70
 
67
- A runtime is the actual machine a pane or thread is connected to. The selected
68
- runtime is whichever devbox or available Template box is currently selected in
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 runtime matters because terminals, forwarded ports, file views, git
72
- status, wake/sleep controls, and runtime usage indicators follow it. If a user
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 ordinary project's Template box that future
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 runtime menu. The command
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
- Some CLI or older surfaces may use the term checkpoint for the same general idea
115
- as a saved machine state. In user-facing product guidance, prefer snapshot
116
- unless a command or UI label specifically says checkpoint.
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 runtimes can run commands, serve ports, and accept live agent work.
121
- Sleeping runtimes retain their machine state in memory, like sleeping a laptop
122
- instead of restarting it, but they do not run commands or consume awake runtime
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 runtime states such as Running, Connected, Sleeping,
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 runtime and current operation.
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 ordinary project, the Template box is the source of future devbox state.
138
- For a Team Template member project, the shared Team Template saved version is
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 ordinary-project devbox, apply that setup to
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 member project, ask a team admin to update the Team Template
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
- runtime.
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 runtime status, metrics, and ports when
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 runtime restores its previous pane. Pane widths
63
- can be resized. Showing Terminal reattaches the runtime's open terminal
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 the keyboard shortcuts dialog, which lists the fixed history keys
203
- and every customizable shortcut with its current binding. **Account menu >
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+/**, **Account menu > Keyboard shortcuts**, or **Customize** in
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 **Member projects** mode has no personal Template box and omits that
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 runtime-backed threads or, when
258
- available, the Template box when you want runtime controls and Files,
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**, **Desktop app 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
- ## Runtime Status
266
+ ## Box status
268
267
 
269
- The runtime status control describes the selected runtime, which may be 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 runtime when those actions
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
- runtime. CPU and memory fill colors highlight elevated load. The disk meter
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 runtime. Empty tracks remain visible while the selected
284
- runtime has no live metrics.
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 **Account
298
- → Sleep timeout** and choose 5, 15, 30, or 60 minutes, or **Team default**.
299
- Team admins can set the default in **Team settings → Sleep timeout**; without
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 Team Template member projects.
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 at the bottom of the left pane for **Desktop app
307
- settings...** and **Configure agents...**. Desktop app settings contains
308
- preferences for the app and terminal on this computer; Configure agents
309
- manages Codex and Claude accounts and API keys. The menu also contains
310
- keyboard shortcuts, account, billing, team, update, and log-out actions.
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. Team Template member projects omit the page and its thread,
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 **Desktop app settings > General > Thread list**. The logos appear
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 **Desktop app settings >
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 **Terminal settings > Behavior > Bell**.
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
- **Account → Notifications → Quiet hours** sets a daily interval shared with
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
- runtime. Use Files to browse, search, upload, download, preview, and add
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 runtime for the selected thread. If a devbox thread is
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 runtime. It follows
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 runtime, so the user and agents can share the same web
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 runtime, permission prompts, browser dialogs, and
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
- **Account → Advanced → Chrome window** shows the box's whole Chrome window in
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 runtime has no security key or platform authenticator of its own. In 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 **Desktop app settings > Browser > Allow sites to use a passkey
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 **Desktop app settings > Browser**.
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 runtime and forwarded to localhost on your
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 runtime. It follows the
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 **Manage team** from the account menu to review current
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
- Team settings also shows **Static egress IP**. This optional feature gives the
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 runtime traffic continues normally. A temporary policy
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