@boxes-dev/dvb-runtime 1.0.974 → 1.0.976
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/flow.md +14 -4
- package/dist/agent-init-guides/git-ssh.md +6 -0
- package/dist/agent-init-guides/manifest.md +24 -7
- package/dist/bin/dvb.mjs +2356 -1096
- package/dist/bin/dvbd.mjs +8 -8
- package/dist/product-docs/references/agent-tools.md +37 -0
- package/dist/product-docs/references/cli.md +40 -0
- package/dist/product-docs/references/desktop-workbench.md +13 -6
- package/dist/product-docs/references/linear.md +8 -3
- package/dist/product-docs/references/managed-environment-files.md +52 -11
- package/dist/product-docs/references/onbox-agent-tools.md +69 -9
- package/dist/product-docs/references/project-setup.md +29 -13
- package/dist/product-docs/references/slack.md +36 -6
- package/dist/product-docs/references/team-template.md +9 -4
- package/dist/product-docs/references/template-box-environment.md +17 -0
- package/dist/product-docs/references/threads-and-agents.md +8 -7
- 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]="3aca243b-b652-5346-916a-65220deabcd7")}catch(e){}}();
|
|
4
4
|
import { createRequire as __dvbCreateRequire } from "node:module";
|
|
5
5
|
import { dirname as __dvbDirname } from "node:path";
|
|
6
6
|
import { fileURLToPath as __dvbFileURLToPath } from "node:url";
|
|
@@ -96328,8 +96328,8 @@ var init_otel = __esm({
|
|
|
96328
96328
|
return trimmed && trimmed.length > 0 ? trimmed : void 0;
|
|
96329
96329
|
};
|
|
96330
96330
|
readBuildMetadata = () => {
|
|
96331
|
-
const rawPackageVersion = "1.0.
|
|
96332
|
-
const rawGitSha = "
|
|
96331
|
+
const rawPackageVersion = "1.0.976";
|
|
96332
|
+
const rawGitSha = "5768c4b613d1c2ebffc358e464b1b6d51597245f";
|
|
96333
96333
|
const packageVersion = typeof rawPackageVersion === "string" ? rawPackageVersion : void 0;
|
|
96334
96334
|
const gitSha = typeof rawGitSha === "string" ? rawGitSha : void 0;
|
|
96335
96335
|
return { packageVersion, gitSha };
|
|
@@ -128624,9 +128624,9 @@ var init_sentry = __esm({
|
|
|
128624
128624
|
uncaughtExceptionMonitorInstalled = false;
|
|
128625
128625
|
currentDevboxSentryUser = null;
|
|
128626
128626
|
readBuildMetadata2 = () => {
|
|
128627
|
-
const rawPackageVersion = "1.0.
|
|
128628
|
-
const rawGitSha = "
|
|
128629
|
-
const rawSentryRelease = "boxes-dev-dvb@1.0.
|
|
128627
|
+
const rawPackageVersion = "1.0.976";
|
|
128628
|
+
const rawGitSha = "5768c4b613d1c2ebffc358e464b1b6d51597245f";
|
|
128629
|
+
const rawSentryRelease = "boxes-dev-dvb@1.0.976+5768c4b613d1c2ebffc358e464b1b6d51597245f";
|
|
128630
128630
|
const packageVersion = typeof rawPackageVersion === "string" ? rawPackageVersion : void 0;
|
|
128631
128631
|
const gitSha = typeof rawGitSha === "string" ? rawGitSha : void 0;
|
|
128632
128632
|
const sentryRelease = typeof rawSentryRelease === "string" ? rawSentryRelease : void 0;
|
|
@@ -130818,7 +130818,7 @@ var init_packageVersion = __esm({
|
|
|
130818
130818
|
return path8.join(process.cwd(), "dvb");
|
|
130819
130819
|
};
|
|
130820
130820
|
readEmbeddedPackageVersion = () => {
|
|
130821
|
-
const raw = "1.0.
|
|
130821
|
+
const raw = "1.0.976";
|
|
130822
130822
|
return trimVersion(raw);
|
|
130823
130823
|
};
|
|
130824
130824
|
readNearestPackageMetadata = (basePath) => {
|
|
@@ -144013,4 +144013,4 @@ long/umd/index.js:
|
|
|
144013
144013
|
*)
|
|
144014
144014
|
*/
|
|
144015
144015
|
|
|
144016
|
-
//# debugId=
|
|
144016
|
+
//# debugId=3aca243b-b652-5346-916a-65220deabcd7
|
|
@@ -59,6 +59,43 @@ Template member projects. Template-box/devbox rows contain
|
|
|
59
59
|
automation trigger. Only fields needed to understand state or issue follow-up
|
|
60
60
|
commands are included.
|
|
61
61
|
|
|
62
|
+
## Configure Devbox Lifecycle And Template Maintenance
|
|
63
|
+
|
|
64
|
+
After resolving the exact project, read its lifecycle revision before changing
|
|
65
|
+
startup or teardown settings:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
dvb projects lifecycle get --project <project-fingerprint> --json
|
|
69
|
+
dvb projects lifecycle set --project <project-fingerprint> \
|
|
70
|
+
<lifecycle-options> --if-revision <revision> --json
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Script inputs come from local files. Startup and teardown timeouts accept
|
|
74
|
+
1–120 seconds, and clear flags remove either script. A Team Template member
|
|
75
|
+
project supports these project-owned lifecycle defaults. After
|
|
76
|
+
`configuration_conflict`, read and reconcile the newer state; never overwrite
|
|
77
|
+
it with the stale revision.
|
|
78
|
+
|
|
79
|
+
For an ordinary project with a personal Template box, configure the maintenance
|
|
80
|
+
script and complete GitHub watch set as one unit:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
dvb projects maintenance get --project <project-fingerprint> --json
|
|
84
|
+
dvb projects maintenance apply --project <project-fingerprint> \
|
|
85
|
+
--script-file <path> --timeout-seconds <1-480> \
|
|
86
|
+
--watches-file <path> --if-revision <revision> \
|
|
87
|
+
[--confirm-watch-removals] --json
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
The version-1 watch JSON uses `.` or direct-child project repository paths and
|
|
91
|
+
exact repository-relative file or directory paths, not globs. Omitted editable
|
|
92
|
+
watches are removals and need explicit confirmation; read-only watches remain
|
|
93
|
+
unchanged. The write preserves the current repeating schedule. New, changed,
|
|
94
|
+
or re-enabled watches receive a fresh default-branch baseline and do not start
|
|
95
|
+
a run. Team Template member projects return
|
|
96
|
+
`template_maintenance_unavailable` rather than changing their shared Team
|
|
97
|
+
Template.
|
|
98
|
+
|
|
62
99
|
## Create A Devbox Without Starting A Thread
|
|
63
100
|
|
|
64
101
|
After the user approves creating a managed environment:
|
|
@@ -102,6 +102,10 @@ dvb agent-init
|
|
|
102
102
|
The command gives the agent a read-only investigation and planning workflow.
|
|
103
103
|
The agent prepares a manifest with you, checks it, and asks for explicit
|
|
104
104
|
approval before `dvb agent-init run` uploads files or creates a Template box.
|
|
105
|
+
The current version-3 manifest also lets the agent design startup and teardown
|
|
106
|
+
behavior and, when useful, one Template maintenance script with matching GitHub
|
|
107
|
+
watches. Maintenance starts with its repeating schedule off and fresh watch
|
|
108
|
+
baselines; setup does not run the script.
|
|
105
109
|
|
|
106
110
|
## List And Select Machines
|
|
107
111
|
|
|
@@ -129,6 +133,42 @@ opaque continuation cursor. Add `--all` only for a complete inventory.
|
|
|
129
133
|
|
|
130
134
|
See `dvb agent-docs agent-tools` for the complete safe workflow.
|
|
131
135
|
|
|
136
|
+
## Configure Devbox Lifecycle And Template Maintenance
|
|
137
|
+
|
|
138
|
+
A signed-in coding agent on your computer can inspect and edit a project's
|
|
139
|
+
startup and teardown defaults:
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
dvb projects lifecycle get --project <project> --json
|
|
143
|
+
dvb projects lifecycle set --project <project> \
|
|
144
|
+
<lifecycle-options> --if-revision <revision> --json
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
The agent writes scripts to local files and passes their paths with
|
|
148
|
+
`--startup-script-file` or `--teardown-script-file`; the CLI copies the file
|
|
149
|
+
contents. Timeout flags accept 1–120 seconds. Clear flags remove a script.
|
|
150
|
+
Always read first and use its revision. If the revision changed, read again and
|
|
151
|
+
reconcile the newer settings.
|
|
152
|
+
|
|
153
|
+
For an ordinary project with a personal Template box, the agent can design one
|
|
154
|
+
maintenance script and its complete GitHub watch set together:
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
dvb projects maintenance get --project <project> --json
|
|
158
|
+
dvb projects maintenance apply --project <project> \
|
|
159
|
+
--script-file <path> --timeout-seconds <1-480> \
|
|
160
|
+
--watches-file <path> --if-revision <revision> --json
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
The watch file uses version 1 and lists `.` or direct-child project repository
|
|
164
|
+
paths, whether each watch is enabled, and exact repository-relative files or
|
|
165
|
+
directories. Paths are not globs. Omitting an editable existing watch requires
|
|
166
|
+
`--confirm-watch-removals`. The command preserves the repeating schedule and
|
|
167
|
+
does not start a run; new or changed watches begin from a fresh default-branch
|
|
168
|
+
baseline. Team Template member projects support lifecycle editing but return
|
|
169
|
+
`template_maintenance_unavailable` for maintenance because they have no
|
|
170
|
+
personal Template box.
|
|
171
|
+
|
|
132
172
|
## Open A Terminal
|
|
133
173
|
|
|
134
174
|
Use:
|
|
@@ -132,6 +132,12 @@ section without changing its normal thread and devbox workflow.
|
|
|
132
132
|
Use **New project...** in the project selector to add another project. On
|
|
133
133
|
macOS, **File > New Project...** does the same thing.
|
|
134
134
|
|
|
135
|
+
When team access is enabled, **Teammates' projects** opens another team
|
|
136
|
+
member's project in the read-only Team workbench. Team admins also see **Team
|
|
137
|
+
Templates**, with shortcuts to manage non-archived templates, create one, or
|
|
138
|
+
open the complete collection. Team members start a project from a Team Template
|
|
139
|
+
through **New project...** instead of this admin-only management menu.
|
|
140
|
+
|
|
135
141
|
Project settings, integrations, automations, and a teammate's shared thread do
|
|
136
142
|
not select one of your Template boxes or devboxes. On those pages, machine
|
|
137
143
|
status and workspace tools are hidden and the workbench does not wake the
|
|
@@ -177,8 +183,8 @@ Opening it does not select or wake a machine.
|
|
|
177
183
|
The same Settings section opens **Desktop app settings...** and **Configure
|
|
178
184
|
agents...** in separate windows. Desktop app settings contains only preferences
|
|
179
185
|
for the app and terminal on this computer. The account identity at the bottom
|
|
180
|
-
of the left pane opens account, billing, team,
|
|
181
|
-
|
|
186
|
+
of the left pane opens account, billing, team, update, and log-out actions
|
|
187
|
+
without mixing those controls into project settings.
|
|
182
188
|
|
|
183
189
|
## Template box
|
|
184
190
|
|
|
@@ -201,10 +207,11 @@ devbox. See `fork-workflows.md` for that workflow.
|
|
|
201
207
|
|
|
202
208
|
An enabled team can have several named Team Templates: shared starting
|
|
203
209
|
environments that team admins prepare separately from any member's projects.
|
|
204
|
-
|
|
205
|
-
select the exact template
|
|
206
|
-
start the ordinary **New project...** flow and choose **Start
|
|
207
|
-
Template**; project creation does not start from the template
|
|
210
|
+
Team admins can open **Team Templates** from the desktop project selector or
|
|
211
|
+
Team Settings, then select the exact template they want to inspect or edit. To
|
|
212
|
+
create a project, start the ordinary **New project...** flow and choose **Start
|
|
213
|
+
from a Team Template**; project creation does not start from the template
|
|
214
|
+
detail page.
|
|
208
215
|
|
|
209
216
|
Only one admin can edit a particular Team Template at a time; different
|
|
210
217
|
templates have independent editing locks and release histories. **Take
|
|
@@ -33,7 +33,11 @@ the workspace.
|
|
|
33
33
|
After Linear redirects back, the Linear integration home continues through the
|
|
34
34
|
remaining setup steps: link your identity, create your automation, and activate
|
|
35
35
|
it. Team admins can expand **Team connection** there to inspect
|
|
36
|
-
permissions,
|
|
36
|
+
app permissions, the exact Linear teams the agent can access, linked users,
|
|
37
|
+
administrative activity, and technical details. Expand **Linear team access**
|
|
38
|
+
and choose **Manage in Linear** to open the connected workspace's application
|
|
39
|
+
settings. A Linear workspace admin can grant or revoke team access there. After
|
|
40
|
+
the change, a boxes.dev team admin can run **Check** to refresh the list.
|
|
37
41
|
The same team-level information remains available in Team Settings.
|
|
38
42
|
|
|
39
43
|
If Linear reports missing scopes, a revoked app, or invalid token state,
|
|
@@ -63,8 +67,9 @@ attention.
|
|
|
63
67
|
|
|
64
68
|
Your Linear receiver runs when you assign or delegate an issue to the boxes.dev
|
|
65
69
|
Linear agent. It becomes your default receiver for the connected Linear
|
|
66
|
-
workspace, applies across Linear teams and projects
|
|
67
|
-
starts each agent thread on a fresh devbox that appears in the main thread
|
|
70
|
+
workspace, applies across the Linear teams and projects the agent can access,
|
|
71
|
+
and starts each agent thread on a fresh devbox that appears in the main thread
|
|
72
|
+
list.
|
|
68
73
|
|
|
69
74
|
boxes.dev rejects a second active default Linear receiver for the same linked
|
|
70
75
|
Linear user and Linear workspace.
|
|
@@ -6,8 +6,10 @@ behavior.
|
|
|
6
6
|
|
|
7
7
|
## What boxes.dev Manages
|
|
8
8
|
|
|
9
|
-
A project owner can register a project-relative dotenv file
|
|
10
|
-
|
|
9
|
+
A project owner can register a project-relative dotenv file in **Project
|
|
10
|
+
settings → Environment files**. Accepted names are `.env`, `.env.*` and
|
|
11
|
+
`*.env` patterns such as `.env.local` or `config.env`, `.dev.vars`, and
|
|
12
|
+
`.flaskenv`. Each registered file
|
|
11
13
|
has its own list of names, values, optional inline comments, and descriptions.
|
|
12
14
|
The saved values are the source of truth: Template boxes and devboxes receive
|
|
13
15
|
updates, but changes made on a box never update the central copy.
|
|
@@ -28,11 +30,46 @@ New files are created with owner-only permissions. Existing regular files keep
|
|
|
28
30
|
their current owner, group, mode, and content below the marker. Unsafe paths,
|
|
29
31
|
symbolic-link traversal, and non-file destinations are refused.
|
|
30
32
|
|
|
31
|
-
## Adding
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
project's Template box
|
|
35
|
-
|
|
33
|
+
## Adding A File
|
|
34
|
+
|
|
35
|
+
**Add a file** starts by listing the dotenv files that already exist on the
|
|
36
|
+
source boxes.dev reads: the project's Template box, or for a Team Template its
|
|
37
|
+
latest saved version or the admin's current editing session. Check the files to
|
|
38
|
+
register and choose **Add file**, or **Add 3 files** for several at once, so the
|
|
39
|
+
ordinary case needs no typing. **Rescan** repeats the search. Files that are
|
|
40
|
+
already managed stay visible but cannot be added twice, and a very long list may
|
|
41
|
+
be shortened, in which case the editor says so.
|
|
42
|
+
|
|
43
|
+
Several files are reviewed one at a time rather than in bulk, because each file
|
|
44
|
+
gets its own set of choices about which values boxes.dev should manage. The
|
|
45
|
+
editor shows which file is in front of you, such as `Reviewing 2 of 3`, and each
|
|
46
|
+
file is saved as you finish it. A file that fails can be retried or skipped, and
|
|
47
|
+
the rest of the batch carries on; files already saved stay managed even if you
|
|
48
|
+
stop partway, and the editor says so before you do. On a Team Template, adding
|
|
49
|
+
several files reads the source once for the whole batch rather than once per
|
|
50
|
+
file.
|
|
51
|
+
|
|
52
|
+
Choose **New file…** to name a file that does not exist yet. The form is a
|
|
53
|
+
folder and a file name: the folder offers the folders already on the source and
|
|
54
|
+
also accepts one you type, and the line beneath echoes the full location the
|
|
55
|
+
file will have. Naming the folder separately matters because the two surfaces
|
|
56
|
+
resolve paths differently - an ordinary project against its project folder, a
|
|
57
|
+
Team Template against the machine's home directory with each of its repositories
|
|
58
|
+
as a child folder. A file name containing a slash, or a name the dotenv naming
|
|
59
|
+
rule does not accept, is reported straight away, before boxes.dev checks
|
|
60
|
+
anything.
|
|
61
|
+
|
|
62
|
+
If a checked path does not exist but a file with the same name was found in
|
|
63
|
+
another folder, the editor offers that file, so a mistyped folder takes one
|
|
64
|
+
click to correct. The offer is only a suggestion; keeping the path as entered
|
|
65
|
+
is a normal choice.
|
|
66
|
+
|
|
67
|
+
A Template box that has not finished updating shows only a single path box,
|
|
68
|
+
without the list of existing files or the folder chooser.
|
|
69
|
+
|
|
70
|
+
boxes.dev then checks the chosen path. If an ordinary dotenv file exists there,
|
|
71
|
+
the editor recognizes conservative single-line assignments and lets the owner
|
|
72
|
+
choose for each one:
|
|
36
73
|
|
|
37
74
|
- **Manage**: save the value centrally and move the assignment into the managed
|
|
38
75
|
section;
|
|
@@ -51,9 +88,10 @@ preserved below the new managed section.
|
|
|
51
88
|
|
|
52
89
|
When a team admin adds a file to a Team Template, boxes.dev checks the retained
|
|
53
90
|
source box for the latest saved release. Before the first release, it checks
|
|
54
|
-
that admin's current Team Template editing session
|
|
55
|
-
|
|
56
|
-
content, or removed content
|
|
91
|
+
that admin's current Team Template editing session, and the editor says which of
|
|
92
|
+
the two it is reading. The admin must explicitly classify every imported
|
|
93
|
+
assignment as a Team value, a Member value, local content, or removed content
|
|
94
|
+
before saving.
|
|
57
95
|
|
|
58
96
|
Each derived or team-managed project applies that import decision once. If its
|
|
59
97
|
file still matches the reviewed source, boxes.dev moves or removes the selected
|
|
@@ -104,7 +142,10 @@ its snapshot until sync succeeds.
|
|
|
104
142
|
|
|
105
143
|
## Viewing And Recovering Current Values
|
|
106
144
|
|
|
107
|
-
|
|
145
|
+
Saved values are masked in normal project settings. Values that have not been
|
|
146
|
+
saved yet stay readable, both in an import review and while someone types a new
|
|
147
|
+
value, so whoever decides what to manage can see what each value is. **Hide
|
|
148
|
+
values** covers them during a screen share. Revealing a saved value, showing a
|
|
108
149
|
value-bearing file preview, copying the managed file, or exporting it requires
|
|
109
150
|
a fresh confirmation with the Google account linked to the current boxes.dev
|
|
110
151
|
account. That confirmation applies only to the current signed-in session and
|
|
@@ -11,12 +11,16 @@ If a command described here is absent from help, the box has not received that
|
|
|
11
11
|
capability yet. Do not install workstation `dvb`; wait for boxes.dev to update
|
|
12
12
|
the box and try again.
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
existing box or project setting is enabled. Turning
|
|
16
|
-
projected skill from both managed agent homes.
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
14
|
+
Most permission-gated operations appear as focused agent skills only while
|
|
15
|
+
their existing box or project setting is enabled. Turning one of those settings
|
|
16
|
+
off removes its projected skill from both managed agent homes. The devbox
|
|
17
|
+
lifecycle and Template maintenance skill is deliberately always discoverable
|
|
18
|
+
on an ordinary Template box so an agent can inspect the workflow, receive the
|
|
19
|
+
operation-specific denial, and request only the exact missing permission.
|
|
20
|
+
Codex and Claude load the current catalog on their next start or resume; an
|
|
21
|
+
already-running process can retain its startup catalog. Skill visibility is
|
|
22
|
+
discovery, not authorization: each command checks the current setting when it
|
|
23
|
+
runs.
|
|
20
24
|
|
|
21
25
|
The `boxes-agent-permissions` skill is always available so an agent can explain
|
|
22
26
|
and request disabled access. Its presence grants nothing; the exact operation
|
|
@@ -100,6 +104,61 @@ state-changing operation and should run only when the user asks to take or
|
|
|
100
104
|
refresh a snapshot and the environment is ready to become the basis for future
|
|
101
105
|
devboxes.
|
|
102
106
|
|
|
107
|
+
## Devbox Lifecycle And Template Maintenance
|
|
108
|
+
|
|
109
|
+
From the project's current ordinary Template box, an agent can inspect and edit
|
|
110
|
+
the startup and teardown defaults used by future devboxes:
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
dvb-onbox project lifecycle get --json
|
|
114
|
+
dvb-onbox project lifecycle set \
|
|
115
|
+
--startup-script-file /home/boxes/<file> \
|
|
116
|
+
--startup-timeout-seconds <1-120> \
|
|
117
|
+
--teardown-script-file /home/boxes/<file> \
|
|
118
|
+
--teardown-timeout-seconds <1-120> \
|
|
119
|
+
--if-revision <revision> \
|
|
120
|
+
--json
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Each script and timeout flag is optional, and clear flags remove either script.
|
|
124
|
+
Read first, pass the returned revision, and reconcile a newer read after
|
|
125
|
+
`configuration_conflict`. Before saving a nonempty teardown script, explain
|
|
126
|
+
what it does and why the project needs that work when a devbox is destroyed.
|
|
127
|
+
Both lifecycle reads and writes require **Edit devbox lifecycle**.
|
|
128
|
+
|
|
129
|
+
Template maintenance uses one script and one complete GitHub watch set:
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
dvb-onbox project maintenance get --json
|
|
133
|
+
dvb-onbox project maintenance apply \
|
|
134
|
+
--script-file /home/boxes/<file> \
|
|
135
|
+
--timeout-seconds <1-480> \
|
|
136
|
+
--watches-file /home/boxes/<file> \
|
|
137
|
+
--if-revision <revision> \
|
|
138
|
+
[--confirm-watch-removals] \
|
|
139
|
+
--json
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Design the maintenance script and watches together. The version-1 JSON watch
|
|
143
|
+
file lists each project repository (`.` or a direct-child project-relative
|
|
144
|
+
path), an enabled boolean, and exact repository-relative file or directory
|
|
145
|
+
paths. Globs are not supported. The command copies regular files whose resolved
|
|
146
|
+
paths remain inside `/home/boxes`; it does not keep following the source files.
|
|
147
|
+
|
|
148
|
+
Applying maintenance preserves its current repeating schedule. Unchanged
|
|
149
|
+
watches keep their baseline, while new, changed, or re-enabled watches start
|
|
150
|
+
from the current default branch and do not run maintenance immediately.
|
|
151
|
+
Omitting an editable existing watch requires `--confirm-watch-removals`;
|
|
152
|
+
grandfathered read-only watches remain unchanged. Maintenance reads and writes
|
|
153
|
+
require **Edit template maintenance**, a separate permission that covers the
|
|
154
|
+
script and GitHub watches together.
|
|
155
|
+
|
|
156
|
+
These settings are devbox lifecycle and Template maintenance, not boxes.dev
|
|
157
|
+
Automations. The commands accept no project, box, owner, or repository ID and
|
|
158
|
+
fail outside the current ordinary Template box. If either operation reports
|
|
159
|
+
disabled access, request only `edit-devbox-lifecycle` or
|
|
160
|
+
`edit-template-maintenance`, respectively.
|
|
161
|
+
|
|
103
162
|
## Current Thread Link
|
|
104
163
|
|
|
105
164
|
A managed Codex or Claude agent can ask boxes.dev for the permanent link to
|
|
@@ -138,9 +197,10 @@ dvb-onbox permissions request \
|
|
|
138
197
|
--permission create-devboxes-and-threads
|
|
139
198
|
```
|
|
140
199
|
|
|
141
|
-
The
|
|
200
|
+
The seven request values are `create-devboxes-and-threads`,
|
|
142
201
|
`create-team-templates`, `update-thread-titles`,
|
|
143
|
-
`move-devboxes-to-folders`,
|
|
202
|
+
`move-devboxes-to-folders`, `create-devbox-folders`,
|
|
203
|
+
`edit-devbox-lifecycle`, and `edit-template-maintenance`. Add `--json` for a
|
|
144
204
|
stable structured result.
|
|
145
205
|
|
|
146
206
|
The command creates one request for the exact managed thread and source box,
|
|
@@ -765,7 +825,7 @@ dvb-onbox team-template edit-box status --edit-box <edit-box-id> --json
|
|
|
765
825
|
Use the target commands below to finish the filesystem setup. For a bounded
|
|
766
826
|
script that may take longer than two minutes, use a regular file and a stable
|
|
767
827
|
key; it runs through the same attested target access and accepts up to 20
|
|
768
|
-
minutes,
|
|
828
|
+
minutes, 3 MiB of script input, and 4 MiB per output stream:
|
|
769
829
|
|
|
770
830
|
```bash
|
|
771
831
|
dvb-onbox team-template edit-box run --edit-box <edit-box-id> \
|
|
@@ -107,7 +107,7 @@ open that project in the desktop app, so the handoff page does not need to stay
|
|
|
107
107
|
open.
|
|
108
108
|
|
|
109
109
|
The commands mirror the wizard's stages: `dvb agent-init start` seeds the
|
|
110
|
-
version
|
|
110
|
+
version 3 manifest with everything detectable. A standard GitHub origin seeds
|
|
111
111
|
managed access without waiting for connection or repository inventory; the
|
|
112
112
|
manifest can instead select SSH or skip Git access. If GitHub is not connected,
|
|
113
113
|
`dvb agent-init github connect` opens the existing boxes.dev GitHub connection
|
|
@@ -117,20 +117,35 @@ is required, it prints the exact GitHub action and the SSH alternative. `dvb
|
|
|
117
117
|
agent-init run` executes the whole plan — encrypted bundle, upload, Template
|
|
118
118
|
box creation, Git access configuration, and the same remote setup thread as
|
|
119
119
|
desktop setup. Non-GitHub repositories keep their existing SSH entries.
|
|
120
|
-
Existing version 1 manifests remain supported without changes.
|
|
121
|
-
status` always reports the current stage and next action, and
|
|
122
|
-
guide` prints the workflow instructions the agent follows. If
|
|
123
|
-
interrupted, the same resume, retry, and start-over rules apply as for
|
|
124
|
-
setup.
|
|
120
|
+
Existing version 1 and version 2 manifests remain supported without changes.
|
|
121
|
+
`dvb agent-init status` always reports the current stage and next action, and
|
|
122
|
+
`dvb agent-init guide` prints the workflow instructions the agent follows. If
|
|
123
|
+
`run` is interrupted, the same resume, retry, and start-over rules apply as for
|
|
124
|
+
desktop setup.
|
|
125
125
|
|
|
126
126
|
While reviewing the manifest, the coding agent presents the available instance
|
|
127
127
|
types and asks the user which one to use. The choice applies to the project's
|
|
128
128
|
Template box and all of its devboxes and cannot be changed after initialization.
|
|
129
129
|
When the repository's `origin` default branch is known, the manifest also
|
|
130
130
|
starts with recommended inline shell commands that refresh each new devbox from
|
|
131
|
-
that remote branch.
|
|
132
|
-
|
|
133
|
-
blocks setup.
|
|
131
|
+
that remote branch. Version 3 includes full startup and teardown sections with
|
|
132
|
+
independent timeouts. The commands are editable and optional, and a missing
|
|
133
|
+
default branch never blocks setup.
|
|
134
|
+
|
|
135
|
+
Template maintenance starts unconfigured. When the repository needs ongoing
|
|
136
|
+
environment updates, the coding agent should author the maintenance script and
|
|
137
|
+
its GitHub watches together so the watched files match the work the script
|
|
138
|
+
performs. Declared watches need boxes.dev GitHub App pull access and a current
|
|
139
|
+
default branch even when project Git uses SSH. The launch review reports the
|
|
140
|
+
lifecycle timeouts, maintenance timeout, watch and path counts, and that the
|
|
141
|
+
repeating schedule is off, baselines are fresh, and setup will not run the
|
|
142
|
+
maintenance script. Script bodies stay in the reviewed manifest instead of
|
|
143
|
+
being repeated in the summary.
|
|
144
|
+
|
|
145
|
+
After the Template box is registered, setup applies the reviewed lifecycle and
|
|
146
|
+
maintenance configuration before completion. If a declared repository loses
|
|
147
|
+
App access, setup pauses with the exact reconnect or access action. Retrying
|
|
148
|
+
after access is restored continues without duplicate maintenance records.
|
|
134
149
|
|
|
135
150
|
For database dumps in agent-driven setup, the manifest names the exact env file
|
|
136
151
|
and variable without storing the secret value. `dvb agent-init check` performs
|
|
@@ -303,10 +318,11 @@ when GitHub access refreshes.
|
|
|
303
318
|
Review also shows an editable **Devbox startup script**. For one repository,
|
|
304
319
|
boxes.dev recommends commands that refresh the project root from the selected
|
|
305
320
|
repository's default branch. For multiple repositories, the recommendation
|
|
306
|
-
refreshes every reviewed child folder. The script
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
321
|
+
refreshes every reviewed child folder. The script will run while each future
|
|
322
|
+
devbox is prepared for its first thread, before the first prompt is sent. This
|
|
323
|
+
keeps the checkout current when the Template-box snapshot contains an older
|
|
324
|
+
version. It is optional: the user can edit it or leave it blank, and an unknown
|
|
325
|
+
default branch leaves the recommendation blank without blocking project
|
|
310
326
|
creation.
|
|
311
327
|
|
|
312
328
|
GitHub creation clones committed Git contents and Git LFS objects. It does not
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# Slack Integration
|
|
2
2
|
|
|
3
3
|
The Slack integration lets you mention `@boxes.dev` to start an automation on a
|
|
4
|
-
fresh devbox,
|
|
5
|
-
replies back in Slack.
|
|
4
|
+
fresh devbox, start a thread in an opted-in teammate's workspace, send
|
|
5
|
+
follow-ups to the linked agent thread, and receive final replies back in Slack.
|
|
6
6
|
|
|
7
7
|
Use `automations.md` for general automation behavior. This doc covers the Slack
|
|
8
8
|
parts.
|
|
@@ -68,6 +68,14 @@ Your default Slack receiver runs when you mention `@boxes.dev` without a named
|
|
|
68
68
|
command. Each mention starts an agent thread on a fresh devbox and appears in
|
|
69
69
|
the main thread list alongside other devbox threads.
|
|
70
70
|
|
|
71
|
+
To start your own thread, mention `@boxes.dev` and write your request. Under
|
|
72
|
+
**Who else can trigger a new thread?**, choose **No one** (the default),
|
|
73
|
+
**Teammates I choose**, or **Any teammate with Slack connected**. This setting
|
|
74
|
+
belongs to you: teammates cannot give themselves access. Anyone you allow must
|
|
75
|
+
be an active member of the same boxes.dev team with a linked identity in the
|
|
76
|
+
connected Slack workspace. They can start a thread in your workspace by
|
|
77
|
+
mentioning `@boxes.dev @YourName`, followed by their request.
|
|
78
|
+
|
|
71
79
|
## Create A Slack Named Command Automation
|
|
72
80
|
|
|
73
81
|
In the desktop workbench, create an automation and choose **Slack** as the
|
|
@@ -90,7 +98,7 @@ When you choose **Only selected channels**, the editor shows the channel
|
|
|
90
98
|
picker below the menu.
|
|
91
99
|
|
|
92
100
|
For named commands, choose who can run it. The owner can always run it; you can
|
|
93
|
-
also allow
|
|
101
|
+
also allow chosen teammates or any teammate with Slack connected.
|
|
94
102
|
|
|
95
103
|
## Running From Slack
|
|
96
104
|
|
|
@@ -106,6 +114,18 @@ For a named command:
|
|
|
106
114
|
@boxes.dev !bugfix investigate the auth error above and suggest a fix
|
|
107
115
|
```
|
|
108
116
|
|
|
117
|
+
To start a thread in a teammate's workspace:
|
|
118
|
+
|
|
119
|
+
```text
|
|
120
|
+
@boxes.dev @Ananya investigate the failed deploy above
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
The teammate mention must immediately follow `@boxes.dev`, and a request must
|
|
124
|
+
follow the teammate mention. The teammate must have allowed you through their
|
|
125
|
+
default Slack receiver's access setting. The new agent thread belongs to that
|
|
126
|
+
teammate and uses their automation, Template box, devbox, credentials, and
|
|
127
|
+
usage. It does not copy either teammate's existing devbox filesystem.
|
|
128
|
+
|
|
109
129
|
boxes.dev starts each automation run on a fresh devbox from the latest
|
|
110
130
|
Template box snapshot. The agent sees the automation prompt plus Slack context,
|
|
111
131
|
including the triggering message and available Slack thread messages. If Slack
|
|
@@ -117,9 +137,11 @@ time, subject to awake devbox capacity. If Slack retries the same event,
|
|
|
117
137
|
boxes.dev reuses the already linked automation run instead of starting a
|
|
118
138
|
duplicate.
|
|
119
139
|
|
|
120
|
-
Slack receives a started reply with a link to the boxes.dev thread.
|
|
121
|
-
|
|
122
|
-
the
|
|
140
|
+
Slack receives a started reply with a link to the boxes.dev thread. When a
|
|
141
|
+
teammate starts a thread in your workspace, the reply names you and boxes.dev
|
|
142
|
+
sends you a direct message with links to the source Slack message and new
|
|
143
|
+
boxes.dev thread. If final Slack replies are enabled, boxes.dev posts the
|
|
144
|
+
agent's final answer back into the same Slack thread or DM.
|
|
123
145
|
|
|
124
146
|
## Follow-Ups And Controls
|
|
125
147
|
|
|
@@ -127,6 +149,10 @@ After a Slack request starts a boxes.dev thread, mention `@boxes.dev` again in
|
|
|
127
149
|
the same Slack thread to send a follow-up. Ordinary Slack replies without the
|
|
128
150
|
mention stay in Slack and are not sent to the agent.
|
|
129
151
|
|
|
152
|
+
To start a new teammate-owned run from an already linked Slack thread,
|
|
153
|
+
explicitly name the teammate again: `@boxes.dev @Ananya <request>`. Later
|
|
154
|
+
unqualified follow-ups in that Slack thread go to the newest run.
|
|
155
|
+
|
|
130
156
|
Use Slack controls in the linked thread:
|
|
131
157
|
|
|
132
158
|
- `@boxes.dev !help` shows available commands when help is needed.
|
|
@@ -163,6 +189,10 @@ omission in Slack, and tells the agent which intended input was not delivered.
|
|
|
163
189
|
If the work depends on an omitted file, attach it manually in the boxes.dev
|
|
164
190
|
thread.
|
|
165
191
|
|
|
192
|
+
Slack file import transfers only the eligible Slack attachments included with
|
|
193
|
+
the request or its thread context. Starting a thread in a teammate's workspace
|
|
194
|
+
never transfers files from an existing teammate devbox.
|
|
195
|
+
|
|
166
196
|
Change the setting in the automation's own editor. For the default
|
|
167
197
|
`@boxes.dev` mention, open **Configure** on the **Default behavior** card on the
|
|
168
198
|
Slack integration home to reach that editor.
|
|
@@ -49,10 +49,15 @@ a saved version or a project created from it.
|
|
|
49
49
|
|
|
50
50
|
## Finding And Managing Team Templates
|
|
51
51
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
52
|
+
Team admins can open **Team Templates** from the desktop project selector or
|
|
53
|
+
**Manage team**. The project-selector submenu links directly to each
|
|
54
|
+
non-archived template and includes **New Team Template...** and **View all Team
|
|
55
|
+
Templates**. The collection shows each named template separately, including
|
|
56
|
+
its description, machine size, latest saved version, and editing status. Team
|
|
57
|
+
admins can also reveal archived templates here.
|
|
58
|
+
|
|
59
|
+
Team members do not see the management submenu. To create a project from a
|
|
60
|
+
saved template, choose **New project...**, then **Start from a Team Template**.
|
|
56
61
|
|
|
57
62
|
Admins create a Team Template from this collection. The default flow starts
|
|
58
63
|
from GitHub: choose one or several existing repositories, or create a new
|
|
@@ -98,6 +98,13 @@ Doing this on an ordinary devbox stays local to that devbox and does not create
|
|
|
98
98
|
a Template snapshot. See `files-git-and-review.md` for the full add, review,
|
|
99
99
|
repair, access-recovery, and unsupported-layout behavior.
|
|
100
100
|
|
|
101
|
+
When **Edit devbox lifecycle** is enabled for the Template box, its managed
|
|
102
|
+
agents can use `dvb-onbox project lifecycle get/set` to update the same startup
|
|
103
|
+
script, teardown script, and timeouts shown in Project settings. The command is
|
|
104
|
+
revision-checked, reads script content from regular files under `/home/boxes`,
|
|
105
|
+
and cannot target another project or box. This lifecycle setting is unrelated
|
|
106
|
+
to boxes.dev Automations.
|
|
107
|
+
|
|
101
108
|
## Template Maintenance
|
|
102
109
|
|
|
103
110
|
The Template box page in the desktop app can keep an established environment
|
|
@@ -109,6 +116,16 @@ minutes. **Run now** is available after the policy is saved.
|
|
|
109
116
|
Automatic scheduling is optional; the supported cadences are every 6 hours,
|
|
110
117
|
every 12 hours, nightly, and weekly.
|
|
111
118
|
|
|
119
|
+
With the separate **Edit template maintenance** Agent permission, a managed
|
|
120
|
+
agent on the Template box can use `dvb-onbox project maintenance get/apply` to
|
|
121
|
+
author the script and complete GitHub watch set together. The command copies a
|
|
122
|
+
script and version-1 watch JSON file from regular files under `/home/boxes`,
|
|
123
|
+
requires the revision returned by `get`, and requires explicit confirmation
|
|
124
|
+
before removing an editable watch. It preserves the existing repeating
|
|
125
|
+
schedule. New, changed, or re-enabled watches receive a fresh baseline without
|
|
126
|
+
starting a maintenance run. Turning this permission on or off does not change
|
|
127
|
+
**Edit devbox lifecycle** or any saved configuration.
|
|
128
|
+
|
|
112
129
|
When GitHub is connected, a policy can also watch exact repository-relative
|
|
113
130
|
files or directories on each repository's default branch. Only the project's own
|
|
114
131
|
GitHub repositories can be watched: the point is to react to the project's own
|
|
@@ -713,13 +713,14 @@ Team admins choose **Thread access** in Team settings:
|
|
|
713
713
|
- **All threads** lets teammates browse and read eligible threads unless the
|
|
714
714
|
owner marked one private.
|
|
715
715
|
|
|
716
|
-
With **Thread titles** or **All threads**, use **
|
|
717
|
-
project selector or mobile Home to choose a teammate's project.
|
|
718
|
-
reuses the familiar devbox, thread-list, transcript, and
|
|
719
|
-
layout in read-only form. It does not include a composer,
|
|
720
|
-
ports, or runtime controls. Opening Team work or a
|
|
721
|
-
select or wake the viewer's last Template box or
|
|
722
|
-
teammate's work does not add it to **Shared with
|
|
716
|
+
With **Thread titles** or **All threads**, use **Teammates' projects** in the
|
|
717
|
+
desktop project selector or mobile Home to choose a teammate's project. The
|
|
718
|
+
Team workbench reuses the familiar devbox, thread-list, transcript, and
|
|
719
|
+
optional Template-box layout in read-only form. It does not include a composer,
|
|
720
|
+
Files, Git/Review, terminal, ports, or runtime controls. Opening Team work or a
|
|
721
|
+
shared transcript does not select or wake the viewer's last Template box or
|
|
722
|
+
devbox. Merely browsing a teammate's work does not add it to **Shared with
|
|
723
|
+
me**.
|
|
723
724
|
|
|
724
725
|
An owner can also share an eligible started Codex or Claude Code transcript
|
|
725
726
|
with anyone on their team who has the link. The share includes the live durable
|