@boxes-dev/dvb-runtime 1.0.1098 → 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/git-ssh.md +2 -2
- package/dist/bin/dvb.mjs +14 -14
- package/dist/bin/dvbd.mjs +4 -4
- 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 +24 -24
- package/dist/product-docs/references/files-git-and-review.md +14 -15
- package/dist/product-docs/references/fork-workflows.md +20 -19
- 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 +18 -16
- 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 +9 -9
- 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 +41 -22
- package/dist/product-docs/references/troubleshooting.md +24 -25
- package/package.json +2 -2
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
The desktop workbench is the main boxes.dev workspace. It is where you switch
|
|
4
4
|
projects, read and start agent threads, open files and Git, use the terminal,
|
|
5
5
|
use the shared Browser, open forwarded ports, and wake or sleep the selected
|
|
6
|
-
|
|
6
|
+
box.
|
|
7
7
|
|
|
8
8
|
## The Main Areas
|
|
9
9
|
|
|
@@ -21,7 +21,7 @@ The workbench has a few persistent areas:
|
|
|
21
21
|
thread is selected and hidden when the left pane
|
|
22
22
|
is too narrow to fit it. A thread inside a collapsed automation stays hidden
|
|
23
23
|
until you expand that automation. The
|
|
24
|
-
content pane's title bar starts with
|
|
24
|
+
content pane's title bar starts with box status, metrics, and ports when
|
|
25
25
|
a Template box or devbox is selected, and ends with the
|
|
26
26
|
Terminal/Files/Git/Review/Browser pane control as icon-only buttons that show
|
|
27
27
|
their names on hover; update notices appear in the middle when available.
|
|
@@ -59,8 +59,8 @@ The titlebar pane control switches the aux pane between Terminal, Files,
|
|
|
59
59
|
Git/Review, and Browser. The app menu can show or hide the Agent pane. At least
|
|
60
60
|
one main area stays visible. A new devbox starts with no aux pane open. The
|
|
61
61
|
Template box and each devbox then remember their last aux-pane choice
|
|
62
|
-
independently, so returning to a
|
|
63
|
-
can be resized. Showing Terminal reattaches the
|
|
62
|
+
independently, so returning to a box restores its previous pane. Pane widths
|
|
63
|
+
can be resized. Showing Terminal reattaches the box's open terminal
|
|
64
64
|
sessions, or starts one if it has none, and closing the last terminal tab
|
|
65
65
|
closes the pane.
|
|
66
66
|
|
|
@@ -223,7 +223,7 @@ row to return it to the default.
|
|
|
223
223
|
Use the project selector in the titlebar to switch between projects on the same
|
|
224
224
|
desktop app account. Threads and devboxes are shown for the selected project.
|
|
225
225
|
Most projects have one Template box. A project created through a Team
|
|
226
|
-
Template's **
|
|
226
|
+
Template's **managed projects** mode has no personal Template box and omits that
|
|
227
227
|
row without changing its normal thread and devbox workflow.
|
|
228
228
|
|
|
229
229
|
Use **New project...** in the project selector to add another project. On
|
|
@@ -254,8 +254,8 @@ through **New project...** instead of this admin-only management menu.
|
|
|
254
254
|
Project settings, integrations, automations, and a teammate's shared thread do
|
|
255
255
|
not select one of your Template boxes or devboxes. On those pages, machine
|
|
256
256
|
status and workspace tools are hidden and the workbench does not wake the
|
|
257
|
-
machine you last used. Return to one of your own
|
|
258
|
-
available, the Template box when you want
|
|
257
|
+
machine you last used. Return to one of your own threads connected to a box or, when
|
|
258
|
+
available, the Template box when you want box controls and Files,
|
|
259
259
|
Git/Review, Terminal, Browser, or Ports.
|
|
260
260
|
|
|
261
261
|
The app menu also includes **Project settings**, **Desktop app settings...**,
|
|
@@ -264,24 +264,24 @@ Configure agents can save multiple Codex and Claude accounts or API keys and
|
|
|
264
264
|
choose one active credential for each agent across all devboxes. The File menu
|
|
265
265
|
also includes **Delete This Project**.
|
|
266
266
|
|
|
267
|
-
##
|
|
267
|
+
## Box status
|
|
268
268
|
|
|
269
|
-
The
|
|
269
|
+
The box status control describes the selected box, which may be the
|
|
270
270
|
Template box or a devbox depending on the selected thread. It can show states
|
|
271
271
|
such as running, sleeping, waking, snapshotting, migration or repair needed, and
|
|
272
272
|
related errors.
|
|
273
273
|
|
|
274
|
-
Use the status control to wake or sleep the selected
|
|
274
|
+
Use the status control to wake or sleep the selected box when those actions
|
|
275
275
|
are available. Its auto-wake setting controls whether a sleeping Template box or
|
|
276
276
|
devbox wakes when you return to it; when auto-wake is off, use an explicit Wake
|
|
277
277
|
action instead.
|
|
278
278
|
|
|
279
279
|
Three small CPU, memory, and disk meters show live utilization for the selected
|
|
280
|
-
|
|
280
|
+
box. CPU and memory fill colors highlight elevated load. The disk meter
|
|
281
281
|
turns yellow below 2 GiB free and red below 1 GiB free. Hover the meters for
|
|
282
282
|
exact resource details, or click them to open an Activity Monitor-style view of
|
|
283
|
-
processes on the
|
|
284
|
-
|
|
283
|
+
processes on the box. Empty tracks remain visible while the selected
|
|
284
|
+
box has no live metrics.
|
|
285
285
|
|
|
286
286
|
## Project Settings
|
|
287
287
|
|
|
@@ -298,7 +298,7 @@ To change the automatic idle-sleep timeout, open **Account
|
|
|
298
298
|
→ Sleep timeout** and choose 5, 15, 30, or 60 minutes, or **Team default**.
|
|
299
299
|
Team admins can set the default in **Team settings → Sleep timeout**; without
|
|
300
300
|
a custom setting it is five minutes. Your choice overrides the team default
|
|
301
|
-
for your Template boxes and devboxes, including
|
|
301
|
+
for your Template boxes and devboxes, including managed projects.
|
|
302
302
|
Changes apply to existing and new boxes. A running box may keep its current
|
|
303
303
|
sleep deadline until its next activity; saving will not wake a sleeping box.
|
|
304
304
|
Longer timeouts use more box-hours; active agents can still keep boxes awake.
|
|
@@ -314,7 +314,7 @@ keyboard shortcuts, account, billing, team, update, and log-out actions.
|
|
|
314
314
|
For a project that has one, the Template box page is for the project's exact
|
|
315
315
|
Template machine. Use it to manage snapshots, repositories, maintenance, or
|
|
316
316
|
the machine itself; open its terminal, inspect files or Git, or check whether
|
|
317
|
-
it is awake.
|
|
317
|
+
it is awake. Managed projects omit the page and its thread,
|
|
318
318
|
snapshot, repository, terminal, and power controls.
|
|
319
319
|
|
|
320
320
|
Under **Project**, select the **Template box** row's title to open its page.
|
|
@@ -573,11 +573,11 @@ own Find shortcut when focused.
|
|
|
573
573
|
## Files And Git
|
|
574
574
|
|
|
575
575
|
The Files and Git/Review segments in the titlebar open panes for the selected
|
|
576
|
-
|
|
576
|
+
box. Use Files to browse, search, upload, download, preview, and add
|
|
577
577
|
plain-file review comments. Use Git/Review to inspect repository status, diffs,
|
|
578
578
|
history, review comments, staging, and commits.
|
|
579
579
|
|
|
580
|
-
These panes route to the
|
|
580
|
+
These panes route to the box for the selected thread. If a devbox thread is
|
|
581
581
|
selected, Files and Git/Review inspect that devbox. If the Template box is
|
|
582
582
|
selected, they inspect the Template box.
|
|
583
583
|
|
|
@@ -585,15 +585,15 @@ See `files-git-and-review.md` for the detailed workflow.
|
|
|
585
585
|
|
|
586
586
|
## Browser
|
|
587
587
|
|
|
588
|
-
The Browser pane opens a Chromium session on the selected
|
|
588
|
+
The Browser pane opens a Chromium session on the selected box. It follows
|
|
589
589
|
the same selection model as Files, Git/Review, Terminal, and Ports: Template box
|
|
590
590
|
when the Template box is selected, the selected devbox when a devbox thread is
|
|
591
591
|
selected.
|
|
592
592
|
|
|
593
593
|
Browser tabs, cookies, local storage, downloads, uploads, and other profile
|
|
594
|
-
state live on that
|
|
594
|
+
state live on that box, so the user and agents can share the same web
|
|
595
595
|
session. The Browser pane supports ordinary page interaction, file chooser
|
|
596
|
-
prompts, downloads into the
|
|
596
|
+
prompts, downloads into the box, permission prompts, browser dialogs, and
|
|
597
597
|
profile reset. **Restart browser** asks for confirmation, then opens one blank
|
|
598
598
|
tab while preserving sign-ins and saved profile data. Check **Restore open
|
|
599
599
|
tabs** in that confirmation to reload the current tabs instead; the choice
|
|
@@ -653,7 +653,7 @@ can lose unsaved form entries. Agents use the shared browser skill's
|
|
|
653
653
|
`POST /.sprite/api/browser/restart` route; reading the browser's state alone
|
|
654
654
|
does not restart a disconnected browser.
|
|
655
655
|
|
|
656
|
-
The
|
|
656
|
+
The box has no security key or platform authenticator of its own. In the
|
|
657
657
|
desktop app, Browser-pane passkey forwarding is off by default and can be
|
|
658
658
|
enabled under **Desktop app settings > Browser > Allow sites to use a passkey
|
|
659
659
|
on this computer**. The first eligible passkey request can also ask whether to
|
|
@@ -696,7 +696,7 @@ element geometry.
|
|
|
696
696
|
## Ports
|
|
697
697
|
|
|
698
698
|
The ports control in the titlebar shows a singular or plural count of localhost
|
|
699
|
-
ports detected on the selected
|
|
699
|
+
ports detected on the selected box and forwarded to localhost on your
|
|
700
700
|
computer. You can open browser-friendly ports or copy the local target for other
|
|
701
701
|
tools, such as database clients.
|
|
702
702
|
|
|
@@ -704,7 +704,7 @@ See `ports-terminal-and-runtime.md` for details.
|
|
|
704
704
|
|
|
705
705
|
## Terminal
|
|
706
706
|
|
|
707
|
-
The terminal pane opens shell sessions on the selected
|
|
707
|
+
The terminal pane opens shell sessions on the selected box. It follows the
|
|
708
708
|
same selection model as Files, Git/Review, Browser, and Ports: Template box when
|
|
709
709
|
the Template box is selected, the selected devbox when a devbox thread is
|
|
710
710
|
selected.
|
|
@@ -733,7 +733,7 @@ periodic safety checks still recover a missed notification. Control-plane
|
|
|
733
733
|
authorization lasts at most ten minutes, and a destination's DNS expiry can
|
|
734
734
|
make the effective lease shorter. When the feature or its current policy is
|
|
735
735
|
unavailable and no valid lease is already applied, configured destinations fail
|
|
736
|
-
closed while unrelated
|
|
736
|
+
closed while unrelated box traffic continues normally. A temporary policy
|
|
737
737
|
or hostname refresh problem can preserve the exact already-applied path only
|
|
738
738
|
through its original lease deadline; it does not renew permission, and Team
|
|
739
739
|
Settings may still show temporary unavailability. Routine boxes.dev
|
|
@@ -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
|
|
@@ -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
|
|
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
|
|
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
|
|
269
|
-
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
@@ -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
|
-
-
|
|
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
|
|
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
|
|
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
|
|
326
|
-
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.
|
|
327
328
|
|
|
328
329
|
## Finishing Work On A Devbox
|
|
329
330
|
|
|
@@ -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
|
|
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
|
|
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 **
|
|
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
|