@boxes-dev/dvb-runtime 1.0.1092 → 1.0.1093
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/agent-init-guides/agent-config.md +5 -2
- package/dist/agent-init-guides/flow.md +23 -6
- package/dist/agent-init-guides/manifest.md +48 -9
- package/dist/bin/dvb.mjs +310 -50
- package/dist/bin/dvbd.mjs +6 -6
- package/dist/product-docs/references/billing-and-limits.md +6 -1
- package/dist/product-docs/references/cli.md +6 -3
- package/dist/product-docs/references/environment-setup-validation.md +12 -0
- package/dist/product-docs/references/files-git-and-review.md +37 -18
- package/dist/product-docs/references/fork-workflows.md +15 -10
- package/dist/product-docs/references/managed-environment-files.md +8 -0
- package/dist/product-docs/references/onbox-agent-tools.md +60 -12
- package/dist/product-docs/references/project-setup.md +48 -24
- package/dist/product-docs/references/template-box-environment.md +34 -1
- package/dist/product-docs/references/threads-and-agents.md +44 -5
- package/dist/product-docs/references/troubleshooting.md +18 -1
- package/package.json +2 -2
package/dist/bin/dvbd.mjs
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
|
|
3
|
-
!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="
|
|
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.
|
|
64679
|
-
const rawGitSha = "
|
|
64680
|
-
const rawSentryRelease = "boxes-dev-dvb@1.0.
|
|
64678
|
+
const rawPackageVersion = "1.0.1093";
|
|
64679
|
+
const rawGitSha = "a3bbdd5feeb2fd4fdf13c3bcd5f52874812c58aa";
|
|
64680
|
+
const rawSentryRelease = "boxes-dev-dvb@1.0.1093+a3bbdd5feeb2fd4fdf13c3bcd5f52874812c58aa";
|
|
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.
|
|
66897
|
+
const raw = "1.0.1093";
|
|
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=
|
|
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
|
|
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
|
|
119
|
-
|
|
120
|
-
|
|
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
|
|
@@ -607,28 +607,39 @@ that thread's machine and asks the agent to follow up. The events are:
|
|
|
607
607
|
- **Merge conflicts**: the pull request branch conflicts with its base branch.
|
|
608
608
|
|
|
609
609
|
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
|
|
610
|
+
Git/Review, choose **Automate follow-ups**, and select the events. The project's
|
|
611
|
+
default follow-up events are selected to start. The selected
|
|
611
612
|
devbox or Template box needs **GitHub CLI access**, and the boxes.dev GitHub
|
|
612
613
|
App needs access to the repository so GitHub can send the events; personal
|
|
613
614
|
GitHub CLI access alone cannot provide them. Follow-ups work only for pull
|
|
614
615
|
requests into the repository's default branch. An agent can also turn them on
|
|
615
|
-
|
|
616
|
+
with `dvb-onbox pr followups enable` when you ask, and may offer to after it
|
|
617
|
+
opens a pull request; see
|
|
616
618
|
[Pull Request Follow-ups](onbox-agent-tools.md#pull-request-follow-ups).
|
|
617
619
|
|
|
618
620
|
To turn them on for new pull requests automatically, open **Project settings**,
|
|
619
621
|
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
|
|
621
|
-
the project's threads opens a pull request, either
|
|
622
|
-
Git/Review or by an agent running `gh pr create` on one
|
|
623
|
-
devboxes. The thread that opened the pull request handles its
|
|
624
|
-
an agent's `gh pr create` output ends with a line saying they
|
|
625
|
-
setting does not cover pull requests opened
|
|
626
|
-
github.com or with `gh pr create` in your own
|
|
627
|
-
already had an open pull request. It acts only when
|
|
628
|
-
created, so turning a pull request's follow-ups off later
|
|
622
|
+
off by default. While it is on, boxes.dev turns on the project's default
|
|
623
|
+
follow-up events when one of the project's threads opens a pull request, either
|
|
624
|
+
with **Create PR** in Git/Review or by an agent running `gh pr create` on one
|
|
625
|
+
of the project's devboxes. The thread that opened the pull request handles its
|
|
626
|
+
follow-ups, and an agent's `gh pr create` output ends with a line saying they
|
|
627
|
+
are on and naming the events. The setting does not cover pull requests opened
|
|
628
|
+
any other way, such as on github.com or with `gh pr create` in your own
|
|
629
|
+
terminal, or a branch that already had an open pull request. It acts only when
|
|
630
|
+
the pull request is created, so turning a pull request's follow-ups off later
|
|
631
|
+
stays in effect.
|
|
632
|
+
|
|
633
|
+
The project's default follow-up events are all four events unless you change
|
|
634
|
+
them under **Default follow-up events** in the same **Git** settings. They
|
|
635
|
+
apply when follow-ups start for a pull request without anyone choosing events:
|
|
636
|
+
the automatic setting above, and an agent's `dvb-onbox pr followups enable`
|
|
637
|
+
without `--triggers`. Changing them does not change the events of pull requests
|
|
638
|
+
that already have follow-ups.
|
|
629
639
|
|
|
630
640
|
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
|
|
641
|
+
may edit the worktree, run tests, commit, and push to the pull request branch
|
|
642
|
+
when your instructions and the repository's rules allow pushing.
|
|
632
643
|
If a safe fix is not clear, it stops and explains why. When a failing check is
|
|
633
644
|
something it can't fix, it also turns follow-ups off. When feedback needs no
|
|
634
645
|
changes, such as an approval, it says so in the thread and leaves follow-ups
|
|
@@ -643,12 +654,20 @@ conversation. Approvals without a comment, edits, and deletions do not start a
|
|
|
643
654
|
follow-up. Your own reviews and comments never start one, because agents act on
|
|
644
655
|
GitHub as you; message the agent in its thread instead. The owner, member, and
|
|
645
656
|
collaborator filter uses the relationship GitHub reports for each author; it
|
|
646
|
-
does not check whether the author can write to the repository.
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
the
|
|
650
|
-
|
|
651
|
-
|
|
657
|
+
does not check whether the author can write to the repository.
|
|
658
|
+
|
|
659
|
+
Bot review feedback includes a bot's reviews, inline review comments, and
|
|
660
|
+
comments in the pull request's conversation, along with edits to them. A bot's
|
|
661
|
+
approval does not start a follow-up, even when it has a comment.
|
|
662
|
+
|
|
663
|
+
Review bots often post a status comment, a review, and inline comments over a
|
|
664
|
+
minute or two, and people often leave several comments in a row. boxes.dev
|
|
665
|
+
waits until three minutes pass without new review feedback from either, or ten
|
|
666
|
+
minutes after the first, then sends it all in one follow-up. If failed checks
|
|
667
|
+
or a merge conflict need a follow-up in the meantime, it starts right away and
|
|
668
|
+
includes the waiting feedback. The agent replies to or resolves review
|
|
669
|
+
conversations only when your instructions or the project's agent guidance tell
|
|
670
|
+
it to.
|
|
652
671
|
|
|
653
672
|
While a Codex agent is working, its follow-up waits for the current turn to
|
|
654
673
|
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.
|
|
55
|
-
|
|
56
|
-
|
|
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**.
|
|
61
|
-
|
|
62
|
-
|
|
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
|
|
92
|
-
If setup leaves a repository on another
|
|
93
|
-
before starting the agent. A successful
|
|
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
|
|
@@ -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,
|
|
454
|
-
|
|
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
|
|
907
|
-
thread that ran it, and its output ends with 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
|
|
929
|
-
pull request that has no follow-ups and keeps
|
|
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
|
-
|
|
944
|
-
|
|
945
|
-
|
|
946
|
-
|
|
947
|
-
|
|
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).
|
|
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
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
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
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
default branch
|
|
638
|
-
|
|
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
|
-
|
|
853
|
-
|
|
854
|
-
|
|
855
|
-
|
|
856
|
-
|
|
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
|
|
1033
|
-
|
|
1034
|
-
|
|
1035
|
-
|
|
1036
|
-
|
|
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
|
|
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
|
|
377
|
-
|
|
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
|
|
408
|
-
|
|
409
|
-
|
|
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.
|