@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.
Files changed (35) hide show
  1. package/dist/agent-init-guides/flow.md +31 -4
  2. package/dist/agent-init-guides/git-ssh.md +2 -2
  3. package/dist/agent-init-guides/manifest.md +10 -2
  4. package/dist/agent-init-guides/running.md +8 -3
  5. package/dist/agent-init-guides/untracked.md +29 -4
  6. package/dist/bin/dvb.mjs +108 -27
  7. package/dist/bin/dvbd.mjs +10 -9
  8. package/dist/product-docs/references/agent-tools.md +6 -7
  9. package/dist/product-docs/references/automations.md +4 -4
  10. package/dist/product-docs/references/aws.md +17 -11
  11. package/dist/product-docs/references/billing-and-limits.md +23 -11
  12. package/dist/product-docs/references/cli.md +14 -15
  13. package/dist/product-docs/references/core-concepts.md +35 -30
  14. package/dist/product-docs/references/desktop-workbench.md +26 -25
  15. package/dist/product-docs/references/files-git-and-review.md +20 -17
  16. package/dist/product-docs/references/fork-workflows.md +44 -31
  17. package/dist/product-docs/references/getting-started.md +7 -8
  18. package/dist/product-docs/references/glossary.md +46 -22
  19. package/dist/product-docs/references/google-cloud.md +13 -8
  20. package/dist/product-docs/references/index.md +18 -16
  21. package/dist/product-docs/references/linear.md +2 -2
  22. package/dist/product-docs/references/managed-environment-files.md +1 -1
  23. package/dist/product-docs/references/member-managed-files.md +4 -4
  24. package/dist/product-docs/references/mobile.md +23 -18
  25. package/dist/product-docs/references/onbox-agent-tools.md +25 -26
  26. package/dist/product-docs/references/ports-terminal-and-runtime.md +27 -28
  27. package/dist/product-docs/references/project-setup.md +36 -16
  28. package/dist/product-docs/references/security-and-data.md +10 -10
  29. package/dist/product-docs/references/slack.md +3 -3
  30. package/dist/product-docs/references/tailscale.md +2 -2
  31. package/dist/product-docs/references/team-template.md +22 -22
  32. package/dist/product-docs/references/template-box-environment.md +7 -3
  33. package/dist/product-docs/references/threads-and-agents.md +79 -31
  34. package/dist/product-docs/references/troubleshooting.md +24 -25
  35. 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 ordinary project, or the current saved
176
- Team Template version for a member project. If several assignments start at
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 ordinary project against its project folder, a
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 ordinary project
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 Member project continues following the Team Template's current file
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 Member
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
- member project or return it after that member confirms their account. This is
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
- - archived chats, which can be expanded when you need older work;
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 runtime, or choose an action such as Send, Terminal,
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 ordinary project,
89
- **New thread on Template box**. A Team Template member project has no template
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 member-project devbox starts from the Team Template's
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 ordinary project, from an open Template-box thread, use **New snapshot** in the header overflow
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 ordinary project, use **Restore thread**, then choose **To new
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 Team Template member project offers only
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 runtime and connect only when you Send. Merely opening any
134
- of these sessions does not wake a runtime. On a new-thread screen, you can
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
- runtime is asleep or disconnected, and updates after boxes.dev receives a
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 runtime wakes or the agent accepts it.
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 runtime.
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 runtime when terminal
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 runtime.
365
+ preparing terminal size, connecting, reconnecting, and waking the box.
363
366
 
364
- If the shell exits, use **Reopen shell**. If the route or runtime target is no
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, runtime process inspection, and
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 Team Template member project has no personal Template box. Native-only
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
- member project). `effectiveGitAction` includes the account's default
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, member-project policy, cleanup,
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 ordinary project created from it. Request only the minimum
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 ordinary 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 ordinary project's environment file. |
353
- | `agent_settings` | `agent` (`claude` or `codex`), `content`, `expectedRevision`, as described below. In a member project, this saves the member's own settings. |
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 member projects, ask
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. Ordinary project drafts also
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 Member project whose Team Template locks agent permissions, **Always
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 ordinary project uses its latest eligible
1183
- Template-box snapshot and returns `snapshot_required` when none exists. A Team
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 ordinary project's Template
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
- an ordinary Template box**. To create a new definition from the current
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 ordinary project's Template box. Use
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. Ordinary project setup completion, project lifecycle commands,
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 ordinary project.
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
- Member projects follow these requirements, and a missing file will block their
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 member project receives. `--member` asks each member for their
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 member
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 ordinary project's Template box to create
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 member project creation is enabled,
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 member project creation becomes active only after
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 an ordinary Template box
2410
+ ### Work on a Team Template from a project's Template box
2412
2411
 
2413
- This section applies to an agent on an ordinary project's Template box with 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, And Runtime
1
+ # Ports, Terminal, and box controls
2
2
 
3
- The Ports menu, Terminal, Files, and Git follow the selected runtime. If you
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
- ## Runtime Status
9
+ ## Box status
10
10
 
11
- The runtime status pill in the desktop titlebar shows whether the selected
12
- runtime is running, sleeping, waking, connecting, snapshotting, upgrading, or at
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 runtime is running, open the status menu to sleep it. The same menu can
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 runtime
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 runtime is sleeping, use Wake from the status pill, Terminal, Files,
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 Runtime
75
+ ## Selected box
76
76
 
77
- Most runtime tools route to the selected thread:
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 runtime yet: runtime tools
82
- may ask you to wait, select a connected thread, or wake the runtime.
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 runtime.
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 runtime is sleeping, use Wake before terminal sessions load.
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 machine and paste its file path. Claude Code
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 runtime path. Ctrl+C
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 ordinary project, or only assigned devboxes in a Team
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 runtime reselection. Use the quiet inline **Unpin** action to return to the
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 runtime and no detected ports, the menu header simply counts
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 runtime, waiting for the first port snapshot, reconnecting, or
332
+ selected box, waiting for the first port snapshot, reconnecting, or
334
333
  unavailable.
335
334
 
336
- ## Runtime Usage And Activity
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 runtime, with command, CPU, memory, PID, and owner labels when
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 runtime is running. Reset kills shells, agent sessions, background
363
- commands, and user services, while preserving files and keeping the runtime running.
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 ordinary
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 runtime has no reset target. boxes.dev confirms before resetting
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 machine sleeping, a warning banner
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 ordinary project with one Template box. The Template box is the
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
- **Member projects**, which have no personal Template box; see
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, ordinary project actions become available while the setup thread
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 regardless of the Template box's current checkout. Keep the
333
- generated block intact when adding application setup commands after it. Omit
334
- it only when the user deliberately wants the Template box's saved checkout;
335
- without it, an explicit thread branch choice is needed to prepare remote code.
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 branch never blocks setup. After setup, clearing the startup
338
- script does not remove saved branch defaults.
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 a new terminal or agent session after connecting or changing
532
- the role. See `aws.md` for profile precedence, central refresh, removal, and
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 ordinary project and 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. It installs dependencies, runs setup commands, and validates important
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 ordinary project instead, with the same manual
1091
- environment setup afterwards. Each ordinary project made through
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
- **Member projects** path is the exception: it creates an independent project
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,