@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
|
@@ -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
|
|
@@ -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
|
|
@@ -38,9 +38,9 @@ actions name missing files and link back to them.
|
|
|
38
38
|
|
|
39
39
|
## Storage And Delivery
|
|
40
40
|
|
|
41
|
-
boxes.dev encrypts each member file for that exact project. An
|
|
41
|
+
boxes.dev encrypts each member file for that exact project. An independent project
|
|
42
42
|
created from a Team Template receives a frozen, independently encrypted copy.
|
|
43
|
-
A
|
|
43
|
+
A managed project continues following the Team Template's current file
|
|
44
44
|
destinations, while each member's bytes remain scoped to their own project.
|
|
45
45
|
|
|
46
46
|
The devbox writes the exact uploaded bytes. Missing parent directories are
|
|
@@ -66,7 +66,7 @@ safely does block them until it is fixed, and Project settings explains what
|
|
|
66
66
|
the member must do. An agent session that is already running is not stopped
|
|
67
67
|
when a requirement or file changes.
|
|
68
68
|
|
|
69
|
-
When an admin changes a Home/Project choice or relative path for a
|
|
69
|
+
When an admin changes a Home/Project choice or relative path for a managed
|
|
70
70
|
project, boxes.dev removes the old managed destination but does not write the
|
|
71
71
|
saved bytes to the new destination automatically. The member must explicitly
|
|
72
72
|
choose **Use my saved file at this new destination** or upload a replacement.
|
|
@@ -84,7 +84,7 @@ Google account linked to the current boxes.dev account.
|
|
|
84
84
|
|
|
85
85
|
Central storage contains encrypted bytes, not plaintext or a usable root key.
|
|
86
86
|
Authorized boxes.dev services can decrypt a file to deliver it to the exact
|
|
87
|
-
|
|
87
|
+
managed project or return it after that member confirms their account. This is
|
|
88
88
|
not end-to-end or zero-knowledge encryption.
|
|
89
89
|
|
|
90
90
|
The delivered file is plaintext on the devbox. The project owner, root user,
|
|
@@ -83,20 +83,20 @@ Open a project to see its threads. The list can include:
|
|
|
83
83
|
|
|
84
84
|
Opening the project, browsing its thread history, or editing an unstarted draft
|
|
85
85
|
does not wake or connect to a machine. Mobile connects only after you open a
|
|
86
|
-
live thread that has a
|
|
86
|
+
live thread that has a box, or choose an action such as Send, Terminal,
|
|
87
87
|
Browser, Files, snapshot, sleep, or destroy that needs one. A live devbox
|
|
88
88
|
thread connects to that exact devbox rather than another project machine.
|
|
89
89
|
|
|
90
90
|
Tap the new-thread button to open a new-devbox draft directly. Long-press it
|
|
91
|
-
to open the menu with **New thread** and, in an
|
|
92
|
-
**New thread on Template box**. A
|
|
91
|
+
to open the menu with **New thread** and, in an independent project,
|
|
92
|
+
**New thread on Template box**. A managed project has no template
|
|
93
93
|
choice. If the project does not support devboxes, tapping opens a Template-box
|
|
94
94
|
draft instead. The draft uses the project's last Codex or Claude choice from
|
|
95
95
|
mobile, desktop, or
|
|
96
96
|
`dvb agents`, and otherwise uses Codex unless you configured only Claude during
|
|
97
97
|
desktop setup. Codex and Claude are the agent choices, with no separate Claude
|
|
98
98
|
CLI thread type for new work. An ordinary new devbox starts from the latest
|
|
99
|
-
Template-box snapshot; a
|
|
99
|
+
Template-box snapshot; a managed-project devbox starts from the Team Template's
|
|
100
100
|
current saved version. Inside an existing devbox group, **New thread** opens a
|
|
101
101
|
draft directly on that same devbox, where you choose the agent before sending.
|
|
102
102
|
|
|
@@ -105,15 +105,15 @@ unpinning, marking unread, muting notifications, archiving, unarchiving,
|
|
|
105
105
|
deleting when available, and ending live sessions. Eligible Codex and Claude threads on the Template box can
|
|
106
106
|
be moved to a new devbox after their current turn finishes.
|
|
107
107
|
|
|
108
|
-
For an
|
|
108
|
+
For an independent project, from an open Template-box thread, use **New snapshot** in the header overflow
|
|
109
109
|
menu to update the snapshot used by future devboxes. The Template box briefly
|
|
110
110
|
becomes unavailable while the snapshot is created; the mobile app reports when
|
|
111
111
|
it succeeds or why it could not start.
|
|
112
112
|
|
|
113
113
|
An archived cold-storage thread stays readable on mobile without waking a
|
|
114
|
-
machine. In an
|
|
114
|
+
machine. In an independent project, use **Restore thread**, then choose **To new
|
|
115
115
|
devbox** to restore from the latest project snapshot or **To Template box** to
|
|
116
|
-
use the existing Template-box path. A
|
|
116
|
+
use the existing Template-box path. A managed project offers only
|
|
117
117
|
**To new devbox** and pins the current Team Template saved version when the
|
|
118
118
|
restore starts. The restored thread returns directly to the normal thread list.
|
|
119
119
|
|
|
@@ -133,8 +133,8 @@ notifications** turns them back on.
|
|
|
133
133
|
The session view shows the thread transcript and a composer for sending new
|
|
134
134
|
messages. Archived, cold-storage, and history-only sessions remain read-only
|
|
135
135
|
from project data until you explicitly restore them. Unstarted drafts remain
|
|
136
|
-
editable without a
|
|
137
|
-
of these sessions does not wake a
|
|
136
|
+
editable without a box and connect only when you Send. Merely opening any
|
|
137
|
+
of these sessions does not wake a box. On a new-thread screen, you can
|
|
138
138
|
choose Codex or Claude, add attachments, and tap **Send** immediately while the
|
|
139
139
|
draft record finishes creating quietly in the background. Claude Code
|
|
140
140
|
transcripts use the same structured rendering as the
|
|
@@ -190,7 +190,7 @@ Close Find with **×** to return to reading or replying.
|
|
|
190
190
|
|
|
191
191
|
The rate-limit indicator shows the newest reading available for the selected
|
|
192
192
|
Codex or Claude account. Its last reading remains visible while the thread's
|
|
193
|
-
|
|
193
|
+
box is asleep or disconnected, and updates after boxes.dev receives a
|
|
194
194
|
newer reading.
|
|
195
195
|
|
|
196
196
|
When Codex waits for MCP servers during startup, the startup row names the
|
|
@@ -206,7 +206,7 @@ the warning offers **Open MCPs**.
|
|
|
206
206
|
|
|
207
207
|
After you tap **Send** on an existing managed Codex or Claude thread, you can
|
|
208
208
|
leave the thread immediately. boxes.dev keeps the follow-up in its delivery
|
|
209
|
-
queue while the
|
|
209
|
+
queue while the box wakes or the agent accepts it.
|
|
210
210
|
|
|
211
211
|
Claude follow-ups waiting for the current turn appear at the end of the
|
|
212
212
|
scrollable transcript. Once a message reaches the devbox, use its delete
|
|
@@ -261,7 +261,7 @@ still drafts in the composer so you can send them as soon as the turn finishes
|
|
|
261
261
|
stopping.
|
|
262
262
|
|
|
263
263
|
Choose **… → Terminal** in a thread when you need a shell for the
|
|
264
|
-
thread's current
|
|
264
|
+
thread's current box.
|
|
265
265
|
|
|
266
266
|
Choose **… → Agent permissions** in an open thread to view or change what
|
|
267
267
|
agents on that thread's devbox or Template box can do. Each row shows the
|
|
@@ -360,11 +360,11 @@ desktop workbench workflows.
|
|
|
360
360
|
|
|
361
361
|
## Terminal
|
|
362
362
|
|
|
363
|
-
The mobile terminal attaches to the selected thread
|
|
363
|
+
The mobile terminal attaches to the selected thread's box when terminal
|
|
364
364
|
access is available. It shows connection states such as opening the shell,
|
|
365
|
-
preparing terminal size, connecting, reconnecting, and waking the
|
|
365
|
+
preparing terminal size, connecting, reconnecting, and waking the box.
|
|
366
366
|
|
|
367
|
-
If the shell exits, use **Reopen shell**. If the route or
|
|
367
|
+
If the shell exits, use **Reopen shell**. If the route or box target is no
|
|
368
368
|
longer available, go back to the thread and reopen the terminal.
|
|
369
369
|
|
|
370
370
|
The terminal includes mobile accessory controls for Ctrl, paste, special keys,
|
|
@@ -480,6 +480,8 @@ include:
|
|
|
480
480
|
- quiet hours, a one-hour notification pause, phone alerts, and unread app icon
|
|
481
481
|
badge preference;
|
|
482
482
|
- theme, monospace font, and thread text size;
|
|
483
|
+
- **Sort threads**, the thread list order shared with desktop (see
|
|
484
|
+
`threads-and-agents.md`, Thread List Organization);
|
|
483
485
|
- release package details and refresh controls in installed builds;
|
|
484
486
|
- account deletion.
|
|
485
487
|
- a Help center link that opens the public guides at `https://boxes.dev/help`
|
|
@@ -572,7 +574,7 @@ app-store update.
|
|
|
572
574
|
## Mobile Versus Desktop
|
|
573
575
|
|
|
574
576
|
Use desktop for setup, full project orientation, file upload/download workflows,
|
|
575
|
-
Git staging and commits, port forwarding,
|
|
577
|
+
Git staging and commits, port forwarding, box process inspection, and
|
|
576
578
|
detailed review.
|
|
577
579
|
|
|
578
580
|
Use mobile when you want to monitor progress, answer questions, send a quick
|
|
@@ -189,7 +189,7 @@ MCPs**. Codex-synced plugins use Codex's own trusted install flow. Local Codex
|
|
|
189
189
|
plugins, Claude plugins, and unsupported/local MCPs belong on the Template box
|
|
190
190
|
when they should become part of future devboxes.
|
|
191
191
|
|
|
192
|
-
A
|
|
192
|
+
A managed project has no personal Template box. Native-only
|
|
193
193
|
Plugins and unsupported/local MCPs installed on one of its devboxes stay on
|
|
194
194
|
that exact devbox; the member cannot publish them into the shared Team
|
|
195
195
|
Template. Centrally managed project MCPs continue to use **Integrations →
|
|
@@ -278,7 +278,7 @@ agent permission defaults (the values in effect, with
|
|
|
278
278
|
`permissionDefaultsLockedByTeamTemplate` true when a Team Template locks
|
|
279
279
|
them), and Claude and Codex agent settings
|
|
280
280
|
(`agentSettings`, plus the Team Template's read-only `teamAgentSettings` in a
|
|
281
|
-
|
|
281
|
+
managed project). `effectiveGitAction` includes the account's default
|
|
282
282
|
when no project preference is set. `autoWake` reports the account-wide
|
|
283
283
|
preference shown in Project settings. `permissionDefaultsEditable` is always false.
|
|
284
284
|
|
|
@@ -291,7 +291,7 @@ Older projects without recorded creation inputs report a null origin.
|
|
|
291
291
|
|
|
292
292
|
Team Template output includes its identity, description, source/repositories,
|
|
293
293
|
machine size, active saved version, project defaults and save epochs, setup
|
|
294
|
-
instructions, integration requirements,
|
|
294
|
+
instructions, integration requirements, managed-project policy, cleanup,
|
|
295
295
|
maintenance and watches, Project URL/MCP definitions, environment definitions,
|
|
296
296
|
member-file requirements, agent settings, and `agentPermissions` (the saved
|
|
297
297
|
`policy` with `locked` and `values`, or null before an admin saves one, plus
|
|
@@ -313,7 +313,7 @@ grant. An active `edit-template-box` or `edit-team-template` grant also covers
|
|
|
313
313
|
that thread's project settings. Team Template writes need team-admin authority
|
|
314
314
|
and `edit-team-template`, or an existing authorized template editing host or
|
|
315
315
|
association. A grant for the source template works without an editing session,
|
|
316
|
-
including from an
|
|
316
|
+
including from an independent project created from it. Request only the minimum
|
|
317
317
|
permission returned by a denied write. Agent permission defaults remain
|
|
318
318
|
user-only even with an editing grant.
|
|
319
319
|
|
|
@@ -348,9 +348,9 @@ Project operations use these fields in addition to `section`:
|
|
|
348
348
|
| `maintenance_delete` | No additional fields. |
|
|
349
349
|
| `maintenance_watches` | `expectedRevision` from `maintenance.revision`, `confirmWatchRemovals`, `script`, `timeoutSeconds`, `watches` with `repository`, `enabled`, and `paths`; preserves the schedule. |
|
|
350
350
|
| `member_files` | `expectedDefinitionScopeId`, `expectedDefinitionDesiredRevision`, `expectedMemberDesiredRevision` from `memberFilesRevision`; `updates` with `fileId` and `valueAction` (`kind: "delete"`, `kind: "accept"`, or `kind: "replace"` with `plaintextBase64` and `byteLength`). |
|
|
351
|
-
| `environment_file` | `draft` for an
|
|
352
|
-
| `environment_file_delete` | `contextId`, `expectedContextRevision` for an
|
|
353
|
-
| `agent_settings` | `agent` (`claude` or `codex`), `content`, `expectedRevision`, as described below. In a
|
|
351
|
+
| `environment_file` | `draft` for an independent project's environment file, as described below. For a managed project's personal values, use `env set|remove`. |
|
|
352
|
+
| `environment_file_delete` | `contextId`, `expectedContextRevision` for an independent project's environment file. |
|
|
353
|
+
| `agent_settings` | `agent` (`claude` or `codex`), `content`, `expectedRevision`, as described below. In a managed project, this saves the member's own settings. |
|
|
354
354
|
|
|
355
355
|
Team Template operations use these fields in addition to `section`:
|
|
356
356
|
|
|
@@ -377,7 +377,7 @@ Team Template operations use these fields in addition to `section`:
|
|
|
377
377
|
| `agent_settings` | `agent` (`claude` or `codex`), `content`, `expectedRevision`, as described below. |
|
|
378
378
|
| `agent_permissions` | `expectedRevision` from `agentPermissions.revision`, `locked`, and complete `values` with every field from the read result. The first save with `locked: false` while `memberProjectCount` is above zero also needs `existingMembers`: `follow_team_template` or `keep_current`. |
|
|
379
379
|
|
|
380
|
-
Before a first `agent_permissions` save with existing
|
|
380
|
+
Before a first `agent_permissions` save with existing managed projects, ask
|
|
381
381
|
the user whether those projects should move to the new permissions
|
|
382
382
|
(`follow_team_template`) or keep their current ones as each member's own
|
|
383
383
|
choice (`keep_current`); without the field the save fails with
|
|
@@ -389,7 +389,7 @@ An environment `draft` contains `contextId`, `expectedContextRevision`, `path`,
|
|
|
389
389
|
`displayOrder`, `adoptionRevision`, `adoptionSourceSha256`,
|
|
390
390
|
`adoptionManagedNames`, `adoptionRemovedNames`, and the complete `rows` array.
|
|
391
391
|
Read these file fields before editing; for a new file use null IDs/revisions,
|
|
392
|
-
empty adoption arrays, and a new relative path.
|
|
392
|
+
empty adoption arrays, and a new relative path. Independent project drafts also
|
|
393
393
|
need `state: "active"` or `"pending_adoption"`.
|
|
394
394
|
Each row contains `rowId`, `displayOrder`, `name`, `inlineComment`,
|
|
395
395
|
`description`, and `valueAction`. Team Template rows also need `provider`
|
|
@@ -839,7 +839,7 @@ those configured separately. Other devboxes will keep their individual
|
|
|
839
839
|
permissions. The choice is personal to the owner's
|
|
840
840
|
project, including projects created from a Team Template; it will not change
|
|
841
841
|
teammates' permissions. Template-only permissions keep their existing scope.
|
|
842
|
-
In a
|
|
842
|
+
In a managed project whose Team Template locks agent permissions, **Always
|
|
843
843
|
allow for project** is not offered; **Allow** still enables the permission on
|
|
844
844
|
the requesting box. See `team-template.md` for how a Team Template sets these
|
|
845
845
|
project permissions.
|
|
@@ -1179,9 +1179,8 @@ If that source box has no saved defaults for the agent, the managed catalog
|
|
|
1179
1179
|
default is used.
|
|
1180
1180
|
|
|
1181
1181
|
The new devbox belongs to the source box's project and uses that project's
|
|
1182
|
-
current reusable source. An
|
|
1183
|
-
Template-box snapshot and returns `snapshot_required` when none exists. A
|
|
1184
|
-
Template member project uses the current saved version. The command never
|
|
1182
|
+
current reusable source. An independent project uses its latest eligible
|
|
1183
|
+
Template-box snapshot and returns `snapshot_required` when none exists. A managed project uses the current saved version. The command never
|
|
1185
1184
|
snapshots or clones the live source box. Files, edits, branches, and commits
|
|
1186
1185
|
that exist only on the source devbox are absent. Push a needed commit to a Git
|
|
1187
1186
|
remote and tell the child to fetch and check it out, or use `current-devbox`;
|
|
@@ -2111,9 +2110,9 @@ Run `dvb-onbox box status --json` before choosing a workflow:
|
|
|
2111
2110
|
|
|
2112
2111
|
- `team_template_edit_box`: the agent runs directly on the Team Template
|
|
2113
2112
|
editing machine. Use **Work directly on a Team Template editing box** below.
|
|
2114
|
-
- `template_box`: local shell commands affect an
|
|
2113
|
+
- `template_box`: local shell commands affect an independent project's Template
|
|
2115
2114
|
box. To edit an associated Team Template, use **Work on a Team Template from
|
|
2116
|
-
|
|
2115
|
+
a project's Template box**. To create a new definition from the current
|
|
2117
2116
|
project, use **Create a Team Template from this project**.
|
|
2118
2117
|
- `devbox`: local edits affect only this devbox; do not treat it as the shared
|
|
2119
2118
|
template. In a Team Template project, a team admin's agent can edit that
|
|
@@ -2137,10 +2136,10 @@ on its current editing machine. Ordinary file and shell tools operate on that
|
|
|
2137
2136
|
checkout. Use the actual repository paths there; do not use remote `exec` or
|
|
2138
2137
|
`push` commands to reach the machine you already occupy.
|
|
2139
2138
|
|
|
2140
|
-
This editing machine is not an
|
|
2139
|
+
This editing machine is not an independent project's Template box. Use
|
|
2141
2140
|
`dvb-onbox project maintenance get|apply` for its Team Template maintenance
|
|
2142
2141
|
policy and the **Member-file requirements** commands for member-file
|
|
2143
|
-
definitions.
|
|
2142
|
+
definitions. Independent project setup completion, project lifecycle commands,
|
|
2144
2143
|
and `dvb-onbox snapshot` are not the Team Template save workflow. Configure
|
|
2145
2144
|
startup behavior in the Team Template's **When a new devbox is created** card
|
|
2146
2145
|
and use the editor's save flow when the user has requested publication. See
|
|
@@ -2160,7 +2159,7 @@ project created from the template with `edit-team-template`, without an editing
|
|
|
2160
2159
|
session. Run these commands in its current editing box too. From an ordinary
|
|
2161
2160
|
Template box with an active editor association, add `--template <team-template-id>`
|
|
2162
2161
|
to select that associated Team Template. Every operation edits the Team
|
|
2163
|
-
Template; it does not add requirements to the caller's
|
|
2162
|
+
Template; it does not add requirements to the caller's independent project.
|
|
2164
2163
|
|
|
2165
2164
|
```bash
|
|
2166
2165
|
dvb-onbox team-template member-files list --json
|
|
@@ -2184,7 +2183,7 @@ and removals. After an uncertain response, list again to inspect the outcome
|
|
|
2184
2183
|
before retrying a change.
|
|
2185
2184
|
|
|
2186
2185
|
Definitions take effect independently of saving a filesystem version. Existing
|
|
2187
|
-
|
|
2186
|
+
managed projects follow these requirements, and a missing file will block their
|
|
2188
2187
|
next startup. Changing a destination will require members to approve the new
|
|
2189
2188
|
destination or upload a replacement. Changing instructions will not require
|
|
2190
2189
|
destination approval. See [Member files](member-managed-files.md) for upload
|
|
@@ -2209,19 +2208,19 @@ dvb-onbox team-template env remove --file sandbox/.env.local --name LOG_LEVEL
|
|
|
2209
2208
|
```
|
|
2210
2209
|
|
|
2211
2210
|
Paths are relative to `/home/boxes`. `--value` or `--value-stdin` saves a Team
|
|
2212
|
-
value that every
|
|
2211
|
+
value that every managed project receives. `--member` asks each member for their
|
|
2213
2212
|
own value instead, required unless `--optional` is added, with optional
|
|
2214
2213
|
`--instructions`. Switching a variable from Team to Member deletes its Team
|
|
2215
2214
|
value. From an ordinary Template box, add `--template <team-template-id>`.
|
|
2216
2215
|
|
|
2217
|
-
Changes take effect without saving a new Team Template version. Existing
|
|
2216
|
+
Changes take effect without saving a new Team Template version. Existing managed
|
|
2218
2217
|
projects receive Team values within about a minute. A new required Member value
|
|
2219
2218
|
does not block existing devboxes; members will see it as needed in **Project
|
|
2220
2219
|
settings → Environment files**.
|
|
2221
2220
|
|
|
2222
2221
|
### Create a Team Template from this project
|
|
2223
2222
|
|
|
2224
|
-
A team admin can ask an agent on an
|
|
2223
|
+
A team admin can ask an agent on an independent project's Template box to create
|
|
2225
2224
|
a new Team Template based on that project. This path uses clean GitHub clones;
|
|
2226
2225
|
it never snapshots the source box or copies its home directory, credentials,
|
|
2227
2226
|
environment values, uncommitted files, or unrelated machine state.
|
|
@@ -2327,7 +2326,7 @@ fields, including `sourceKey` even when its schedule is disabled:
|
|
|
2327
2326
|
|
|
2328
2327
|
When adding a new definition that has no source counterpart, choose a stable,
|
|
2329
2328
|
nonempty `sourceKey` for it. Include definitions, never MCP credentials or
|
|
2330
|
-
environment values. If
|
|
2329
|
+
environment values. If managed project creation is enabled,
|
|
2331
2330
|
`environmentConfirmed` confirms that the template does not capture or depend
|
|
2332
2331
|
on member-specific environment values.
|
|
2333
2332
|
|
|
@@ -2404,13 +2403,13 @@ dvb-onbox team-template edit-box discard --edit-box <edit-box-id> \
|
|
|
2404
2403
|
```
|
|
2405
2404
|
|
|
2406
2405
|
Saving fences this exact edit box and uses the normal verified Team Template
|
|
2407
|
-
release pipeline. Requested
|
|
2406
|
+
release pipeline. Requested managed project creation becomes active only after
|
|
2408
2407
|
the first saved release is eligible. `edit-box discard` is only for the
|
|
2409
2408
|
unsaved draft created through this path.
|
|
2410
2409
|
|
|
2411
|
-
### Work on a Team Template from
|
|
2410
|
+
### Work on a Team Template from a project's Template box
|
|
2412
2411
|
|
|
2413
|
-
This section applies to an agent on an
|
|
2412
|
+
This section applies to an agent on an independent project's Template box with an
|
|
2414
2413
|
active association to a Team Template editing session, including one created
|
|
2415
2414
|
through the creation workflow above. It does not describe a thread running
|
|
2416
2415
|
directly in the Team Template editor. Agents and other processes on the
|
|
@@ -1,25 +1,25 @@
|
|
|
1
|
-
# Ports, Terminal,
|
|
1
|
+
# Ports, Terminal, and box controls
|
|
2
2
|
|
|
3
|
-
The Ports menu, Terminal, Files, and Git follow the selected
|
|
3
|
+
The Ports menu, Terminal, Files, and Git follow the selected box. If you
|
|
4
4
|
select the Template box, they use the Template box. If you select a devbox
|
|
5
5
|
thread, they use that devbox. Ordinary `localhost` forwarding follows selection
|
|
6
6
|
by default, but you can keep it on one devbox while working elsewhere. Stable
|
|
7
7
|
local URLs also stay with each opted-in devbox after you select another thread.
|
|
8
8
|
|
|
9
|
-
##
|
|
9
|
+
## Box status
|
|
10
10
|
|
|
11
|
-
The
|
|
12
|
-
|
|
11
|
+
The box status pill in the desktop titlebar shows whether the selected
|
|
12
|
+
box is running, sleeping, waking, connecting, snapshotting, upgrading, or at
|
|
13
13
|
the awake devbox limit.
|
|
14
14
|
|
|
15
|
-
When the
|
|
15
|
+
When the box is running, open the status menu to sleep it. The same menu can
|
|
16
16
|
also toggle whether sleeping Template boxes and devboxes wake automatically when
|
|
17
17
|
you return to them. Auto-wake is on by default and is saved as an account
|
|
18
|
-
preference. When auto-wake is off, passive navigation leaves the
|
|
18
|
+
preference. When auto-wake is off, passive navigation leaves the box
|
|
19
19
|
asleep. Explicitly sending a message to a Codex or Claude thread will still
|
|
20
20
|
wake its machine through the normal wake flow, even with auto-wake off.
|
|
21
21
|
|
|
22
|
-
When the
|
|
22
|
+
When the box is sleeping, use Wake from the status pill, Terminal, Files,
|
|
23
23
|
Git, or Ports. If a devbox is sleeping because the awake devbox limit is full,
|
|
24
24
|
boxes.dev asks you to sleep another devbox before continuing.
|
|
25
25
|
|
|
@@ -72,14 +72,14 @@ If delivery could not be confirmed, inspect the thread before trying again.
|
|
|
72
72
|
boxes.dev will not automatically resend an uncertain check. This helps avoid
|
|
73
73
|
repeating a deployment or similar operation after a lost response.
|
|
74
74
|
|
|
75
|
-
## Selected
|
|
75
|
+
## Selected box
|
|
76
76
|
|
|
77
|
-
Most
|
|
77
|
+
Most box tools route to the selected thread:
|
|
78
78
|
|
|
79
79
|
- Template box selected: tools run against the project Template box.
|
|
80
80
|
- Devbox thread selected: tools run against that devbox.
|
|
81
|
-
- A thread that has not started or has no connected
|
|
82
|
-
may ask you to wait, select a connected thread, or wake the
|
|
81
|
+
- A thread that has not started or has no connected box yet: box tools
|
|
82
|
+
may ask you to wait, select a connected thread, or wake the box.
|
|
83
83
|
|
|
84
84
|
This routing matters most for ports and Git. A server started on a devbox
|
|
85
85
|
appears in the devbox's Ports menu, not the Template box's menu.
|
|
@@ -87,7 +87,7 @@ appears in the devbox's Ports menu, not the Template box's menu.
|
|
|
87
87
|
## Terminal
|
|
88
88
|
|
|
89
89
|
Open Terminal from the desktop titlebar. The terminal pane supports multiple
|
|
90
|
-
terminal tabs for the selected
|
|
90
|
+
terminal tabs for the selected box.
|
|
91
91
|
|
|
92
92
|
Common terminal actions:
|
|
93
93
|
|
|
@@ -96,7 +96,7 @@ Common terminal actions:
|
|
|
96
96
|
- Drag tabs to reorder them.
|
|
97
97
|
- Close a terminal tab with the close control on the tab.
|
|
98
98
|
- If a detached session is shown, choose Connect to attach to it again.
|
|
99
|
-
- If the selected
|
|
99
|
+
- If the selected box is sleeping, use Wake before terminal sessions load.
|
|
100
100
|
|
|
101
101
|
Closing a terminal tab ends that terminal session. Closing the desktop app
|
|
102
102
|
preserves open terminal sessions and restores their tabs when you reopen it.
|
|
@@ -135,7 +135,7 @@ alerts when terminal notification settings allow them.
|
|
|
135
135
|
Paste a clipboard image into a desktop terminal with **Cmd+V** on macOS,
|
|
136
136
|
**Ctrl+V** on Linux, or the terminal's **Paste** menu. Claude's image shortcut
|
|
137
137
|
(**Ctrl+V** on macOS/Linux, **Alt+V** on Windows) also works. boxes.dev will
|
|
138
|
-
upload the image to the selected
|
|
138
|
+
upload the image to the selected box and paste its file path. Claude Code
|
|
139
139
|
will recognize that path as an image attachment; a shell will receive the path
|
|
140
140
|
without running a command.
|
|
141
141
|
PNG and JPEG images are supported, up to 20 MiB per image and 50 MiB per paste.
|
|
@@ -155,7 +155,7 @@ syntax is intentional. `--stdin` passes stdin bytes. JSON reports separate
|
|
|
155
155
|
bounded stdout and stderr, the remote exit code, duration, timeout or
|
|
156
156
|
cancellation state, and whether either stream was truncated.
|
|
157
157
|
|
|
158
|
-
The command wakes a sleeping target through the normal
|
|
158
|
+
The command wakes a sleeping target through the normal box path. Ctrl+C
|
|
159
159
|
cancels only the selected command. If the devbox needs a newer local boxes.dev
|
|
160
160
|
service, exec fails explicitly and does not fall back to another transport.
|
|
161
161
|
|
|
@@ -303,8 +303,7 @@ availability to refresh, then retry the link.
|
|
|
303
303
|
|
|
304
304
|
Choose **Configure port forwarding…** for project-level rules. The same
|
|
305
305
|
configuration applies to every real machine in the project: the Template box
|
|
306
|
-
and devboxes in an
|
|
307
|
-
Template member project. These rules also apply when you keep localhost on a
|
|
306
|
+
and devboxes in an independent project, or only assigned devboxes in a managed project. These rules also apply when you keep localhost on a
|
|
308
307
|
box. Stable local URLs remain active for every opted-in devbox. New projects
|
|
309
308
|
forward detected ports to the matching local port by default. Configuration can
|
|
310
309
|
change that default, allow or exclude individual ports and inclusive ranges,
|
|
@@ -324,16 +323,16 @@ row can say that the port is in use locally or is not forwarded.
|
|
|
324
323
|
When available, choose **Use next available** to approve forwarding that remote
|
|
325
324
|
port to a different local port. The chosen local port stays pinned for the
|
|
326
325
|
current desktop app session across box sleep/wake, renderer reloads, and thread
|
|
327
|
-
or
|
|
326
|
+
or box reselection. Use the quiet inline **Unpin** action to return to the
|
|
328
327
|
saved project mapping. Quitting the desktop app clears the pin. Session pins do
|
|
329
328
|
not change the saved project mapping.
|
|
330
329
|
|
|
331
|
-
With a connected
|
|
330
|
+
With a connected box and no detected ports, the menu header simply counts
|
|
332
331
|
zero ports. In other empty states the menu explains itself: waiting for the
|
|
333
|
-
selected
|
|
332
|
+
selected box, waiting for the first port snapshot, reconnecting, or
|
|
334
333
|
unavailable.
|
|
335
334
|
|
|
336
|
-
##
|
|
335
|
+
## Box usage and activity
|
|
337
336
|
|
|
338
337
|
When live metrics are available, the titlebar can show CPU and memory usage.
|
|
339
338
|
Memory usage covers the whole machine, including containers and system services,
|
|
@@ -343,7 +342,7 @@ for a service update, its tooltip may show **Workload memory** instead, which
|
|
|
343
342
|
covers only the processes managed by boxes.dev.
|
|
344
343
|
|
|
345
344
|
Click the usage indicator to open Activity. Activity lists processes inside the
|
|
346
|
-
selected
|
|
345
|
+
selected box, with command, CPU, memory, PID, and owner labels when
|
|
347
346
|
available. Activity's **Workload memory** total covers that workload, while the
|
|
348
347
|
titlebar shows the whole machine. Per-process memory figures may also include
|
|
349
348
|
shared memory, so the rows do not necessarily add up to either total. You can
|
|
@@ -359,12 +358,12 @@ to recover. Reduce memory use before retrying the interrupted work.
|
|
|
359
358
|
## Reset
|
|
360
359
|
|
|
361
360
|
The desktop app menu has **Machine > Reset (stop processes)…** when the selected
|
|
362
|
-
managed
|
|
363
|
-
commands, and user services, while preserving files and keeping the
|
|
361
|
+
managed box is running. Reset kills shells, agent sessions, background
|
|
362
|
+
commands, and user services, while preserving files and keeping the box running.
|
|
364
363
|
|
|
365
|
-
If a devbox thread is selected, reset targets that devbox. In an
|
|
364
|
+
If a devbox thread is selected, reset targets that devbox. In an independent
|
|
366
365
|
project, selecting the Template box targets it instead. A project with no
|
|
367
|
-
selected real
|
|
366
|
+
selected real box has no reset target. boxes.dev confirms before resetting
|
|
368
367
|
and then reports what was stopped.
|
|
369
368
|
|
|
370
369
|
The Machine menu names the target as a Devbox with the selected thread's title
|
|
@@ -377,7 +376,7 @@ machine's service to be running and cannot recover a failed wake attempt.
|
|
|
377
376
|
For a running machine, try **Machine > Reset (stop processes)…** before rebooting.
|
|
378
377
|
**Machine > Reboot (restart machine)…** works on running and sleeping Template
|
|
379
378
|
boxes and devboxes. It starts that exact machine without restoring saved memory.
|
|
380
|
-
After a failed wake leaves the selected
|
|
379
|
+
After a failed wake leaves the selected box sleeping, a warning banner
|
|
381
380
|
offers **Try again** to retry a normal wake and **Reboot…** to restart without
|
|
382
381
|
saved memory. The normal **Wake** control remains available to retry waking.
|
|
383
382
|
|