@boxes-dev/dvb-runtime 1.0.1112 → 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.
@@ -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
@@ -35,12 +35,16 @@ Git, or Ports. If a devbox is sleeping because the awake devbox limit is full,
35
35
  boxes.dev asks you to sleep another devbox before continuing.
36
36
 
37
37
  Background work started by an agent can keep a devbox awake after the agent
38
- finishes its reply. Codex background commands receive up to one hour of sleep
39
- protection. Claude background tasks use their declared timeout, capped at four
40
- hours, or one hour when no timeout is declared. Finishing the work releases
38
+ finishes its reply. In the chat view, Claude background subagents keep it
39
+ awake while they work, including while they wait on a tool. After 12 minutes without
40
+ new activity, normal idle sleep can resume.
41
+
42
+ Codex background commands and Claude subagents started in a terminal receive
43
+ up to one hour of sleep protection. Claude background commands and workflows
44
+ use their declared timeout, capped at four hours, or one hour when no timeout
45
+ is declared. Finishing the work releases
41
46
  that protection sooner. When the limit expires, normal idle sleep can resume;
42
- the limit does not terminate the command. You can still sleep the machine
43
- yourself.
47
+ the limit does not terminate the command. You can still sleep the box yourself.
44
48
 
45
49
  Claude's background shell commands in the chat view have a separate execution
46
50
  limit: 30 minutes by default, up to two hours. When that limit expires, Claude
@@ -263,9 +267,16 @@ dialog shows the new link with a **Copy link** button. Public links do not
263
267
  depend on local forwarding, remain active when you select another devbox or
264
268
  close the desktop app, and remain allocated while the app is stopped or the
265
269
  machine is sleeping. Traffic through a public link can keep an awake machine
266
- active; Project URL traffic does not. Public links do not wake a sleeping
267
- devbox: while the devbox sleeps, visitors see an unavailable page and the
268
- Ports menu marks the link as paused.
270
+ active; Project URL traffic does not.
271
+
272
+ While the box sleeps, the Ports menu marks the link as paused, and
273
+ visitors see a page with a **Wake devbox** button. Anyone with the link can
274
+ press it without signing in. The box then wakes as if its owner had woken
275
+ it: it uses the owner's box-hours, and the owner's billing and awake devbox
276
+ limits apply. The page reloads into the app once the box is ready. Other
277
+ requests to the link, including API calls and WebSocket connections, do not
278
+ wake the box. If a limit blocks the wake or the wake fails, the page says
279
+ so, and after a failed wake the visitor can try again.
269
280
 
270
281
  Public links and Project URLs pass their public hostname to the app. If Vite
271
282
  rejects those requests with "Blocked request. This host is not allowed", add
@@ -358,8 +358,15 @@ manifest can instead select SSH or skip Git access. If GitHub is not connected,
358
358
  flow. Once GitHub is connected, the same command opens the GitHub page that
359
359
  gives the boxes.dev GitHub App access to the project's repositories: the
360
360
  owner's installation settings, or the install page with the owning account
361
- selected. `dvb agent-init check` verifies the exact writable repositories, App
362
- visibility, and current GitHub access before a managed launch; when an update
361
+ selected. The command then waits, for up to 20 minutes without progress,
362
+ until the user finishes each step on GitHub and boxes.dev can access every
363
+ repository, so the agent doesn't need the user to say they're done. The setup
364
+ page names the step: a **Connect GitHub** button while the user signs in, and
365
+ the repositories and an **Open GitHub** link while boxes.dev needs access.
366
+ When GitHub returns the user to **Account** after an App install, update, or
367
+ request, Account says what happened and tells a user in setup to go back to
368
+ their coding agent. `dvb agent-init check` verifies the exact writable
369
+ repositories, App visibility, and current GitHub access before a managed launch; when an update
363
370
  is required, it prints the exact GitHub action and the SSH alternative. If
364
371
  GitHub renamed or transferred a repository after its local origin was set,
365
372
  `check` and `github connect` print a `git remote set-url` command for the
@@ -516,8 +516,9 @@ Start the ordinary new-project flow and choose **Start from a Team Template**.
516
516
  The picker shows only templates with a current saved version and does not
517
517
  preselect one. Select the exact template, name the project and complete
518
518
  **Needed to create the project**, which brings required environment values
519
- and all member files together. **Show optional** starts collapsed; these
520
- can be added now or later in Project settings. Independent projects also
519
+ and required member files together. **Show optional** starts collapsed and
520
+ holds optional values and files; these can be added now or later in Project
521
+ settings. Independent projects also
521
522
  offer coding-agent choices; at least one must be selected when the template
522
523
  includes setup instructions. Team defaults remain available for review.
523
524
 
@@ -115,12 +115,14 @@ Doing this on an ordinary devbox stays local to that devbox and does not create
115
115
  a Template snapshot. See `files-git-and-review.md` for the full add, review,
116
116
  repair, access-recovery, and unsupported-layout behavior.
117
117
 
118
- When **Edit devbox lifecycle** is enabled for the Template box, its managed
119
- agents can use `dvb-onbox project lifecycle get/set` to update the same startup
120
- script, teardown script, and timeouts shown in Project settings. The command is
121
- revision-checked, reads script content from regular files under `/home/boxes`,
122
- and cannot target another project or box. This lifecycle setting is unrelated
123
- to boxes.dev Automations.
118
+ An agent on the Template box or any of its devboxes can use `dvb-onbox project
119
+ lifecycle get/set` to update the same startup script, teardown script, and
120
+ timeouts shown in Project settings. The agent needs to ask you for permission
121
+ to edit project settings first. On a Template box where **Edit devbox
122
+ lifecycle** is already on, its agents can use the command without asking. The
123
+ command is revision-checked, reads script content from regular files under
124
+ `/home/boxes`, and cannot target another project. This lifecycle setting is
125
+ unrelated to boxes.dev Automations.
124
126
 
125
127
  ## Template Maintenance
126
128
 
@@ -150,16 +152,16 @@ saving it.
150
152
  Automatic scheduling is optional; the supported cadences are every 6 hours,
151
153
  every 12 hours, nightly, and weekly.
152
154
 
153
- With the separate **Edit template maintenance** Agent permission, a managed
154
- agent on the Template box can use `dvb-onbox project maintenance get/apply` to
155
- author the script and complete GitHub watch set together, and `run` to start
156
- the saved script and follow its result. The command copies a
155
+ An agent on the Template box or any of its devboxes can use `dvb-onbox project
156
+ maintenance get/apply` to author the script and complete GitHub watch set
157
+ together, and `run` to start the saved script and follow its result. It needs
158
+ the same permission to edit project settings, unless **Edit template
159
+ maintenance** is already on for the Template box it runs on. The command copies a
157
160
  script and version-1 watch JSON file from regular files under `/home/boxes`,
158
161
  requires the revision returned by `get`, and requires explicit confirmation
159
162
  before removing an editable watch. It preserves the existing repeating
160
163
  schedule. New, changed, or re-enabled watches receive a fresh baseline without
161
- starting a maintenance run. Turning this permission on or off does not change
162
- **Edit devbox lifecycle** or any saved configuration.
164
+ starting a maintenance run.
163
165
 
164
166
  When GitHub is connected, a policy can also watch exact repository-relative
165
167
  files or directories on each repository's default branch. Only the project's own
@@ -841,11 +841,13 @@ have not sent or skipped stay under **Answer questions**. If
841
841
  the turn ends, edited answers that you have not sent will move to the reply box.
842
842
  Answers reach the running turn even if ordinary replies are set to Queue.
843
843
 
844
- On mobile, the questions appear together in the scrollable conversation and
845
- stay visible until answered or the turn ends. Tap an option to answer a single
846
- choice question immediately; use **Send** for written answers or a set of
847
- questions. Edited unsent answers also return to the reply box when the turn
848
- ends. See `mobile.md` for mobile message recovery and question controls.
844
+ On mobile, the questions appear one at a time in the scrollable conversation
845
+ and stay visible until answered or the turn ends. Tapping an option answers the
846
+ question and moves to the next one; on the last question it sends the answers.
847
+ For a written answer, type it and tap **Continue**, or **Send** on the last
848
+ question. The arrows at the top of the form move between questions. Edited
849
+ unsent answers also return to the reply box when the turn ends. See
850
+ `mobile.md` for mobile message recovery and question controls.
849
851
 
850
852
  Codex threads expose model controls in the composer footer:
851
853
 
@@ -1119,19 +1121,32 @@ intentionally moves them to cold storage or that machine is destroyed.
1119
1121
  When Claude Code enters plan mode, the desktop and mobile mode control shows
1120
1122
  **Plan** while Claude is planning without changing project files. An older
1121
1123
  connected runtime can show the passive label **Plan mode** instead. When Claude
1122
- is ready to leave plan mode, its **Exit plan mode** approval offers **Allow** or
1123
- **Deny**; denying keeps the thread in plan mode, while allowing lets Claude
1124
- return to implementation work.
1125
-
1126
- Claude Code may ask the user structured questions. The question card can show
1127
- choice answers, multi-select answers, and skip options. Every Claude-authored
1124
+ proposes a plan, the transcript shows it formatted, and the **Plan** card asks
1125
+ **Implement this plan?** Choose **Yes, implement this plan** to leave plan mode
1126
+ and let Claude start the work in the previous mode. To revise the plan instead,
1127
+ type what to change in **No, tell Claude what to change** and submit it, or
1128
+ send the change as a steer from the reply box. Claude will stay in plan mode
1129
+ and propose a revised plan. A queued message waits until the plan is answered. A
1130
+ box running an older version of boxes.dev shows **Allow** and **Deny** instead.
1131
+
1132
+ Claude Code may ask the user structured questions. The question card shows
1133
+ one question at a time, above the reply box on desktop and in the conversation
1134
+ on mobile, with arrows and a "1 of N" position when Claude asked several. A
1135
+ question can allow one choice or several. When it allows one, choosing an
1136
+ option moves to the next question that still needs an answer, and the answers
1137
+ are sent once every question has one. Multi-select and custom answers use **Continue**, or
1138
+ **Submit** on the last question. On desktop, number keys choose options while
1139
+ the card has focus, and Esc stops the turn. **Skip** appears on a
1140
+ question when Claude offered a skip option for it. Every Claude-authored
1128
1141
  question also includes **Type something else...** for a custom answer and
1129
1142
  **Chat about this** when the choices or premise need clarification. Chat sends
1130
1143
  the current partial selections or custom text back as context so Claude can
1131
- reformulate the question; it does not record a completed answer. Some
1132
- single-choice answers submit immediately, while multi-select and custom
1133
- answers use a Submit action. Answering a question on a sleeping box wakes the
1134
- box and sends the answer once the app reconnects.
1144
+ reformulate the question; it does not record a completed answer. Permission
1145
+ requests use the same card with **Allow** and **Deny**. While one of these
1146
+ questions is waiting, Claude can't take a steer; answer it first, then retry
1147
+ the message.
1148
+ Answering a question on a sleeping box wakes the box and sends the answer once
1149
+ the app reconnects.
1135
1150
 
1136
1151
  To let Claude continue without an answer, choose **Question auto-continue
1137
1152
  timeout** under **Settings → Agents → Agent replies** on desktop or
@@ -1292,6 +1307,9 @@ folder's name, and its devbox count. A closed folder also shows the most
1292
1307
  urgent state among its threads, such as running, needs input, or unread. While
1293
1308
  the user scrolls through an open folder, its row stays pinned below the
1294
1309
  **Devboxes** heading until the next folder or the unfiled devboxes reach it.
1310
+ To move a devbox, the user can choose a folder from **Move to** in its menu or
1311
+ drag the devbox onto the folder. Dragging it to the unfiled devboxes takes it
1312
+ out of its folder. A pinned devbox can't be dragged into a folder.
1295
1313
  **Sidebar density**, under **Appearance and layout** in **Settings > General**,
1296
1314
  sets the thread list's spacing to **Comfortable** (the default), **Cozy**, or
1297
1315
  **Compact**. It is saved on that computer only, and **Restore appearance and
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@boxes-dev/dvb-runtime",
3
- "version": "1.0.1112",
3
+ "version": "1.0.1114",
4
4
  "description": "Runtime for the boxes.dev CLI. Install @boxes-dev/dvb to use the CLI.",
5
5
  "homepage": "https://boxes.dev",
6
6
  "type": "module",
@@ -77,5 +77,5 @@
77
77
  "e2b": "^2.18.0",
78
78
  "ink-testing-library": "^4.0.0"
79
79
  },
80
- "devboxReleasedAt": "2026-11-04T06:04:43Z"
80
+ "devboxReleasedAt": "2026-11-06T01:06:52Z"
81
81
  }