@boxes-dev/dvb-runtime 1.0.1097 → 1.0.1099

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 (35) hide show
  1. package/dist/agent-init-guides/flow.md +31 -4
  2. package/dist/agent-init-guides/git-ssh.md +2 -2
  3. package/dist/agent-init-guides/manifest.md +10 -2
  4. package/dist/agent-init-guides/running.md +8 -3
  5. package/dist/agent-init-guides/untracked.md +29 -4
  6. package/dist/bin/dvb.mjs +108 -27
  7. package/dist/bin/dvbd.mjs +10 -9
  8. package/dist/product-docs/references/agent-tools.md +6 -7
  9. package/dist/product-docs/references/automations.md +4 -4
  10. package/dist/product-docs/references/aws.md +17 -11
  11. package/dist/product-docs/references/billing-and-limits.md +23 -11
  12. package/dist/product-docs/references/cli.md +14 -15
  13. package/dist/product-docs/references/core-concepts.md +35 -30
  14. package/dist/product-docs/references/desktop-workbench.md +26 -25
  15. package/dist/product-docs/references/files-git-and-review.md +20 -17
  16. package/dist/product-docs/references/fork-workflows.md +44 -31
  17. package/dist/product-docs/references/getting-started.md +7 -8
  18. package/dist/product-docs/references/glossary.md +46 -22
  19. package/dist/product-docs/references/google-cloud.md +13 -8
  20. package/dist/product-docs/references/index.md +18 -16
  21. package/dist/product-docs/references/linear.md +2 -2
  22. package/dist/product-docs/references/managed-environment-files.md +1 -1
  23. package/dist/product-docs/references/member-managed-files.md +4 -4
  24. package/dist/product-docs/references/mobile.md +23 -18
  25. package/dist/product-docs/references/onbox-agent-tools.md +25 -26
  26. package/dist/product-docs/references/ports-terminal-and-runtime.md +27 -28
  27. package/dist/product-docs/references/project-setup.md +36 -16
  28. package/dist/product-docs/references/security-and-data.md +10 -10
  29. package/dist/product-docs/references/slack.md +3 -3
  30. package/dist/product-docs/references/tailscale.md +2 -2
  31. package/dist/product-docs/references/team-template.md +22 -22
  32. package/dist/product-docs/references/template-box-environment.md +7 -3
  33. package/dist/product-docs/references/threads-and-agents.md +79 -31
  34. package/dist/product-docs/references/troubleshooting.md +24 -25
  35. package/package.json +2 -2
@@ -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
@@ -139,8 +139,12 @@ root.
139
139
  Uploads can run in parallel. The file tree shows a slim row for each active
140
140
  upload with progress; successful rows clear after completion, and failed rows
141
141
  can be retried or dismissed. After successful uploads, the target directory
142
- reloads. Desktop uploads support files up to 1 GiB each, with up to 2 GiB of
143
- active uploads per user at a time.
142
+ reloads. Desktop uploads support files up to 5 GiB each, with up to 10 GiB of
143
+ active uploads per user at a time. Before uploading, boxes.dev checks the
144
+ box's free disk space and warns if the files will not fit. It checks again
145
+ before copying each file onto the box. Free up space or choose fewer files
146
+ if an upload is blocked. A box awaiting an update may still have the previous
147
+ 1 GiB file limit; retry after its normal automatic update.
144
148
 
145
149
  ## Diffs From Files
146
150
 
@@ -194,7 +198,7 @@ selector in Git/Review. If boxes.dev detects unindexed direct-child repos, use
194
198
  **Review new repositories** to choose which ones join the project index. Older
195
199
  machines show the previous all-repository **Rescan** action until they update.
196
200
 
197
- 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.
198
202
 
199
203
  ## History View
200
204
 
@@ -238,7 +242,7 @@ boxes.dev refreshes expiring credentials automatically before they expire.
238
242
  If the refresh credential has also expired, reconnect GitHub. Temporary GitHub
239
243
  outages are retried without treating your authorization as revoked.
240
244
 
241
- 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
242
246
  that the connected user's credential can read. boxes.dev verifies the machine
243
247
  and current repository access before returning the credential; GitHub enforces
244
248
  write permission and branch rules when you push.
@@ -261,8 +265,8 @@ perform ordinary Git operations while approval is pending.
261
265
 
262
266
  ## Adding And Reviewing Project Repositories
263
267
 
264
- The Template-box repository controls in this section apply to ordinary
265
- 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
266
270
  Team Template's current saved version. Members can use Git/Review on an assigned
267
271
  devbox, but cannot change the shared source or add a repository for future
268
272
  devboxes from their project.
@@ -296,7 +300,7 @@ without rerunning the repository work.
296
300
  repository into a multi-repository layout. It also does not appear for an SSH
297
301
  or non-GitHub project. To clone manually, including in an SSH or non-GitHub
298
302
  project, use a direct-child folder in a supported, non-overlapping
299
- 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
300
304
  project whose root is itself a Git repository creates an overlapping layout
301
305
  that **Review new repositories** will not add.
302
306
 
@@ -325,7 +329,7 @@ but cannot add another repository at the project root.
325
329
 
326
330
  ### Private Git Dependencies
327
331
 
328
- Ordinary projects with automatic GitHub access can fetch private dependencies
332
+ Independent projects with automatic GitHub access can fetch private dependencies
329
333
  using the connected account's existing access, without adding another checkout.
330
334
  For an early access check with `dvb agent-init` on your own computer, list private
331
335
  GitHub dependencies in the setup manifest. For example, use
@@ -341,8 +345,7 @@ layout. If an existing setup is blocked, grant any missing GitHub access,
341
345
  continue its setup thread, and retry the dependency fetch. The manifest list
342
346
  only chooses which dependencies to check before setup; leaving it out or empty
343
347
  does not change repository access. Credentials retain their GitHub permissions.
344
- This flow does not change Team Template
345
- 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.
346
349
 
347
350
  ## Git Author Identity
348
351
 
@@ -727,7 +730,7 @@ closes or merges. The manual **Fix checks**, **Address feedback**, and
727
730
  After the selected repository, remote, or branch changes, Git/Review may
728
731
  briefly show that GitHub repository state is updating. Pull-request actions
729
732
  become available only after boxes.dev confirms the new selection; if the state
730
- remains unavailable, wake the runtime and refresh Git/Review.
733
+ remains unavailable, wake the box and refresh Git/Review.
731
734
 
732
735
  ## Commit View
733
736
 
@@ -749,7 +752,7 @@ Commit is disabled until there is at least one staged file, a non-empty commit
749
752
  message, no unresolved conflicts, and no other Git action in progress.
750
753
 
751
754
  The commit message may be prefilled from merge, squash, template, or amend
752
- 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
753
756
  you work.
754
757
 
755
758
  ## Conflicts And Read-Only Diffs
@@ -770,6 +773,6 @@ layout, or direct-child folders for a multi-repository layout. Nested
770
773
  repositories, submodules, linked-worktree duplicates, and overlapping root plus
771
774
  child layouts are not added by the review flow.
772
775
 
773
- 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
774
777
  outside the selected Git repo. Git/Review is Git-aware and shows files from the
775
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.
@@ -235,16 +236,22 @@ titled with its first thread's title. To label the devbox separately, choose
235
236
  `r` on the group row in `dvb agents`. Renaming the devbox does not change any
236
237
  thread title, and renaming a thread does not change the devbox name. A named
237
238
  devbox keeps its group row even when all but one of its threads are archived.
238
- Saving an empty name returns the group to the first thread's title, and a
239
- devbox with one remaining thread goes back to a single thread row. Teammates
239
+ Saving an empty name returns the group to the first thread's title. A devbox
240
+ with one remaining thread then goes back to a single thread row, except in the
241
+ desktop and mobile apps when the devbox has archived threads. Teammates
240
242
  who can see the devbox's threads see the same name, but only the owner can
241
243
  rename it.
242
244
 
243
- Secondary threads on a devbox can be archived without destroying the devbox. The
244
- devbox row and original devbox thread still own devbox lifecycle actions;
245
- archiving a secondary thread only hides that child thread from the active devbox
246
- group until it is unarchived. If the archived child was selected, desktop opens
247
- the most recent remaining thread on that same devbox.
245
+ Threads on a devbox can be archived without destroying the devbox. The devbox
246
+ row and original devbox thread still own devbox lifecycle actions. In the
247
+ desktop and mobile apps, an archived thread moves to an **Archived threads**
248
+ list at the end of its devbox's group, which appears only when that devbox has
249
+ archived threads. A devbox with one active thread and some archived ones still
250
+ shows as a group. If the devbox's original thread is archived, the devbox
251
+ stays in the list with its group, and **New thread** on it is unavailable
252
+ until that thread is unarchived. If the archived child was selected, desktop
253
+ opens the most recent remaining thread on that same devbox. `dvb agents` lists
254
+ archived threads in its own archived section rather than inside each devbox.
248
255
 
249
256
  ## Branching A Conversation Onto A New Devbox
250
257
 
@@ -282,10 +289,10 @@ While a devbox is selected:
282
289
  - the terminal connects to the devbox;
283
290
  - forwarded ports come from the devbox;
284
291
  - file and git views inspect the devbox;
285
- - runtime controls wake, sleep, or show status for the devbox;
292
+ - box controls wake, sleep, or show status for the devbox;
286
293
  - agent follow-ups continue in that devbox.
287
294
 
288
- 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
289
296
  or the devbox label in the workbench.
290
297
 
291
298
  ## Getting Files Onto Or Off A Devbox
@@ -298,7 +305,7 @@ There are three common ways to move work:
298
305
  and manage PR checks, review threads, merge, or branch cleanup.
299
306
  - Use the file view: inspect files, view diffs, and download files or media
300
307
  when the user needs a local copy.
301
- - 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
302
309
  supports file upload or composer attachments.
303
310
 
304
311
  For finished code changes, git is usually the right path. File download is
@@ -316,8 +323,8 @@ Test work on the selected devbox:
316
323
  - inspect logs, files, screenshots, or other outputs from the devbox;
317
324
  - ask the agent for screenshots or other proof when visual behavior matters.
318
325
 
319
- Port forwarding follows the selected runtime, so selecting a different devbox or
320
- 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.
321
328
 
322
329
  ## Finishing Work On A Devbox
323
330
 
@@ -408,11 +415,17 @@ warns about uncommitted changes, changed files, and local-only commits when that
408
415
  information is available. It also names the pull requests whose automatic
409
416
  follow-ups the devbox's threads handle. Destroying the devbox stops those
410
417
  follow-ups, and the pull request shows them as paused until a restored or
411
- other thread turns them on again. The devbox's threads move into the archived section
412
- of the thread list as soon as the destroy starts, on every device, while the
413
- cold-storage archive finishes in the background; if archiving fails, the
414
- threads return to the active list untouched. Preserving the transcripts does
415
- not wake the Template box or copy native transcript files onto it. After the
418
+ other thread turns them on again. The devbox's threads move to its archive as
419
+ soon as the destroy starts, on every device, while the cold-storage archive
420
+ finishes in the background; if archiving fails, the threads return to the
421
+ active list untouched. Once the devbox is gone, its threads move to
422
+ **Devboxes** → **Archived threads** on desktop and to **Archived threads** at
423
+ the end of the project on mobile, grouped under the destroyed devbox's name.
424
+ Archived automation runs stay in their automation's **Archived** group on
425
+ desktop, with their threads directly beneath the run's devbox. `dvb agents`
426
+ shows the threads in its archived section throughout. Preserving the
427
+ transcripts does not wake the Template box or copy native transcript files
428
+ onto it. After the
416
429
  selected devbox is destroyed, desktop opens the no-thread-selected state. It
417
430
  does not automatically create another draft or devbox; use
418
431
  **New thread** when more isolated work is needed.
@@ -424,9 +437,9 @@ types must finish or be stopped before the devbox can be destroyed.
424
437
  Destroying a devbox does not automatically save code to the Template box or to
425
438
  Git. Commit, push, merge, download, or otherwise save anything important first.
426
439
  The archived transcripts remain readable without a running machine. To
427
- 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
428
441
  devbox from the latest verified project snapshot or to its current Template
429
- 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
430
443
  current saved Team Template version. The available destination returns the
431
444
  thread directly to the normal thread list. Restoring a thread restores its
432
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
@@ -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
@@ -113,7 +115,7 @@ Use this terminology consistently:
113
115
  eligibility, tagged ephemeral project machines, stock CLI behavior, ordinary
114
116
  snapshot identity rotation, native cleanup, incident removal, and version-one
115
117
  limits.
116
- - `billing-and-limits.md`: plans, box-hours, awake runtimes, awake devbox
118
+ - `billing-and-limits.md`: plans, box-hours, awake boxes, awake devbox
117
119
  limits, project limits, usage, overages, checkout, and billing portal
118
120
  behavior.
119
121
  - `security-and-data.md`: setup uploads, secrets, auth storage at a product
@@ -126,10 +128,10 @@ Use this terminology consistently:
126
128
  ## Context Guidance
127
129
 
128
130
  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
131
+ Independent project setup uses the project's Template box; a Team Template editor
132
+ thread runs directly on its editing box, while an independent project's
133
+ Template box can operate on that box remotely. Prefer setup and new-user
134
+ guidance for independent project onboarding, and Team Template guidance for shared
133
135
  environment authoring.
134
136
 
135
137
  If the user is on a devbox thread, assume they are doing task work. Prefer