@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.
- package/dist/agent-init-guides/flow.md +31 -4
- package/dist/agent-init-guides/git-ssh.md +2 -2
- package/dist/agent-init-guides/manifest.md +10 -2
- package/dist/agent-init-guides/running.md +8 -3
- package/dist/agent-init-guides/untracked.md +29 -4
- package/dist/bin/dvb.mjs +108 -27
- package/dist/bin/dvbd.mjs +10 -9
- package/dist/product-docs/references/agent-tools.md +6 -7
- package/dist/product-docs/references/automations.md +4 -4
- package/dist/product-docs/references/aws.md +17 -11
- package/dist/product-docs/references/billing-and-limits.md +23 -11
- package/dist/product-docs/references/cli.md +14 -15
- package/dist/product-docs/references/core-concepts.md +35 -30
- package/dist/product-docs/references/desktop-workbench.md +26 -25
- package/dist/product-docs/references/files-git-and-review.md +20 -17
- package/dist/product-docs/references/fork-workflows.md +44 -31
- package/dist/product-docs/references/getting-started.md +7 -8
- package/dist/product-docs/references/glossary.md +46 -22
- package/dist/product-docs/references/google-cloud.md +13 -8
- package/dist/product-docs/references/index.md +18 -16
- package/dist/product-docs/references/linear.md +2 -2
- package/dist/product-docs/references/managed-environment-files.md +1 -1
- package/dist/product-docs/references/member-managed-files.md +4 -4
- package/dist/product-docs/references/mobile.md +23 -18
- package/dist/product-docs/references/onbox-agent-tools.md +25 -26
- package/dist/product-docs/references/ports-terminal-and-runtime.md +27 -28
- package/dist/product-docs/references/project-setup.md +36 -16
- package/dist/product-docs/references/security-and-data.md +10 -10
- package/dist/product-docs/references/slack.md +3 -3
- package/dist/product-docs/references/tailscale.md +2 -2
- package/dist/product-docs/references/team-template.md +22 -22
- package/dist/product-docs/references/template-box-environment.md +7 -3
- package/dist/product-docs/references/threads-and-agents.md +79 -31
- package/dist/product-docs/references/troubleshooting.md +24 -25
- 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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
265
|
-
projects. A
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
23
|
-
the shared baseline that future devboxes inherit.
|
|
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
|
|
31
|
-
latest verified Template box snapshot. In a
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
239
|
-
|
|
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
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
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
|
-
-
|
|
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
|
|
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
|
|
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
|
|
320
|
-
an
|
|
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
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
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
|
|
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
|
|
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 **
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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/
|
|
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.
|
|
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
|
|
5
|
-
|
|
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
|
|
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
|
-
|
|
38
|
-
|
|
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
|
|
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
|
|
74
|
-
maintenance, snapshots, and setup-oriented work.
|
|
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.
|
|
86
|
-
|
|
87
|
-
|
|
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
|
-
|
|
92
|
-
|
|
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
|
|
116
|
+
## Selected box
|
|
95
117
|
|
|
96
|
-
The Template box
|
|
97
|
-
|
|
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
|
|
107
|
-
memory but is not running commands or consuming active
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
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
|
|
53
|
-
the assigned devboxes in a
|
|
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
|
|
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
|
|
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 **
|
|
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
|
-
-
|
|
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
|
|
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
|
|
32
|
-
terminals, ports, files, and
|
|
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,
|
|
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
|
|
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
|
|
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,
|
|
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,
|
|
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
|
|
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
|
-
|
|
130
|
-
thread runs directly on its editing
|
|
131
|
-
Template box can operate on that
|
|
132
|
-
guidance for
|
|
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
|