@boxes-dev/dvb-runtime 1.0.1113 → 1.0.1114

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/bin/dvbd.mjs CHANGED
@@ -64830,9 +64830,9 @@ var init_sentry = __esm({
64830
64830
  uncaughtExceptionMonitorInstalled = false;
64831
64831
  currentDevboxSentryUser = null;
64832
64832
  readBuildMetadata = () => {
64833
- const rawPackageVersion = "1.0.1113";
64834
- const rawGitSha = "5c92512300006a85ac7be2bd93af7c9f48fb2799";
64835
- const rawSentryRelease = "boxes-dev-dvb@1.0.1113+5c92512300006a85ac7be2bd93af7c9f48fb2799";
64833
+ const rawPackageVersion = "1.0.1114";
64834
+ const rawGitSha = "8751be962096c774547e09b75191953bdb1ad8e5";
64835
+ const rawSentryRelease = "boxes-dev-dvb@1.0.1114+8751be962096c774547e09b75191953bdb1ad8e5";
64836
64836
  const packageVersion = typeof rawPackageVersion === "string" ? rawPackageVersion : void 0;
64837
64837
  const gitSha = typeof rawGitSha === "string" ? rawGitSha : void 0;
64838
64838
  const sentryRelease = typeof rawSentryRelease === "string" ? rawSentryRelease : void 0;
@@ -67383,7 +67383,7 @@ var init_packageVersion = __esm({
67383
67383
  return path8.join(process.cwd(), "dvb");
67384
67384
  };
67385
67385
  readEmbeddedPackageVersion = () => {
67386
- const raw = "1.0.1113";
67386
+ const raw = "1.0.1114";
67387
67387
  return trimVersion(raw);
67388
67388
  };
67389
67389
  readNearestPackageMetadata = (basePath) => {
@@ -280,16 +280,16 @@ machine you last used. Return to one of your own threads connected to a box or,
280
280
  available, the Template box when you want box controls and Files,
281
281
  Git/Review, Terminal, Browser, or Ports.
282
282
 
283
- The app menu also includes **Project settings**, **Settings...**,
284
- **Configure agents...**, **Sign Out**, update actions, and **Show Workbench**.
285
- Configure agents can save multiple Codex and Claude accounts or API keys and
283
+ The app menu also includes **Project Settings...**, **Settings...**,
284
+ **Configure Agents...**, update actions, and **Sign Out**. Configure agents can
285
+ save multiple Codex and Claude accounts or API keys and
286
286
  choose one active credential for each agent across all devboxes. Codex needs to
287
287
  restart to switch to or from an API key. While Codex is working on a devbox, it
288
288
  keeps the old credential and the desktop shows **Restart Codex** above the reply
289
289
  box. Threads stay connected and running work can still be steered or stopped,
290
290
  but new work needs to wait until the running work finishes or Codex restarts.
291
291
  Restarting stops all running Codex work on that devbox. The File menu also
292
- includes **Delete This Project**.
292
+ includes **Show Workbench** and **Delete This Project**.
293
293
 
294
294
  ## Box status
295
295
 
@@ -427,9 +427,10 @@ interrupt that work.
427
427
  Destroy and archive permanently deletes the devbox filesystem and preserves its
428
428
  eligible threads as archived cold-storage transcripts, including secondary
429
429
  threads that were already archived inside the devbox. The confirmation dialog
430
- warns about uncommitted changes, changed files, and local-only commits when that
431
- information is available. It also names the pull requests whose automatic
432
- follow-ups the devbox's threads handle. Destroying the devbox stops those
430
+ says when an agent is still working, and it warns about uncommitted changes,
431
+ changed files, and local-only commits when that information is available. It
432
+ also names the pull requests whose automatic follow-ups the devbox's threads
433
+ handle. Destroying the devbox stops those
433
434
  follow-ups, and the pull request shows them as paused until a restored or
434
435
  other thread turns them on again. As soon as the destroy starts, the devbox's
435
436
  threads move under its name in **Devboxes** → **Archived threads** on desktop
@@ -116,7 +116,7 @@ Use devbox threads for normal coding tasks.
116
116
 
117
117
  Setup asks you to connect at least one coding agent. You can connect or repair
118
118
  agent auth later from **Settings → Agents** in the desktop account menu.
119
- The macOS **Configure agents...** command opens the same section. The mobile app has the same controls under
119
+ The macOS **Configure Agents...** command opens the same section. The mobile app has the same controls under
120
120
  **Settings → Agent accounts**.
121
121
 
122
122
  Codex can be connected with ChatGPT login or an API key. Claude Code can be
@@ -169,6 +169,64 @@ moving its file, boxes.dev omits the old saved value. The member must review the
169
169
  new destination and choose **Use saved value here**, or enter a replacement.
170
170
  Other managed values continue syncing while that one is unresolved.
171
171
 
172
+ ## Loading Values Into Agents And Terminals
173
+
174
+ Managed files are ordinary files on disk, so an agent, MCP server, or terminal
175
+ command does not see their values unless something reads the file. To make a
176
+ file's values part of the environment itself, check **Load into agent and
177
+ terminal environments** in the file's editor. It is off by default and is
178
+ saved with the file's other changes.
179
+
180
+ While it is on, every box in the project adds the file's values to the
181
+ environment of Codex and Claude threads, the MCP servers those agents start,
182
+ terminals, and startup scripts. MCP settings can then refer to a value by
183
+ name instead of containing it:
184
+
185
+ - Claude Code expands `${NAME}` in `.mcp.json` and `~/.claude.json` server
186
+ settings, including `command`, `args`, `env`, `url`, and `headers`.
187
+ - Codex gives a stdio server only a few default variables plus the ones
188
+ you list, so name them in `env_vars = ["NAME"]` under
189
+ `[mcp_servers.<server>]` in `~/.codex/config.toml`. An HTTP server can use
190
+ `bearer_token_env_var = "NAME"` or `env_http_headers`.
191
+
192
+ A loaded value is a default: a name that the agent, box, or terminal already
193
+ sets keeps its own value. Some variables are never loaded, and the editor marks
194
+ rows whose names won't load:
195
+
196
+ - names that contain lowercase letters;
197
+ - names that start with `ANTHROPIC_`, `CLAUDE_`, `CODEX_`, `BOXES_`, or
198
+ `DEVBOX_`, which control agent sign-in and boxes.dev itself;
199
+ - `AWS_PROFILE`, `AWS_SDK_LOAD_CONFIG`, `GCE_METADATA_HOST`, and
200
+ `GOOGLE_CLOUD_QUOTA_PROJECT`, which the AWS and Google Cloud connections set;
201
+ - values that span several lines.
202
+
203
+ When two loaded files set the same name, the file whose path sorts first
204
+ wins. Loaded values are limited to 256 KiB in total. Files are read in path
205
+ order, and a value that would go past the limit is left out.
206
+
207
+ A box applies a change when it syncs, usually within seconds of a save or of
208
+ the box waking. New terminals, startup scripts, and new Claude threads start
209
+ with the new values. A Codex or Claude agent that is already running restarts
210
+ in the background once it is idle, with its conversations intact, and its MCP
211
+ servers start again with the new values. Codex threads on a box share one
212
+ agent, so a new Codex thread gets the change at that restart. An agent that is
213
+ working, waiting on a question, or holding queued messages or background tasks
214
+ restarts after that work finishes. Open terminals pick up changes at their
215
+ next prompt. A program already running in a terminal, including Claude Code or
216
+ Codex started there, keeps the environment it started with until you restart
217
+ it. Turning the setting off removes the values the same way.
218
+
219
+ In a Team Template, the admin chooses the setting for each file. It covers
220
+ everything at that path in managed projects, including variables members add
221
+ there. A member sees whether a Team Template file loads, and checks the box
222
+ for each file of their own. A normal project created from a Team Template
223
+ copies the setting with the file. `dvb-onbox env list` reports the setting;
224
+ it can be changed only in settings.
225
+
226
+ Loaded values are readable by every process the agent or terminal starts, the
227
+ same as the values in the file itself. Values are kept in a file on the box
228
+ that only the box user can read.
229
+
172
230
  ## Agent Commands
173
231
 
174
232
  Coding agents can list, set, and remove a project's variables with
@@ -1,13 +1,14 @@
1
1
  # Member Files
2
2
 
3
- Use this doc for questions about Team Template file requirements, member-owned
4
- configuration files, safe destinations, replacement, destination approval, or
5
- what happens at startup when a file is missing.
3
+ Use this doc for questions about Team Template file requirements, required and
4
+ optional member files, member-owned configuration files, safe destinations,
5
+ replacement, destination approval, or what happens at startup when a file is
6
+ missing.
6
7
 
7
8
  ## What Member Files Are
8
9
 
9
- A Team Template admin can require every project member to provide their own
10
- file at a fixed destination. This is useful for personal CLI configuration,
10
+ A Team Template admin can ask every project member to provide their own file
11
+ at a fixed destination. This is useful for personal CLI configuration,
11
12
  for example `$HOME/.convex/config.json`, when the tool expects a complete file
12
13
  rather than environment variables.
13
14
 
@@ -22,19 +23,23 @@ in an authorized Team Template editing session. See
22
23
  [Member-file requirements](onbox-agent-tools.md#member-file-requirements) for
23
24
  commands and revision handling.
24
25
 
25
- Every requirement is required. A member selects the local file while creating
26
- the project. The original local filename is used only in that browser view and
27
- is not saved by boxes.dev. Files may contain arbitrary bytes and can be up to
28
- 256 KiB.
29
-
30
- During project creation, files appear with required environment values under
31
- **Needed to create the project**, before the collapsed optional values. **Choose file**
26
+ Each requirement is either required or optional. New requirements are
27
+ required; the admin clears **Required** for a file that only some members
28
+ create, such as an optional local configuration file. A member selects every
29
+ required file while creating the project, and can skip an optional file and
30
+ add it later in **Project settings → Member files**. The original local
31
+ filename is used only in that browser view and is not saved by boxes.dev.
32
+ Files may contain arbitrary bytes and can be up to 256 KiB.
33
+
34
+ During project creation, required files appear with required environment
35
+ values under **Needed to create the project**. Optional files appear after the
36
+ optional values in the collapsed **Show optional** section. **Choose file**
32
37
  opens the native file picker. After reading it, the form shows the local
33
38
  filename and byte size, with **Change** and **Remove** actions.
34
39
  Reading the file does not verify its contents or credentials.
35
40
  Home destinations use `~/` in this form.
36
41
  Oversized or unreadable files show an error at that requirement. The bottom
37
- actions name missing files and link back to them.
42
+ actions name missing required files and link back to them.
38
43
 
39
44
  ## Storage And Delivery
40
45
 
@@ -46,7 +51,9 @@ destinations, while each member's bytes remain scoped to their own project.
46
51
  The devbox writes the exact uploaded bytes. Missing parent directories are
47
52
  created with owner-only access, and the file is written atomically with mode
48
53
  `0600`. A managed file owns its complete destination: local edits are replaced
49
- during the next repair.
54
+ during the next repair. Until a member saves a file, boxes.dev doesn't
55
+ write or remove anything at its destination, so a member who skips an optional
56
+ file can keep a copy they create there themselves.
50
57
 
51
58
  Delivery runs when a devbox is created or wakes, when the saved file changes,
52
59
  and during periodic repair. Deleting or modifying the local copy therefore
@@ -60,9 +67,10 @@ the bytes only after boxes.dev has bound it to the exact member and project.
60
67
  ## Startup And Changes
61
68
 
62
69
  A missing member file, or one awaiting destination approval, does not block a
63
- startup script or a new Codex or Claude session. They start without it, and the
64
- desktop and mobile apps warn the member until they add it; either app's
65
- Project settings can upload it. A file that cannot be written
70
+ startup script or a new Codex or Claude session. They start without it. For a
71
+ required file, the desktop and mobile apps warn the member until they add it;
72
+ either app's Project settings can upload it. A missing optional file shows as
73
+ optional there, without a warning. A file that cannot be written
66
74
  safely does block them until it is fixed, and Project settings explains what
67
75
  the member must do. An agent session that is already running is not stopped
68
76
  when a requirement or file changes.
@@ -73,9 +81,9 @@ saved bytes to the new destination automatically. The member must explicitly
73
81
  choose **Use my saved file at this new destination** or upload a replacement.
74
82
  Changing instructions alone does not require approval.
75
83
 
76
- Members can replace or remove their own saved file. Removing it makes the
77
- required item incomplete, and new devboxes and agent sessions start without the
78
- file until a replacement is saved. Each devbox removes its managed destination
84
+ Members can replace or remove their own saved file. Removing a required file
85
+ makes that requirement incomplete, and new devboxes and agent sessions start
86
+ without the file until a replacement is saved. Each devbox removes its managed destination
79
87
  at the next sync; a sleeping devbox does so after it wakes. Removal does not
80
88
  delete extra copies elsewhere or revoke credentials a process has already read.
81
89
  Downloading the centrally saved bytes requires a recent confirmation with the
@@ -236,10 +236,12 @@ Failed Codex messages and their attachment names also appear in the scrollable
236
236
  transcript. Use **Restore** to return the message and attachments to the composer
237
237
  alongside your current draft, or the dismiss button to remove the failed message.
238
238
 
239
- Codex question forms appear inline with all questions visible together. For a
240
- single choice question, tapping an option sends it immediately. For written
241
- answers or multiple questions, use the form's submit button. Unfinished answers
242
- stay in place when you scroll away and back. If Codex finishes its turn before
239
+ Codex and Claude questions appear inline one at a time, with arrows at the top
240
+ of the form to move between questions. Tapping an option answers the question
241
+ and moves to the next one; for a written answer, type it and tap **Continue**.
242
+ The answers are sent from the last question (Claude first returns to any
243
+ question still unanswered). Unfinished Codex answers stay in place when you
244
+ scroll away and back. If Codex finishes its turn before
243
245
  you send an asynchronous answer, your edited answer returns to the composer.
244
246
 
245
247
  A pending Codex question or form can appear before the phone connects to the
@@ -259,8 +259,9 @@ dvb-onbox template-box snapshot --json
259
259
  Each command wakes a sleeping Template box and runs as its `boxes` user.
260
260
  `exec` runs one noninteractive command for up to 120 seconds with 1 MiB of
261
261
  output per stream. `run` sends a regular script file of up to 3 MiB to `bash`,
262
- runs it for up to 20 minutes, and returns up to 4 MiB per output stream; use it
263
- to write files on the Template box. `snapshot` waits for the new snapshot that
262
+ runs it for up to 8 minutes, and returns up to 4 MiB per output stream; use it
263
+ to write files on the Template box. Split longer work into scripts that each
264
+ finish within that limit. `snapshot` waits for the new snapshot that
264
265
  future devboxes will use. Take one only when the user wants the change to reach
265
266
  future devboxes. Ordinary shell commands still act on the current devbox.
266
267
 
@@ -428,6 +429,17 @@ Project operations use these fields in addition to `section`:
428
429
  | `default_branches` | `defaultBranches`: `relativePath` and `defaultBranch` for every repository, with the same paths as the `defaultBranches` read. When none are saved, use each repository's folder relative to the project folder (`.` for the project folder). |
429
430
  | `ports` | `expectedConfigurationRevision`; `configuration` with `defaultAction` and `rules` from the read result. |
430
431
  | `storage` | `enabled`. |
432
+ | `browser` | `enabled`; whether the project's Browser is available in the apps and to agents. |
433
+ | `thread_sharing` | `enabled`; shares the current thread with the owner's team by link, or stops sharing it. The result includes the link. |
434
+ | `devbox_name` | `name` for the current devbox in the sidebar; empty text clears it. Needs title editing (`update-thread-titles`) on the box instead of `edit-project-settings`. |
435
+ | `folder_update` | `folderId`, `displayName`, and `whenToUse` (text or null). Needs folder-creation access instead of `edit-project-settings`. |
436
+ | `folder_reorder` | `folderIds` in the new order, listing every folder. Needs folder-creation access. |
437
+ | `folder_delete` | `folderId`. Needs folder-creation access. |
438
+ | `project_url_create` | `name`, `targetPort`, `defaultDelivery`, and `deliveryRules`, as shown by `dvb-onbox url show --json`. Independent projects only. |
439
+ | `project_url_update` | `projectUrlId` from `dvb-onbox url list --json`, plus the complete definition fields above. |
440
+ | `project_url_set_enabled` | `projectUrlId`, `enabled`. |
441
+ | `project_url_rotate` | `projectUrlId`; replaces the public address. Outside services registered with the old address will stop reaching it. |
442
+ | `project_url_delete` | `projectUrlId`. |
431
443
  | `auto_wake` | `enabled` (boolean or null to use the product default); affects the owner's account across projects. |
432
444
  | `maintenance` | `script`, `timeoutSeconds`, and the complete schedule fields listed below. |
433
445
  | `maintenance_delete` | No additional fields. |
@@ -515,6 +527,76 @@ settings.
515
527
  Use `env set|remove` for environment values and `team-template member-files`
516
528
  for requirement definitions. These retain their own input and revision rules.
517
529
 
530
+ ### Account preferences
531
+
532
+ The owner's own preferences apply across all of their projects. Read them from
533
+ any box in one of the owner's projects, and change one with a settings file
534
+ like the project command:
535
+
536
+ ```bash
537
+ dvb-onbox account settings get --json
538
+ dvb-onbox account settings set --settings-file /home/boxes/account-edit.json --json
539
+ ```
540
+
541
+ Changes need the same `edit-project-settings` grant as project settings; an
542
+ `edit-template-box` or `edit-team-template` grant also covers them. Read first
543
+ and send complete values for the section you change.
544
+
545
+ | Section | Fields |
546
+ | --- | --- |
547
+ | `sleep_timeout` | `minutes` (a supported idle-sleep value, or null to use the team default). |
548
+ | `auto_wake` | `enabled` (boolean, or null for the product default). |
549
+ | `thread_list` | `sortOrder` and `groupStartedDevboxes`. |
550
+ | `notifications_quiet_hours` | `enabled`, `startMinute`, `endMinute` (minutes after midnight in the user's time zone). |
551
+ | `notifications_pause` | `paused`; pausing silences notifications for the standard pause period, and `false` resumes them. |
552
+ | `agent_replies` | `defaultFollowUpMode` (`queue`, `steer`, or null), `claudeQuestionTimeout`, `promptSuggestionsEnabled`. |
553
+ | `claude_ai_connectors` | `enabled`. |
554
+ | `chrome_window` | `enabled`; whether the Browser opens as a separate Chrome window on the user's computer. |
555
+ | `git_identity` | `name`, `email`, `expectedRevision` from `gitIdentity.saved.revision` (null when none is saved). |
556
+ | `git_identity_clear` | `expectedRevision`; returns to the GitHub default identity. |
557
+ | `github_merge_method` | `preferredMergeMethod`; needs a connected GitHub account. |
558
+ | `github_cli_on_boxes` | `enabled`; whether boxes get the user's GitHub CLI sign-in. Needs a current GitHub connection. |
559
+
560
+ Sign-ins, saved agent accounts and API keys, billing, and preferences stored on
561
+ the user's computer, such as theme, terminal, and keyboard shortcuts, remain in
562
+ the apps.
563
+
564
+ ### Team settings
565
+
566
+ A team admin's agent can read and change the team's own settings from any box
567
+ in one of the admin's projects:
568
+
569
+ ```bash
570
+ dvb-onbox team settings get --json
571
+ dvb-onbox team settings set --settings-file /home/boxes/team-edit.json --json
572
+ ```
573
+
574
+ Reads list the team's name, members and roles, invites, allowed domains,
575
+ teammate thread access policy, idle sleep default, and static egress
576
+ destinations. Changes need the thread's `edit-team-template` grant; only team
577
+ admins can read or change these settings.
578
+
579
+ | Section | Fields |
580
+ | --- | --- |
581
+ | `metadata` | `companyDisplayName`. |
582
+ | `domain_routing` | `domainId` from `domains`, `routingMode`, and `blockMessage` (text or null; used only when blocking). |
583
+ | `thread_access_policy` | `policy`. |
584
+ | `sleep_timeout` | `minutes`; the idle sleep default for members without their own setting. |
585
+ | `egress_add` | `hostname` and `ports`; needs static egress enabled for the team. |
586
+ | `egress_remove` | `destinationId` from `staticEgress.destinations`. |
587
+ | `member_invite` | `email`, `role` (`admin` or `member`), `reason`, `approvalRequestId`. |
588
+ | `member_invite_revoke` | `inviteId` from `invites`, `reason`, `approvalRequestId`. |
589
+ | `member_role` | `userId` from `members`, `role`, `reason`, `approvalRequestId`. |
590
+
591
+ Membership sections don't use the grant. Each change needs the admin's approval
592
+ of that exact change: submit it with `approvalRequestId: null`, wait with
593
+ `dvb-onbox permissions wait --request-id <id> --json`, then resubmit the same
594
+ change with that ID, as described in
595
+ [Integration status and setup](#integration-status-and-setup). The approval
596
+ names the person, the role, and the team; `reason` is optional context shown as
597
+ the agent's words. Removing a member, connecting Slack, Linear, Tailscale, or
598
+ AWS for the team, and billing remain team admin steps in the apps.
599
+
518
600
  ## Environment Variables
519
601
 
520
602
  An agent can list, set, and remove the centrally managed environment variables
@@ -552,8 +634,11 @@ Environment files**.
552
634
 
553
635
  `--value-stdin` reads the value from standard input and drops one trailing
554
636
  newline. `list` returns names, where each value comes from, and whether a value
555
- is saved; it needs no editing grant and never returns values. Saved changes reach running machines within
556
- about a minute. After an uncertain response, run `list` before retrying.
637
+ is saved; it needs no editing grant and never returns values. A file that loads
638
+ into agent and terminal environments reports `loadIntoEnvironment: true`; only
639
+ the user can change that setting, in Project settings. See
640
+ [Loading values into agents and terminals](managed-environment-files.md#loading-values-into-agents-and-terminals).
641
+ Saved changes reach running machines within about a minute. After an uncertain response, run `list` before retrying.
557
642
 
558
643
  ## Automations
559
644
 
@@ -649,8 +734,12 @@ separate `--prompt-file`, not both. File paths can be relative or absolute.
649
734
  Runs begin at the first matching time after now, so `startDate` can be
650
735
  today or earlier. The `startDate` of a weekly schedule must fall on one of
651
736
  its `weekdays`, and that of a monthly schedule on its `monthDay`.
652
- Slack named-command and API triggers must be set up in the desktop app.
653
- Use `create-receiver` for a default Slack or Linear receiver.
737
+ `{"kind": "api", "requestMode": "fixed"}` lets a program start runs at the
738
+ result's `apiTrigger.endpoint`; `configurable` also lets the caller supply
739
+ the prompt. `{"kind": "slack", "command": "deploy"}` starts runs from that
740
+ Slack command, using the default command options; finer Slack options are in
741
+ the desktop app. Use `create-receiver` for a default Slack or Linear
742
+ receiver.
654
743
  - `threadPlacement`: `nested` (under the automation) or `main` (the main
655
744
  thread list).
656
745
  - `target`: `{"kind": "thread", "thread": "current"}` to continue the calling
@@ -735,11 +824,15 @@ It checks new Slack destinations against the saved Slack connection without
735
824
  contacting Slack, so a channel the boxes.dev app can't post to is reported
736
825
  only when you save.
737
826
 
738
- An automation with an API, Slack, or Linear trigger can have its name, prompt,
739
- and settings changed, but a supplied `trigger` fails with
740
- `unsupported_trigger_change`. `get` describes those triggers without their
741
- settings, and `defaultIntegrationReceiver` is true for the default Slack or
742
- Linear receiver.
827
+ The first save that sets up an API trigger returns its secret in
828
+ `apiTrigger.secret`; later reads show only the endpoint. Give the secret to the
829
+ user or store it in a managed environment file, because it isn't shown again.
830
+ Switching from `fixed` to `configurable` issues a new secret and the old one
831
+ stops working. A default Slack or Linear receiver, and an automation with a
832
+ Linear trigger, can have its name, prompt, and settings changed, but a supplied
833
+ `trigger` fails with `unsupported_trigger_change`. `get` describes Slack
834
+ triggers by command only, and `defaultIntegrationReceiver` is true for the
835
+ default Slack or Linear receiver.
743
836
 
744
837
  ### Activate, run, and delete
745
838
 
@@ -781,8 +874,9 @@ trying again so you don't create a duplicate.
781
874
 
782
875
  ## Devbox Lifecycle And Template Maintenance
783
876
 
784
- From the project's current ordinary Template box, an agent can inspect and edit
785
- the startup and teardown defaults used by future devboxes:
877
+ From the Template box or any devbox of a project with its own Template box, an
878
+ agent can inspect and edit the startup and teardown defaults used by future
879
+ devboxes:
786
880
 
787
881
  ```bash
788
882
  dvb-onbox project lifecycle get --json
@@ -799,7 +893,9 @@ Each script and timeout flag is optional, and clear flags remove either script.
799
893
  Read first, pass the returned revision, and reconcile a newer read after
800
894
  `configuration_conflict`. Before saving a nonempty teardown script, explain
801
895
  what it does and why the project needs that work when a devbox is destroyed.
802
- Both lifecycle reads and writes require **Edit devbox lifecycle**.
896
+ Lifecycle reads and writes require the thread's `edit-project-settings` grant,
897
+ which an `edit-template-box` grant also covers. On a Template box where the
898
+ owner already turned on **Edit devbox lifecycle**, they work without a grant.
803
899
 
804
900
  Template maintenance uses one script and one complete GitHub watch set:
805
901
 
@@ -828,8 +924,10 @@ watches keep their baseline, while new, changed, or re-enabled watches start
828
924
  from the current default branch and do not run maintenance immediately.
829
925
  Omitting an editable existing watch requires `--confirm-watch-removals`;
830
926
  grandfathered read-only watches remain unchanged. Maintenance reads and writes
831
- on an ordinary Template box require **Edit template maintenance**, a separate
832
- permission that covers the script and GitHub watches together.
927
+ work from the Template box or any of its devboxes and need the same
928
+ `edit-project-settings` grant as lifecycle edits. On a Template box where the
929
+ owner already turned on **Edit template maintenance**, they work without a
930
+ grant.
833
931
 
834
932
  To investigate maintenance, list runs and choose a `publicRunId` for `logs`.
835
933
  History includes active runs and up to twenty retained completed runs, with
@@ -841,9 +939,8 @@ unavailable run IDs return `maintenance_run_not_found`. The existing maintenance
841
939
  permission and Template box or Team Template editing-session requirements also
842
940
  apply to history and logs.
843
941
 
844
- `run` starts the saved script on the current ordinary Template box, the same
845
- way as **Run now** in Project settings, and requires **Edit template
846
- maintenance**. It returns the run's `publicRunId` and a disposition: `create`
942
+ `run` starts the saved script on the project's Template box, the same way as
943
+ **Run now** in Project settings, and needs the same access as `apply`. It returns the run's `publicRunId` and a disposition: `create`
847
944
  for a new run, `merge` when the request joined a run already waiting to start,
848
945
  or `followup` when the run will start after one in progress. A project without
849
946
  a saved script returns `maintenance_not_configured`. After the script succeeds,
@@ -851,8 +948,9 @@ boxes.dev saves a snapshot, and agents on the Template box pause briefly while
851
948
  it is saved. Follow the run with `runs` until its status is `succeeded`,
852
949
  `failed`, or `canceled`, then read `logs`; only `succeeded` means both the
853
950
  script and the snapshot finished. Finish a maintenance repair with a successful
854
- run. In a Team Template editing session, `run` returns `source_box_unavailable`;
855
- run Team Template maintenance from the desktop app.
951
+ run. In a Team Template editing session, `run` queues that Team Template's
952
+ saved script, the same way as **Run now** in its maintenance settings; follow it
953
+ with `runs` the same way.
856
954
 
857
955
  The same maintenance commands work in a Team Template's current editing
858
956
  session. They update that Team Template's shared maintenance script and watches
@@ -862,13 +960,12 @@ identifies the Team Template by name and ID. Schedule settings remain editable
862
960
  under **Template environment → Maintenance** in the desktop app.
863
961
 
864
962
  These settings are devbox lifecycle and Template maintenance, not boxes.dev
865
- Automations. The commands accept no project, box, owner, or repository ID.
866
- Devbox lifecycle commands require the current ordinary Template box; configure
867
- Team Template lifecycle defaults under **When a new devbox is created**,
868
- including its **When a devbox is destroyed** section.
869
- If either operation reports
870
- disabled access, request only `edit-devbox-lifecycle` or
871
- `edit-template-maintenance`, respectively.
963
+ Automations. The commands accept no project, box, owner, or repository ID; the
964
+ current box determines the project. A project created from a Team Template has
965
+ no Template box of its own; configure Team Template lifecycle defaults under
966
+ **When a new devbox is created**, including its **When a devbox is destroyed**
967
+ section. If either operation reports disabled access, request the permission
968
+ that the error names, usually `edit-project-settings`.
872
969
 
873
970
  ## Current Thread Link
874
971
 
@@ -883,7 +980,10 @@ dvb-onbox threads get-link --json
883
980
  The command takes no thread ID: the current managed thread and box determine
884
981
  the result. It does not share the thread or broaden teammate access. If the
885
982
  thread is private, not yet eligible, or the managed context does not match,
886
- the command reports that the link is unavailable rather than guessing one.
983
+ the command reports that the link is unavailable rather than guessing one. To
984
+ share the current thread with the owner's team when the user asks, use the
985
+ `thread_sharing` section of `dvb-onbox project settings set`; it returns the
986
+ share link.
887
987
 
888
988
  For a commit, use:
889
989
 
@@ -910,8 +1010,7 @@ dvb-onbox permissions request \
910
1010
 
911
1011
  The request values are `create-devboxes-and-threads`,
912
1012
  `create-team-templates`, `update-thread-titles`,
913
- `move-devboxes-to-folders`, `create-devbox-folders`,
914
- `edit-devbox-lifecycle`, `edit-template-maintenance`, `destroy-devbox`,
1013
+ `move-devboxes-to-folders`, `create-devbox-folders`, `destroy-devbox`,
915
1014
  `destroy-created-devboxes`, `destroy-project-devboxes`, `read-project-threads`, `read-user-threads`, `read-shared-threads`,
916
1015
  `read-team-threads`, `control-created-threads`, `control-project-threads`,
917
1016
  `control-user-threads`, `message-agents`, `message-teammates-agents`, `edit-template-box`,
@@ -938,11 +1037,14 @@ permissions switch or project setting can enable it. Request
938
1037
  `edit-template-box` from a devbox in a project with its own Template box to
939
1038
  edit that Template box and the project's settings and environment variables. Request
940
1039
  `edit-project-settings` from any box in the project to edit its settings,
941
- including the user's own environment and member-file values. It cannot change
1040
+ including devbox lifecycle, Template maintenance, Project URLs, and the user's
1041
+ own environment and member-file values, to share the current thread, and to
1042
+ change the user's [account preferences](#account-preferences). It cannot change
942
1043
  agent permission defaults. Request
943
- `edit-team-template` from a box in a project created from a Team Template to edit that
944
- Team Template's settings, including environment and member-file definitions; only a team admin can
945
- receive it. Request `edit-personal-environment` from a devbox in a Team
1044
+ `edit-team-template` from any box in one of the user's projects to edit
1045
+ [team settings](#team-settings) and, in a project created from a Team
1046
+ Template, that Team Template's settings, including environment and member-file
1047
+ definitions; only a team admin can receive it. Request `edit-personal-environment` from a devbox in a Team
946
1048
  Template project to edit the user's own environment variables for that
947
1049
  project; any member can receive it, and a thread that already has
948
1050
  `edit-team-template` or `edit-project-settings` does not need it. A thread holds one of these grants at a
@@ -958,7 +1060,7 @@ thread can hold it together with one of them.
958
1060
  `edit-tailscale-integration` and `edit-google-cloud-integration` are independent
959
1061
  three-hour grants for routine integration settings. A thread can hold both
960
1062
  alongside its other grants. They do not inherit from broader settings access.
961
- `change-aws-profile` and `enable-tailscale-integration` require the exact settings
1063
+ `change-aws-profile`, `enable-tailscale-integration`, and `change-team-membership` require the exact settings
962
1064
  operation to prepare their approval, rather than `permissions request`. See
963
1065
  [Integration status and setup](#integration-status-and-setup).
964
1066
 
@@ -1314,9 +1416,10 @@ control ports, credential-bearing tools, unauthenticated admin surfaces, or
1314
1416
  another sensitive/internal service. The command rejects excluded, undetected,
1315
1417
  and non-HTTP ports rather than choosing a different port.
1316
1418
 
1317
- Anyone with the generated link can reach the app without signing in. Tell the
1318
- user that the URL is public before sharing it, and make sure the app itself is
1319
- appropriate for unauthenticated Internet access. Stopping the app makes the URL
1419
+ Anyone with the generated link can reach the app without signing in, and can
1420
+ wake the box from the link's sleeping page, which uses the owner's box-hours.
1421
+ Tell the user that the URL is public before sharing it, and make sure the app
1422
+ itself is appropriate for unauthenticated Internet access. Stopping the app makes the URL
1320
1423
  unavailable but does not revoke it. Run `stop-sharing` as soon as the callback
1321
1424
  or preview is no longer needed; stopping public sharing does not stop the app.
1322
1425
 
@@ -2352,8 +2455,11 @@ target exists.
2352
2455
  `folder_revision_conflict` means another person or agent changed the membership.
2353
2456
  Run `get` again and reconsider the operation; moves never overwrite a newer
2354
2457
  revision. Keep one idempotency key per logical create or move, and retry an
2355
- uncertain result only with the same key and identical arguments. Agents cannot
2356
- edit, reorder, or delete existing folders. If the command is absent from help
2458
+ uncertain result only with the same key and identical arguments. With
2459
+ folder-creation access, rename a folder or change its **When to use**,
2460
+ reorder, or delete folders with the `folder_update`, `folder_reorder`, and
2461
+ `folder_delete` sections of `dvb-onbox project settings set`; deleting a folder
2462
+ returns its devboxes to the date sections. If the command is absent from help
2357
2463
  or reports `daemon_update_required`, wait for the managed boxes.dev service to
2358
2464
  update; do not install workstation `dvb` or call backend services directly.
2359
2465
 
@@ -2445,9 +2551,10 @@ Project URL traffic does not wake a sleeping box or keep it awake. `list` and
2445
2551
  `show` work without a running app. `claim`, `subscribe`, and `browser-link`
2446
2552
  require the URL's configured port to be allowed by the project port policy and
2447
2553
  to have a detected HTTP listener. The commands configure only which box
2448
- participates; durable URL creation, delivery rules, port changes,
2449
- disable/enable, replacement, and deletion remain project-level operations
2450
- outside the box.
2554
+ participates. To create a Project URL or change its port, delivery rules,
2555
+ enabled state, address, or existence, use the `project_url_*` sections of
2556
+ `dvb-onbox project settings set`, which need the `edit-project-settings`
2557
+ grant.
2451
2558
 
2452
2559
  Ordinary OAuth uses the Project URL's canonical callback directly and needs no
2453
2560
  boxes.dev-specific OAuth setting. When two browser profiles must stay on two
@@ -2557,17 +2664,22 @@ dvb-onbox team-template member-files remove \
2557
2664
  --file <file-id> --if-revision <definition-revision> --json
2558
2665
  ```
2559
2666
 
2560
- `add` requires `--root home|project` and a relative `--path`. Optional
2561
- `--display-order` sets a nonnegative position; new requirements otherwise go
2562
- after existing ones. `update` accepts any of `--root`, `--path`, `--instructions`,
2563
- `--clear-instructions`, and `--display-order`; omitted settings stay unchanged.
2667
+ `add` requires `--root home|project` and a relative `--path`. New requirements
2668
+ are required; add `--optional` for a file that members can skip during project
2669
+ creation and add later. Optional `--display-order` sets a nonnegative position;
2670
+ new requirements otherwise go after existing ones. `update` accepts any of
2671
+ `--root`, `--path`, `--instructions`, `--clear-instructions`, `--optional`,
2672
+ `--required`, and `--display-order`; omitted settings stay unchanged. Each
2673
+ listed requirement includes `required`.
2564
2674
  List first and use the returned file ID and definition revision for updates
2565
2675
  and removals. After an uncertain response, list again to inspect the outcome
2566
2676
  before retrying a change.
2567
2677
 
2568
2678
  Definitions take effect independently of saving a filesystem version. Existing
2569
- managed projects follow these requirements, and a missing file will block their
2570
- next startup. Changing a destination will require members to approve the new
2679
+ managed projects follow these requirements, and independent projects keep the
2680
+ copy made when they were created. A missing file does not block startup: the
2681
+ member's devboxes start without it, and the apps warn them about missing
2682
+ required files. Changing a destination will require members to approve the new
2571
2683
  destination or upload a replacement. Changing instructions will not require
2572
2684
  destination approval. See [Member files](member-managed-files.md) for upload
2573
2685
  and delivery behavior. These commands return definitions only and do not
@@ -2760,8 +2872,9 @@ dvb-onbox team-template edit-box status --edit-box <edit-box-id> --json
2760
2872
 
2761
2873
  Use the target commands below to finish the filesystem setup. For a bounded
2762
2874
  script that may take longer than two minutes, use a regular file and a stable
2763
- key; it runs through the same attested target access and accepts up to 20
2764
- minutes, 3 MiB of script input, and 4 MiB per output stream:
2875
+ key; it runs through the same attested target access and accepts up to 8
2876
+ minutes, 3 MiB of script input, and 4 MiB per output stream. Split longer work
2877
+ into scripts that each finish within that limit:
2765
2878
 
2766
2879
  ```bash
2767
2880
  dvb-onbox team-template edit-box run --edit-box <edit-box-id> \
@@ -2828,6 +2941,11 @@ the ended editing session. A later checkout needs its own active association.
2828
2941
  `--template`, selecting a checkout not held by the same admin, or using a stale
2829
2942
  target fails without choosing another template.
2830
2943
 
2944
+ Several `exec`, `edit-box run`, and `push` commands can run on the same editing
2945
+ machine at once, and the machine stays awake while they run. When a command
2946
+ reaches its time limit, boxes.dev stops the command and the background
2947
+ processes it started, then reports exit code 124 with `timedOut: true`.
2948
+
2831
2949
  `push` copies one regular file from the source project Template box into the
2832
2950
  Team Template checkout. Both paths must be absolute and below `/home/boxes`.
2833
2951
  Directories and symbolic links are rejected, and the source file must be at