@boxes-dev/dvb-runtime 1.0.1014 → 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 (28) 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/files-git-and-review.md +8 -5
  14. package/dist/product-docs/references/fork-workflows.md +21 -9
  15. package/dist/product-docs/references/glossary.md +5 -2
  16. package/dist/product-docs/references/linear.md +10 -7
  17. package/dist/product-docs/references/member-managed-files.md +5 -2
  18. package/dist/product-docs/references/mobile.md +2 -0
  19. package/dist/product-docs/references/onbox-agent-tools.md +4 -3
  20. package/dist/product-docs/references/ports-terminal-and-runtime.md +15 -5
  21. package/dist/product-docs/references/project-setup.md +8 -0
  22. package/dist/product-docs/references/security-and-data.md +43 -26
  23. package/dist/product-docs/references/slack.md +8 -6
  24. package/dist/product-docs/references/tailscale.md +3 -0
  25. package/dist/product-docs/references/team-template.md +30 -41
  26. package/dist/product-docs/references/threads-and-agents.md +15 -6
  27. package/dist/product-docs/references/troubleshooting.md +30 -23
  28. 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.1014";
96332
- const rawGitSha = "ad97cd572234e687a71892488a6e009a3298c247";
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.1014";
128628
- const rawGitSha = "ad97cd572234e687a71892488a6e009a3298c247";
128629
- const rawSentryRelease = "boxes-dev-dvb@1.0.1014+ad97cd572234e687a71892488a6e009a3298c247";
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.1014";
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
 
@@ -287,9 +287,11 @@ without rerunning the repository work.
287
287
 
288
288
  **Add from GitHub** does not convert a project whose root is itself a Git
289
289
  repository into a multi-repository layout. It also does not appear for an SSH
290
- or non-GitHub project. In those cases, or whenever you prefer to clone
291
- manually, clone a repository into a direct-child folder and open Git/Review on
292
- 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.
293
295
 
294
296
  When unindexed direct children are present, **Review new repositories** lets
295
297
  you select them independently, up to 20 in one review operation. A recognized
@@ -380,8 +382,9 @@ boxes.dev, `gh` stays in ordinary user-managed mode and uses the CLI's existing
380
382
  local configuration and environment. When the setting is on, boxes.dev manages
381
383
  the CLI identity after confirming access to every known repository in the
382
384
  current project; do not run `gh auth login`, `gh auth logout`, or another
383
- `gh auth` command that changes that managed account. A project with missing App
384
- 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
385
388
  is on. Aliases and extensions run as ordinary code owned by the same machine
386
389
  user and can use the effective managed or local identity.
387
390
 
@@ -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
 
@@ -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
 
@@ -231,6 +231,8 @@ Mobile settings include:
231
231
  - theme, monospace font, and thread text size;
232
232
  - release package details and refresh controls in installed builds;
233
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.
234
236
 
235
237
  Someone opening your invite link can sign up with Google in their phone
236
238
  browser. After signing up on a phone, they will see that setup happens on
@@ -97,7 +97,7 @@ cleanup, final snapshot, and closeout request before that finalization finishes;
97
97
  after it accepts the request, send the final user-facing response. Do not use it
98
98
  to dismiss setup early or skip unfinished work.
99
99
 
100
- After the project runs successfully on the Template box, an agent can create the
100
+ After the app runs successfully on the Template box, an agent can create the
101
101
  snapshot used by future devboxes:
102
102
 
103
103
  ```bash
@@ -166,12 +166,13 @@ session. They update that Team Template's shared maintenance script and watches
166
166
  and require the editing session's owner to remain a team admin. Use repository
167
167
  paths from the Team Template's configured GitHub repositories. The JSON result
168
168
  identifies the Team Template by name and ID. Schedule settings remain editable
169
- in **Project defaults → Maintenance** in the desktop app.
169
+ under **Template environment → Maintenance** in the desktop app.
170
170
 
171
171
  These settings are devbox lifecycle and Template maintenance, not boxes.dev
172
172
  Automations. The commands accept no project, box, owner, or repository ID.
173
173
  Devbox lifecycle commands require the current ordinary Template box; configure
174
- Team Template lifecycle defaults in **Project defaults → Devbox lifecycle**.
174
+ Team Template lifecycle defaults under **When a new devbox is created**,
175
+ including its **When a devbox is destroyed** section.
175
176
  If either operation reports
176
177
  disabled access, request only `edit-devbox-lifecycle` or
177
178
  `edit-template-maintenance`, respectively.
@@ -14,8 +14,10 @@ the awake devbox limit.
14
14
 
15
15
  When the runtime 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
- you return to them. When auto-wake is off, passive navigation leaves the runtime
18
- asleep until you explicitly wake it.
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
19
+ asleep. Explicitly sending a message to a Codex or Claude thread will still
20
+ wake its machine through the normal wake flow, even with auto-wake off.
19
21
 
20
22
  When the runtime is sleeping, use Wake from the status pill, Terminal, Files,
21
23
  Git, or Ports. If a devbox is sleeping because the awake devbox limit is full,
@@ -47,6 +49,9 @@ Common terminal actions:
47
49
  - If a detached session is shown, choose Connect to attach to it again.
48
50
  - If the selected runtime is sleeping, use Wake before terminal sessions load.
49
51
 
52
+ Closing a terminal tab ends that terminal session. Closing the desktop app
53
+ preserves open terminal sessions and restores their tabs when you reopen it.
54
+
50
55
  **Desktop app settings > Connection** includes a Terminal Connection choice.
51
56
  Managed is the default attachment transport. Direct (Mosh) negotiates an
52
57
  encrypted UDP path for the lowest latency and repairs that path if connectivity
@@ -133,9 +138,14 @@ globe action to create an HTTPS public link for that exact port. Anyone with
133
138
  the link can use the application without signing in. After you confirm, the
134
139
  dialog shows the new link with a **Copy link** button. Public links do not
135
140
  depend on local forwarding, remain active when you select another devbox or
136
- close the desktop app, and stay in place until you stop sharing them. They do
137
- not wake a sleeping devbox: while the devbox sleeps, visitors see an
138
- unavailable page and the Ports menu marks the link as paused.
141
+ close the desktop app, and remain allocated while the app is stopped or the
142
+ machine is sleeping. Traffic through a public link can keep an awake machine
143
+ active; Project URL traffic does not. Public links do not wake a sleeping
144
+ devbox: while the devbox sleeps, visitors see an unavailable page and the
145
+ Ports menu marks the link as paused.
146
+
147
+ If recovery replaces the machine, boxes.dev will revoke its old public links.
148
+ Share the app again on the recovered machine to get a new URL.
139
149
 
140
150
  The Ports button and menu cover only the selected Template box or devbox. The
141
151
  button shows that machine's active-link count, each detected port row offers
@@ -57,6 +57,14 @@ During Finalize Bundle, Agent threads lets users choose Codex or Claude history
57
57
  to import. The picker defaults to threads from the selected project repos and
58
58
  their Git worktrees, with a show-all option for other local history.
59
59
 
60
+ You can set up a linked Git worktree. Desktop setup will remind you that local
61
+ config such as `.env` files may be missing; choose the checkout where your app
62
+ runs, or continue with the worktree if it has the configuration you need.
63
+ Agent-driven setup can inspect relevant missing configuration and, with your
64
+ approval, select individual files from the main checkout through the manifest's
65
+ `from:` option. It will copy those files to the Template box without changing
66
+ either local checkout. Other checkouts are not included automatically.
67
+
60
68
  If a local repository is shallow, **Finalize Bundle → Repository** will note
61
69
  that older commits won't be included. You can continue with the existing history.
62
70
  To include older commits, open **Get full history**, run `git fetch --unshallow`
@@ -123,37 +123,54 @@ Existing boxes.dev threads remain.
123
123
  Disconnecting GitHub removes the stored GitHub user tokens from boxes.dev and
124
124
  stops pull-request actions until the user reconnects. Repository access granted
125
125
  to the GitHub App is managed separately through **Manage repos**.
126
-
127
- For a GitHub-created project using automatic access, the connected user's
128
- GitHub App user token remains encrypted at rest in boxes.dev. When Git needs
129
- access, the machine requests that credential through a local helper. boxes.dev
130
- first checks that the exact repository was selected during project creation
131
- and that the connected user still has write access. The token can exist in the
132
- boxes.dev service, local service, Git process, and snapshot process memory, but
133
- is not written to the remote URL or a managed credential file.
134
-
135
- Repository selection is an issuance boundary, not a downscope on the token
136
- itself. Code running on the box can request and inspect the credential, whose
137
- access is the intersection of the connected user's repositories and the
138
- repositories and permissions granted to the boxes.dev GitHub App. Current
126
+ Disconnecting the main GitHub connection also removes optional personal access
127
+ and schedules that authorization for revocation with GitHub. **Disconnect
128
+ personal access** performs the personal-access removal and revocation without
129
+ disconnecting the main GitHub connection.
130
+
131
+ When automatic Git access uses the GitHub App, the connected user's App
132
+ credential remains encrypted at rest in boxes.dev. When Git needs access, the
133
+ machine requests that credential through a local helper. boxes.dev first checks
134
+ that the exact repository is associated with the project and that the connected
135
+ user still has write access. The token can exist in the boxes.dev service, local
136
+ service, Git process, and snapshot process memory, but is not written to the
137
+ remote URL or a managed credential file.
138
+
139
+ Repository selection is an issuance boundary, not a downscope on the App token
140
+ itself. Code running on the box can request and inspect the App credential,
141
+ whose access is the intersection of the connected user's repositories and the
142
+ repositories and permissions granted to the boxes.dev GitHub App. Current App
139
143
  connections use GitHub access tokens that last eight hours. boxes.dev refreshes
140
144
  them centrally with GitHub's rotating refresh credential, which remains
141
145
  encrypted in boxes.dev and is not copied to Template boxes or devboxes. A user
142
146
  who connected before this change may see a one-time connection update; their
143
147
  existing access keeps working until they complete it. After that update,
144
148
  boxes.dev waits for outstanding machine cache leases to drain before retiring
145
- the replaced long-lived token. Disconnecting GitHub or removing access stops
146
- future helper issuance after its bounded cache lease, but does not itself
147
- revoke a token already returned to a process. GitHub attributes the Git
148
- operation to the connected user.
149
+ the replaced long-lived token. Disconnecting the main GitHub connection or
150
+ removing App access stops future App helper issuance after its bounded cache
151
+ lease, but does not itself revoke an App token already returned to a process.
152
+ GitHub attributes the Git operation to the connected user.
153
+
154
+ Optional personal access uses the official GitHub CLI authorization the user
155
+ approved. Before boxes.dev issues this credential, the personal authorization
156
+ must match the main GitHub identity and pass the exact repository checks for the
157
+ operation. Those checks do not narrow the credential itself: code running on
158
+ the machine can inspect the full token, whose permissions come from the GitHub
159
+ CLI authorization rather than the GitHub App grants. Personal tokens can be
160
+ expiring or non-expiring. **Disconnect personal access** removes the saved
161
+ authorization and schedules its revocation with GitHub; a copy can remain
162
+ usable until GitHub completes the revocation.
149
163
 
150
164
  Connecting or reconnecting GitHub enables **GitHub CLI in devboxes** by default
151
165
  under **Integrations → GitHub**. This account-wide preference lets `gh`, coding
152
166
  agents, aliases, extensions, and other same-user code request the connected
153
- identity on current and future Template boxes and devboxes. Before issuing it,
154
- boxes.dev confirms that the token can access every known GitHub repository in
155
- the current project. A failed exact repository check returns no managed token
156
- and leaves `gh` in ordinary machine-local mode for that project.
167
+ identity on current and future Template boxes and devboxes. Before issuing a
168
+ managed credential, boxes.dev checks that one authorization can access every
169
+ known GitHub repository in the current project. It prefers App access and can
170
+ use the user's separately authorized personal access when the App does not
171
+ provide the required repository access. If neither authorization passes those
172
+ checks, boxes.dev returns no managed token and leaves `gh` in ordinary
173
+ machine-local mode for that project.
157
174
 
158
175
  boxes.dev does not write the managed credential to native `gh` configuration
159
176
  or a managed credential file, but it can exist in the local service, `gh`,
@@ -202,11 +219,11 @@ interact with local services inside either machine.
202
219
 
203
220
  A Team Template member project has no personal Template box. Team admins author
204
221
  its shared saved files in separate Team Template editing machines, and members
205
- cannot access those machines through their projects. A prepared member devbox
206
- runs the team-authored startup script before boxes.dev installs that member's
207
- agent, GitHub, AWS, Tailscale, MCP, and other personal state. Once assigned, the
208
- devbox belongs only to that member and is never returned to another member's
209
- prepared pool.
222
+ cannot access those machines through their projects. Prepared devboxes belong
223
+ to one member and project. The team-authored startup script runs immediately
224
+ before the member's startup script, with the same prepared member credentials
225
+ and files available to both. Team admins are trusted authors of that code.
226
+ Once assigned to a draft, the devbox never returns to a prepared pool.
210
227
 
211
228
  Anything available inside the selected machine can usually be read or changed by
212
229
  the agent running there. This includes checked-out code, local env files, local