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