@boxes-dev/dvb-runtime 1.0.1098 → 1.0.1100
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agent-init-guides/git-ssh.md +2 -2
- package/dist/bin/dvb.mjs +121 -72
- package/dist/bin/dvbd.mjs +6 -6
- package/dist/postgres-tools/SHA256SUMS +32 -8
- package/dist/postgres-tools/linux-arm64-el8/bin/pg_dump +0 -0
- package/dist/postgres-tools/linux-arm64-el8/bin/pg_restore +0 -0
- package/dist/postgres-tools/linux-arm64-el8/lib/libpq.so.5 +0 -0
- package/dist/postgres-tools/linux-arm64-el8/notices/PostgreSQL-COPYRIGHT.txt +23 -0
- package/dist/postgres-tools/linux-arm64-el9/bin/pg_dump +0 -0
- package/dist/postgres-tools/linux-arm64-el9/bin/pg_restore +0 -0
- package/dist/postgres-tools/linux-arm64-el9/lib/libpq.so.5 +0 -0
- package/dist/postgres-tools/linux-arm64-el9/notices/PostgreSQL-COPYRIGHT.txt +23 -0
- package/dist/postgres-tools/linux-arm64-ubuntu22.04/bin/pg_dump +0 -0
- package/dist/postgres-tools/linux-arm64-ubuntu22.04/bin/pg_restore +0 -0
- package/dist/postgres-tools/linux-arm64-ubuntu22.04/lib/libpq.so.5 +0 -0
- package/dist/postgres-tools/linux-x64-el8/bin/pg_dump +0 -0
- package/dist/postgres-tools/linux-x64-el8/bin/pg_restore +0 -0
- package/dist/postgres-tools/linux-x64-el8/lib/libpq.so.5 +0 -0
- package/dist/postgres-tools/linux-x64-el8/notices/PostgreSQL-COPYRIGHT.txt +23 -0
- package/dist/postgres-tools/linux-x64-el9/bin/pg_dump +0 -0
- package/dist/postgres-tools/linux-x64-el9/bin/pg_restore +0 -0
- package/dist/postgres-tools/linux-x64-el9/lib/libpq.so.5 +0 -0
- package/dist/postgres-tools/linux-x64-el9/notices/PostgreSQL-COPYRIGHT.txt +23 -0
- package/dist/postgres-tools/linux-x64-ubuntu22.04/bin/pg_dump +0 -0
- package/dist/postgres-tools/linux-x64-ubuntu22.04/bin/pg_restore +0 -0
- package/dist/postgres-tools/linux-x64-ubuntu22.04/lib/libpq.so.5 +0 -0
- package/dist/postgres-tools/linux-x64-ubuntu22.04/notices/PostgreSQL-and-Debian-copyright.txt +270 -0
- package/dist/postgres-tools/linux-x64-ubuntu24.04/notices/PostgreSQL-and-Debian-copyright.txt +270 -0
- package/dist/postgres-tools/release.json +306 -18
- 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 +26 -13
- package/dist/product-docs/references/cli.md +14 -15
- package/dist/product-docs/references/convex.md +92 -0
- package/dist/product-docs/references/core-concepts.md +35 -30
- package/dist/product-docs/references/desktop-workbench.md +62 -47
- package/dist/product-docs/references/files-git-and-review.md +14 -15
- package/dist/product-docs/references/fork-workflows.md +26 -25
- package/dist/product-docs/references/getting-started.md +11 -12
- 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 +20 -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 +63 -41
- package/dist/product-docs/references/ports-terminal-and-runtime.md +31 -28
- package/dist/product-docs/references/project-setup.md +15 -12
- package/dist/product-docs/references/security-and-data.md +23 -13
- package/dist/product-docs/references/slack.md +45 -7
- package/dist/product-docs/references/tailscale.md +2 -2
- package/dist/product-docs/references/team-template.md +26 -23
- package/dist/product-docs/references/template-box-environment.md +7 -3
- package/dist/product-docs/references/threads-and-agents.md +48 -24
- package/dist/product-docs/references/troubleshooting.md +24 -25
- package/package.json +2 -2
- /package/dist/postgres-tools/{linux-arm64 → linux-arm64-ubuntu22.04}/notices/PostgreSQL-and-Debian-copyright.txt +0 -0
- /package/dist/postgres-tools/{linux-arm64 → linux-arm64-ubuntu24.04}/bin/pg_dump +0 -0
- /package/dist/postgres-tools/{linux-arm64 → linux-arm64-ubuntu24.04}/bin/pg_restore +0 -0
- /package/dist/postgres-tools/{linux-arm64 → linux-arm64-ubuntu24.04}/lib/libpq.so.5 +0 -0
- /package/dist/postgres-tools/{linux-x64 → linux-arm64-ubuntu24.04}/notices/PostgreSQL-and-Debian-copyright.txt +0 -0
- /package/dist/postgres-tools/{linux-x64 → linux-x64-ubuntu24.04}/bin/pg_dump +0 -0
- /package/dist/postgres-tools/{linux-x64 → linux-x64-ubuntu24.04}/bin/pg_restore +0 -0
- /package/dist/postgres-tools/{linux-x64 → linux-x64-ubuntu24.04}/lib/libpq.so.5 +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Files, Git, And Review
|
|
2
2
|
|
|
3
|
-
The Files and Git/Review panes let you inspect the selected
|
|
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
|
|
|
@@ -414,12 +415,12 @@ warns about uncommitted changes, changed files, and local-only commits when that
|
|
|
414
415
|
information is available. It also names the pull requests whose automatic
|
|
415
416
|
follow-ups the devbox's threads handle. Destroying the devbox stops those
|
|
416
417
|
follow-ups, and the pull request shows them as paused until a restored or
|
|
417
|
-
other thread turns them on again.
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
418
|
+
other thread turns them on again. As soon as the destroy starts, the devbox's
|
|
419
|
+
threads move to **Devboxes** → **Archived threads** on desktop and to
|
|
420
|
+
**Archived threads** at the end of the project on mobile, on every device,
|
|
421
|
+
while the cold-storage archive finishes in the background. If archiving fails,
|
|
422
|
+
the threads return to the active list untouched. Once the devbox is gone, its
|
|
423
|
+
threads are grouped there under the destroyed devbox's name.
|
|
423
424
|
Archived automation runs stay in their automation's **Archived** group on
|
|
424
425
|
desktop, with their threads directly beneath the run's devbox. `dvb agents`
|
|
425
426
|
shows the threads in its archived section throughout. Preserving the
|
|
@@ -436,9 +437,9 @@ types must finish or be stopped before the devbox can be destroyed.
|
|
|
436
437
|
Destroying a devbox does not automatically save code to the Template box or to
|
|
437
438
|
Git. Commit, push, merge, download, or otherwise save anything important first.
|
|
438
439
|
The archived transcripts remain readable without a running machine. To
|
|
439
|
-
continue one, choose **Restore thread**. An
|
|
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
|
|
@@ -112,16 +111,16 @@ Use devbox threads for normal coding tasks.
|
|
|
112
111
|
## Agent Auth After Setup
|
|
113
112
|
|
|
114
113
|
Setup asks you to connect at least one coding agent. You can connect or repair
|
|
115
|
-
agent auth later from
|
|
116
|
-
|
|
114
|
+
agent auth later from **Settings → Agents** in the desktop account menu.
|
|
115
|
+
The macOS **Configure agents...** command opens the same section. The mobile app has the same controls under
|
|
117
116
|
**Settings → Agent accounts**.
|
|
118
117
|
|
|
119
118
|
Codex can be connected with ChatGPT login or an API key. Claude Code can be
|
|
120
|
-
connected with Claude login or an API key.
|
|
119
|
+
connected with Claude login or an API key. Settings → Agents can keep multiple
|
|
121
120
|
accounts or API keys for each agent; choose the active credential with its
|
|
122
121
|
radio control. That choice is global across your devboxes, and Codex and Claude
|
|
123
122
|
can use different active accounts. If a thread cannot start because an agent is
|
|
124
|
-
not authenticated, open
|
|
123
|
+
not authenticated, open Settings → Agents, reconnect or choose another saved
|
|
125
124
|
credential, and then start or retry the thread.
|
|
126
125
|
|
|
127
126
|
## First Useful Task
|
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
# Glossary
|
|
2
2
|
|
|
3
3
|
Use this doc for concise definitions of boxes.dev product terms. Prefer these
|
|
4
|
-
terms in user-facing answers
|
|
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
|
|
@@ -109,11 +111,13 @@ Use this terminology consistently:
|
|
|
109
111
|
- `vercel.md`: connecting Vercel once for the Vercel CLI on every box, the
|
|
110
112
|
managed login file, `vercel login` and `vercel logout` on a box, SAML team
|
|
111
113
|
sign-in, reconnecting, and disconnecting.
|
|
114
|
+
- `convex.md`: connecting a Convex team to this project's boxes, expiring native
|
|
115
|
+
CLI credentials, existing personal logins, renewal, and removing access.
|
|
112
116
|
- `tailscale.md`: team-managed tailnet setup, Tailscale-policy-based project
|
|
113
117
|
eligibility, tagged ephemeral project machines, stock CLI behavior, ordinary
|
|
114
118
|
snapshot identity rotation, native cleanup, incident removal, and version-one
|
|
115
119
|
limits.
|
|
116
|
-
- `billing-and-limits.md`: plans, box-hours, awake
|
|
120
|
+
- `billing-and-limits.md`: plans, box-hours, awake boxes, awake devbox
|
|
117
121
|
limits, project limits, usage, overages, checkout, and billing portal
|
|
118
122
|
behavior.
|
|
119
123
|
- `security-and-data.md`: setup uploads, secrets, auth storage at a product
|
|
@@ -126,10 +130,10 @@ Use this terminology consistently:
|
|
|
126
130
|
## Context Guidance
|
|
127
131
|
|
|
128
132
|
For a setup thread, use its task and current box role to choose the guidance.
|
|
129
|
-
|
|
130
|
-
thread runs directly on its editing
|
|
131
|
-
Template box can operate on that
|
|
132
|
-
guidance for
|
|
133
|
+
Independent project setup uses the project's Template box; a Team Template editor
|
|
134
|
+
thread runs directly on its editing box, while an independent project's
|
|
135
|
+
Template box can operate on that box remotely. Prefer setup and new-user
|
|
136
|
+
guidance for independent project onboarding, and Team Template guidance for shared
|
|
133
137
|
environment authoring.
|
|
134
138
|
|
|
135
139
|
If the user is on a devbox thread, assume they are doing task work. Prefer
|
|
@@ -172,8 +172,8 @@ thread. Runs that already failed or stopped require a new Linear Agent Session.
|
|
|
172
172
|
If assignment does not start, confirm that the connected Linear workspace is the
|
|
173
173
|
one containing the issue, your Linear identity is linked, your default Linear
|
|
174
174
|
automation is active, and the project's saved environment is usable: the
|
|
175
|
-
latest Template box snapshot for an
|
|
176
|
-
Team Template version for a
|
|
175
|
+
latest Template box snapshot for an independent project, or the current saved
|
|
176
|
+
Team Template version for a managed project. If several assignments start at
|
|
177
177
|
once and some do not launch, check awake devbox capacity and billing.
|
|
178
178
|
|
|
179
179
|
If work products do not attach, check the URL and the selected session. In an
|
|
@@ -53,7 +53,7 @@ Choose **New file…** to name a file that does not exist yet. The form is a
|
|
|
53
53
|
folder and a file name: the folder offers the folders already on the source and
|
|
54
54
|
also accepts one you type, and the line beneath echoes the full location the
|
|
55
55
|
file will have. Naming the folder separately matters because the two surfaces
|
|
56
|
-
resolve paths differently - an
|
|
56
|
+
resolve paths differently - an independent project against its project folder, a
|
|
57
57
|
Team Template against the machine's home directory with each of its repositories
|
|
58
58
|
as a child folder. A file name containing a slash, or a name the dotenv naming
|
|
59
59
|
rule does not accept, is reported straight away, before boxes.dev checks
|