@boxes-dev/dvb-runtime 1.0.1062 → 1.0.1064
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/git-signing.md +7 -0
- package/dist/bin/dvb.mjs +241 -103
- package/dist/bin/dvbd.mjs +4 -4
- package/dist/product-docs/SKILL.md +8 -3
- package/dist/product-docs/references/agent-tools.md +3 -0
- package/dist/product-docs/references/cli.md +6 -6
- package/dist/product-docs/references/core-concepts.md +5 -3
- package/dist/product-docs/references/desktop-workbench.md +6 -0
- package/dist/product-docs/references/files-git-and-review.md +54 -20
- package/dist/product-docs/references/mobile.md +11 -1
- package/dist/product-docs/references/onbox-agent-tools.md +173 -22
- package/dist/product-docs/references/project-setup.md +87 -44
- package/dist/product-docs/references/security-and-data.md +14 -13
- package/dist/product-docs/references/template-box-environment.md +15 -9
- package/dist/product-docs/references/threads-and-agents.md +36 -12
- package/dist/product-docs/references/troubleshooting.md +11 -11
- package/package.json +2 -2
package/dist/bin/dvbd.mjs
CHANGED
|
@@ -64674,9 +64674,9 @@ var init_sentry = __esm({
|
|
|
64674
64674
|
uncaughtExceptionMonitorInstalled = false;
|
|
64675
64675
|
currentDevboxSentryUser = null;
|
|
64676
64676
|
readBuildMetadata = () => {
|
|
64677
|
-
const rawPackageVersion = "1.0.
|
|
64678
|
-
const rawGitSha = "
|
|
64679
|
-
const rawSentryRelease = "boxes-dev-dvb@1.0.
|
|
64677
|
+
const rawPackageVersion = "1.0.1064";
|
|
64678
|
+
const rawGitSha = "29f88cda72014ceed9419cc5b1ce95333682be41";
|
|
64679
|
+
const rawSentryRelease = "boxes-dev-dvb@1.0.1064+29f88cda72014ceed9419cc5b1ce95333682be41";
|
|
64680
64680
|
const packageVersion = typeof rawPackageVersion === "string" ? rawPackageVersion : void 0;
|
|
64681
64681
|
const gitSha = typeof rawGitSha === "string" ? rawGitSha : void 0;
|
|
64682
64682
|
const sentryRelease = typeof rawSentryRelease === "string" ? rawSentryRelease : void 0;
|
|
@@ -66893,7 +66893,7 @@ var init_packageVersion = __esm({
|
|
|
66893
66893
|
return path8.join(process.cwd(), "dvb");
|
|
66894
66894
|
};
|
|
66895
66895
|
readEmbeddedPackageVersion = () => {
|
|
66896
|
-
const raw = "1.0.
|
|
66896
|
+
const raw = "1.0.1064";
|
|
66897
66897
|
return trimVersion(raw);
|
|
66898
66898
|
};
|
|
66899
66899
|
readNearestPackageMetadata = (basePath) => {
|
|
@@ -25,9 +25,14 @@ coding agent running inside a boxes.dev Template box or devbox, read only the
|
|
|
25
25
|
relevant section of `references/onbox-agent-tools.md` before completing setup,
|
|
26
26
|
taking a snapshot, delegating work, reading or changing the current thread
|
|
27
27
|
title, moving devboxes to project folders, creating a Git commit with
|
|
28
|
-
optional thread attribution, or using Team Template commands.
|
|
29
|
-
|
|
30
|
-
|
|
28
|
+
optional thread attribution, or using Team Template commands.
|
|
29
|
+
For Project settings, Team Template settings, or the source of inherited Agent
|
|
30
|
+
Guidance, read **Project And Team Template Settings** in that reference and use
|
|
31
|
+
its settings commands. Read the project's captured creation input before
|
|
32
|
+
comparing current template defaults. Settings reads need no editing grant.
|
|
33
|
+
|
|
34
|
+
The documented command is authoritative about whether an optional capability
|
|
35
|
+
is enabled; a disabled or unavailable result is normal and
|
|
31
36
|
must not block unrelated work. Do not read `agent-tools.md`, probe workstation
|
|
32
37
|
`dvb`, or look up project inventory from a managed box; those are not part of
|
|
33
38
|
the on-box tool surface. For other product questions, read
|
|
@@ -200,6 +200,9 @@ supports current Codex and Claude threads, not the retired `claude_code` type.
|
|
|
200
200
|
Add `--muted` when the user asks for a quiet thread, such as a worker whose
|
|
201
201
|
result you will collect yourself. A muted thread's finished turns don't notify
|
|
202
202
|
the user or mark it unread; requests for input still do.
|
|
203
|
+
A Claude thread started this way behaves like one started in the desktop app:
|
|
204
|
+
people can reply to it from desktop or mobile, and `dvb agents` asks before
|
|
205
|
+
moving it into a terminal.
|
|
203
206
|
|
|
204
207
|
The result contains a durable `operationId` and stable `clientThreadId`. Retry
|
|
205
208
|
the same logical start with the same idempotency key and identical arguments.
|
|
@@ -300,12 +300,12 @@ surface-specific Claude mode. Press `Esc` before submission to discard a blank
|
|
|
300
300
|
draft or keep a non-blank draft; while waiting for `Ctrl+O`, `Esc` cancels only
|
|
301
301
|
the automatic open and leaves the agent running.
|
|
302
302
|
|
|
303
|
-
|
|
304
|
-
Claude threads in the desktop app. They do not use a
|
|
305
|
-
type. The desktop app can observe their progress and use
|
|
306
|
-
interrupt-and-transfer flow when control needs to move between
|
|
307
|
-
use the same autonomous permission mode as Claude threads
|
|
308
|
-
desktop app.
|
|
303
|
+
Claude threads created from this composer use a persistent Claude terminal
|
|
304
|
+
but remain ordinary Claude threads in the desktop app. They do not use a
|
|
305
|
+
separate conversation type. The desktop app can observe their progress and use
|
|
306
|
+
the usual interrupt-and-transfer flow when control needs to move between
|
|
307
|
+
surfaces. They use the same autonomous permission mode as Claude threads
|
|
308
|
+
started from the desktop app.
|
|
309
309
|
|
|
310
310
|
For a bounded noninteractive snapshot, use:
|
|
311
311
|
|
|
@@ -76,9 +76,11 @@ Template box, they operate on the Template box.
|
|
|
76
76
|
## Snapshot
|
|
77
77
|
|
|
78
78
|
A snapshot is a saved state of an ordinary project's Template box that future
|
|
79
|
-
devboxes can start from. A snapshot preserves the saved filesystem
|
|
80
|
-
development data
|
|
81
|
-
|
|
79
|
+
devboxes can start from. A snapshot preserves the saved filesystem, local
|
|
80
|
+
development data, and memory. Apps that run independently of agents and
|
|
81
|
+
terminals, such as Docker containers and system services, keep running on new
|
|
82
|
+
devboxes. Copied agents, terminals, and processes started from them do not
|
|
83
|
+
continue, and background services from setup start again. Team Template
|
|
82
84
|
member projects use the Team Template's current saved version instead; team
|
|
83
85
|
admins update it from the Team Template editor.
|
|
84
86
|
|
|
@@ -51,6 +51,12 @@ sign-in in your browser while the current account stays open, then switches to
|
|
|
51
51
|
the new account once sign-in finishes. With only one account signed in, it
|
|
52
52
|
appears directly in the account menu at the bottom of the left pane.
|
|
53
53
|
|
|
54
|
+
While the app waits for Google sign-in, on first sign-in or when adding an
|
|
55
|
+
account, **Open in browser** opens the sign-in page again and **Copy link**
|
|
56
|
+
copies its address for another browser on the same computer. Use them when the
|
|
57
|
+
browser didn't show the page or its tab was closed. If neither button appears,
|
|
58
|
+
update the desktop app.
|
|
59
|
+
|
|
54
60
|
Once more than one account is signed in, the account menu shows **Switch
|
|
55
61
|
account** in its place. That submenu lists every signed-in account, with a
|
|
56
62
|
check beside the current one; click another account to switch. The workbench
|
|
@@ -373,20 +373,50 @@ An explicitly cleared identity will stay off until you configure it again.
|
|
|
373
373
|
|
|
374
374
|
## GitHub CLI In Terminals And Agents
|
|
375
375
|
|
|
376
|
-
Connecting or reconnecting GitHub turns on **GitHub CLI
|
|
376
|
+
Connecting or reconnecting GitHub turns on **GitHub CLI access** by
|
|
377
377
|
default. For supported GitHub repositories, first-run desktop setup shows the
|
|
378
378
|
checked **Allow GitHub CLI in devboxes** choice in **Finalize Bundle → GitHub
|
|
379
379
|
access**. Keep it selected to let terminal commands and coding agents use `gh`,
|
|
380
380
|
or clear it before continuing to turn the grant back off. Later, open
|
|
381
381
|
**Integrations → GitHub** to change the account-wide choice at any time.
|
|
382
382
|
Commands such as `gh pr`, `gh run`, and `gh api` use the connected user's
|
|
383
|
-
identity.
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
383
|
+
identity. Managed `gh` prefers connected personal access, subject to the user's
|
|
384
|
+
GitHub permissions and organization authorization. Without personal access, it
|
|
385
|
+
uses GitHub App access after checking every known project repository; that
|
|
386
|
+
credential can reach repositories available to both the user and the App.
|
|
387
|
+
GitHub will enforce the active credential's permissions on each command.
|
|
388
|
+
|
|
389
|
+
Personal sign-in is optional even when App repository access works. Choose
|
|
390
|
+
**Enable** under **Full GitHub CLI access (optional)** in Account, Integrations →
|
|
391
|
+
GitHub, or the optional follow-up in onboarding or project setup, or run `gh auth login` inside a
|
|
392
|
+
managed machine. The App covers pull, push, pull requests, and CLI commands
|
|
393
|
+
within its permissions; personal authorization enables broader CLI use,
|
|
394
|
+
including starting workflows, within the approved scopes and the user's
|
|
395
|
+
permissions. Login will show a
|
|
396
|
+
one-time code and GitHub approval URL and wait for approval with the same GitHub
|
|
397
|
+
account connected to boxes.dev. GitHub will request the official GitHub CLI's
|
|
398
|
+
`repo`, `read:org`, `gist`, and `workflow` scopes, including GitHub Actions
|
|
399
|
+
access. boxes.dev will store the
|
|
400
|
+
authorization centrally and reuse it across the user's Template boxes and
|
|
401
|
+
devboxes; it will not create a native machine-local login.
|
|
402
|
+
|
|
403
|
+
After authorization, Integrations and setup surfaces with selected repositories
|
|
404
|
+
will check personal access to those repositories. A red warning will name any
|
|
405
|
+
repository it cannot reach and explain that GitHub CLI commands for it will
|
|
406
|
+
fail. Open **GitHub permissions** to authorize the official GitHub CLI for the
|
|
407
|
+
organization, complete any required SSO sign-in, and choose **Check again**.
|
|
408
|
+
Alternatively, choose **Disconnect personal access** to return managed `gh` to
|
|
409
|
+
App access. This check won't switch credentials or block setup. It confirms
|
|
410
|
+
repository access, while GitHub enforces each command's permissions. A provider
|
|
411
|
+
outage or rate limit will show that access couldn't be checked rather than
|
|
412
|
+
claiming that permission is missing.
|
|
413
|
+
|
|
414
|
+
When the App has read-only Actions access, reviewed `gh workflow run` and
|
|
415
|
+
`gh run rerun` commands will suggest personal sign-in. This advice does not
|
|
416
|
+
block, retry, or replay the command. After approval, rerun the command explicitly.
|
|
417
|
+
Other GitHub failures do not automatically start authorization. If approval is
|
|
418
|
+
denied, a code expires, or the wrong account was used, run `gh auth login` again
|
|
419
|
+
and approve with the displayed account.
|
|
390
420
|
|
|
391
421
|
For a GitHub-backed project, **Integrations → GitHub** also checks whether the
|
|
392
422
|
boxes.dev GitHub App can access that project's repositories. If access is
|
|
@@ -394,11 +424,14 @@ missing, the page names the affected repository and opens the applicable
|
|
|
394
424
|
GitHub grant or management flow. Request or add the repository there, then
|
|
395
425
|
return to boxes.dev for an automatic recheck or choose **Check again**. An
|
|
396
426
|
organization admin may need to approve the request. Reconnect GitHub only when
|
|
397
|
-
the page says the account connection needs it.
|
|
427
|
+
the page says the account connection needs it. The ready **Repository access**
|
|
428
|
+
row shows checkmarked capabilities, with push and workflow-file edits shown
|
|
429
|
+
only where the live repository and installation grants allow them. Viewing
|
|
430
|
+
Actions does not grant permission to start a run. If App approval is unavailable,
|
|
398
431
|
choose **Use personal access**, copy the one-time code, and approve the official
|
|
399
|
-
GitHub CLI on GitHub.
|
|
400
|
-
|
|
401
|
-
|
|
432
|
+
GitHub CLI on GitHub. Personal access takes priority for managed CLI commands;
|
|
433
|
+
Git and explicit pull-request credential selection still prefers App access
|
|
434
|
+
where it works. Personal access supports eligible HTTPS Git and
|
|
402
435
|
explicit pull-request actions, but it does not add App webhook delivery for a
|
|
403
436
|
repository the App cannot access. You can disconnect personal access without
|
|
404
437
|
disconnecting the main GitHub connection.
|
|
@@ -407,13 +440,14 @@ This setting is separate from automatic Git pull/push access. It does not
|
|
|
407
440
|
change repository remotes, switch a project between HTTPS and SSH, or affect
|
|
408
441
|
commit authorship. When the setting is off, or GitHub is not connected to
|
|
409
442
|
boxes.dev, `gh` stays in ordinary user-managed mode and uses the CLI's existing
|
|
410
|
-
local configuration and environment
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
443
|
+
local configuration and environment, including native `gh auth login`. When
|
|
444
|
+
managed access is on, `gh auth login` connects personal access through the
|
|
445
|
+
central approval flow. Manage disconnects in **Integrations → GitHub**; native
|
|
446
|
+
logout, token display, token upload, custom scopes, enterprise hosts, and local
|
|
447
|
+
credential changes are unavailable with managed access. When personal access
|
|
448
|
+
is connected, GitHub enforces repository permission on each CLI request;
|
|
449
|
+
personal CLI access does not require App access to the project's repositories.
|
|
450
|
+
Aliases and extensions run as ordinary code owned by the same machine
|
|
417
451
|
user and can use the effective managed or local identity.
|
|
418
452
|
|
|
419
453
|
Open **Project settings** in the desktop app, then expand **Git** to choose the
|
|
@@ -498,7 +532,7 @@ it opens that pull request in your browser.
|
|
|
498
532
|
|
|
499
533
|
For an open pull request, open its actions menu and choose **Automate
|
|
500
534
|
follow-ups**. Select **Failed checks**, **Bot review feedback**, or both. The
|
|
501
|
-
selected devbox or Template box needs **GitHub CLI
|
|
535
|
+
selected devbox or Template box needs **GitHub CLI access** before
|
|
502
536
|
you can turn the feature on. The boxes.dev GitHub App also needs access to the
|
|
503
537
|
repository so GitHub can send the selected events; personal GitHub CLI access
|
|
504
538
|
alone cannot provide those webhooks.
|
|
@@ -206,7 +206,10 @@ whether Claude is idle, working, waiting for input, or changing ownership.
|
|
|
206
206
|
terminal. **Take over** asks for confirmation, safely closes that terminal
|
|
207
207
|
session, and resumes the same thread on mobile; text typed but not sent in the
|
|
208
208
|
terminal is lost. Your mobile draft and attachments stay in the composer and
|
|
209
|
-
become editable again after takeover succeeds.
|
|
209
|
+
become editable again after takeover succeeds. When Claude has finished
|
|
210
|
+
replying but a background command it started is still running, the card shows
|
|
211
|
+
Claude as idle and offers only **Take over**, which stops that command. Claude
|
|
212
|
+
is told that the command stopped, so you can ask it to run the command again.
|
|
210
213
|
|
|
211
214
|
Claude Code model and reasoning selections stay with the thread, sync with the
|
|
212
215
|
desktop composer, and remain selected when the thread is reopened or resumed.
|
|
@@ -268,6 +271,13 @@ directly from the thread. Image previews fit the available
|
|
|
268
271
|
screen and support pinch zoom and panning with inertial flings and elastic edge
|
|
269
272
|
settling.
|
|
270
273
|
|
|
274
|
+
In a devbox thread, tapping the **Devbox** pill in the header opens a read-only
|
|
275
|
+
list of the devbox's Git changes: each repository's branch, merge conflicts,
|
|
276
|
+
commits that haven't been pushed, and changed files with added and removed line
|
|
277
|
+
counts. Tapping a changed file opens its diff in the file viewer. A warning
|
|
278
|
+
icon in the pill or the thread row means a repository has unresolved merge
|
|
279
|
+
conflicts.
|
|
280
|
+
|
|
271
281
|
Large downloads may open through the browser, and they arrive with the file's
|
|
272
282
|
real name and extension so your phone can open them in the right app. Full
|
|
273
283
|
file browsing, uploads, inline review, Git staging, commits, and history are
|
|
@@ -30,7 +30,8 @@ and request disabled access. Its presence grants nothing; the exact operation
|
|
|
30
30
|
and permission-request commands still enforce the source box, thread, owner,
|
|
31
31
|
and current setting.
|
|
32
32
|
|
|
33
|
-
|
|
33
|
+
Settings reads are available without an editing grant. The Team Template
|
|
34
|
+
checkout commands use their own editing authority. Their
|
|
34
35
|
skill is available in Team Template editing sessions and can also be present
|
|
35
36
|
on a project Template box without Team Template access. Direct editing uses
|
|
36
37
|
the current editing session; remote work from an ordinary Template box needs
|
|
@@ -152,6 +153,142 @@ to write files on the Template box. `snapshot` waits for the new snapshot that
|
|
|
152
153
|
future devboxes will use. Take one only when the user wants the change to reach
|
|
153
154
|
future devboxes. Ordinary shell commands still act on the current devbox.
|
|
154
155
|
|
|
156
|
+
## Project And Team Template Settings
|
|
157
|
+
|
|
158
|
+
Read the current project's settings from any of its boxes. No editing
|
|
159
|
+
permission is needed for reads:
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
dvb-onbox project settings get --json
|
|
163
|
+
dvb-onbox team-template settings get --json
|
|
164
|
+
dvb-onbox team-template settings get --template <team-template-id> --json
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Project output includes Agent Guidance, prompt prefix, startup/teardown scripts
|
|
168
|
+
and timeouts, Git preferences, port forwarding, storage, environment metadata,
|
|
169
|
+
member-file requirements and supplied state, maintenance where applicable, and
|
|
170
|
+
agent permission defaults. `effectiveGitAction` includes the account's default
|
|
171
|
+
when no project preference is set. `autoWake` reports the account-wide
|
|
172
|
+
preference shown in Project settings. `permissionDefaultsEditable` is always false.
|
|
173
|
+
|
|
174
|
+
Inspect `origin` to identify the source Team Template and saved version, the
|
|
175
|
+
captured `projectConfigurationInput`, and its `configurationSource` when
|
|
176
|
+
recorded. These show what was copied when the project was created. Compare
|
|
177
|
+
those inputs with `team-template settings get` to explain inherited guidance;
|
|
178
|
+
changing template defaults will not replace an existing project's copy.
|
|
179
|
+
Older projects without recorded creation inputs report a null origin.
|
|
180
|
+
|
|
181
|
+
Team Template output includes its identity, description, source/repositories,
|
|
182
|
+
machine size, active saved version, project defaults and save epochs, setup
|
|
183
|
+
instructions, integration requirements, member-project policy, cleanup,
|
|
184
|
+
maintenance and watches, Project URL/MCP definitions, environment definitions,
|
|
185
|
+
and member-file requirements. Omit `--template` to select the current editing
|
|
186
|
+
box's template or the project's source template. An explicit ID must belong to
|
|
187
|
+
the caller's team. Reading does not open or wake a template editing machine.
|
|
188
|
+
Environment/file metadata never includes saved secret values or file contents.
|
|
189
|
+
|
|
190
|
+
To save one section, write an operation to a regular JSON file inside
|
|
191
|
+
`/home/boxes` (at most 512 KiB), then run:
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
dvb-onbox project settings set --settings-file /home/boxes/settings-edit.json --json
|
|
195
|
+
dvb-onbox team-template settings set --settings-file /home/boxes/settings-edit.json --json
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
Project writes need the current thread's three-hour `edit-project-settings`
|
|
199
|
+
grant. An active `edit-template-box` or `edit-team-template` grant also covers
|
|
200
|
+
that thread's project settings. Team Template writes need team-admin authority
|
|
201
|
+
and `edit-team-template`, or an existing authorized template editing host or
|
|
202
|
+
association. A grant for the source template works without an editing session,
|
|
203
|
+
including from an ordinary project created from it. Request only the minimum
|
|
204
|
+
permission returned by a denied write. Agent permission defaults remain
|
|
205
|
+
user-only even with an editing grant.
|
|
206
|
+
|
|
207
|
+
For example, preserve every lifecycle field returned by `get`, then change
|
|
208
|
+
only the intended value in this operation:
|
|
209
|
+
|
|
210
|
+
```json
|
|
211
|
+
{
|
|
212
|
+
"section": "lifecycle",
|
|
213
|
+
"settings": {
|
|
214
|
+
"agentGuidance": "Run focused tests before committing.",
|
|
215
|
+
"promptPrefix": "",
|
|
216
|
+
"startupScript": "",
|
|
217
|
+
"startupTimeoutSeconds": 60,
|
|
218
|
+
"teardownScript": "",
|
|
219
|
+
"teardownTimeoutSeconds": 30
|
|
220
|
+
}
|
|
221
|
+
}
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
Project operations use these fields in addition to `section`:
|
|
225
|
+
|
|
226
|
+
| Section | Fields |
|
|
227
|
+
| --- | --- |
|
|
228
|
+
| `lifecycle` | `settings`: all six lifecycle fields shown above. |
|
|
229
|
+
| `git` | `settings`: `preferredAction` (`pull_request`, `direct_push`, or null) and `threadAttributionEnabled`. |
|
|
230
|
+
| `ports_enabled` | `enabled`. |
|
|
231
|
+
| `ports` | `expectedConfigurationRevision`; `configuration` with `defaultAction` and `rules` from the read result. |
|
|
232
|
+
| `storage` | `enabled`. |
|
|
233
|
+
| `auto_wake` | `enabled` (boolean or null to use the product default); affects the owner's account across projects. |
|
|
234
|
+
| `maintenance` | `script`, `timeoutSeconds`, and the complete schedule fields listed below. |
|
|
235
|
+
| `maintenance_delete` | No additional fields. |
|
|
236
|
+
| `maintenance_watches` | `expectedRevision` from `maintenance.revision`, `confirmWatchRemovals`, `script`, `timeoutSeconds`, `watches` with `repository`, `enabled`, and `paths`; preserves the schedule. |
|
|
237
|
+
| `member_files` | `expectedDefinitionScopeId`, `expectedDefinitionDesiredRevision`, `expectedMemberDesiredRevision` from `memberFilesRevision`; `updates` with `fileId` and `valueAction` (`kind: "delete"`, `kind: "accept"`, or `kind: "replace"` with `plaintextBase64` and `byteLength`). |
|
|
238
|
+
| `environment_file` | `draft` for an ordinary project's environment file, as described below. For a managed project's personal values, use `env set|remove`. |
|
|
239
|
+
| `environment_file_delete` | `contextId`, `expectedContextRevision` for an ordinary project's environment file. |
|
|
240
|
+
|
|
241
|
+
Team Template operations use these fields in addition to `section`:
|
|
242
|
+
|
|
243
|
+
| Section | Fields |
|
|
244
|
+
| --- | --- |
|
|
245
|
+
| `metadata` | `name`, `description` (text; empty clears it). |
|
|
246
|
+
| `defaults` | `expectedSaveEpoch` from `defaults.saveEpoch`; complete `defaults` with optional `lifecycle`, `git`, and `portForwarding` sections. Omitted sections are cleared. |
|
|
247
|
+
| `setup` | `expectedVersion` from `setup.version`, `instructions`. |
|
|
248
|
+
| `integrations` | `expectedSaveEpoch` from `integrations.saveEpoch`, complete `requirements` array. |
|
|
249
|
+
| `member_projects` | `expectedRevision` from `memberProjects.revision`; `policy` with `creationEnabled`, `startupScript`, `startupTimeoutSeconds`, `teardownScript`, and `teardownTimeoutSeconds`. |
|
|
250
|
+
| `cleanup` | `script`. |
|
|
251
|
+
| `maintenance` | `expectedConfigurationVersion`, `script`, `timeoutSeconds`, and all schedule fields. |
|
|
252
|
+
| `maintenance_delete` | `expectedConfigurationVersion`. |
|
|
253
|
+
| `watch_save` | `repositoryId`, `expectedConfigurationVersion` (null for a new watch), `enabled`, `watchedPaths`. |
|
|
254
|
+
| `watch_delete` | `watchId`, `expectedConfigurationVersion`. |
|
|
255
|
+
| `url_create` | `definition` with `displayName`, `targetPort`, `defaultDelivery`, `deliveryRules`, and `state`. |
|
|
256
|
+
| `url_update` | `projectUrlDefinitionId`, `expectedSaveEpoch`, complete `definition`. |
|
|
257
|
+
| `url_delete` | `projectUrlDefinitionId`, `expectedSaveEpoch`. |
|
|
258
|
+
| `mcp_create` | `definition` with `displayName`, `nativeName`, `url`, `authMode` (`oauth`, `static_headers`, or `none`), and `staticHeaderNames`. |
|
|
259
|
+
| `mcp_update` | `mcpDefinitionId`, `expectedSaveEpoch`, complete `definition`. |
|
|
260
|
+
| `mcp_delete` | `mcpDefinitionId`, `expectedSaveEpoch`. |
|
|
261
|
+
| `environment_file` | `draft` for a Team Template environment file, as described below. |
|
|
262
|
+
| `environment_file_delete` | `contextId`, `expectedContextRevision`. |
|
|
263
|
+
|
|
264
|
+
An environment `draft` contains `contextId`, `expectedContextRevision`, `path`,
|
|
265
|
+
`displayOrder`, `adoptionRevision`, `adoptionSourceSha256`,
|
|
266
|
+
`adoptionManagedNames`, `adoptionRemovedNames`, and the complete `rows` array.
|
|
267
|
+
Read these file fields before editing; for a new file use null IDs/revisions,
|
|
268
|
+
empty adoption arrays, and a new relative path. Ordinary project drafts also
|
|
269
|
+
need `state: "active"` or `"pending_adoption"`.
|
|
270
|
+
Each row contains `rowId`, `displayOrder`, `name`, `inlineComment`,
|
|
271
|
+
`description`, and `valueAction`. Team Template rows also need `provider`
|
|
272
|
+
(`team` or `member`), `required`, and `memberInstructions`.
|
|
273
|
+
Use null for a new row ID or absent comment/description/instructions.
|
|
274
|
+
To preserve saved values while changing metadata, use
|
|
275
|
+
`valueAction: {"kind":"keep"}`. Replacements use
|
|
276
|
+
`{"kind":"replace","plaintext":"..."}`; deletion uses `{"kind":"delete"}`.
|
|
277
|
+
Omitted rows are removed. Saved values never appear in the read result.
|
|
278
|
+
|
|
279
|
+
Maintenance schedule fields are `scheduleEnabled`, `schedulePreset`,
|
|
280
|
+
`scheduleTimezone`, `scheduleLocalTime` (text or null), and `scheduleWeekday`
|
|
281
|
+
(number or null). Use the existing desktop editor's allowed schedule values
|
|
282
|
+
from the current read result. Read IDs and revisions before updating a
|
|
283
|
+
definition. After a conflict or uncertain result, read again and reconcile.
|
|
284
|
+
Updates preserve definition identity and use the same validation as desktop
|
|
285
|
+
saves. `set` does not publish a filesystem version. Source identity and machine
|
|
286
|
+
size are creation settings; snapshots, publishing, account sign-in, and machine
|
|
287
|
+
lifecycle retain their existing commands.
|
|
288
|
+
|
|
289
|
+
Use `env set|remove` for environment values and `team-template member-files`
|
|
290
|
+
for requirement definitions. These retain their own input and revision rules.
|
|
291
|
+
|
|
155
292
|
## Environment Variables
|
|
156
293
|
|
|
157
294
|
An agent can list, set, and remove the centrally managed environment variables
|
|
@@ -170,12 +307,12 @@ What these commands change depends on the project:
|
|
|
170
307
|
|
|
171
308
|
- In a project with its own Template box, they edit the project's variables.
|
|
172
309
|
On the Template box they need no extra permission. On a devbox, the current
|
|
173
|
-
thread needs
|
|
310
|
+
thread needs `edit-project-settings` or `edit-template-box`.
|
|
174
311
|
- In a Team Template project, they edit the user's own variables: values for
|
|
175
312
|
Member rows the team defined, and variables the user added to any file.
|
|
176
313
|
Team values belong to the team and cannot be changed here. The current
|
|
177
|
-
thread needs `edit-
|
|
178
|
-
admin.
|
|
314
|
+
thread needs `edit-project-settings`, `edit-personal-environment`, or
|
|
315
|
+
`edit-team-template` for a team admin.
|
|
179
316
|
|
|
180
317
|
`--file` is relative to the folder the result reports as `pathBase`.
|
|
181
318
|
`set` replaces the variable if it exists, adds it if it doesn't, and creates
|
|
@@ -188,7 +325,7 @@ Environment files**.
|
|
|
188
325
|
|
|
189
326
|
`--value-stdin` reads the value from standard input and drops one trailing
|
|
190
327
|
newline. `list` returns names, where each value comes from, and whether a value
|
|
191
|
-
is saved; it never returns values. Saved changes reach running machines within
|
|
328
|
+
is saved; it needs no editing grant and never returns values. Saved changes reach running machines within
|
|
192
329
|
about a minute. After an uncertain response, run `list` before retrying.
|
|
193
330
|
|
|
194
331
|
## Automations
|
|
@@ -450,7 +587,7 @@ The request values are `create-devboxes-and-threads`,
|
|
|
450
587
|
`edit-devbox-lifecycle`, `edit-template-maintenance`, `destroy-devbox`,
|
|
451
588
|
`destroy-created-devboxes`, `read-project-threads`, `read-user-threads`, `read-shared-threads`,
|
|
452
589
|
`read-team-threads`, `message-agents`, `edit-template-box`,
|
|
453
|
-
`edit-team-template`, `edit-personal-environment`, and `edit-automations`.
|
|
590
|
+
`edit-team-template`, `edit-project-settings`, `edit-personal-environment`, and `edit-automations`.
|
|
454
591
|
Add `--json` for a stable structured result.
|
|
455
592
|
|
|
456
593
|
The command creates one request for the exact managed thread and source box,
|
|
@@ -461,19 +598,22 @@ for every agent on that source box until the owner turns it off; it is not a
|
|
|
461
598
|
one-operation grant. **Deny** declines this request without changing permission
|
|
462
599
|
settings. An agent cannot answer its own request.
|
|
463
600
|
|
|
464
|
-
`edit-template-box`, `edit-team-template`, and `edit-personal-environment`
|
|
601
|
+
`edit-template-box`, `edit-team-template`, `edit-project-settings`, and `edit-personal-environment`
|
|
465
602
|
work differently. They apply only to the agent in the requesting thread, and
|
|
466
603
|
the owner sees **Deny** and **Allow for 3 hours**. The grant expires 3 hours
|
|
467
604
|
after approval. Other threads and boxes never receive it, and no Agent
|
|
468
605
|
permissions switch or project setting can enable it. Request
|
|
469
606
|
`edit-template-box` from a devbox in a project with its own Template box to
|
|
470
|
-
edit that Template box and the project's environment variables. Request
|
|
471
|
-
`edit-
|
|
472
|
-
|
|
607
|
+
edit that Template box and the project's settings and environment variables. Request
|
|
608
|
+
`edit-project-settings` from any box in the project to edit its settings,
|
|
609
|
+
including the user's own environment and member-file values. It cannot change
|
|
610
|
+
agent permission defaults. Request
|
|
611
|
+
`edit-team-template` from a box in a project created from a Team Template to edit that
|
|
612
|
+
Team Template's settings, including environment and member-file definitions; only a team admin can
|
|
473
613
|
receive it. Request `edit-personal-environment` from a devbox in a Team
|
|
474
614
|
Template project to edit the user's own environment variables for that
|
|
475
615
|
project; any member can receive it, and a thread that already has
|
|
476
|
-
`edit-team-template` does not need it. A thread holds one of these grants at a
|
|
616
|
+
`edit-team-template` or `edit-project-settings` does not need it. A thread holds one of these grants at a
|
|
477
617
|
time. After the grant expires, the next command reports the missing permission
|
|
478
618
|
and the agent needs a new request.
|
|
479
619
|
|
|
@@ -646,12 +786,19 @@ Treat it as the authority for the current box; do not guess from an older
|
|
|
646
786
|
list. Discovery reads only the source box and does not create, wake, or
|
|
647
787
|
inspect a destination devbox.
|
|
648
788
|
|
|
789
|
+
For worker threads whose results you will review and include in your own reply,
|
|
790
|
+
prefer `--muted`, as in the start examples below. This will keep each worker's
|
|
791
|
+
completion from notifying the user. Keep notifications enabled when you expect
|
|
792
|
+
the user to review or continue the thread directly, and follow any explicit
|
|
793
|
+
notification preference.
|
|
794
|
+
|
|
649
795
|
From an authorized ordinary devbox, start another thread on that same devbox:
|
|
650
796
|
|
|
651
797
|
```bash
|
|
652
798
|
dvb-onbox threads start \
|
|
653
799
|
--target current-devbox \
|
|
654
800
|
--agent codex \
|
|
801
|
+
--muted \
|
|
655
802
|
--prompt-file <path> \
|
|
656
803
|
--idempotency-key <caller-key> \
|
|
657
804
|
--json
|
|
@@ -670,6 +817,7 @@ From an authorized source box, start a Codex or Claude thread on a new devbox:
|
|
|
670
817
|
dvb-onbox threads start \
|
|
671
818
|
--target new-devbox \
|
|
672
819
|
--agent codex \
|
|
820
|
+
--muted \
|
|
673
821
|
--prompt-file <path> \
|
|
674
822
|
--idempotency-key <caller-key> \
|
|
675
823
|
--json
|
|
@@ -682,6 +830,7 @@ when supported, one of that model's reasoning efforts and a Codex speed:
|
|
|
682
830
|
dvb-onbox threads start \
|
|
683
831
|
--target new-devbox \
|
|
684
832
|
--agent codex \
|
|
833
|
+
--muted \
|
|
685
834
|
--prompt-file <path> \
|
|
686
835
|
--idempotency-key <caller-key> \
|
|
687
836
|
--model <model-id> \
|
|
@@ -716,6 +865,7 @@ To start another thread on an ordinary devbox, use its instance ID:
|
|
|
716
865
|
dvb-onbox threads start \
|
|
717
866
|
--target devbox:<instance-id> \
|
|
718
867
|
--agent claude \
|
|
868
|
+
--muted \
|
|
719
869
|
--prompt-file <path> \
|
|
720
870
|
--idempotency-key <caller-key> \
|
|
721
871
|
--json
|
|
@@ -731,12 +881,11 @@ Retry an uncertain result with the same idempotency key and identical
|
|
|
731
881
|
arguments, including model and reasoning effort and any explicit speed;
|
|
732
882
|
changed arguments under the same key fail.
|
|
733
883
|
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
argument, so a retry with the same idempotency key must repeat it.
|
|
884
|
+
A muted thread will not send notifications or become unread when its turns
|
|
885
|
+
finish, fail, or are interrupted. It will still notify the user and show that
|
|
886
|
+
it needs input when its agent asks a question or needs an approval, because
|
|
887
|
+
only the user can answer those. `--muted` is a start argument, so a retry with
|
|
888
|
+
the same idempotency key must repeat it.
|
|
740
889
|
|
|
741
890
|
The source box can continue and inspect only the delegated children it created
|
|
742
891
|
through this command. It cannot target another same-project thread. The default
|
|
@@ -1344,8 +1493,10 @@ environment; do not assume arbitrary home files are excluded.
|
|
|
1344
1493
|
|
|
1345
1494
|
### Member-file requirements
|
|
1346
1495
|
|
|
1347
|
-
|
|
1348
|
-
|
|
1496
|
+
Read requirements without an editing grant from a project box or the current
|
|
1497
|
+
editing box. A team admin can add, update, and remove requirements from a
|
|
1498
|
+
project created from the template with `edit-team-template`, without an editing
|
|
1499
|
+
session. Run these commands in its current editing box too. From an ordinary
|
|
1349
1500
|
Template box with an active editor association, add `--template <team-template-id>`
|
|
1350
1501
|
to select that associated Team Template. Every operation edits the Team
|
|
1351
1502
|
Template; it does not add requirements to the caller's ordinary project.
|
|
@@ -1381,9 +1532,9 @@ upload or read a member's file contents.
|
|
|
1381
1532
|
|
|
1382
1533
|
### Team Template environment variables
|
|
1383
1534
|
|
|
1384
|
-
|
|
1385
|
-
|
|
1386
|
-
|
|
1535
|
+
Read the Team Template's environment definitions without an editing grant.
|
|
1536
|
+
An admin can define them from the same places as member-file requirements.
|
|
1537
|
+
A project box whose thread has `edit-team-template` does not need an open
|
|
1387
1538
|
editing session for these commands.
|
|
1388
1539
|
|
|
1389
1540
|
```bash
|