@boxes-dev/dvb-runtime 1.0.1092 → 1.0.1094

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
@@ -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]="d2c2de6f-73ab-5585-92be-eeb14db99969")}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]="57feb75d-01ce-5c1b-85e0-5a03f16ca546")}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";
@@ -64675,9 +64675,9 @@ var init_sentry = __esm({
64675
64675
  uncaughtExceptionMonitorInstalled = false;
64676
64676
  currentDevboxSentryUser = null;
64677
64677
  readBuildMetadata = () => {
64678
- const rawPackageVersion = "1.0.1092";
64679
- const rawGitSha = "c33e3fee06c68f6f8f775a039865743a5c7fa5c8";
64680
- const rawSentryRelease = "boxes-dev-dvb@1.0.1092+c33e3fee06c68f6f8f775a039865743a5c7fa5c8";
64678
+ const rawPackageVersion = "1.0.1094";
64679
+ const rawGitSha = "6df6dd088ab8880d887c654f30e84a6a315d5d38";
64680
+ const rawSentryRelease = "boxes-dev-dvb@1.0.1094+6df6dd088ab8880d887c654f30e84a6a315d5d38";
64681
64681
  const packageVersion = typeof rawPackageVersion === "string" ? rawPackageVersion : void 0;
64682
64682
  const gitSha = typeof rawGitSha === "string" ? rawGitSha : void 0;
64683
64683
  const sentryRelease = typeof rawSentryRelease === "string" ? rawSentryRelease : void 0;
@@ -66894,7 +66894,7 @@ var init_packageVersion = __esm({
66894
66894
  return path8.join(process.cwd(), "dvb");
66895
66895
  };
66896
66896
  readEmbeddedPackageVersion = () => {
66897
- const raw = "1.0.1092";
66897
+ const raw = "1.0.1094";
66898
66898
  return trimVersion(raw);
66899
66899
  };
66900
66900
  readNearestPackageMetadata = (basePath) => {
@@ -80047,4 +80047,4 @@ smol-toml/dist/index.js:
80047
80047
  *)
80048
80048
  */
80049
80049
 
80050
- //# debugId=d2c2de6f-73ab-5585-92be-eeb14db99969
80050
+ //# debugId=57feb75d-01ce-5c1b-85e0-5a03f16ca546
@@ -91,7 +91,12 @@ checkout, choose a paid plan, or add a payment method from billing.
91
91
  ## Paid Plans And Seats
92
92
 
93
93
  Paid plans apply to assigned paid seats. Team admins can assign and remove paid
94
- seats from the billing page.
94
+ seats from Billing on the website. A paid plan keeps at least one paid seat, so
95
+ the last paid seat offers Cancel plan instead of Remove seat. To stop paying, a
96
+ team admin needs to select Cancel plan there or at the bottom of Billing on the
97
+ website. Cancellation takes effect at the end of the billing period, and the
98
+ plan and its seats stay active until then. Keep plan undoes a scheduled
99
+ cancellation.
95
100
 
96
101
  Paid seats receive the plan's included box-hours each billing period. If usage
97
102
  goes beyond the included amount, boxes.dev uses prepaid overage credits when
@@ -115,9 +115,12 @@ the user connects Codex or Claude Code before launch.
115
115
  The agent prepares a manifest with you, checks it, and asks for explicit
116
116
  approval before `dvb agent-init run` uploads files or creates a Template box.
117
117
  The current version-3 manifest also lets the agent design startup and teardown
118
- behavior and, when useful, one Template maintenance script with matching GitHub
119
- watches. Maintenance starts with its repeating schedule off and fresh watch
120
- baselines; setup does not run the script.
118
+ behavior and one Template maintenance script with matching GitHub watches. The
119
+ agent recommends maintenance when dependencies or tooling change over time and
120
+ watches files such as lockfiles rather than application source. Maintenance
121
+ starts with its repeating schedule off and fresh watch baselines. The setup
122
+ agent on the Template box tests the script twice and saves any fixes; setup
123
+ does not start a maintenance run.
121
124
 
122
125
  ## List And Select Machines
123
126
 
@@ -23,6 +23,18 @@ command without repeating an unrecorded workaround.
23
23
  For remote Team Template editing, perform these checks on the target editing
24
24
  box. Success on the source project's Template box does not verify the target.
25
25
 
26
+ For normal setup, configure new devboxes to fetch the latest remote default
27
+ branch, usually `main`, regardless of the Template box's current branch or
28
+ files. Use another saved starting branch when the user requests it. Inheriting
29
+ the Template box's saved checkout should be a deliberate user choice.
30
+
31
+ Read back the project's branch defaults; checking out `main` on the Template
32
+ box alone does not configure them. Follow
33
+ [Project setup](project-setup.md) for the setup
34
+ flow's supported controls and generated Git declaration. Keep dependency,
35
+ environment, and service commands after branch preparation, and remove custom
36
+ commands that switch branches or reset away the selected code.
37
+
26
38
  ## Verify Required Service Startup
27
39
 
28
40
  Check how the required services start through the documented development
@@ -386,6 +386,11 @@ uses GitHub App access after checking every known project repository; that
386
386
  credential can reach repositories available to both the user and the App.
387
387
  GitHub will enforce the active credential's permissions on each command.
388
388
 
389
+ An unavailable GitHub CLI connection does not by itself block new Codex or
390
+ Claude threads. Reconnect GitHub in **Integrations → GitHub** when a command
391
+ requires it. A devbox startup script that uses GitHub may still need that
392
+ connection to finish.
393
+
389
394
  Personal sign-in is optional even when App repository access works. Choose
390
395
  **Enable** under **Full GitHub CLI access (optional)** in Account, Integrations →
391
396
  GitHub, or the optional follow-up in onboarding or project setup, or run `gh auth login` inside a
@@ -607,28 +612,39 @@ that thread's machine and asks the agent to follow up. The events are:
607
612
  - **Merge conflicts**: the pull request branch conflicts with its base branch.
608
613
 
609
614
  To turn follow-ups on for one pull request, open its actions menu in
610
- Git/Review, choose **Automate follow-ups**, and select the events. The selected
615
+ Git/Review, choose **Automate follow-ups**, and select the events. The project's
616
+ default follow-up events are selected to start. The selected
611
617
  devbox or Template box needs **GitHub CLI access**, and the boxes.dev GitHub
612
618
  App needs access to the repository so GitHub can send the events; personal
613
619
  GitHub CLI access alone cannot provide them. Follow-ups work only for pull
614
620
  requests into the repository's default branch. An agent can also turn them on
615
- itself with `dvb-onbox pr followups enable`; see
621
+ with `dvb-onbox pr followups enable` when you ask, and may offer to after it
622
+ opens a pull request; see
616
623
  [Pull Request Follow-ups](onbox-agent-tools.md#pull-request-follow-ups).
617
624
 
618
625
  To turn them on for new pull requests automatically, open **Project settings**,
619
626
  expand **Git**, and turn on **Automate follow-ups on new pull requests**. It is
620
- off by default. While it is on, boxes.dev turns on all four events when one of
621
- the project's threads opens a pull request, either with **Create PR** in
622
- Git/Review or by an agent running `gh pr create` on one of the project's
623
- devboxes. The thread that opened the pull request handles its follow-ups, and
624
- an agent's `gh pr create` output ends with a line saying they are on. The
625
- setting does not cover pull requests opened any other way, such as on
626
- github.com or with `gh pr create` in your own terminal, or a branch that
627
- already had an open pull request. It acts only when the pull request is
628
- created, so turning a pull request's follow-ups off later stays in effect.
627
+ off by default. While it is on, boxes.dev turns on the project's default
628
+ follow-up events when one of the project's threads opens a pull request, either
629
+ with **Create PR** in Git/Review or by an agent running `gh pr create` on one
630
+ of the project's devboxes. The thread that opened the pull request handles its
631
+ follow-ups, and an agent's `gh pr create` output ends with a line saying they
632
+ are on and naming the events. The setting does not cover pull requests opened
633
+ any other way, such as on github.com or with `gh pr create` in your own
634
+ terminal, or a branch that already had an open pull request. It acts only when
635
+ the pull request is created, so turning a pull request's follow-ups off later
636
+ stays in effect.
637
+
638
+ The project's default follow-up events are all four events unless you change
639
+ them under **Default follow-up events** in the same **Git** settings. They
640
+ apply when follow-ups start for a pull request without anyone choosing events:
641
+ the automatic setting above, and an agent's `dvb-onbox pr followups enable`
642
+ without `--triggers`. Changing them does not change the events of pull requests
643
+ that already have follow-ups.
629
644
 
630
645
  Before acting, the agent fetches the pull request's current state with `gh`. It
631
- may edit the worktree, run tests, commit, and push to the pull request branch.
646
+ may edit the worktree, run tests, commit, and push to the pull request branch
647
+ when your instructions and the repository's rules allow pushing.
632
648
  If a safe fix is not clear, it stops and explains why. When a failing check is
633
649
  something it can't fix, it also turns follow-ups off. When feedback needs no
634
650
  changes, such as an approval, it says so in the thread and leaves follow-ups
@@ -643,12 +659,20 @@ conversation. Approvals without a comment, edits, and deletions do not start a
643
659
  follow-up. Your own reviews and comments never start one, because agents act on
644
660
  GitHub as you; message the agent in its thread instead. The owner, member, and
645
661
  collaborator filter uses the relationship GitHub reports for each author; it
646
- does not check whether the author can write to the repository. boxes.dev waits
647
- until two minutes pass without a new comment, or ten minutes after the first
648
- one, then sends the comments together. If another selected event is ready in
649
- the meantime, its follow-up starts right away and includes the waiting
650
- comments. The agent replies to or resolves review conversations only
651
- when your instructions or the project's agent guidance tell it to.
662
+ does not check whether the author can write to the repository.
663
+
664
+ Bot review feedback includes a bot's reviews, inline review comments, and
665
+ comments in the pull request's conversation, along with edits to them. A bot's
666
+ approval does not start a follow-up, even when it has a comment.
667
+
668
+ Review bots often post a status comment, a review, and inline comments over a
669
+ minute or two, and people often leave several comments in a row. boxes.dev
670
+ waits until three minutes pass without new review feedback from either, or ten
671
+ minutes after the first, then sends it all in one follow-up. If failed checks
672
+ or a merge conflict need a follow-up in the meantime, it starts right away and
673
+ includes the waiting feedback. The agent replies to or resolves review
674
+ conversations only when your instructions or the project's agent guidance tell
675
+ it to.
652
676
 
653
677
  While a Codex agent is working, its follow-up waits for the current turn to
654
678
  finish. Later events join a waiting follow-up that already covers those kinds,
@@ -51,15 +51,18 @@ the prepared devbox; it does not query the remote as the user types. Unlisted
51
51
  names can still be entered and are verified when fetched.
52
52
 
53
53
  boxes.dev fetches the selected remote branches and checks them out before
54
- running startup scripts. It remembers choices on this computer for the signed-in
55
- account after the first message is accepted. Discarding a draft does not change
56
- that preference. Clients without this picker use the project's configured
57
- defaults.
54
+ running startup scripts. For projects with configured branch defaults, an
55
+ accepted first message saves the chosen branches as that owner's project
56
+ defaults. New drafts, other devices, automations, and clients without this
57
+ picker use the same saved defaults. Discarding a draft, reopening an old draft,
58
+ or a failed start does not change them. Existing devboxes keep their checkout.
58
59
 
59
60
  Setup and import show default branches and startup commands as separate settings
60
- under **New devboxes**. Project settings show configured defaults above the
61
- startup script. Existing projects without managed defaults can keep the branch
62
- saved in the Template box snapshot by choosing **From Template box**.
61
+ under **New devboxes**. Edit configured defaults in **Project settings → Devbox
62
+ lifecycle → New devbox defaults**, above the startup script, then choose
63
+ **Save**. Clearing or restoring startup commands keeps the branch defaults.
64
+ Existing projects without configured defaults can keep the branch saved in
65
+ the Template box snapshot by choosing **From Template box**.
63
66
 
64
67
  Projects using the generated Git startup commands retain their existing reset
65
68
  and clean behavior on the new devbox: tracked files match the fetched branch,
@@ -67,6 +70,7 @@ untracked files are removed, and ignored files such as dependencies remain.
67
70
  Existing projects without those generated commands keep their saved checkout
68
71
  until a branch is explicitly selected. An explicit choice in such a project
69
72
  preserves local work and stops for conflicting changes or unpublished commits.
73
+ That choice applies to the current draft without saving a project default.
70
74
  The Template box is unaffected.
71
75
 
72
76
  Changing a choice while composing prepares the latest selection. Before setup
@@ -88,9 +92,10 @@ can be set from 1 to 120 seconds.
88
92
  Startup scripts can install dependencies, configure the environment, or start
89
93
  services after branch preparation. The standard generated fetch/checkout
90
94
  commands are handled by boxes.dev; any extra commands remain startup work.
91
- Remove branch-switching commands from custom scripts when choosing starting branches.
92
- If setup leaves a repository on another branch, boxes.dev reports the conflict
93
- before starting the agent. A successful checkout alone does not mean an app
95
+ Remove commands that switch branches or reset Git history from custom scripts
96
+ when choosing starting branches. If setup leaves a repository on another
97
+ branch, boxes.dev reports the conflict before starting the agent. A successful
98
+ checkout alone does not mean an app
94
99
  is listening or has rebuilt for that branch.
95
100
 
96
101
  When a project has a devbox startup script, boxes.dev may reserve a
@@ -46,6 +46,10 @@ connecting, changing, or removing Google Cloud.
46
46
 
47
47
  ## How Tools Receive Credentials
48
48
 
49
+ The Google Cloud CLI (`gcloud`) is preinstalled on Template boxes and devboxes,
50
+ including Team Template editing boxes. Existing boxes receive it through
51
+ normal boxes.dev updates; no manual installation or snapshot is needed.
52
+
49
53
  For a connected project, boxes.dev serves Google Cloud credentials on the
50
54
  project's real boxes: the Template box and devboxes in an ordinary project, and
51
55
  the assigned devboxes in a Team Template member project. It does this the same
@@ -123,6 +123,14 @@ Claude session. In a Team Template-managed project, the desktop app warns the
123
123
  member about each missing required value, such as one the team added later,
124
124
  and links to **Project settings**.
125
125
 
126
+ For a Team row, an admin can check **Allow personal override**. In a Team
127
+ Template-managed project, each member can then save a private replacement in
128
+ **Project settings → Environment files**. Without a replacement, the Team value
129
+ is used. **Use team value** removes the member's replacement. Turning the
130
+ checkbox off uses the Team value without deleting saved private replacements;
131
+ turning it back on permits those replacements again. Renaming the variable or
132
+ moving its file still requires the member to approve the new destination.
133
+
126
134
  Project creation groups required values and member files under **Needed to
127
135
  create the project**. **Show optional** starts collapsed, groups rows by destination
128
136
  file and shows search when there are more than eight optional rows. Search
@@ -450,8 +450,9 @@ What these commands change depends on the project:
450
450
  On the Template box they need no extra permission. On a devbox, the current
451
451
  thread needs `edit-project-settings` or `edit-template-box`.
452
452
  - In a Team Template project, they edit the user's own variables: values for
453
- Member rows the team defined, and variables the user added to any file.
454
- Team values belong to the team and cannot be changed here. The current
453
+ Member rows the team defined, personal overrides on Team rows where the admin
454
+ enabled **Allow personal override**, and variables the user added to any file.
455
+ Removing a personal override returns to the Team value. The current
455
456
  thread needs `edit-project-settings`, `edit-personal-environment`, or
456
457
  `edit-team-template` for a team admin.
457
458
 
@@ -682,6 +683,7 @@ Template maintenance uses one script and one complete GitHub watch set:
682
683
  dvb-onbox project maintenance get --json
683
684
  dvb-onbox project maintenance runs --json
684
685
  dvb-onbox project maintenance logs --run <run-id> --json
686
+ dvb-onbox project maintenance run --json
685
687
  dvb-onbox project maintenance apply \
686
688
  --script-file /home/boxes/<file> \
687
689
  --timeout-seconds <1-480> \
@@ -715,6 +717,19 @@ unavailable run IDs return `maintenance_run_not_found`. The existing maintenance
715
717
  permission and Template box or Team Template editing-session requirements also
716
718
  apply to history and logs.
717
719
 
720
+ `run` starts the saved script on the current ordinary Template box, the same
721
+ way as **Run now** in Project settings, and requires **Edit template
722
+ maintenance**. It returns the run's `publicRunId` and a disposition: `create`
723
+ for a new run, `merge` when the request joined a run already waiting to start,
724
+ or `followup` when the run will start after one in progress. A project without
725
+ a saved script returns `maintenance_not_configured`. After the script succeeds,
726
+ boxes.dev saves a snapshot, and agents on the Template box pause briefly while
727
+ it is saved. Follow the run with `runs` until its status is `succeeded`,
728
+ `failed`, or `canceled`, then read `logs`; only `succeeded` means both the
729
+ script and the snapshot finished. Finish a maintenance repair with a successful
730
+ run. In a Team Template editing session, `run` returns `source_box_unavailable`;
731
+ run Team Template maintenance from the desktop app.
732
+
718
733
  The same maintenance commands work in a Team Template's current editing
719
734
  session. They update that Team Template's shared maintenance script and watches
720
735
  and require the editing session's owner to remain a team admin. Use repository
@@ -903,8 +918,9 @@ requests into the repository's default branch. One thread per boxes.dev
903
918
  account handles a pull request's follow-ups at a time.
904
919
 
905
920
  When the project's **Automate follow-ups on new pull requests** Git setting is
906
- on, `gh pr create` turns on all four triggers for the new pull request in the
907
- thread that ran it, and its output ends with a line saying so. A line saying
921
+ on, `gh pr create` turns on the project's default follow-up events for the new
922
+ pull request in the thread that ran it, and its output ends with a line saying
923
+ so and naming the events. A line saying
908
924
  follow-ups only work for pull requests into the default branch means none were
909
925
  turned on, and a line saying boxes.dev couldn't turn them on gives the reason.
910
926
  When gh prints nothing about follow-ups and you need to know whether they are
@@ -925,8 +941,11 @@ repositories and the project has more than one. They always act for the thread
925
941
  that runs them.
926
942
 
927
943
  `--triggers` takes a comma-separated list of `failed-checks`, `bot-reviews`,
928
- `human-reviews`, and `conflicts`. Without it, `enable` turns on all four for a
929
- pull request that has no follow-ups and keeps the current triggers otherwise.
944
+ `human-reviews`, and `conflicts`. Without it, `enable` turns on the project's
945
+ default follow-up events for a pull request that has no follow-ups and keeps
946
+ the current triggers otherwise. The defaults are all four unless the user
947
+ changed them in the project's Git settings; `enable` reports which triggers it
948
+ turned on.
930
949
  `enable` also resumes paused follow-ups that this thread handles.
931
950
 
932
951
  When another thread handles the pull request's follow-ups, `enable` returns
@@ -940,11 +959,11 @@ previous thread still run there.
940
959
  `disable` turns off follow-ups that this thread handles. It can't turn off
941
960
  another thread's follow-ups.
942
961
 
943
- Turn follow-ups on after opening a pull request meant for review, or when you
944
- want to hear about its CI results, unless `gh pr create` reported that they are
945
- already on. Leave them off for throwaway or draft-only experiments unless the
946
- user asks. If you keep getting follow-ups you can't resolve or that aren't
947
- worth acting on, turn them off and tell the user why.
962
+ Run `enable` only when the user has asked for follow-ups. If `gh pr create`
963
+ reported that it turned them on, nothing more is needed. Otherwise, you may
964
+ offer to turn them on after opening a pull request for review. When an
965
+ "Automated PR follow-up" message arrives, handle it as the
966
+ `boxes-pr-followups` skill describes.
948
967
 
949
968
  Errors use these codes: `repo_required`, `no_pull_request`, `pr_closed`,
950
969
  `github_app_required`, `github_cli_unavailable`, `held_by_other_thread`,
@@ -1386,7 +1405,9 @@ Prompt files are limited to 32 KiB.
1386
1405
 
1387
1406
  Delegation does not grant destruction permission or access to unrelated
1388
1407
  threads. To clean up a devbox created this way, see
1389
- [Destroy And Archive Created Devboxes](#destroy-and-archive-created-devboxes). Read-only thread and project discovery has its own permission below.
1408
+ [Destroy And Archive Created Devboxes](#destroy-and-archive-created-devboxes).
1409
+ To archive finished threads started on the current devbox, see
1410
+ [Archive Created Threads On This Devbox](#archive-created-threads-on-this-devbox). Read-only thread and project discovery has its own permission below.
1390
1411
  `dvb-onbox` does not expose arbitrary direct exec, services, or generic machine
1391
1412
  management. The current-box public link commands above are its only port-control
1392
1413
  surface.
@@ -1874,6 +1895,33 @@ request the devbox made for itself. It returns `cancelled`, or `not_pending`
1874
1895
  with a null `requestId` if there is nothing to cancel. Once archival has
1875
1896
  started, it returns `destruction_started`.
1876
1897
 
1898
+ ### Archive Created Threads On This Devbox
1899
+
1900
+ **Destroy and archive created devboxes** also lets any agent on an ordinary
1901
+ devbox archive worker threads created there by agents on that same devbox,
1902
+ such as a worker started with `threads start --target current-devbox`:
1903
+
1904
+ ```bash
1905
+ dvb-onbox threads archive --thread <thread-id> --json
1906
+ ```
1907
+
1908
+ Use the thread ID returned by `threads start` or shown by `threads list`.
1909
+ Archive a thread only after its work is finished and you have collected its
1910
+ result. Any agent on the creating devbox can archive the worker; it doesn't
1911
+ have to be the agent that started it. Archiving keeps the thread's history,
1912
+ and the user can unarchive it in the desktop or mobile app. Repeating the
1913
+ command is safe; `changed` is `false` when the thread was already archived.
1914
+ A Codex thread's saved session on the devbox is updated first; if that fails,
1915
+ the command returns `archive_failed` and the thread stays in the active list.
1916
+
1917
+ The devbox's anchor thread, which is its first thread, returns `anchor_thread`
1918
+ and is archived only when the whole devbox is destroyed and archived.
1919
+ Manually started threads, threads created from another box, and threads on
1920
+ other boxes return `thread_not_found`. Threads that haven't started return
1921
+ `thread_not_ready`, and agents on a Template box get `not_devbox`. After an
1922
+ `archive_disabled` error, request `destroy-created-devboxes`. Permission to
1923
+ destroy this devbox does not grant permission to archive individual workers.
1924
+
1877
1925
  ## Devbox Folders
1878
1926
 
1879
1927
  Project folders group whole ordinary devboxes in the desktop thread list. They
@@ -322,11 +322,20 @@ desktop setup.
322
322
  While reviewing the manifest, the coding agent presents the available instance
323
323
  types and asks the user which one to use. The choice applies to the project's
324
324
  Template box and all of its devboxes and cannot be changed after initialization.
325
- When the repository's `origin` default branch is known, the manifest also
326
- starts with recommended inline shell commands that refresh each new devbox from
327
- that remote branch. Version 3 includes full startup and teardown sections with
328
- independent timeouts. The commands are editable and optional, and a missing
329
- default branch never blocks setup.
325
+ When every selected repository's `origin` default branch is known, the manifest starts
326
+ with generated Git commands that declare the branch to use for new devboxes.
327
+ This also covers repositories in subfolders. If you narrow the repository
328
+ selection, update the generated block's paths to match it.
329
+ boxes.dev recognizes that generated block, saves its branch defaults separately,
330
+ and prepares the checkout before running any remaining startup commands. Normally
331
+ configure the project's starting branch, usually `main`, so new devboxes fetch
332
+ fresh remote code regardless of the Template box's current checkout. Keep the
333
+ generated block intact when adding application setup commands after it. Omit
334
+ it only when the user deliberately wants the Template box's saved checkout;
335
+ without it, an explicit thread branch choice is needed to prepare remote code.
336
+ Version 3 includes full startup and teardown sections with independent timeouts.
337
+ A missing default branch never blocks setup. After setup, clearing the startup
338
+ script does not remove saved branch defaults.
330
339
 
331
340
  Template maintenance starts unconfigured. When the repository needs ongoing
332
341
  environment updates, the coding agent should author the maintenance script and
@@ -627,15 +636,15 @@ or links. The user can instead choose **Use an SSH key for GitHub pull/push
627
636
  access instead**. An explicit SSH or automatic-access choice remains selected
628
637
  when GitHub access refreshes.
629
638
 
630
- Review also shows an editable **Devbox startup script**. For one repository,
631
- boxes.dev recommends commands that refresh the project root from the selected
632
- repository's default branch. For multiple repositories, the recommendation
633
- refreshes every reviewed child folder. The script will run while each future
634
- devbox is prepared for its first thread, before the first prompt is sent. This
635
- keeps the checkout current when the Template-box snapshot contains an older
636
- version. It is optional: the user can edit it or leave it blank, and an unknown
637
- default branch leaves the recommendation blank without blocking project
638
- creation.
639
+ Review's **New devboxes** section shows the **Default branch** separately from
640
+ the optional **Startup script**. boxes.dev fetches and prepares each repository's
641
+ selected branch before running the startup script and sending the first prompt.
642
+ The branch shown here supplies the project default; a thread can choose another
643
+ branch. Use the script for application setup, such as installing dependencies
644
+ or starting services. Leaving it blank skips those extra commands and keeps the
645
+ branch default. If a default branch is unknown, confirm the intended starting
646
+ branch and choose **Use default branch**. Setup can continue without one, but
647
+ then new devboxes inherit the saved checkout unless a thread selects a branch.
639
648
 
640
649
  GitHub creation clones committed Git contents and Git LFS objects. It does not
641
650
  copy uncommitted local work, scan local configuration, install dependencies, or
@@ -848,12 +857,23 @@ loopback address unchecked by default because they depend on software running
848
857
  on the local computer. Remote HTTP MCP definitions stay selected, but their
849
858
  OAuth or token credentials may need to be authorized again on the Template box.
850
859
 
860
+ Claude hooks appear in a separate **Hooks** row. If any hook runs a command,
861
+ the row shows a **Check first** badge and starts unchecked, because a command
862
+ hook whose script or tool is missing on the Template box can stop Claude from
863
+ responding to any prompt. When no hook runs a command, **Hooks** stays
864
+ selected. The rest of the Claude settings stay selected either way and are
865
+ copied without the hooks unless **Hooks** is also selected. Users can select
866
+ **Hooks** when the Template box will have what the commands need.
867
+
851
868
  When desktop local-folder setup detects a Git remote, **Finalize Bundle** shows
852
- an editable **Devbox startup script** field. The field saves shell commands as
853
- the project's startup setting; it does not create a script file on the Template
854
- box. If the default branch cannot be detected, the user can enter it and
855
- populate the recommended commands. Leaving the field blank disables startup
856
- automation and does not block setup.
869
+ **New devboxes**, with the **Default branch** separate from the optional
870
+ **Startup script**. boxes.dev prepares the selected branch before running the
871
+ script. If the default branch cannot be detected, confirm the intended starting
872
+ branch and choose **Use default branch**. Continuing without one preserves the
873
+ saved checkout unless a thread selects a branch. The script field saves shell commands
874
+ in the project settings; it does not create a script file on the Template box.
875
+ Leaving it blank skips extra startup commands and does not remove a branch
876
+ default already shown in the review.
857
877
 
858
878
  ## Git Access
859
879
 
@@ -1029,11 +1049,15 @@ Common recovery paths:
1029
1049
  - Interrupted local setup: resume the setup scan, review, bundle, or upload
1030
1050
  step.
1031
1051
  - Upload failure: retry the upload.
1032
- - Remote Git access failure: choose **Fix Git access**. boxes.dev removes the
1033
- incomplete Template box, keeps the approved setup review and other bundle
1034
- choices, and returns to Finalize Bundle with Git access marked unverified.
1035
- Reconnect GitHub or grant the App access named there, switch to and verify
1036
- SSH, or skip Git access before continuing.
1052
+ - Remote Git SSH verification failure: the message names the Git host and what
1053
+ setup observed: the repository couldn't be read after SSH sign-in, a
1054
+ follow-up SSH connection failed, or sign-in didn't complete although the SSH
1055
+ server answered. Fix what it points to, then choose **Retry setup** to check
1056
+ the same key again. To change or skip Git access, choose **Fix Git access**.
1057
+ boxes.dev removes the incomplete Template box, keeps the approved setup review
1058
+ and other bundle choices, and returns to Finalize Bundle with Git access
1059
+ marked unverified. Reconnect GitHub or grant the App access named there,
1060
+ switch to and verify SSH, or skip Git access before continuing.
1037
1061
  - User-stopped remote setup: choose **Open setup thread** and continue the same
1038
1062
  conversation. boxes.dev keeps the setup thread state and does not
1039
1063
  automatically continue after Stop. When the user and agent agree the setup
@@ -117,12 +117,26 @@ configured, the page shows a short summary with a **Set up maintenance**
117
117
  button that opens the form. The script runs as the `boxes` user in the
118
118
  project's working directory, with a user-selected timeout of up to eight
119
119
  minutes. **Run now** is available after the policy is saved.
120
+
121
+ A maintenance script should fetch and fast-forward each repository it depends
122
+ on to its default branch, then install locked dependencies and refresh
123
+ generated files or tooling without prompts. It should exit nonzero with a
124
+ clear message when a checkout has uncommitted changes or is on another
125
+ branch, when a required value is missing, or when an update fails; a script
126
+ that skips its update and exits 0 saves a stale snapshot. Credentials belong
127
+ in managed environment files, not in the script. The runner starts from a
128
+ login shell, then runs the script with noninteractive bash and
129
+ `set -e -o pipefail`, with `HOME=/home/boxes` and `/opt/devbox-tools/bin` first
130
+ on PATH. Interactive `~/.bashrc` setup, such as nvm's shell hook, does not
131
+ load. Agent setup tests a proposed script twice in this environment before
132
+ saving it.
120
133
  Automatic scheduling is optional; the supported cadences are every 6 hours,
121
134
  every 12 hours, nightly, and weekly.
122
135
 
123
136
  With the separate **Edit template maintenance** Agent permission, a managed
124
137
  agent on the Template box can use `dvb-onbox project maintenance get/apply` to
125
- author the script and complete GitHub watch set together. The command copies a
138
+ author the script and complete GitHub watch set together, and `run` to start
139
+ the saved script and follow its result. The command copies a
126
140
  script and version-1 watch JSON file from regular files under `/home/boxes`,
127
141
  requires the revision returned by `get`, and requires explicit confirmation
128
142
  before removing an editable watch. It preserves the existing repeating
@@ -169,6 +183,25 @@ indicator. Provider-side detection failures stay visible on the affected watch
169
183
  without raising that red indicator; retry them and contact support if they
170
184
  persist.
171
185
 
186
+ The desktop workbench also shows the owner of an ordinary project a maintenance
187
+ attention banner. **Maintenance settings** opens the relevant card. A failed
188
+ or timed-out script offers **Ask an agent to fix it**, which creates a fresh,
189
+ unsent Template box draft with the full saved script, the failed run's script
190
+ if it differs, and the full recorded output tail. It does not enable Agent
191
+ permissions. Dismissing the banner hides it for seven days on that device and
192
+ does not acknowledge the failure or clear the Template row's attention icon.
193
+
194
+ When no maintenance policy exists, a default-branch checkout at least 100
195
+ commits behind GitHub gets a separate reminder to pull or set up maintenance,
196
+ with an agent setup draft shortcut. The check uses the Template's last
197
+ observed HEAD and GitHub without waking the box. It skips unknown commits,
198
+ inaccessible repositories and other branches, and names the most-behind
199
+ repository when there are several. Any saved policy suppresses this reminder.
200
+ After dismissal it returns only after seven days and at least 100 additional
201
+ missing commits. Both dismissals are per viewer, Template and device. These
202
+ banners apply to ordinary projects; Team Template administration has its own
203
+ maintenance workflow.
204
+
172
205
  Maintenance and snapshot creation never overlap, but maintenance may interrupt
173
206
  someone actively using the Template box. Avoid editing or running important
174
207
  interactive work there while a maintenance run is expected.
@@ -241,6 +241,25 @@ start selected under **Add to**; a pasted Codex or Claude setup command selects
241
241
  only its agent. Adjust the selection, then choose **Add MCP** to save and
242
242
  authorize the connection.
243
243
 
244
+ Slack's official MCP server, `https://mcp.slack.com/mcp`, accepts OAuth sign-in
245
+ only from apps registered with Slack, so boxes.dev can't sign in to it. Pasting
246
+ that exact URL in **Add MCP** skips detection, opens **Advanced** with an
247
+ `Authorization` header, and links to the setup steps in the help center. The
248
+ header value is `Bearer ` followed by the user's own Slack user token
249
+ (`xoxp-`). That token comes from an internal or Marketplace Slack app in the
250
+ user's workspace with **Slack Model Context Protocol (MCP) Server** turned on
251
+ under **Agents**, the user token scopes for the wanted tools, and an
252
+ installation by that user; a workspace admin may need to approve the app.
253
+ boxes.dev doesn't renew these tokens, and an app with token rotation turned on
254
+ issues tokens that expire after 12 hours, so use an app without rotation.
255
+ After Slack revokes a token, replace the header value through the row's
256
+ **⋯ → Edit**. On a box, `codex mcp add slack --url
257
+ https://mcp.slack.com/mcp --bearer-token-env-var <VAR>` creates the same
258
+ header connection from a token in that environment variable. Sign-in to any
259
+ other OAuth server that offers neither dynamic client registration nor client
260
+ metadata documents fails with an error saying the provider requires a
261
+ registered app; use an access token header only if that provider issues one.
262
+
244
263
  The mobile app manages the same list under a project's **Project settings →
245
264
  MCPs**, including adding connections and signing in for each agent on the
246
265
  phone. See `mobile.md`.
@@ -373,8 +392,12 @@ blocked from native installation.
373
392
 
374
393
  **Add plugin** in the page header opens a dialog with a Codex tab and a Claude
375
394
  tab. Its single input searches the plugins offered by the marketplaces already
376
- configured on the Template box, and the same input also accepts a marketplace
377
- address or a pasted native command:
395
+ configured on the Template box. For Claude, boxes.dev adds Anthropic's official
396
+ marketplace (`claude-plugins-official`) to the Template box, so the Claude tab
397
+ has plugins to search without any setup, and devboxes get it from a Template
398
+ box snapshot. If the marketplace is removed, boxes.dev adds it back the next
399
+ time the Template box restarts or receives a boxes.dev update. The same input
400
+ also accepts a marketplace address or a pasted native command:
378
401
 
379
402
  - `https://github.com/owner/repo`, or the same address without `https://`
380
403
  - `codex plugin marketplace add <url>` or `claude plugin marketplace add <url>`
@@ -398,15 +421,31 @@ not a public GitHub repository or a plugin that bundles components like MCP
398
421
  servers, hooks, or required configuration that have to be set up on each box.
399
422
  **Install** becomes available once that check finishes.
400
423
 
424
+ When Codex on the Template box is signed in with ChatGPT, the Codex tab also
425
+ names that ChatGPT account by email, and a search there includes plugins from
426
+ OpenAI's catalog for that account. Those rows are labeled **ChatGPT account**.
427
+ Choosing one skips the source check: the plugin is added to the ChatGPT account
428
+ through Codex's own install, not to boxes.dev or the project, so it is neither
429
+ **Managed for this project** nor a **Template box** plugin and needs no
430
+ snapshot. Codex manages it like its other synced plugins, and Codex on the
431
+ Template box stops using it if it signs in to a different account or switches
432
+ to an API key. A plugin that bundles an app, such as Gmail, may still need
433
+ authorization for that app; the page says so after the install. With an
434
+ API-key sign-in the tab says that ChatGPT account plugins are not listed, and
435
+ the API-key catalog's plugins appear as ordinary Template box plugins. This
436
+ needs the Template box's managed Codex to be up to date; an older Codex shows
437
+ the tab without account plugins.
438
+
401
439
  Two collapsed sections hold read-only information and appear only when they have
402
440
  something to show. **Seen only on devboxes** names plugins that reported state
403
441
  places on an ordinary devbox but not on the Template box, along with the
404
442
  devboxes that last reported them. This is saved status only; opening or
405
443
  refreshing the page does not inspect, wake, or change those devboxes. **Synced
406
444
  by Codex** contains provider-backed plugins Codex reports for the signed-in
407
- account and workspace. Codex owns their installation and refresh behavior, and a
408
- Template snapshot is not required for them. A new Codex session is the reliable
409
- boundary for picking up a synced-plugin change.
445
+ account and workspace, including ChatGPT account plugins added from the Codex
446
+ tab, and names that ChatGPT account. Codex owns their installation and refresh
447
+ behavior, and a Template snapshot is not required for them. A new Codex session
448
+ is the reliable boundary for picking up a synced-plugin change.
410
449
 
411
450
  A **Template box** change affects the live Template box immediately, and the
412
451
  page then offers **Snapshot Template box** so future devboxes will inherit it.