@boxes-dev/dvb-runtime 1.0.1012 → 1.0.1015

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 (31) hide show
  1. package/dist/agent-init-guides/env-files.md +29 -3
  2. package/dist/agent-init-guides/flow.md +14 -1
  3. package/dist/agent-init-guides/manifest.md +4 -0
  4. package/dist/bin/dvb.mjs +2046 -1961
  5. package/dist/bin/dvbd.mjs +8 -8
  6. package/dist/product-docs/SKILL.md +4 -0
  7. package/dist/product-docs/references/agent-tools.md +3 -3
  8. package/dist/product-docs/references/automations.md +10 -6
  9. package/dist/product-docs/references/aws.md +4 -3
  10. package/dist/product-docs/references/billing-and-limits.md +6 -4
  11. package/dist/product-docs/references/core-concepts.md +3 -3
  12. package/dist/product-docs/references/desktop-workbench.md +17 -4
  13. package/dist/product-docs/references/environment-setup-validation.md +44 -0
  14. package/dist/product-docs/references/files-git-and-review.md +46 -11
  15. package/dist/product-docs/references/fork-workflows.md +21 -9
  16. package/dist/product-docs/references/glossary.md +5 -2
  17. package/dist/product-docs/references/index.md +9 -3
  18. package/dist/product-docs/references/linear.md +10 -7
  19. package/dist/product-docs/references/member-managed-files.md +5 -2
  20. package/dist/product-docs/references/mobile.md +9 -4
  21. package/dist/product-docs/references/onbox-agent-tools.md +102 -40
  22. package/dist/product-docs/references/ports-terminal-and-runtime.md +24 -9
  23. package/dist/product-docs/references/project-setup.md +8 -0
  24. package/dist/product-docs/references/security-and-data.md +43 -26
  25. package/dist/product-docs/references/slack.md +45 -15
  26. package/dist/product-docs/references/tailscale.md +3 -0
  27. package/dist/product-docs/references/team-template.md +30 -41
  28. package/dist/product-docs/references/template-box-environment.md +5 -0
  29. package/dist/product-docs/references/threads-and-agents.md +38 -15
  30. package/dist/product-docs/references/troubleshooting.md +35 -26
  31. package/package.json +2 -2
package/dist/bin/dvbd.mjs CHANGED
@@ -1,6 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
 
3
- !function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="868e60b5-d120-5cf2-844e-1db0a8190bfe")}catch(e){}}();
3
+ !function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="728f53c2-e047-5434-aec5-20079166b413")}catch(e){}}();
4
4
  import { createRequire as __dvbCreateRequire } from "node:module";
5
5
  import { dirname as __dvbDirname } from "node:path";
6
6
  import { fileURLToPath as __dvbFileURLToPath } from "node:url";
@@ -96328,8 +96328,8 @@ var init_otel = __esm({
96328
96328
  return trimmed && trimmed.length > 0 ? trimmed : void 0;
96329
96329
  };
96330
96330
  readBuildMetadata = () => {
96331
- const rawPackageVersion = "1.0.1012";
96332
- const rawGitSha = "184a335b89e66a5c47fdc4b334d88b2aff043dbb";
96331
+ const rawPackageVersion = "1.0.1015";
96332
+ const rawGitSha = "f7d51775dfc70f77c6962b079d2f50346a1afa6a";
96333
96333
  const packageVersion = typeof rawPackageVersion === "string" ? rawPackageVersion : void 0;
96334
96334
  const gitSha = typeof rawGitSha === "string" ? rawGitSha : void 0;
96335
96335
  return { packageVersion, gitSha };
@@ -128624,9 +128624,9 @@ var init_sentry = __esm({
128624
128624
  uncaughtExceptionMonitorInstalled = false;
128625
128625
  currentDevboxSentryUser = null;
128626
128626
  readBuildMetadata2 = () => {
128627
- const rawPackageVersion = "1.0.1012";
128628
- const rawGitSha = "184a335b89e66a5c47fdc4b334d88b2aff043dbb";
128629
- const rawSentryRelease = "boxes-dev-dvb@1.0.1012+184a335b89e66a5c47fdc4b334d88b2aff043dbb";
128627
+ const rawPackageVersion = "1.0.1015";
128628
+ const rawGitSha = "f7d51775dfc70f77c6962b079d2f50346a1afa6a";
128629
+ const rawSentryRelease = "boxes-dev-dvb@1.0.1015+f7d51775dfc70f77c6962b079d2f50346a1afa6a";
128630
128630
  const packageVersion = typeof rawPackageVersion === "string" ? rawPackageVersion : void 0;
128631
128631
  const gitSha = typeof rawGitSha === "string" ? rawGitSha : void 0;
128632
128632
  const sentryRelease = typeof rawSentryRelease === "string" ? rawSentryRelease : void 0;
@@ -130826,7 +130826,7 @@ var init_packageVersion = __esm({
130826
130826
  return path8.join(process.cwd(), "dvb");
130827
130827
  };
130828
130828
  readEmbeddedPackageVersion = () => {
130829
- const raw = "1.0.1012";
130829
+ const raw = "1.0.1015";
130830
130830
  return trimVersion(raw);
130831
130831
  };
130832
130832
  readNearestPackageMetadata = (basePath) => {
@@ -144021,4 +144021,4 @@ long/umd/index.js:
144021
144021
  *)
144022
144022
  */
144023
144023
 
144024
- //# debugId=868e60b5-d120-5cf2-844e-1db0a8190bfe
144024
+ //# debugId=728f53c2-e047-5434-aec5-20079166b413
@@ -8,6 +8,10 @@ description: Product documentation for boxes.dev, the platform running this mach
8
8
  Use this skill when the user asks how boxes.dev works or how to use a boxes.dev
9
9
  feature.
10
10
 
11
+ For human-readable walkthroughs, point signed-in users to
12
+ `https://boxes.dev/help`. The help center covers these same product topics in
13
+ task-oriented articles, with search and screenshots.
14
+
11
15
  For a local coding agent using `dvb` to discover or manage projects,
12
16
  devboxes, threads, or one-off commands, read `references/agent-tools.md`
13
17
  directly and do not read the index first. Treat that focused reference as the
@@ -196,7 +196,7 @@ and mobile apps. A Team Template member project accepts `new-devbox`
196
196
  and exact existing devboxes but rejects `template` because it has no personal
197
197
  Template box.
198
198
  Use exactly one of `--prompt`, `--prompt-file`, or `--stdin`. Thread start
199
- supports Codex and Claude, not Claude Code.
199
+ supports current Codex and Claude threads, not the retired `claude_code` type.
200
200
 
201
201
  The result contains a durable `operationId` and stable `clientThreadId`. Retry
202
202
  the same logical start with the same idempotency key and identical arguments.
@@ -211,8 +211,8 @@ dvb threads read <client-thread-id> --json
211
211
  `turnId`, role, bounded text state, and text. It excludes reasoning, tool
212
212
  activity, and storage metadata; it never wakes the devbox or marks the thread
213
213
  viewed. The default is 20 recent turns; follow the returned opaque cursor for
214
- earlier pages. Codex and brokered Claude transcripts are supported. Claude
215
- Code returns a typed `unsupported_agent` transcript status.
214
+ earlier pages. Current Codex and Claude transcripts are supported. Threads of
215
+ the retired `claude_code` type return a typed `unsupported_agent` transcript status.
216
216
 
217
217
  Send a follow-up only when the canonical thread is idle:
218
218
 
@@ -45,10 +45,13 @@ appear** to **In the main thread list** when you want runs alongside normal
45
45
  devbox threads instead. Default Slack and Linear integration automations are
46
46
  fixed to the main thread list.
47
47
 
48
- Draft automations are not live. After an automation is created, you can run it
49
- manually, pause it, activate it, duplicate it, or delete it when it has no
50
- recorded runs. You can discard a draft from its overflow menu in the
51
- Automations section.
48
+ Draft automations are not live. **Create** saves the automation in a paused
49
+ state. Test it with **Run now**, then choose **Activate** to enable normal
50
+ triggers. Default Slack and Linear integration automations have no Run now
51
+ button; test them through a Slack mention or Linear assignment after activation.
52
+ You can pause or duplicate a created automation, and delete it when it has no
53
+ recorded runs. You can discard a draft from its overflow menu in the Automations
54
+ section.
52
55
 
53
56
  ## Editing Automations
54
57
 
@@ -147,8 +150,9 @@ normalized request with the same key returns the original run; reusing the key
147
150
  for different input returns a conflict.
148
151
 
149
152
  An accepted request returns `202`, the run id, a status URL, and the effective
150
- thread title and agent controls without echoing the prompt. The status resource
151
- reports launch progress. `thread_ready` means the child thread exists and can be
153
+ thread title and agent controls without echoing the prompt. GET requests to the
154
+ status URL require the same Bearer secret and report launch progress.
155
+ `thread_ready` means the child thread exists and can be
152
156
  opened; it does not mean the first agent turn has finished. A request may be
153
157
  rejected if the automation is still a draft, paused, errored, or cannot create a
154
158
  devbox because the awake devbox limit is reached. Independent requests can start
@@ -46,8 +46,8 @@ and return to boxes.dev. It is safe to reopen the app while a code-based
46
46
  sign-in is waiting.
47
47
 
48
48
  After sign-in, deliberately choose one of the AWS accounts already assigned to
49
- your identity, then choose one of its permission sets. boxes.dev does not guess
50
- either value. That choice becomes the default `boxes-dev` profile for the
49
+ your identity, then choose one of its permission sets and **Use this access**.
50
+ boxes.dev does not guess either value. That choice becomes the default `boxes-dev` profile for the
51
51
  current project. Another project can reuse the same central sign-in and choose
52
52
  different assigned access without another browser sign-in.
53
53
 
@@ -166,7 +166,8 @@ The **Managed profiles** section shows the project's centrally managed access:
166
166
  - `boxes-dev` is the required default. Use **Edit** to change its account or
167
167
  permission set.
168
168
  - Use **Add profile** to create another lowercase `boxes-*` profile, up to 10
169
- total profiles per project. The profile name stays fixed after creation so
169
+ total profiles per project. Choose its account and permission set, then
170
+ confirm with **Add profile**. The profile name stays fixed after creation so
170
171
  scripts do not silently change identity.
171
172
  - Use a named profile's menu to edit its access or remove only that profile.
172
173
  Removing the default means removing AWS from the project.
@@ -21,6 +21,8 @@ Current self-serve plans are:
21
21
  $0.60 per extra box-hour.
22
22
 
23
23
  Team and enterprise arrangements may differ from these self-serve limits.
24
+ Included box-hours, project limits, and awake-devbox limits apply per user;
25
+ prepaid overage credits are shared through the team's billing account.
24
26
 
25
27
  ## Box-Hours
26
28
 
@@ -129,9 +131,9 @@ Self-serve plans also limit projects:
129
131
  - Starter: up to 5 projects.
130
132
  - Pro: up to 10 projects.
131
133
 
132
- If a team reaches its project limit, setting up another project is blocked. The
134
+ If a user reaches their project limit, setting up another project is blocked. The
133
135
  user should delete a project, upgrade if available, or contact
134
- help@boxes.dev for a higher-limit use case.
136
+ hi@boxes.dev for a higher-limit use case.
135
137
 
136
138
  ## Billing Surfaces
137
139
 
@@ -168,8 +170,8 @@ Common reasons:
168
170
  - The user does not have a paid seat.
169
171
  - Included usage is exhausted and no usable prepaid credits remain.
170
172
  - The team subscription is past due or unpaid.
171
- - The team reached the awake devbox limit.
172
- - The team reached the project limit.
173
+ - The user reached their awake devbox limit.
174
+ - The user reached their project limit.
173
175
 
174
176
  The usual next step is either to sleep an awake devbox, contact a team admin, or
175
177
  have a team admin manage billing.
@@ -76,9 +76,9 @@ Template box, they operate on the Template box.
76
76
  ## Snapshot
77
77
 
78
78
  A snapshot is a saved state of an ordinary project's Template box that future
79
- devboxes can start from. A snapshot includes the useful machine state needed to
80
- make a new devbox come up like the Template box did at snapshot time, including
81
- filesystem state and running development state when supported. Team Template
79
+ devboxes can start from. A snapshot preserves the saved filesystem and local
80
+ development data. New devboxes start their own processes; they do not continue
81
+ copied agent or user processes from the Template box. Team Template
82
82
  member projects use the Team Template's current saved version instead; team
83
83
  admins update it from the Team Template editor.
84
84
 
@@ -139,7 +139,8 @@ macOS, **File > New Project...** does the same thing.
139
139
  your projects with when each was last used and whether its setup is still in
140
140
  progress. From there, **Open** switches the workbench to that project and
141
141
  **Delete** removes it after you type its name to confirm. Deleting a project
142
- also removes its files from this computer.
142
+ also removes boxes.dev's local setup records for that project. It does not
143
+ remove the original project folder from this computer.
143
144
 
144
145
  When team access is enabled, **Teammates' projects** opens another team
145
146
  member's project in the read-only Team workbench. Team admins also see **Team
@@ -184,9 +185,10 @@ runtime has no live metrics.
184
185
  Expand **Settings** near the bottom of the project thread list and open
185
186
  **Project settings** for settings that belong to the project rather than to a
186
187
  particular machine. This page contains **Project storage**, **Git**, **Agent
187
- permissions for new devboxes**, and **Devbox lifecycle**, including the
188
+ permissions for this project**, and **Devbox lifecycle**, including the
188
189
  project's preferred Git action, commit thread-link behavior, startup script,
189
- shared agent guidance, inactivity behavior, and other new-devbox defaults.
190
+ shared agent guidance, automatic waking of sleeping machines, and other
191
+ new-devbox defaults. The automatic idle-sleep timeout is not user-configurable.
190
192
  Opening it does not select or wake a machine.
191
193
 
192
194
  The same Settings section opens **Desktop app settings...** and **Configure
@@ -214,7 +216,7 @@ devbox. See `fork-workflows.md` for that workflow.
214
216
 
215
217
  ## Team Template Workbench
216
218
 
217
- An enabled team can have several named Team Templates: shared starting
219
+ A team can have several named Team Templates: shared starting
218
220
  environments that team admins prepare separately from any member's projects.
219
221
  Team admins can open **Team Templates** from the desktop project selector or
220
222
  Team Settings, then select the exact template they want to inspect or edit. To
@@ -246,6 +248,12 @@ threads, new-devbox placeholders, and automation views all use the same detail
246
248
  area. A Codex or Claude thread can switch between GUI and the CLI from its
247
249
  header without becoming a different thread.
248
250
 
251
+ Mermaid code blocks in Codex and Claude replies appear as diagrams. Use the
252
+ diagram's controls to copy its source, expand it for zooming, or download an
253
+ SVG. A diagram loads after the agent finishes its code block; if it cannot be
254
+ rendered, the source remains visible. Mobile chats also show diagrams with
255
+ source copy and an expanded preview.
256
+
249
257
  Claude's active and recently finished subagents appear above the composer.
250
258
  Open an agent from that list or its launch card to read its transcript, and use
251
259
  **Back** or **Escape** to return to the parent thread and focus its composer.
@@ -419,6 +427,11 @@ Invalid policy never authorizes a new path.
419
427
 
420
428
  ## Updates And Feedback
421
429
 
430
+ Open Help in the desktop sidebar, then **Help center**, for the logged-in
431
+ human guides at `https://boxes.dev/help`. It opens in the external browser and
432
+ keeps the working conversation in the desktop app. The existing quick fixes
433
+ and Send feedback action remain in the Help dialog.
434
+
422
435
  When a desktop update has downloaded, the titlebar can show a restart-to-update
423
436
  action and release notes link. The app menu also includes update actions.
424
437
 
@@ -0,0 +1,44 @@
1
+ # Development Environment Validation
2
+
3
+ Use this reference for the environment setup or repair requested in the current
4
+ thread. Follow that flow's setup plan, repository documentation, credential
5
+ rules, and completion instructions. For Team Template work, first select the
6
+ direct or remote editing workflow in
7
+ [On-box agent tools](onbox-agent-tools.md#team-template-commands).
8
+
9
+ ## Verify Persistent Configuration
10
+
11
+ Check the required tool versions and dependency/build steps. An installed
12
+ executable may not be selected by the agent's commands, and dependency
13
+ installation may not build the local packages those commands need.
14
+
15
+ After configuring tool activation, verify versions and a representative
16
+ project command from a fresh agent command without manually exporting PATH,
17
+ sourcing an rc file, or adding other temporary setup-only overrides. Check a
18
+ fresh terminal too when terminal use is in scope: interactive terminals and
19
+ agent commands may initialize differently. Keep environment selection that is
20
+ part of the project's normal command; verify that the next user can run that
21
+ command without repeating an unrecorded workaround.
22
+
23
+ For remote Team Template editing, perform these checks on the target editing
24
+ box. Success on the source project's Template box does not verify the target.
25
+
26
+ ## Verify Required Service Startup
27
+
28
+ Check how the required services start through the documented development
29
+ command or configured startup behavior. A manually started database on the
30
+ Team Template editing machine does not establish readiness in a new project;
31
+ the Team Template save flow cleans and cold-boots that machine before capture.
32
+
33
+ A script file on disk is not a registered startup setting. Maintenance and
34
+ destination startup serve different purposes. Read back settings you apply,
35
+ and report any remaining configuration step. Use the applicable project mode's
36
+ lifecycle instructions; see
37
+ [Team Templates](team-template.md#when-a-new-devbox-is-created).
38
+
39
+ ## Report Readiness For The Requested Work
40
+
41
+ Report what passed, failed, or remains unverified, with the commands and any
42
+ required user actions. A passing test subset does not establish that full
43
+ typechecking, builds, or local development works. Record memory limitations
44
+ and whether startup on a newly created machine was actually exercised.
@@ -218,6 +218,20 @@ Integrations → GitHub or Account settings. Push or Publish is shown only when
218
218
  Git/Review can identify a supported destination, or disabled with a reason when
219
219
  the repository is relevant but currently blocked.
220
220
 
221
+ You can connect the same GitHub account to multiple boxes.dev accounts, such
222
+ as your personal and work accounts. Connect GitHub separately from each
223
+ boxes.dev account; their connection settings and credentials remain separate.
224
+ To switch to a different GitHub account within one boxes.dev account,
225
+ disconnect the current GitHub account first.
226
+
227
+ If you revoke the boxes.dev App's authorization on GitHub, reconnect it in
228
+ each affected boxes.dev account. Removing or suspending an App installation
229
+ affects that installation's repositories, while access to other installations
230
+ remains available. Restore repository access from **Manage repos** when needed.
231
+ boxes.dev refreshes expiring credentials automatically before they expire.
232
+ If the refresh credential has also expired, reconnect GitHub. Temporary GitHub
233
+ outages are retried without treating your authorization as revoked.
234
+
221
235
  For a project created from GitHub with automatic access, fetch, pull, and push
222
236
  use the connected user's credential after boxes.dev verifies that the exact
223
237
  repository was selected for the project and the user still has write access.
@@ -273,9 +287,11 @@ without rerunning the repository work.
273
287
 
274
288
  **Add from GitHub** does not convert a project whose root is itself a Git
275
289
  repository into a multi-repository layout. It also does not appear for an SSH
276
- or non-GitHub project. In those cases, or whenever you prefer to clone
277
- manually, clone a repository into a direct-child folder and open Git/Review on
278
- that runtime.
290
+ or non-GitHub project. To clone manually, including in an SSH or non-GitHub
291
+ project, use a direct-child folder in a supported, non-overlapping
292
+ multi-repository layout and open Git/Review on that runtime. Cloning inside a
293
+ project whose root is itself a Git repository creates an overlapping layout
294
+ that **Review new repositories** will not add.
279
295
 
280
296
  When unindexed direct children are present, **Review new repositories** lets
281
297
  you select them independently, up to 20 in one review operation. A recognized
@@ -302,10 +318,17 @@ but cannot add another repository at the project root.
302
318
 
303
319
  ## Git Author Identity
304
320
 
305
- Account settings has one **Git identity** name and email that boxes.dev can
306
- carry to the member's ordinary Template boxes and all assigned devboxes. Saving it is explicit:
307
- boxes.dev does not infer or save commit authorship from the account profile,
308
- login email, or connected GitHub account.
321
+ By default, boxes.dev uses your connected GitHub account's name and private
322
+ no-reply email for Git commits on your ordinary Template boxes and devboxes.
323
+ If your GitHub profile has no name, it uses your GitHub username. This default
324
+ follows your connected GitHub account without saving an account override.
325
+
326
+ To choose a different name and email, edit **Git identity** in Account settings
327
+ and save, or edit the fields during Team Template setup. Only an explicit edit
328
+ will save an override; continuing setup with the displayed default will keep
329
+ using GitHub. A saved override will stay the same when you reconnect GitHub or
330
+ change your login profile. Without a connected GitHub account, enter a name
331
+ and email or use your project's Git configuration.
309
332
 
310
333
  The Account value is a fallback. A global identity imported during project
311
334
  setup or later written to `~/.gitconfig` wins across that machine, and a
@@ -318,6 +341,7 @@ Edits reach active machines automatically. A sleeping machine stays asleep and
318
341
  uses the latest value after its next normal wake. **Stop supplying identity**
319
342
  removes only the boxes.dev fallback; it does not erase imported global,
320
343
  repository-local, signing, credential, alias, hook, or other Git configuration.
344
+ An explicitly cleared identity will stay off until you configure it again.
321
345
 
322
346
  ## GitHub CLI In Terminals And Agents
323
347
 
@@ -358,8 +382,9 @@ boxes.dev, `gh` stays in ordinary user-managed mode and uses the CLI's existing
358
382
  local configuration and environment. When the setting is on, boxes.dev manages
359
383
  the CLI identity after confirming access to every known repository in the
360
384
  current project; do not run `gh auth login`, `gh auth logout`, or another
361
- `gh auth` command that changes that managed account. A project with missing App
362
- access stays in ordinary machine-local mode even while the account-wide choice
385
+ `gh auth` command that changes that managed account. If neither the App nor
386
+ authorized personal access can reach every known repository in the project,
387
+ `gh` stays in ordinary machine-local mode even while the account-wide choice
363
388
  is on. Aliases and extensions run as ordinary code owned by the same machine
364
389
  user and can use the effective managed or local identity.
365
390
 
@@ -458,10 +483,20 @@ the agent will stop and explain why instead. The automatic turn will not merge
458
483
  or force-push the pull request, delete its branch, rerun workflows, or reply to
459
484
  or resolve review comments.
460
485
 
486
+ When the pull request merges, boxes.dev will also send that agent a final
487
+ notice so it can account for the merge in future work. This may wake the
488
+ machine and will wait behind any active agent turn. The notice will not ask the
489
+ agent to edit files or change branches. Paused follow-ups will still receive
490
+ this notice, provided the original agent thread remains available; archived or
491
+ deleted threads will not receive it. Turning follow-ups off will also turn off
492
+ the merge notice. Closing a pull request without merging will end follow-ups
493
+ silently.
494
+
461
495
  Bot feedback includes only reviews and comments that GitHub identifies as
462
496
  bot-authored. Comments from people will not start an automatic follow-up. Only
463
- one agent can handle follow-ups for a pull request at a time; turning them on
464
- from another agent will show the current agent and ask you to move the job.
497
+ one agent per boxes.dev account can handle follow-ups for a pull request at a
498
+ time; turning them on from another agent will show the current agent and ask
499
+ you to move the job.
465
500
 
466
501
  Use **Edit follow-ups** to change the selected events or turn the feature off.
467
502
  After three automatic follow-ups without a healthy pull request, boxes.dev will
@@ -44,9 +44,9 @@ The field saves shell commands directly as a project setting; boxes.dev does
44
44
  not create a script file for it. The startup timeout defaults to 60 seconds and
45
45
  can be set from 1 to 120 seconds.
46
46
 
47
- When a project has a devbox startup script, boxes.dev may reserve a disposable
48
- devbox and run that script after the user starts typing, before the first prompt
49
- is sent. For Codex and Claude Code, boxes.dev may also prepare the conversation
47
+ When an ordinary project has a devbox startup script, boxes.dev may reserve a
48
+ disposable devbox and run that script after the user starts typing, before the
49
+ first prompt is sent. For Codex and Claude Code, boxes.dev may also prepare the conversation
50
50
  on that devbox after the script finishes, so a matching Send can reuse both
51
51
  without rerunning setup. Images and files added to the composer can upload while
52
52
  the user continues composing; when sent, boxes.dev attaches them to the prepared
@@ -56,6 +56,14 @@ applies the current settings to a different devbox. An abandoned draft's devbox
56
56
  expires, but external side effects from a script cannot be undone, so startup
57
57
  scripts should be safe to run speculatively.
58
58
 
59
+ Team Template member projects may prepare warm machines in advance, but their
60
+ startup scripts wait until Send claims a devbox for the member. After the
61
+ member's files and credentials are ready, the team startup script runs before
62
+ the member's startup script and the first agent turn. Both startup scripts run
63
+ in the sole repository when the template tracks exactly one, or in the project
64
+ root otherwise. Teardown still runs in the project root. Team startup failures
65
+ show warnings and do not block the member script, agent turn, or other members.
66
+
59
67
  Before running your project's script, boxes.dev prepares its configured managed
60
68
  environment files, project storage, Git identity and credentials, AWS
61
69
  credentials, and static egress. Tailscale connects after Send, so a script that
@@ -110,9 +118,12 @@ may include an additive `warnings` array. An
110
118
  its configured project guidance may be incomplete. Older responses with no
111
119
  `warnings` field have no operation warning.
112
120
 
113
- Use `dvb exec` for bounded one-off commands on this environment. Starting or
114
- sending a new agent thread noninteractively is not part of this workflow yet.
115
- Use the existing desktop/mobile thread flow or interactive `dvb agents` for
121
+ Use `dvb exec` for bounded one-off commands on this environment. To start an
122
+ agent conversation noninteractively, use `dvb threads start` with an existing
123
+ devbox target, a prompt file, and an idempotency key. The command also supports
124
+ creating a new devbox or starting on the Template box. See
125
+ [Agent tools](agent-tools.md) for the complete command and target options.
126
+ Desktop, mobile, and interactive `dvb agents` are also available for
116
127
  conversation work.
117
128
 
118
129
  ## Starting Snapshots For New Devboxes
@@ -174,7 +185,7 @@ attachments will stay in the original chat, and the new chat will start with
174
185
  an empty composer.
175
186
 
176
187
  **New devbox** takes a fresh snapshot of the selected thread's exact Template
177
- box or devbox. It preserves that box's current files and runtime state, then
188
+ box or devbox. It captures that box's current files and development data, then
178
189
  restores the snapshot into an independent devbox before creating the child
179
190
  conversation there. Managed Codex and Claude work must be idle for the copy;
180
191
  boxes.dev retries when an active turn or queued agent work is still settling.
@@ -254,8 +265,9 @@ Typical completion options:
254
265
  branch-preparation path fetches but does not pull, merge, or rebase. Directly
255
266
  pushing a branch remains a separate, explicitly labeled option. For an
256
267
  existing upstream, its dialog pulls first using the repository's Git
257
- configuration or a one-run Rebase or Merge choice, then requires a separate
258
- Push confirmation. Pull conflicts stop before Push and remain in the devbox
268
+ configuration or a one-run Rebase or Merge choice. **Pull & push** confirms
269
+ both steps; push runs only after a successful pull. Pull conflicts stop
270
+ before push and remain in the devbox
259
271
  for the user or agent to resolve or abort in Terminal. A no-upstream Publish
260
272
  still fetches and checks the destination without pulling.
261
273
  - Download generated artifacts from the file view.
@@ -109,8 +109,11 @@ usually be woken later.
109
109
 
110
110
  ## Snapshot
111
111
 
112
- A saved state of the Template box used to create future devboxes. Take a new
113
- snapshot after the Template box is in a state future devboxes should inherit.
112
+ A saved machine state used to create future devboxes. Ordinary projects use
113
+ Template box snapshots; take a new snapshot after the Template box is in a
114
+ state future devboxes should inherit. When **Continue in new chat** creates a
115
+ new devbox, it takes a fresh snapshot of the selected thread's exact Template
116
+ box or devbox.
114
117
 
115
118
  ## Team
116
119
 
@@ -43,6 +43,9 @@ Use this terminology consistently:
43
43
  copied-data boundaries.
44
44
  - `template-box-environment.md`: the Template box machine environment, baseline
45
45
  development tools, setup constraints, local-run verification, and snapshots.
46
+ - `environment-setup-validation.md`: shared validation guidance for ordinary
47
+ project and Team Template environment setup, including fresh agent commands,
48
+ persistent configuration, service startup, and readiness reporting.
46
49
  - `managed-environment-files.md`: centrally managed dotenv files, initial
47
50
  import, managed-prefix ownership, Team Template Team/member values,
48
51
  reveal/export, outages, snapshots, security boundaries, and limits.
@@ -105,9 +108,12 @@ Use this terminology consistently:
105
108
 
106
109
  ## Context Guidance
107
110
 
108
- If the user is in the setup thread, assume they are probably on the Template box
109
- and may be learning boxes.dev for the first time. Prefer setup, Template box,
110
- and new-user guidance.
111
+ For a setup thread, use its task and current box role to choose the guidance.
112
+ Ordinary project setup uses the project's Template box; a Team Template editor
113
+ thread runs directly on its editing machine, while an associated ordinary
114
+ Template box can operate on that machine remotely. Prefer setup and new-user
115
+ guidance for ordinary project onboarding, and Team Template guidance for shared
116
+ environment authoring.
111
117
 
112
118
  If the user is on a devbox thread, assume they are doing task work. Prefer
113
119
  devbox, file transfer, ports, git, testing, and completion guidance.
@@ -2,8 +2,9 @@
2
2
 
3
3
  The Linear integration lets you start your boxes.dev automation by assigning or
4
4
  delegating an issue to the boxes.dev Linear agent. The linked agent thread runs
5
- on a fresh devbox created from your Template box snapshot and reports progress
6
- and final results back to the Linear Agent Session.
5
+ on a fresh devbox created from your Template box snapshot or your Team
6
+ Template's current saved version, and reports progress and final results back
7
+ to the Linear Agent Session.
7
8
 
8
9
  Use `automations.md` for general automation behavior. This doc covers the
9
10
  Linear-specific setup and workflow.
@@ -12,7 +13,8 @@ Linear-specific setup and workflow.
12
13
 
13
14
  You need:
14
15
 
15
- - a boxes.dev team with a Template box snapshot for the repo;
16
+ - a boxes.dev project with a usable Template box snapshot or saved Team Template
17
+ version for the repo;
16
18
  - team admin access in boxes.dev to connect the Linear workspace;
17
19
  - permission in Linear to install the boxes.dev app, or a Linear admin who can
18
20
  approve it;
@@ -104,7 +106,7 @@ The agent sees:
104
106
 
105
107
  Reply in the Linear Agent Session to send a follow-up prompt to the linked
106
108
  boxes.dev thread. If a turn is already running, boxes.dev queues the follow-up
107
- as guidance; otherwise it starts the next turn in the existing thread.
109
+ message; otherwise it starts the next turn in the existing thread.
108
110
 
109
111
  Use Linear's stop control to stop active boxes.dev work. Undelegating the
110
112
  agent, moving the issue to a terminal completed or canceled state, or deleting
@@ -143,9 +145,10 @@ Linear receiver.
143
145
 
144
146
  If assignment does not start, confirm that the connected Linear workspace is the
145
147
  one containing the issue, your Linear identity is linked, your default Linear
146
- automation is active, and the Template box has a usable snapshot. If several
147
- assignments start at once and some do not launch, check awake devbox capacity
148
- and billing.
148
+ automation is active, and the project's saved environment is usable: the
149
+ latest Template box snapshot for an ordinary project, or the current saved
150
+ Team Template version for a member project. If several assignments start at
151
+ once and some do not launch, check awake devbox capacity and billing.
149
152
 
150
153
  If work products do not attach, confirm the agent is running inside a
151
154
  Linear-triggered automation and that the URL is valid.
@@ -64,8 +64,11 @@ Changing instructions alone does not require approval.
64
64
 
65
65
  Members can replace or remove their own saved file. Removing it makes the
66
66
  required item incomplete and blocks future startup until a replacement is
67
- saved. Downloading the centrally saved bytes requires a recent confirmation
68
- with the Google account linked to the current boxes.dev account.
67
+ saved. Each devbox removes its managed destination at the next sync; a sleeping
68
+ devbox does so after it wakes. Removal does not delete extra copies elsewhere
69
+ or revoke credentials a process has already read. Downloading the centrally
70
+ saved bytes requires a recent confirmation with the Google account linked to
71
+ the current boxes.dev account.
69
72
 
70
73
  ## Security Boundaries
71
74
 
@@ -159,8 +159,9 @@ current runtime.
159
159
 
160
160
  ## Devbox Actions
161
161
 
162
- Mobile shows devbox status and lightweight Git-change counts on devbox rows and
163
- devbox pills. From a devbox row or devbox group you can:
162
+ Mobile thread lists show Git-change counts inline and a live devbox status dot
163
+ at the right, matching desktop. Sleeping devboxes show a timestamp in that
164
+ space. From a devbox row or devbox group you can:
164
165
 
165
166
  - start another thread on the same devbox;
166
167
  - pin or unpin the devbox;
@@ -230,10 +231,14 @@ Mobile settings include:
230
231
  - theme, monospace font, and thread text size;
231
232
  - release package details and refresh controls in installed builds;
232
233
  - account deletion.
234
+ - a Help center link that opens `https://boxes.dev/help` in the browser, where
235
+ normal boxes.dev sign-in is required.
233
236
 
234
237
  Someone opening your invite link can sign up with Google in their phone
235
- browser. After signup, they can open the web app to manage their team, or
236
- download the Mac app on their computer to set up a local project.
238
+ browser. After signing up on a phone, they will see that setup happens on
239
+ their Mac, where to find the setup steps in their email, and a link to install
240
+ the mobile app. Signing up on a computer continues straight to first-project
241
+ setup in the web app.
237
242
 
238
243
  Thread text size defaults to **Medium** for transcript and message text on this
239
244
  device. Choose **Compact**, **Medium**, or **Large** in **Settings → Appearance**.