@boxes-dev/dvb-runtime 1.0.1097 → 1.0.1099
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agent-init-guides/flow.md +31 -4
- package/dist/agent-init-guides/git-ssh.md +2 -2
- package/dist/agent-init-guides/manifest.md +10 -2
- package/dist/agent-init-guides/running.md +8 -3
- package/dist/agent-init-guides/untracked.md +29 -4
- package/dist/bin/dvb.mjs +108 -27
- package/dist/bin/dvbd.mjs +10 -9
- package/dist/product-docs/references/agent-tools.md +6 -7
- package/dist/product-docs/references/automations.md +4 -4
- package/dist/product-docs/references/aws.md +17 -11
- package/dist/product-docs/references/billing-and-limits.md +23 -11
- package/dist/product-docs/references/cli.md +14 -15
- package/dist/product-docs/references/core-concepts.md +35 -30
- package/dist/product-docs/references/desktop-workbench.md +26 -25
- package/dist/product-docs/references/files-git-and-review.md +20 -17
- package/dist/product-docs/references/fork-workflows.md +44 -31
- package/dist/product-docs/references/getting-started.md +7 -8
- package/dist/product-docs/references/glossary.md +46 -22
- package/dist/product-docs/references/google-cloud.md +13 -8
- package/dist/product-docs/references/index.md +18 -16
- package/dist/product-docs/references/linear.md +2 -2
- package/dist/product-docs/references/managed-environment-files.md +1 -1
- package/dist/product-docs/references/member-managed-files.md +4 -4
- package/dist/product-docs/references/mobile.md +23 -18
- package/dist/product-docs/references/onbox-agent-tools.md +25 -26
- package/dist/product-docs/references/ports-terminal-and-runtime.md +27 -28
- package/dist/product-docs/references/project-setup.md +36 -16
- package/dist/product-docs/references/security-and-data.md +10 -10
- package/dist/product-docs/references/slack.md +3 -3
- package/dist/product-docs/references/tailscale.md +2 -2
- package/dist/product-docs/references/team-template.md +22 -22
- package/dist/product-docs/references/template-box-environment.md +7 -3
- package/dist/product-docs/references/threads-and-agents.md +79 -31
- package/dist/product-docs/references/troubleshooting.md +24 -25
- package/package.json +2 -2
|
@@ -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,
|
|
@@ -74,26 +74,29 @@ Open a project to see its threads. The list can include:
|
|
|
74
74
|
|
|
75
75
|
- pinned threads and devboxes;
|
|
76
76
|
- recent threads;
|
|
77
|
-
- devbox groups, with child threads under the devbox
|
|
78
|
-
|
|
77
|
+
- devbox groups, with child threads under the devbox and, when the devbox has
|
|
78
|
+
archived threads, an **Archived threads** list at the end of the group;
|
|
79
|
+
- an **Archived threads** list at the end of the project for the Template
|
|
80
|
+
box's archived threads, threads from destroyed devboxes (grouped under each
|
|
81
|
+
devbox's name), and other archived threads that have no devbox;
|
|
79
82
|
- drafts that have not sent their first message yet.
|
|
80
83
|
|
|
81
84
|
Opening the project, browsing its thread history, or editing an unstarted draft
|
|
82
85
|
does not wake or connect to a machine. Mobile connects only after you open a
|
|
83
|
-
live thread that has a
|
|
86
|
+
live thread that has a box, or choose an action such as Send, Terminal,
|
|
84
87
|
Browser, Files, snapshot, sleep, or destroy that needs one. A live devbox
|
|
85
88
|
thread connects to that exact devbox rather than another project machine.
|
|
86
89
|
|
|
87
90
|
Tap the new-thread button to open a new-devbox draft directly. Long-press it
|
|
88
|
-
to open the menu with **New thread** and, in an
|
|
89
|
-
**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
|
|
90
93
|
choice. If the project does not support devboxes, tapping opens a Template-box
|
|
91
94
|
draft instead. The draft uses the project's last Codex or Claude choice from
|
|
92
95
|
mobile, desktop, or
|
|
93
96
|
`dvb agents`, and otherwise uses Codex unless you configured only Claude during
|
|
94
97
|
desktop setup. Codex and Claude are the agent choices, with no separate Claude
|
|
95
98
|
CLI thread type for new work. An ordinary new devbox starts from the latest
|
|
96
|
-
Template-box snapshot; a
|
|
99
|
+
Template-box snapshot; a managed-project devbox starts from the Team Template's
|
|
97
100
|
current saved version. Inside an existing devbox group, **New thread** opens a
|
|
98
101
|
draft directly on that same devbox, where you choose the agent before sending.
|
|
99
102
|
|
|
@@ -102,15 +105,15 @@ unpinning, marking unread, muting notifications, archiving, unarchiving,
|
|
|
102
105
|
deleting when available, and ending live sessions. Eligible Codex and Claude threads on the Template box can
|
|
103
106
|
be moved to a new devbox after their current turn finishes.
|
|
104
107
|
|
|
105
|
-
For an
|
|
108
|
+
For an independent project, from an open Template-box thread, use **New snapshot** in the header overflow
|
|
106
109
|
menu to update the snapshot used by future devboxes. The Template box briefly
|
|
107
110
|
becomes unavailable while the snapshot is created; the mobile app reports when
|
|
108
111
|
it succeeds or why it could not start.
|
|
109
112
|
|
|
110
113
|
An archived cold-storage thread stays readable on mobile without waking a
|
|
111
|
-
machine. In an
|
|
114
|
+
machine. In an independent project, use **Restore thread**, then choose **To new
|
|
112
115
|
devbox** to restore from the latest project snapshot or **To Template box** to
|
|
113
|
-
use the existing Template-box path. A
|
|
116
|
+
use the existing Template-box path. A managed project offers only
|
|
114
117
|
**To new devbox** and pins the current Team Template saved version when the
|
|
115
118
|
restore starts. The restored thread returns directly to the normal thread list.
|
|
116
119
|
|
|
@@ -130,8 +133,8 @@ notifications** turns them back on.
|
|
|
130
133
|
The session view shows the thread transcript and a composer for sending new
|
|
131
134
|
messages. Archived, cold-storage, and history-only sessions remain read-only
|
|
132
135
|
from project data until you explicitly restore them. Unstarted drafts remain
|
|
133
|
-
editable without a
|
|
134
|
-
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
|
|
135
138
|
choose Codex or Claude, add attachments, and tap **Send** immediately while the
|
|
136
139
|
draft record finishes creating quietly in the background. Claude Code
|
|
137
140
|
transcripts use the same structured rendering as the
|
|
@@ -187,7 +190,7 @@ Close Find with **×** to return to reading or replying.
|
|
|
187
190
|
|
|
188
191
|
The rate-limit indicator shows the newest reading available for the selected
|
|
189
192
|
Codex or Claude account. Its last reading remains visible while the thread's
|
|
190
|
-
|
|
193
|
+
box is asleep or disconnected, and updates after boxes.dev receives a
|
|
191
194
|
newer reading.
|
|
192
195
|
|
|
193
196
|
When Codex waits for MCP servers during startup, the startup row names the
|
|
@@ -203,7 +206,7 @@ the warning offers **Open MCPs**.
|
|
|
203
206
|
|
|
204
207
|
After you tap **Send** on an existing managed Codex or Claude thread, you can
|
|
205
208
|
leave the thread immediately. boxes.dev keeps the follow-up in its delivery
|
|
206
|
-
queue while the
|
|
209
|
+
queue while the box wakes or the agent accepts it.
|
|
207
210
|
|
|
208
211
|
Claude follow-ups waiting for the current turn appear at the end of the
|
|
209
212
|
scrollable transcript. Once a message reaches the devbox, use its delete
|
|
@@ -258,7 +261,7 @@ still drafts in the composer so you can send them as soon as the turn finishes
|
|
|
258
261
|
stopping.
|
|
259
262
|
|
|
260
263
|
Choose **… → Terminal** in a thread when you need a shell for the
|
|
261
|
-
thread's current
|
|
264
|
+
thread's current box.
|
|
262
265
|
|
|
263
266
|
Choose **… → Agent permissions** in an open thread to view or change what
|
|
264
267
|
agents on that thread's devbox or Template box can do. Each row shows the
|
|
@@ -357,11 +360,11 @@ desktop workbench workflows.
|
|
|
357
360
|
|
|
358
361
|
## Terminal
|
|
359
362
|
|
|
360
|
-
The mobile terminal attaches to the selected thread
|
|
363
|
+
The mobile terminal attaches to the selected thread's box when terminal
|
|
361
364
|
access is available. It shows connection states such as opening the shell,
|
|
362
|
-
preparing terminal size, connecting, reconnecting, and waking the
|
|
365
|
+
preparing terminal size, connecting, reconnecting, and waking the box.
|
|
363
366
|
|
|
364
|
-
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
|
|
365
368
|
longer available, go back to the thread and reopen the terminal.
|
|
366
369
|
|
|
367
370
|
The terminal includes mobile accessory controls for Ctrl, paste, special keys,
|
|
@@ -477,6 +480,8 @@ include:
|
|
|
477
480
|
- quiet hours, a one-hour notification pause, phone alerts, and unread app icon
|
|
478
481
|
badge preference;
|
|
479
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);
|
|
480
485
|
- release package details and refresh controls in installed builds;
|
|
481
486
|
- account deletion.
|
|
482
487
|
- a Help center link that opens the public guides at `https://boxes.dev/help`
|
|
@@ -569,7 +574,7 @@ app-store update.
|
|
|
569
574
|
## Mobile Versus Desktop
|
|
570
575
|
|
|
571
576
|
Use desktop for setup, full project orientation, file upload/download workflows,
|
|
572
|
-
Git staging and commits, port forwarding,
|
|
577
|
+
Git staging and commits, port forwarding, box process inspection, and
|
|
573
578
|
detailed review.
|
|
574
579
|
|
|
575
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
|
|
|
@@ -6,10 +6,10 @@ why a setup step is waiting, how to resume setup, or how to add another project.
|
|
|
6
6
|
## What Setup Creates
|
|
7
7
|
|
|
8
8
|
The local-folder, agent-driven, and direct GitHub setup paths described here
|
|
9
|
-
create one
|
|
9
|
+
create one independent project with one Template box. The Template box is the
|
|
10
10
|
persistent base machine for that project. After setup, future devboxes start
|
|
11
11
|
from snapshots of this Template box. A Team Template can separately enable
|
|
12
|
-
**
|
|
12
|
+
**managed projects**, which have no personal Template box; see
|
|
13
13
|
`team-template.md` for that flow.
|
|
14
14
|
|
|
15
15
|
The desktop app's Project step recommends agent-driven setup first: the user's
|
|
@@ -169,7 +169,7 @@ If the desktop window reloads, the app rediscovers the matching local setup and
|
|
|
169
169
|
continues the secure bundle handoff. The setup progress banner also provides
|
|
170
170
|
**Resume setup** while the desktop still needs to finish the handoff, then
|
|
171
171
|
**Open setup thread** once the setup agent is running. Once bundle extraction
|
|
172
|
-
is complete,
|
|
172
|
+
is complete, independent project actions become available while the setup thread
|
|
173
173
|
continues.
|
|
174
174
|
|
|
175
175
|
## Agent-Driven Setup From The Terminal
|
|
@@ -322,6 +322,19 @@ desktop setup.
|
|
|
322
322
|
While reviewing the manifest, the coding agent presents the available instance
|
|
323
323
|
types and asks the user which one to use. The choice applies to the project's
|
|
324
324
|
Template box and all of its devboxes and cannot be changed after initialization.
|
|
325
|
+
The agent also asks for one starting branch for both Template setup and new
|
|
326
|
+
devboxes, recommending each repository's remote default, such as `main` or
|
|
327
|
+
`master`. During the local-file review, choose which unfinished work to save
|
|
328
|
+
on boxes.dev for later. Included work will be preserved on its original branch/commit
|
|
329
|
+
with a named Git stash for staged, unstaged, and selected untracked changes.
|
|
330
|
+
Setup will run on the selected branch with that work saved separately, even
|
|
331
|
+
when the edits came from the same branch. Approved environment/configuration
|
|
332
|
+
files and fixtures will remain available for setup. The setup summary will
|
|
333
|
+
explain how to resume the saved work in a devbox. Saving it in the Template
|
|
334
|
+
snapshot does not involve pushing to a Git remote. Your local branch and files
|
|
335
|
+
will stay intact. File selections do not filter Git history: the repository
|
|
336
|
+
upload includes local branch refs and local-only commits.
|
|
337
|
+
|
|
325
338
|
When every selected repository's `origin` default branch is known, the manifest starts
|
|
326
339
|
with generated Git commands that declare the branch to use for new devboxes.
|
|
327
340
|
This also covers repositories in subfolders. If you narrow the repository
|
|
@@ -329,13 +342,15 @@ selection, update the generated block's paths to match it.
|
|
|
329
342
|
boxes.dev recognizes that generated block, saves its branch defaults separately,
|
|
330
343
|
and prepares the checkout before running any remaining startup commands. Normally
|
|
331
344
|
configure the project's starting branch, usually `main`, so new devboxes fetch
|
|
332
|
-
fresh remote code
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
345
|
+
fresh remote code. Keep the generated block aligned with the chosen setup
|
|
346
|
+
branch when adding application setup commands after it. If the chosen branch
|
|
347
|
+
exists only locally, explain that it cannot be fetched and confirm whether to
|
|
348
|
+
use its clean committed state from the Template snapshot instead. Omit the
|
|
349
|
+
generated block for that choice; unfinished work remains saved separately.
|
|
336
350
|
Version 3 includes full startup and teardown sections with independent timeouts.
|
|
337
|
-
A missing default
|
|
338
|
-
|
|
351
|
+
A missing remote default does not require publishing a branch; the user can
|
|
352
|
+
choose a local branch as above. After setup, clearing the startup script does
|
|
353
|
+
not remove saved branch defaults.
|
|
339
354
|
|
|
340
355
|
Template maintenance starts unconfigured. When the repository needs ongoing
|
|
341
356
|
environment updates, the coding agent should author the maintenance script and
|
|
@@ -528,8 +543,8 @@ Company AWS access is managed separately from project setup under
|
|
|
528
543
|
sign-in and chooses one assigned account and role for the project, or enters an
|
|
529
544
|
IAM user's access key. boxes.dev then applies the managed `boxes-dev` profile to
|
|
530
545
|
the Template box and devboxes without changing the repository or requiring a
|
|
531
|
-
new snapshot. Open
|
|
532
|
-
|
|
546
|
+
new snapshot. Open terminals pick up the change at their next prompt, and
|
|
547
|
+
agent sessions before their next turn. See `aws.md` for profile precedence, central refresh, removal, and
|
|
533
548
|
container limits.
|
|
534
549
|
|
|
535
550
|
Project setup Codex scans may use the user's local Codex sign-in on this
|
|
@@ -614,7 +629,7 @@ Canceling setup or deleting the boxes.dev project does not delete a repository
|
|
|
614
629
|
created on GitHub.
|
|
615
630
|
|
|
616
631
|
A project created through this direct GitHub path can contain up to 20 selected
|
|
617
|
-
repositories, but it still creates exactly one
|
|
632
|
+
repositories, but it still creates exactly one independent project and one
|
|
618
633
|
Template box. Setup starts in
|
|
619
634
|
single-repository mode; switching it to multiple repositories is an explicit
|
|
620
635
|
choice to combine several repositories into one project. With one repository,
|
|
@@ -967,7 +982,12 @@ During provisioning, boxes.dev:
|
|
|
967
982
|
|
|
968
983
|
The setup thread runs on the Template box. It places uploaded project files,
|
|
969
984
|
approved external artifacts, and database dumps where the setup plan says they
|
|
970
|
-
belong.
|
|
985
|
+
belong. Before installing dependencies, it saves approved unfinished work
|
|
986
|
+
separately and prepares the starting branch chosen for both Template setup and
|
|
987
|
+
new devboxes. It reuses the branch and file choices in the setup notes, including
|
|
988
|
+
in a desktop local-folder import, and asks only for missing choices or a specific
|
|
989
|
+
preservation conflict. The source computer's checkout stays intact.
|
|
990
|
+
It installs dependencies, runs setup commands, and validates important
|
|
971
991
|
entrypoints when possible. It preserves tracked project source, tests,
|
|
972
992
|
dependency manifests, and lockfiles by default: when verification exposes a
|
|
973
993
|
project-code problem, it records the failure for follow-up instead of rewriting
|
|
@@ -1087,10 +1107,10 @@ To upload another local project, use **New project...** in the titlebar project
|
|
|
1087
1107
|
selector or **File > New Project...** in the desktop app. On the website,
|
|
1088
1108
|
**New project** offers the coding-agent prompt and **Create from GitHub**. For
|
|
1089
1109
|
a repository that is not on the user's computer, **Create from GitHub** clones
|
|
1090
|
-
another GitHub-backed
|
|
1091
|
-
environment setup afterwards. Each
|
|
1110
|
+
another GitHub-backed independent project instead, with the same manual
|
|
1111
|
+
environment setup afterwards. Each independent project made through
|
|
1092
1112
|
these paths gets its own setup flow and Template box. A Team Template's
|
|
1093
|
-
|
|
1113
|
+
managed-project path is the exception: it creates a managed project
|
|
1094
1114
|
without a personal Template box and uses the Team Template's current saved
|
|
1095
1115
|
version for future devboxes. Existing agent auth can be reused by local-folder
|
|
1096
1116
|
setup, but each local project still needs its own folder selection, scans,
|