@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
@@ -1,6 +1,6 @@
1
1
  # Files, Git, And Review
2
2
 
3
- The Files and Git/Review panes let you inspect the selected runtime without
3
+ The Files and Git/Review panes let you inspect the selected box without
4
4
  leaving the desktop workbench. They can dock beside the thread or pop out into a
5
5
  larger overlay. When a Template box view is selected, they inspect the
6
6
  Template box. When a devbox thread is selected, they inspect that devbox.
@@ -32,7 +32,7 @@ right preview. For images, click the preview to open a
32
32
  full-screen, zoomable view (scroll or use the toolbar to zoom, drag to pan); the
33
33
  full-screen Files window zooms the image in place instead. Clicking an image
34
34
  file link in a thread opens Files and also opens that full-screen image view.
35
- Files that cannot be previewed inline can still be downloaded when the runtime
35
+ Files that cannot be previewed inline can still be downloaded when the box
36
36
  can provide a download URL.
37
37
 
38
38
  Supported text files can also be edited directly in Files. Changes auto-save
@@ -59,7 +59,7 @@ press Enter; Escape closes the prompt and returns to where you were. Go to line
59
59
  isn't available in Markdown Preview or for media and PDF previews.
60
60
 
61
61
  The file header shows the selected file name, path, file size, and modified
62
- time when available. Use Download to copy the selected file from the runtime to
62
+ time when available. Use Download to copy the selected file from the box to
63
63
  your computer. After a download finishes, use Open in Finder in the confirmation
64
64
  to reveal the saved file (Open in folder on Windows and Linux). When the selected
65
65
  file has Git changes, use Git/Review from the file header to open the matching
@@ -112,7 +112,7 @@ The search modal has two tabs:
112
112
  space-separated words each match anywhere in the path, so "usage dashboard"
113
113
  finds `usage-dashboard.tsx` and a folder name plus a file name works too. If
114
114
  nothing matches, press Enter to open exactly what you typed as a path.
115
- - **Text** searches file contents on the selected machine (powered by ripgrep).
115
+ - **Text** searches file contents on the selected box (powered by ripgrep).
116
116
  Matches are grouped by file with line numbers and highlighted matches. By
117
117
  default the search is literal and smart-case (lowercase queries match any
118
118
  case); toggles in the header switch on match case, whole word, and regular
@@ -198,7 +198,7 @@ selector in Git/Review. If boxes.dev detects unindexed direct-child repos, use
198
198
  **Review new repositories** to choose which ones join the project index. Older
199
199
  machines show the previous all-repository **Rescan** action until they update.
200
200
 
201
- If the selected runtime is asleep, wake it before using Git/Review.
201
+ If the selected box is asleep, wake it before using Git/Review.
202
202
 
203
203
  ## History View
204
204
 
@@ -242,7 +242,7 @@ boxes.dev refreshes expiring credentials automatically before they expire.
242
242
  If the refresh credential has also expired, reconnect GitHub. Temporary GitHub
243
243
  outages are retried without treating your authorization as revoked.
244
244
 
245
- For an ordinary project with automatic access, Git can use any GitHub repository
245
+ For an independent project with automatic access, Git can use any GitHub repository
246
246
  that the connected user's credential can read. boxes.dev verifies the machine
247
247
  and current repository access before returning the credential; GitHub enforces
248
248
  write permission and branch rules when you push.
@@ -265,8 +265,8 @@ perform ordinary Git operations while approval is pending.
265
265
 
266
266
  ## Adding And Reviewing Project Repositories
267
267
 
268
- The Template-box repository controls in this section apply to ordinary
269
- projects. A Team Template member project's tracked repositories come from the
268
+ The Template-box repository controls in this section apply to independent
269
+ projects. A managed project's tracked repositories come from the
270
270
  Team Template's current saved version. Members can use Git/Review on an assigned
271
271
  devbox, but cannot change the shared source or add a repository for future
272
272
  devboxes from their project.
@@ -300,7 +300,7 @@ without rerunning the repository work.
300
300
  repository into a multi-repository layout. It also does not appear for an SSH
301
301
  or non-GitHub project. To clone manually, including in an SSH or non-GitHub
302
302
  project, use a direct-child folder in a supported, non-overlapping
303
- multi-repository layout and open Git/Review on that runtime. Cloning inside a
303
+ multi-repository layout and open Git/Review on that box. Cloning inside a
304
304
  project whose root is itself a Git repository creates an overlapping layout
305
305
  that **Review new repositories** will not add.
306
306
 
@@ -329,7 +329,7 @@ but cannot add another repository at the project root.
329
329
 
330
330
  ### Private Git Dependencies
331
331
 
332
- Ordinary projects with automatic GitHub access can fetch private dependencies
332
+ Independent projects with automatic GitHub access can fetch private dependencies
333
333
  using the connected account's existing access, without adding another checkout.
334
334
  For an early access check with `dvb agent-init` on your own computer, list private
335
335
  GitHub dependencies in the setup manifest. For example, use
@@ -345,8 +345,7 @@ layout. If an existing setup is blocked, grant any missing GitHub access,
345
345
  continue its setup thread, and retry the dependency fetch. The manifest list
346
346
  only chooses which dependencies to check before setup; leaving it out or empty
347
347
  does not change repository access. Credentials retain their GitHub permissions.
348
- This flow does not change Team Template
349
- member projects. Run the setup CLI on your own computer, not inside a devbox.
348
+ This flow does not change managed projects. Run the setup CLI on your own computer, not inside a devbox.
350
349
 
351
350
  ## Git Author Identity
352
351
 
@@ -731,7 +730,7 @@ closes or merges. The manual **Fix checks**, **Address feedback**, and
731
730
  After the selected repository, remote, or branch changes, Git/Review may
732
731
  briefly show that GitHub repository state is updating. Pull-request actions
733
732
  become available only after boxes.dev confirms the new selection; if the state
734
- remains unavailable, wake the runtime and refresh Git/Review.
733
+ remains unavailable, wake the box and refresh Git/Review.
735
734
 
736
735
  ## Commit View
737
736
 
@@ -753,7 +752,7 @@ Commit is disabled until there is at least one staged file, a non-empty commit
753
752
  message, no unresolved conflicts, and no other Git action in progress.
754
753
 
755
754
  The commit message may be prefilled from merge, squash, template, or amend
756
- state. Draft commit messages are saved locally per runtime and repository while
755
+ state. Draft commit messages are saved locally per box and repository while
757
756
  you work.
758
757
 
759
758
  ## Conflicts And Read-Only Diffs
@@ -774,6 +773,6 @@ layout, or direct-child folders for a multi-repository layout. Nested
774
773
  repositories, submodules, linked-worktree duplicates, and overlapping root plus
775
774
  child layouts are not added by the review flow.
776
775
 
777
- Files still browses the selected runtime filesystem, so it can show files
776
+ Files still browses the selected box filesystem, so it can show files
778
777
  outside the selected Git repo. Git/Review is Git-aware and shows files from the
779
778
  Git status it receives for the selected context.
@@ -19,23 +19,23 @@ A devbox gives the task its own machine. The agent can edit files, run commands,
19
19
  start services, use ports, and test without disturbing the reusable project
20
20
  source or other devboxes.
21
21
 
22
- In an ordinary project, use the Template box only when the work should change
23
- the shared baseline that future devboxes inherit. Team Template member projects
22
+ In an independent project, use the Template box only when the work should change
23
+ the shared baseline that future devboxes inherit. Managed projects
24
24
  have no personal Template box; team admins maintain their source through the
25
25
  Team Template.
26
26
 
27
27
  ## Creating A New Devbox + Thread
28
28
 
29
29
  Start from **New thread** in the desktop thread list. Choose the agent,
30
- then send the first prompt. In an ordinary project, the devbox starts from the
31
- latest verified Template box snapshot. In a Team Template member project, it
30
+ then send the first prompt. In an independent project, the devbox starts from the
31
+ latest verified Template box snapshot. In a managed project, it
32
32
  starts from the Team Template's current saved version.
33
33
 
34
- If an ordinary project's Template box already has a snapshot, the default creation flow uses the
34
+ If an independent project's Template box already has a snapshot, the default creation flow uses the
35
35
  latest snapshot. If no snapshot exists, boxes.dev may offer to take the first
36
36
  snapshot and then create the devbox.
37
37
 
38
- If an ordinary project's Template box has changed in a way future devboxes should inherit, take a
38
+ If an independent project's Template box has changed in a way future devboxes should inherit, take a
39
39
  new snapshot before starting the devbox.
40
40
 
41
41
  ### Choose starting branches
@@ -90,7 +90,8 @@ not create a script file for it. The startup timeout defaults to 60 seconds and
90
90
  can be set from 1 to 120 seconds.
91
91
 
92
92
  Startup scripts can install dependencies, configure the environment, or start
93
- services after branch preparation. The standard generated fetch/checkout
93
+ services after branch preparation. Startup and teardown scripts receive the
94
+ project's AWS and Google Cloud defaults, the same as a new terminal. The standard generated fetch/checkout
94
95
  commands are handled by boxes.dev; any extra commands remain startup work.
95
96
  Remove commands that switch branches or reset Git history from custom scripts
96
97
  when choosing starting branches. If setup leaves a repository on another
@@ -110,7 +111,7 @@ applies the current settings to a different devbox. An abandoned draft's devbox
110
111
  expires, but external side effects from a script cannot be undone, so startup
111
112
  scripts should be safe to run speculatively.
112
113
 
113
- In a Team Template member project, that preparation runs the team startup
114
+ In a managed project, that preparation runs the team startup
114
115
  script and then the member's startup script, after the member's credentials
115
116
  and required member files and values are ready and before the first agent turn.
116
117
  A missing required member file or value doesn't block startup: the scripts and
@@ -190,14 +191,14 @@ conversation work.
190
191
 
191
192
  ## Starting Snapshots For New Devboxes
192
193
 
193
- For an ordinary project, manage snapshots from the Template box page before starting devbox
194
+ For an independent project, manage snapshots from the Template box page before starting devbox
194
195
  work. Take a new snapshot when setup, dependencies, database state, or running
195
196
  services changed and the new devbox should inherit that state.
196
197
 
197
- On mobile, creating an ordinary-project devbox may let you choose between the latest available
198
+ On mobile, creating an independent-project devbox may let you choose between the latest available
198
199
  Template box snapshot and a fresh snapshot taken before the devbox is created.
199
200
 
200
- A Team Template member project has no member-controlled snapshot choice. New
201
+ A managed project has no member-controlled snapshot choice. New
201
202
  devboxes use the current saved Team Template version, which team admins maintain
202
203
  separately.
203
204
 
@@ -224,7 +225,7 @@ leaving it stuck.
224
225
 
225
226
  A devbox can have more than one thread. Use the devbox row's New thread action
226
227
  when another agent conversation should operate on the same devbox filesystem and
227
- runtime state.
228
+ box state.
228
229
 
229
230
  This is useful for asking a second question about work already in that devbox,
230
231
  or for continuing with another agent without creating another machine.
@@ -288,10 +289,10 @@ While a devbox is selected:
288
289
  - the terminal connects to the devbox;
289
290
  - forwarded ports come from the devbox;
290
291
  - file and git views inspect the devbox;
291
- - runtime controls wake, sleep, or show status for the devbox;
292
+ - box controls wake, sleep, or show status for the devbox;
292
293
  - agent follow-ups continue in that devbox.
293
294
 
294
- If the user is unsure which machine they are using, check the selected runtime
295
+ If the user is unsure which machine they are using, check the selected box
295
296
  or the devbox label in the workbench.
296
297
 
297
298
  ## Getting Files Onto Or Off A Devbox
@@ -304,7 +305,7 @@ There are three common ways to move work:
304
305
  and manage PR checks, review threads, merge, or branch cleanup.
305
306
  - Use the file view: inspect files, view diffs, and download files or media
306
307
  when the user needs a local copy.
307
- - Use uploads or attachments: provide files to an agent or runtime when the UI
308
+ - Use uploads or attachments: provide files to an agent or box when the UI
308
309
  supports file upload or composer attachments.
309
310
 
310
311
  For finished code changes, git is usually the right path. File download is
@@ -322,8 +323,8 @@ Test work on the selected devbox:
322
323
  - inspect logs, files, screenshots, or other outputs from the devbox;
323
324
  - ask the agent for screenshots or other proof when visual behavior matters.
324
325
 
325
- Port forwarding follows the selected runtime, so selecting a different devbox or
326
- an ordinary project's Template box changes which running app the port menu opens.
326
+ Port forwarding follows the selected box, so selecting a different devbox or
327
+ an independent project's Template box changes which running app the port menu opens.
327
328
 
328
329
  ## Finishing Work On A Devbox
329
330
 
@@ -414,12 +415,12 @@ warns about uncommitted changes, changed files, and local-only commits when that
414
415
  information is available. It also names the pull requests whose automatic
415
416
  follow-ups the devbox's threads handle. Destroying the devbox stops those
416
417
  follow-ups, and the pull request shows them as paused until a restored or
417
- other thread turns them on again. The devbox's threads move to its archive as
418
- soon as the destroy starts, on every device, while the cold-storage archive
419
- finishes in the background; if archiving fails, the threads return to the
420
- active list untouched. Once the devbox is gone, its threads move to
421
- **Devboxes** → **Archived threads** on desktop and to **Archived threads** at
422
- the end of the project on mobile, grouped under the destroyed devbox's name.
418
+ other thread turns them on again. As soon as the destroy starts, the devbox's
419
+ threads move to **Devboxes** → **Archived threads** on desktop and to
420
+ **Archived threads** at the end of the project on mobile, on every device,
421
+ while the cold-storage archive finishes in the background. If archiving fails,
422
+ the threads return to the active list untouched. Once the devbox is gone, its
423
+ threads are grouped there under the destroyed devbox's name.
423
424
  Archived automation runs stay in their automation's **Archived** group on
424
425
  desktop, with their threads directly beneath the run's devbox. `dvb agents`
425
426
  shows the threads in its archived section throughout. Preserving the
@@ -436,9 +437,9 @@ types must finish or be stopped before the devbox can be destroyed.
436
437
  Destroying a devbox does not automatically save code to the Template box or to
437
438
  Git. Commit, push, merge, download, or otherwise save anything important first.
438
439
  The archived transcripts remain readable without a running machine. To
439
- continue one, choose **Restore thread**. An ordinary project can restore to a new
440
+ continue one, choose **Restore thread**. An independent project can restore to a new
440
441
  devbox from the latest verified project snapshot or to its current Template
441
- box. A Team Template member project restores only to a new devbox from the
442
+ box. A managed project restores only to a new devbox from the
442
443
  current saved Team Template version. The available destination returns the
443
444
  thread directly to the normal thread list. Restoring a thread restores its
444
445
  conversation, not the destroyed devbox's filesystem or working tree.
@@ -11,7 +11,7 @@ have a Template box: the persistent base machine for that project. Their setup
11
11
  also starts a setup thread there for questions about what setup did, what still
12
12
  needs attention, or how the base environment should be adjusted.
13
13
 
14
- A project created from a Team Template in **Member projects** mode has no
14
+ A project created from a Team Template in **managed projects** mode has no
15
15
  personal Template box or setup thread. Team admins maintain the shared Team
16
16
  Template, and every new devbox starts from its current saved files. In normal
17
17
  use, the project otherwise works like any other project: its threads,
@@ -35,7 +35,7 @@ confirming the project looks healthy:
35
35
 
36
36
  - Open the terminal pane if you want to inspect the environment or run commands.
37
37
  - Use the ports menu to open any running local app or copied forwarded URL.
38
- - Check the Template box page for runtime status and snapshot history.
38
+ - Check the Template box page for box status and snapshot history.
39
39
  - Take a new snapshot when the Template box is in a good state that future
40
40
  devboxes should start from.
41
41
 
@@ -43,7 +43,7 @@ If the project does not run yet, stay on the Template box and ask the setup
43
43
  thread to help finish setup. After the Template box is healthy, create devboxes
44
44
  for ordinary coding tasks.
45
45
 
46
- For a Team Template member project, project creation checks required GitHub
46
+ For a managed project, project creation checks required GitHub
47
47
  access and prepares a devbox before **Open project** becomes available. After
48
48
  opening it, start a new devbox + thread; any remaining optional setup problem
49
49
  appears as a warning with its own recovery action.
@@ -53,7 +53,7 @@ appears as a warning with its own recovery action.
53
53
  The recommended boxes.dev workflow is:
54
54
 
55
55
  1. For a project with a Template box, keep it as the clean baseline and take a
56
- snapshot when its state is worth reusing. Team Template member projects use
56
+ snapshot when its state is worth reusing. Managed projects use
57
57
  the shared saved files maintained by team admins instead.
58
58
  2. Create a new devbox + thread for each meaningful task.
59
59
  3. Let the agent edit code, run commands, and test inside that devbox.
@@ -80,11 +80,11 @@ automation details. Thread transcripts are where you send follow-ups, watch
80
80
  agent progress, interrupt work, retry failed turns, and inspect the final
81
81
  response.
82
82
 
83
- The terminal pane connects to the selected runtime. If you select a devbox, the
83
+ The terminal pane connects to the selected box. If you select a devbox, the
84
84
  terminal is for that devbox. If you select the Template box, the terminal is for
85
85
  the Template box.
86
86
 
87
- The titlebar shows the selected project/runtime, runtime status, the
87
+ The titlebar shows the selected project/box, box status, the
88
88
  Terminal/Files/Git/Review pane control, forwarded ports, and other workspace
89
89
  actions. Billing usage is beside Help in the account row at the bottom of the
90
90
  left pane.
@@ -98,8 +98,7 @@ staging, commits, branches, and history.
98
98
 
99
99
  For a project with a Template box, the setup thread is created for initial
100
100
  project setup. It can also be useful for follow-up setup questions because it
101
- has the setup context, but you do not need to keep using it forever. Team
102
- Template member projects do not have a personal setup thread.
101
+ has the setup context, but you do not need to keep using it forever. Managed projects do not have a personal setup thread.
103
102
 
104
103
  Template box threads can also be setup-oriented. They are often convenient for
105
104
  questions about the codebase or environment that do not require edits, and for
@@ -112,16 +111,16 @@ Use devbox threads for normal coding tasks.
112
111
  ## Agent Auth After Setup
113
112
 
114
113
  Setup asks you to connect at least one coding agent. You can connect or repair
115
- agent auth later from the desktop app. On macOS, open the boxes.dev app menu and
116
- choose **Configure agents...**. The mobile app has the same controls under
114
+ agent auth later from **Settings → Agents** in the desktop account menu.
115
+ The macOS **Configure agents...** command opens the same section. The mobile app has the same controls under
117
116
  **Settings → Agent accounts**.
118
117
 
119
118
  Codex can be connected with ChatGPT login or an API key. Claude Code can be
120
- connected with Claude login or an API key. Configure agents can keep multiple
119
+ connected with Claude login or an API key. Settings → Agents can keep multiple
121
120
  accounts or API keys for each agent; choose the active credential with its
122
121
  radio control. That choice is global across your devboxes, and Codex and Claude
123
122
  can use different active accounts. If a thread cannot start because an agent is
124
- not authenticated, open Configure agents, reconnect or choose another saved
123
+ not authenticated, open Settings → Agents, reconnect or choose another saved
125
124
  credential, and then start or retry the thread.
126
125
 
127
126
  ## First Useful Task
@@ -1,8 +1,9 @@
1
1
  # Glossary
2
2
 
3
3
  Use this doc for concise definitions of boxes.dev product terms. Prefer these
4
- terms in user-facing answers unless a command, UI label, or integration uses a
5
- different term.
4
+ terms in user-facing answers. Recognize the aliases below, then explain the
5
+ concept using its canonical name. Preserve exact command names and integration
6
+ terminology when giving instructions.
6
7
 
7
8
  ## Account
8
9
 
@@ -25,7 +26,7 @@ schedule, an API call, Slack, or Linear.
25
26
 
26
27
  ## Awake
27
28
 
28
- The runtime is running and can accept commands, ports, file access, terminal
29
+ The box is running and can accept commands, ports, file access, terminal
29
30
  sessions, and agent work.
30
31
 
31
32
  ## Box-Hour
@@ -34,8 +35,10 @@ One default 4 vCPU / 8 GiB devbox awake for one hour.
34
35
 
35
36
  ## Checkpoint
36
37
 
37
- An older or CLI-oriented term for a saved machine state. Prefer snapshot in
38
- ordinary product guidance unless a command or UI label says checkpoint.
38
+ Also called a snapshot. The active workstation CLI command
39
+ `dvb checkpoint <template-box>` takes a Template box snapshot. From the
40
+ Template box itself, use `dvb-onbox snapshot`. Prefer snapshot when describing
41
+ the saved state; keep checkpoint in the exact CLI invocation.
39
42
 
40
43
  ## Claude Code Thread
41
44
 
@@ -65,15 +68,31 @@ recommended mode for most feature work, bug fixes, refactors, and experiments.
65
68
 
66
69
  ## Forwarded Port
67
70
 
68
- A development service port detected inside the selected runtime and made
71
+ A development service port detected inside the selected box and made
69
72
  available to open or copy from the desktop app.
70
73
 
71
74
  ## Template box
72
75
 
73
- The persistent base machine for an ordinary project. Use it for shared setup,
74
- maintenance, snapshots, and setup-oriented work. Team Template member projects
76
+ The persistent base box for an independent project. Use it for shared setup,
77
+ maintenance, snapshots, and setup-oriented work. Managed projects
75
78
  do not have one.
76
79
 
80
+ ## Independent project
81
+
82
+ A project with its own Template box. New devboxes normally start from that
83
+ Template box's latest snapshot. Older documentation calls this an ordinary project.
84
+
85
+ ## Managed project
86
+
87
+ A project that uses a Team Template and has no Template box of its own. Each
88
+ new devbox starts from the template's current saved environment; existing
89
+ devboxes keep their files. Older documentation calls this a member project.
90
+
91
+ ## Older project names
92
+
93
+ Member project is an older name for a managed project.
94
+ Ordinary project is an older name for an independent project.
95
+
77
96
  ## Mobile App
78
97
 
79
98
  The companion app for monitoring threads, receiving notifications, replying to
@@ -82,19 +101,23 @@ phone.
82
101
 
83
102
  ## Project
84
103
 
85
- One codebase in boxes.dev. Most projects have one Template box. A Team Template
86
- member project instead uses the Team Template's current saved version for
87
- future devboxes.
104
+ One codebase in boxes.dev. An independent project has its own Template box.
105
+ A managed project uses a Team Template's current saved environment for future
106
+ devboxes. Team members can own either type.
88
107
 
89
108
  ## Runtime
90
109
 
91
- The actual machine a thread or pane is connected to: either the Template box or
92
- a devbox.
110
+ Older wording for a box: either a Template box or a devbox.
111
+
112
+ ## Older selection names
113
+
114
+ Selected runtime and selected machine are older names for the selected box.
93
115
 
94
- ## Selected Runtime
116
+ ## Selected box
95
117
 
96
- The Template box or devbox currently selected in the app. Terminal, ports,
97
- files, git, runtime status, and wake/sleep controls follow the selected runtime.
118
+ The devbox or Template box currently selected in the desktop app. Files, Git,
119
+ Terminal, Browser, and wake/sleep controls use this box. Port forwarding follows
120
+ selection by default; it can also stay on one box when pinned.
98
121
 
99
122
  ## Setup Thread
100
123
 
@@ -103,17 +126,18 @@ explains setup decisions, and answers setup-oriented questions.
103
126
 
104
127
  ## Sleeping
105
128
 
106
- The runtime is paused like a sleeping laptop: it keeps its machine state in
107
- memory but is not running commands or consuming active runtime capacity. It can
129
+ The box is paused like a sleeping laptop: it keeps its state in
130
+ memory but is not running commands or consuming active box-hours. It can
108
131
  usually be woken later.
109
132
 
110
133
  ## Snapshot
111
134
 
112
- A saved machine state used to create future devboxes. Ordinary projects use
135
+ A saved state of a box used to create devboxes. Independent projects use
113
136
  Template box snapshots; take a new snapshot after the Template box is in a
114
137
  state future devboxes should inherit. When **Continue in new chat** creates a
115
138
  new devbox, it takes a fresh snapshot of the selected thread's exact Template
116
- box or devbox.
139
+ box or devbox. The workstation CLI command `dvb checkpoint` takes a Template
140
+ box snapshot; from the Template box itself, use `dvb-onbox snapshot`.
117
141
 
118
142
  ## Team
119
143
 
@@ -122,7 +146,7 @@ projects for its users.
122
146
 
123
147
  ## Thread
124
148
 
125
- A conversation with a coding agent connected to a runtime. Threads may be
149
+ A conversation with a coding agent connected to a box. Threads may be
126
150
  user-started, setup-created, automation-spawned, or integration-triggered.
127
151
 
128
152
  ## Thread Automation
@@ -131,7 +155,7 @@ Same as automation. Use "Thread Automation" when matching the desktop UI.
131
155
 
132
156
  ## Waking
133
157
 
134
- The runtime is transitioning from sleeping back to running. Product surfaces
158
+ The box is transitioning from sleeping back to running. Product surfaces
135
159
  load once wake finishes.
136
160
 
137
161
  ## Work Product URL
@@ -40,17 +40,22 @@ Google Cloud project needs to grant the account access. Choose **Refresh**
40
40
  afterward; reconnecting is not required.
41
41
 
42
42
  Google Cloud setup does not change the repository and does not require a
43
- Template box snapshot. New terminals pick up Google Cloud automatically.
44
- Existing Codex and Claude threads keep current work running, then pick up the
45
- change before their next turn after that work finishes. Already-running shells
46
- keep the environment they started with, so open a new terminal after
47
- connecting, changing, or removing Google Cloud.
43
+ Template box snapshot. New terminals pick up Google Cloud automatically, and
44
+ open Bash terminals pick up connecting, changing, or removing Google Cloud at
45
+ their next prompt. A terminal that was already waiting for a command runs its
46
+ next command with the old settings, so press Enter once first. Values the user
47
+ set in the shell stay unchanged. Existing Codex and Claude threads keep current
48
+ work running, then pick up the change before their next turn after that work
49
+ finishes. Programs that are already running, including ones started from a
50
+ terminal, keep the environment they started with. Devbox startup and teardown
51
+ scripts and Template box maintenance scripts receive the same defaults as a
52
+ new terminal.
48
53
 
49
54
  ## How Tools Receive Credentials
50
55
 
51
56
  For a connected project, boxes.dev serves Google Cloud credentials on the
52
- project's real boxes: the Template box and devboxes in an ordinary project, and
53
- the assigned devboxes in a Team Template member project. It does this the same
57
+ project's real boxes: the Template box and devboxes in an independent project, and
58
+ the assigned devboxes in a managed project. It does this the same
54
59
  way a Google Cloud virtual machine does, so `gcloud`, the Google Cloud client
55
60
  libraries for Python, Node.js, Go and other languages, and tools built on
56
61
  them find the credentials without configuration.
@@ -61,7 +66,7 @@ tool receives the token in memory; boxes.dev does not write a credentials file
61
66
  to the box. The selected Google Cloud project becomes the default project, and
62
67
  Google counts API quota against it.
63
68
 
64
- A quick check in a new terminal is:
69
+ A quick check in a terminal is:
65
70
 
66
71
  ```bash
67
72
  gcloud auth list
@@ -10,9 +10,9 @@ specific feature doc only when needed.
10
10
 
11
11
  ## Product Model
12
12
 
13
- An ordinary boxes.dev project has a persistent Template box and creates
13
+ An independent boxes.dev project has a persistent Template box and creates
14
14
  devboxes from its snapshots for isolated agent work. A Team Template can also
15
- enable **Member projects**, which have no personal Template box and create
15
+ enable **managed projects**, which have no personal Template box and create
16
16
  future devboxes from the Team Template's current saved version instead. A
17
17
  devbox is a full cloud Linux machine with its own filesystem, running services,
18
18
  and ports, and it can host agent threads. The desktop app is the primary
@@ -20,16 +20,18 @@ workbench; mobile and the CLI are companion control surfaces.
20
20
 
21
21
  Use this terminology consistently:
22
22
 
23
- - Template box: the persistent base machine for one ordinary project. A Member
23
+ - Independent project: a project with its own Template box.
24
+ - Managed project: a project that uses a Team Template without its own Template box.
25
+ - Template box: the persistent base box for one independent project. A managed
24
26
  project does not have one.
25
27
  - Devbox: an isolated machine created from a project snapshot or a Team
26
28
  Template's saved version for a task, thread, automation run, or an
27
29
  integration-triggered run.
28
- - Thread: a Codex or Claude conversation connected to a runtime. In the
30
+ - Thread: a Codex or Claude conversation connected to a box. In the
29
31
  desktop app, the same thread can use GUI or CLI view.
30
32
  - Snapshot: a saved filesystem state used to create future devboxes.
31
- - Selected runtime: the Template box or devbox currently selected in the app;
32
- terminals, ports, files, and runtime controls follow that selection.
33
+ - Selected box: the Template box or devbox currently selected in the app;
34
+ terminals, ports, files, and box controls follow that selection.
33
35
 
34
36
  ## Docs Map
35
37
 
@@ -39,11 +41,11 @@ Use this terminology consistently:
39
41
  - `project-setup.md`: how project setup works, what the setup thread does, what
40
42
  gets uploaded, how setup can be retried, and when to use it again.
41
43
  - `team-template.md`: named team-wide starting environments, independent admin
42
- editing and saved versions, member project creation, Git personalization, and
44
+ editing and saved versions, managed project creation, Git personalization, and
43
45
  copied-data boundaries.
44
46
  - `template-box-environment.md`: the Template box machine environment, baseline
45
47
  development tools, setup constraints, local-run verification, and snapshots.
46
- - `environment-setup-validation.md`: shared validation guidance for ordinary
48
+ - `environment-setup-validation.md`: shared validation guidance for independent
47
49
  project and Team Template environment setup, including fresh agent commands,
48
50
  persistent configuration, service startup, and readiness reporting.
49
51
  - `managed-environment-files.md`: centrally managed dotenv files, initial
@@ -55,7 +57,7 @@ Use this terminology consistently:
55
57
  - `shared-storage.md`: the shared `/project` folder, recommended uses and
56
58
  limitations, Claude project memory, persistence, access, and turning it off.
57
59
  - `core-concepts.md`: short definitions for projects, Template boxes, devboxes,
58
- Team Templates, threads, snapshots, wake/sleep, and selected runtime
60
+ Team Templates, threads, snapshots, wake/sleep, and selected box
59
61
  behavior.
60
62
  - `threads-and-agents.md`: creating and continuing Codex or Claude threads,
61
63
  choosing GUI or the CLI on desktop, safely draining remaining legacy Claude
@@ -65,7 +67,7 @@ Use this terminology consistently:
65
67
  - `fork-workflows.md`: when to use a devbox, how devbox work starts, file
66
68
  movement on devboxes, testing, merging or pushing changes, and cleanup.
67
69
  - `desktop-workbench.md`: the desktop app layout, thread list, transcript pane,
68
- Template box page, terminal pane, files, ports, runtime controls, and settings
70
+ Template box page, terminal pane, files, ports, box controls, and settings
69
71
  entry points.
70
72
  - `ui-references.md`: supported inline references for showing users where
71
73
  desktop controls, settings, and other threads live while explaining them.
@@ -73,7 +75,7 @@ Use this terminology consistently:
73
75
  upload/download transfers, review comments, git status, staging, commits,
74
76
  amend, history, branches, and multi-repo behavior.
75
77
  - `ports-terminal-and-runtime.md`: automatic port forwarding, opening forwarded
76
- ports, terminal sessions, runtime status, wake/sleep, reset, and resource
78
+ ports, terminal sessions, box status, wake/sleep, reset, and resource
77
79
  indicators.
78
80
  - `mobile.md`: mobile monitoring and control, push notifications, responding to
79
81
  threads, file viewing, terminal access, the shared Browser, and
@@ -109,11 +111,13 @@ Use this terminology consistently:
109
111
  - `vercel.md`: connecting Vercel once for the Vercel CLI on every box, the
110
112
  managed login file, `vercel login` and `vercel logout` on a box, SAML team
111
113
  sign-in, reconnecting, and disconnecting.
114
+ - `convex.md`: connecting a Convex team to this project's boxes, expiring native
115
+ CLI credentials, existing personal logins, renewal, and removing access.
112
116
  - `tailscale.md`: team-managed tailnet setup, Tailscale-policy-based project
113
117
  eligibility, tagged ephemeral project machines, stock CLI behavior, ordinary
114
118
  snapshot identity rotation, native cleanup, incident removal, and version-one
115
119
  limits.
116
- - `billing-and-limits.md`: plans, box-hours, awake runtimes, awake devbox
120
+ - `billing-and-limits.md`: plans, box-hours, awake boxes, awake devbox
117
121
  limits, project limits, usage, overages, checkout, and billing portal
118
122
  behavior.
119
123
  - `security-and-data.md`: setup uploads, secrets, auth storage at a product
@@ -126,10 +130,10 @@ Use this terminology consistently:
126
130
  ## Context Guidance
127
131
 
128
132
  For a setup thread, use its task and current box role to choose the guidance.
129
- Ordinary project setup uses the project's Template box; a Team Template editor
130
- thread runs directly on its editing machine, while an associated ordinary
131
- Template box can operate on that machine remotely. Prefer setup and new-user
132
- guidance for ordinary project onboarding, and Team Template guidance for shared
133
+ Independent project setup uses the project's Template box; a Team Template editor
134
+ thread runs directly on its editing box, while an independent project's
135
+ Template box can operate on that box remotely. Prefer setup and new-user
136
+ guidance for independent project onboarding, and Team Template guidance for shared
133
137
  environment authoring.
134
138
 
135
139
  If the user is on a devbox thread, assume they are doing task work. Prefer
@@ -172,8 +172,8 @@ thread. Runs that already failed or stopped require a new Linear Agent Session.
172
172
  If assignment does not start, confirm that the connected Linear workspace is the
173
173
  one containing the issue, your Linear identity is linked, your default Linear
174
174
  automation is active, and the project's saved environment is usable: the
175
- latest Template box snapshot for an ordinary project, or the current saved
176
- Team Template version for a member project. If several assignments start at
175
+ latest Template box snapshot for an independent project, or the current saved
176
+ Team Template version for a managed project. If several assignments start at
177
177
  once and some do not launch, check awake devbox capacity and billing.
178
178
 
179
179
  If work products do not attach, check the URL and the selected session. In an
@@ -53,7 +53,7 @@ Choose **New file…** to name a file that does not exist yet. The form is a
53
53
  folder and a file name: the folder offers the folders already on the source and
54
54
  also accepts one you type, and the line beneath echoes the full location the
55
55
  file will have. Naming the folder separately matters because the two surfaces
56
- resolve paths differently - an ordinary project against its project folder, a
56
+ resolve paths differently - an independent project against its project folder, a
57
57
  Team Template against the machine's home directory with each of its repositories
58
58
  as a child folder. A file name containing a slash, or a name the dotenv naming
59
59
  rule does not accept, is reported straight away, before boxes.dev checks