@boxes-dev/dvb-runtime 1.0.1106 → 1.0.1108
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bin/dvb.mjs +1728 -1157
- package/dist/bin/dvbd.mjs +25 -21
- package/dist/product-docs/references/automations.md +22 -4
- package/dist/product-docs/references/cli.md +50 -5
- package/dist/product-docs/references/desktop-workbench.md +10 -3
- package/dist/product-docs/references/environment-setup-validation.md +12 -4
- package/dist/product-docs/references/files-git-and-review.md +11 -2
- package/dist/product-docs/references/fork-workflows.md +17 -5
- package/dist/product-docs/references/getting-started.md +3 -0
- package/dist/product-docs/references/mobile.md +46 -13
- package/dist/product-docs/references/onbox-agent-tools.md +80 -21
- package/dist/product-docs/references/ports-terminal-and-runtime.md +11 -0
- package/dist/product-docs/references/project-setup.md +35 -5
- package/dist/product-docs/references/remote-assistants.md +9 -0
- package/dist/product-docs/references/template-box-environment.md +7 -0
- package/dist/product-docs/references/threads-and-agents.md +164 -21
- package/dist/product-docs/references/troubleshooting.md +18 -2
- package/package.json +2 -2
|
@@ -283,6 +283,10 @@ them), and Claude and Codex agent settings
|
|
|
283
283
|
managed project). `effectiveGitAction` includes the account's default
|
|
284
284
|
when no project preference is set. `autoWake` reports the account-wide
|
|
285
285
|
preference shown in Project settings. `permissionDefaultsEditable` is always false.
|
|
286
|
+
`defaultBranches` lists the branch each repository will check out in new
|
|
287
|
+
devboxes. Its paths are relative to the folder where startup commands run, which
|
|
288
|
+
is the project folder in most projects. An empty list means new devboxes will
|
|
289
|
+
start from the Template box's saved checkout.
|
|
286
290
|
|
|
287
291
|
Inspect `origin` to identify the source Team Template and saved version, the
|
|
288
292
|
captured `projectConfigurationInput`, and its `configurationSource` when
|
|
@@ -311,7 +315,7 @@ dvb-onbox team-template settings set --settings-file /home/boxes/settings-edit.j
|
|
|
311
315
|
```
|
|
312
316
|
|
|
313
317
|
Project writes need the current thread's three-hour `edit-project-settings`
|
|
314
|
-
grant. An active `edit-template-box` or `edit-team-template` grant also covers
|
|
318
|
+
grant. The project's setup thread can save `default_branches` without one. An active `edit-template-box` or `edit-team-template` grant also covers
|
|
315
319
|
that thread's project settings. Team Template writes need team-admin authority
|
|
316
320
|
and `edit-team-template`, or an existing authorized template editing host or
|
|
317
321
|
association. A grant for the source template works without an editing session,
|
|
@@ -343,6 +347,7 @@ Project operations use these fields in addition to `section`:
|
|
|
343
347
|
| `lifecycle` | `settings`: all six lifecycle fields shown above. |
|
|
344
348
|
| `git` | `settings`: `preferredAction` (`pull_request`, `direct_push`, or null) and `threadAttributionEnabled`. |
|
|
345
349
|
| `ports_enabled` | `enabled`. |
|
|
350
|
+
| `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). |
|
|
346
351
|
| `ports` | `expectedConfigurationRevision`; `configuration` with `defaultAction` and `rules` from the read result. |
|
|
347
352
|
| `storage` | `enabled`. |
|
|
348
353
|
| `auto_wake` | `enabled` (boolean or null to use the product default); affects the owner's account across projects. |
|
|
@@ -350,7 +355,7 @@ Project operations use these fields in addition to `section`:
|
|
|
350
355
|
| `maintenance_delete` | No additional fields. |
|
|
351
356
|
| `maintenance_watches` | `expectedRevision` from `maintenance.revision`, `confirmWatchRemovals`, `script`, `timeoutSeconds`, `watches` with `repository`, `enabled`, and `paths`; preserves the schedule. |
|
|
352
357
|
| `member_files` | `expectedDefinitionScopeId`, `expectedDefinitionDesiredRevision`, `expectedMemberDesiredRevision` from `memberFilesRevision`; `updates` with `fileId` and `valueAction` (`kind: "delete"`, `kind: "accept"`, or `kind: "replace"` with `plaintextBase64` and `byteLength`). |
|
|
353
|
-
| `environment_file` | `draft` for an independent project's environment file, as described below. For a managed project's personal values, use `env set
|
|
358
|
+
| `environment_file` | `draft` for an independent project's environment file, as described below. For a managed project's personal values, use `env set\|remove`. |
|
|
354
359
|
| `environment_file_delete` | `contextId`, `expectedContextRevision` for an independent project's environment file. |
|
|
355
360
|
| `agent_settings` | `agent` (`claude` or `codex`), `content`, `expectedRevision`, as described below. In a managed project, this saves the member's own settings. |
|
|
356
361
|
|
|
@@ -541,9 +546,17 @@ separate `--prompt-file`, not both. File paths can be relative or absolute.
|
|
|
541
546
|
safeguards, and no outputs. `create` saves the automation paused.
|
|
542
547
|
- `execution`: `backend` is `codex` or `claude`. Take `model` and
|
|
543
548
|
`reasoningEffort` from `automations options`; `reasoningEffort` is `null`
|
|
544
|
-
only for a model without reasoning control.
|
|
545
|
-
`
|
|
546
|
-
|
|
549
|
+
only for a model without reasoning control. For Codex, add
|
|
550
|
+
`codexProviderConnectionId` to select a saved provider connection. Choose
|
|
551
|
+
its ID and model from `options.codexProviders`; each connection includes
|
|
552
|
+
`connectionId`, `label`, `available`, and `models` with `modelId`,
|
|
553
|
+
`reasoningEfforts`, and `defaultReasoningEffort`. Model IDs and efforts are
|
|
554
|
+
specific to that connection, even when another connection lists the same
|
|
555
|
+
model ID. Omitting the connection field or setting it to `null` inside a
|
|
556
|
+
supplied `execution` selects OpenAI. The ordinary `options.codex` and
|
|
557
|
+
`options.claude` lists remain available. `serviceTier` can be omitted for
|
|
558
|
+
Standard; `fast` is available only for a supported OpenAI or Claude model.
|
|
559
|
+
Saved Codex provider connections support Standard only.
|
|
547
560
|
- `trigger`: `{"kind": "manual"}`, or a schedule with `frequency` `hourly`,
|
|
548
561
|
`daily`, `weekly`, or `monthly`; a whole-number `interval`; an IANA
|
|
549
562
|
`timeZone`; a `startDate` (`YYYY-MM-DD`); `hour` and `minute`; `weekdays`
|
|
@@ -590,6 +603,23 @@ separate `--prompt-file`, not both. File paths can be relative or absolute.
|
|
|
590
603
|
Spec errors (`invalid_spec`) name the field that failed, such as
|
|
591
604
|
`trigger.timeZone` or `outputs[1].channel`.
|
|
592
605
|
|
|
606
|
+
For example, a saved connection whose model has no reasoning choices uses
|
|
607
|
+
this `execution` value:
|
|
608
|
+
|
|
609
|
+
```json
|
|
610
|
+
{
|
|
611
|
+
"backend": "codex",
|
|
612
|
+
"codexProviderConnectionId": "<connection-id>",
|
|
613
|
+
"model": "<model-id>",
|
|
614
|
+
"reasoningEffort": null
|
|
615
|
+
}
|
|
616
|
+
```
|
|
617
|
+
|
|
618
|
+
For a model with reasoning choices, replace `null` with a listed effort.
|
|
619
|
+
A disconnected connection needs to be reconnected in **Configure agents**
|
|
620
|
+
before a run can start. An unavailable connection or model causes an error;
|
|
621
|
+
the run will not switch to another provider or model.
|
|
622
|
+
|
|
593
623
|
### Change an automation
|
|
594
624
|
|
|
595
625
|
`get` returns a `revision`. Pass it to `update --if-revision`. An update is
|
|
@@ -598,6 +628,12 @@ replaces that whole value. `"outputs": []` removes all destinations, and
|
|
|
598
628
|
`{"trigger": {"kind": "manual"}}` removes a schedule. `update` needs
|
|
599
629
|
`--spec-file`, `--prompt-file`, or both.
|
|
600
630
|
|
|
631
|
+
Leaving out `execution` preserves the saved provider and model settings.
|
|
632
|
+
Supplying `execution` replaces the complete selection: include
|
|
633
|
+
`codexProviderConnectionId` to keep a saved connection, or use `null` or omit
|
|
634
|
+
that field to choose OpenAI. Provider changes apply to future new-thread
|
|
635
|
+
runs; threads already started keep their own provider connection.
|
|
636
|
+
|
|
601
637
|
Changing to an existing-thread target removes saved Slack outputs. The saved
|
|
602
638
|
devbox cleanup policy still applies to earlier new-thread runs; it never
|
|
603
639
|
applies to the target's devbox. Read results retain `execution` and other
|
|
@@ -1224,12 +1260,15 @@ The result includes exact model IDs, the default model, each model's available
|
|
|
1224
1260
|
reasoning efforts, and its default effort. Each model also lists its
|
|
1225
1261
|
available speeds: Standard, plus Fast and Ultrafast when the model offers them.
|
|
1226
1262
|
Claude offers Fast (fast mode) on models that support it and never Ultrafast.
|
|
1263
|
+
For Codex, `models` lists the OpenAI choices and `codexProviders` lists saved
|
|
1264
|
+
connections with their IDs, labels, availability, and their own model choices.
|
|
1265
|
+
Use the exact connection ID, not its display name, with `--provider`.
|
|
1227
1266
|
Treat it as the authority for the current box; do not guess from an older
|
|
1228
1267
|
list. Discovery reads only the source box and does not create, wake, or
|
|
1229
1268
|
inspect a destination devbox.
|
|
1230
1269
|
|
|
1231
|
-
For
|
|
1232
|
-
prefer `--muted`, as in the start examples below. This will keep each
|
|
1270
|
+
For threads whose results you will review and include in your own reply,
|
|
1271
|
+
prefer `--muted`, as in the start examples below. This will keep each thread's
|
|
1233
1272
|
completion from notifying the user. Keep notifications enabled when you expect
|
|
1234
1273
|
the user to review or continue the thread directly, and follow any explicit
|
|
1235
1274
|
notification preference.
|
|
@@ -1265,8 +1304,9 @@ dvb-onbox threads start \
|
|
|
1265
1304
|
--json
|
|
1266
1305
|
```
|
|
1267
1306
|
|
|
1268
|
-
To
|
|
1269
|
-
|
|
1307
|
+
To select a saved provider for a Codex child, use its connection ID and a model
|
|
1308
|
+
from that connection's options. Include the reasoning flag only when the model
|
|
1309
|
+
lists reasoning choices:
|
|
1270
1310
|
|
|
1271
1311
|
```bash
|
|
1272
1312
|
dvb-onbox threads start \
|
|
@@ -1275,21 +1315,40 @@ dvb-onbox threads start \
|
|
|
1275
1315
|
--muted \
|
|
1276
1316
|
--prompt-file <path> \
|
|
1277
1317
|
--idempotency-key <caller-key> \
|
|
1318
|
+
--provider <connection-id> \
|
|
1278
1319
|
--model <model-id> \
|
|
1279
1320
|
--reasoning-effort <effort> \
|
|
1280
|
-
--speed fast \
|
|
1281
1321
|
--json
|
|
1282
1322
|
```
|
|
1283
1323
|
|
|
1284
1324
|
`--model` without `--reasoning-effort` uses that model's reported default
|
|
1285
1325
|
effort. Omit `--reasoning-effort` for a model whose effort list is empty.
|
|
1286
1326
|
`--speed` accepts `fast` or `ultrafast` only for a model that reports that
|
|
1287
|
-
speed; an explicit model without speed uses Standard.
|
|
1288
|
-
|
|
1289
|
-
|
|
1290
|
-
|
|
1291
|
-
|
|
1292
|
-
|
|
1327
|
+
speed; an explicit model without speed uses Standard. This applies even when
|
|
1328
|
+
the explicit model is the same as the parent's model. Reasoning effort or speed
|
|
1329
|
+
requires `--model` or `--provider`.
|
|
1330
|
+
|
|
1331
|
+
When a Codex thread starts a Codex child without `--provider`, the child uses
|
|
1332
|
+
the source thread's provider connection, including OpenAI. If all execution
|
|
1333
|
+
flags are omitted, it also inherits the source thread's current native model,
|
|
1334
|
+
reasoning, and speed, including changes made in its terminal. If those current
|
|
1335
|
+
settings cannot be read, the command asks for an explicit `--model`. A bare
|
|
1336
|
+
`--model` selects only within the inherited provider; the same model ID on
|
|
1337
|
+
another connection does not select that connection.
|
|
1338
|
+
|
|
1339
|
+
To choose a provider for the child explicitly, add `--provider openai` or
|
|
1340
|
+
`--provider <connection-id>`. Without `--model`, an explicit provider uses
|
|
1341
|
+
its default model and reasoning, with Standard speed. Other supplied flags
|
|
1342
|
+
can select supported controls. Saved Codex provider connections support
|
|
1343
|
+
Standard only; omit speed and any unsupported reasoning flag. Provider
|
|
1344
|
+
selection is Codex-only. It applies to the new child, and neither changes
|
|
1345
|
+
the parent nor lets a started thread change providers. A disconnected or
|
|
1346
|
+
removed connection causes an error instead of selecting another provider.
|
|
1347
|
+
|
|
1348
|
+
Claude children use the source box's saved Claude defaults when execution
|
|
1349
|
+
flags are omitted. A Codex child started from a Claude thread uses the source
|
|
1350
|
+
box's saved Codex provider and settings. If no saved settings exist, the
|
|
1351
|
+
selected agent's catalog default is used.
|
|
1293
1352
|
|
|
1294
1353
|
The new devbox belongs to the source box's project and uses that project's
|
|
1295
1354
|
current reusable source. An independent project uses its latest eligible
|
|
@@ -1320,7 +1379,7 @@ The Template box may be a source but is never a delegated thread target. All
|
|
|
1320
1379
|
forms return the child thread and devbox IDs. The child appears in the user's
|
|
1321
1380
|
thread list as a regular thread, and the user can read and reply to it there.
|
|
1322
1381
|
Retry an uncertain result with the same idempotency key and identical
|
|
1323
|
-
arguments, including model
|
|
1382
|
+
arguments, including any explicit provider, model, reasoning effort, and speed;
|
|
1324
1383
|
changed arguments under the same key fail.
|
|
1325
1384
|
|
|
1326
1385
|
A muted thread will not send notifications or become unread when its turns
|
|
@@ -2068,8 +2127,8 @@ cancel. Once archival has started, it returns `destruction_started`.
|
|
|
2068
2127
|
### Archive Created Threads On This Devbox
|
|
2069
2128
|
|
|
2070
2129
|
Either level of **Destroy and archive devboxes** also lets any agent on an
|
|
2071
|
-
ordinary devbox archive
|
|
2072
|
-
such as a
|
|
2130
|
+
ordinary devbox archive threads created there by agents on that same devbox,
|
|
2131
|
+
such as a thread started with `threads start --target current-devbox`:
|
|
2073
2132
|
|
|
2074
2133
|
```bash
|
|
2075
2134
|
dvb-onbox threads archive --thread <thread-id> --json
|
|
@@ -2077,7 +2136,7 @@ dvb-onbox threads archive --thread <thread-id> --json
|
|
|
2077
2136
|
|
|
2078
2137
|
Use the thread ID returned by `threads start` or shown by `threads list`.
|
|
2079
2138
|
Archive a thread only after its work is finished and you have collected its
|
|
2080
|
-
result. Any agent on the creating devbox can archive the
|
|
2139
|
+
result. Any agent on the creating devbox can archive the thread; it doesn't
|
|
2081
2140
|
have to be the agent that started it. Archiving keeps the thread's history,
|
|
2082
2141
|
and the user can unarchive it in the desktop or mobile app. Repeating the
|
|
2083
2142
|
command is safe; `changed` is `false` when the thread was already archived.
|
|
@@ -2090,7 +2149,7 @@ Manually started threads, threads created from another box, and threads on
|
|
|
2090
2149
|
other boxes return `thread_not_found`. Threads that haven't started return
|
|
2091
2150
|
`thread_not_ready`, and agents on a Template box get `not_devbox`. After an
|
|
2092
2151
|
`archive_disabled` error, request `destroy-created-devboxes`. Permission to
|
|
2093
|
-
destroy this devbox does not grant permission to archive individual
|
|
2152
|
+
destroy this devbox does not grant permission to archive individual threads.
|
|
2094
2153
|
|
|
2095
2154
|
## Devbox Folders
|
|
2096
2155
|
|
|
@@ -324,6 +324,17 @@ you close the editor; reopen it to apply or discard them.
|
|
|
324
324
|
If a remote port cannot be bound locally, the Ports button shows a warning. A
|
|
325
325
|
row can say that the port is in use locally or is not forwarded.
|
|
326
326
|
|
|
327
|
+
On macOS, the desktop app forwards a localhost port below 1024, such as 80 or
|
|
328
|
+
443, only when a project rule covers that single port or sets the local port. A
|
|
329
|
+
range rule with **Same locally** does not count. Without such a rule, the port
|
|
330
|
+
stays free for local servers. Linux normally reserves those ports for root, so
|
|
331
|
+
the desktop app cannot forward to them there.
|
|
332
|
+
|
|
333
|
+
A row says **privileged port** when the desktop app cannot open a local port
|
|
334
|
+
below 1024. For these rows, **Use next available** searches from 8000 ports
|
|
335
|
+
higher, such as 8080 for 80 or 8443 for 443. A project rule that maps the port
|
|
336
|
+
to a higher local port avoids the prompt.
|
|
337
|
+
|
|
327
338
|
When available, choose **Use next available** to approve forwarding that remote
|
|
328
339
|
port to a different local port. The chosen local port stays pinned for the
|
|
329
340
|
current desktop app session across box sleep/wake, renderer reloads, and thread
|
|
@@ -218,6 +218,17 @@ preference, setup prefers Codex when both agents are available. It requests
|
|
|
218
218
|
high reasoning where supported, otherwise the model's advertised reasoning
|
|
219
219
|
default.
|
|
220
220
|
|
|
221
|
+
To run setup through a saved Codex model provider, include `codex` in
|
|
222
|
+
`agents.runtime` and set `agents.setup` with `backend: codex`, the provider's
|
|
223
|
+
model ID in `model`, and its `codexProviderConnectionId`. Run
|
|
224
|
+
`dvb threads options --json` for available connections and their models.
|
|
225
|
+
The manifest contains the connection ID, never the API key. This path needs
|
|
226
|
+
no OpenAI account, uses the selected model's default reasoning level, and
|
|
227
|
+
bills the chosen provider. An unavailable connection or model needs repair
|
|
228
|
+
before launch; setup won't silently select another provider. Omitting the
|
|
229
|
+
connection field or setting it to `null` keeps the ordinary account selection
|
|
230
|
+
above. A user with only a model provider connected must choose it explicitly.
|
|
231
|
+
|
|
221
232
|
The manifest can explicitly select environment files outside the project.
|
|
222
233
|
Environment, secret, configuration, and extra file entries can also name an
|
|
223
234
|
edited copy to upload while leaving the laptop original untouched. Bash and
|
|
@@ -385,6 +396,9 @@ branch when adding application setup commands after it. If the chosen branch
|
|
|
385
396
|
exists only locally, explain that it cannot be fetched and confirm whether to
|
|
386
397
|
use its clean committed state from the Template snapshot instead. Omit the
|
|
387
398
|
generated block for that choice; unfinished work remains saved separately.
|
|
399
|
+
If no default is saved, or it differs from a remote starting branch, the setup
|
|
400
|
+
agent on the Template box saves that branch before setup finishes, unless a
|
|
401
|
+
custom startup script switches branches itself.
|
|
388
402
|
Version 3 includes full startup and teardown sections with independent timeouts.
|
|
389
403
|
A missing remote default does not require publishing a branch; the user can
|
|
390
404
|
choose a local branch as above. After setup, clearing the startup script does
|
|
@@ -428,7 +442,10 @@ browser. There the user connects Codex, Claude Code, or both, and can connect
|
|
|
428
442
|
GitHub and Slack. Codex and Claude Code use their normal browser sign-in in
|
|
429
443
|
the same tab, which returns to the page through the CLI on the user's
|
|
430
444
|
computer; neither agent needs to be installed there. **Use an API key** saves
|
|
431
|
-
a key instead.
|
|
445
|
+
a key instead. The same page has **Codex model providers** for OpenRouter,
|
|
446
|
+
Vercel AI Gateway and compatible custom endpoints. A usable model provider
|
|
447
|
+
connection allows Codex setup without an OpenAI account. **Done** becomes
|
|
448
|
+
available once a coding agent is connected,
|
|
432
449
|
and the command waits until the user chooses it. If an agent is already
|
|
433
450
|
connected to boxes.dev, no new sign-in is needed; choose **Done** to continue
|
|
434
451
|
setup with that account. Over SSH, the command prints
|
|
@@ -463,7 +480,8 @@ supports devboxes, and behaves identically from then on.
|
|
|
463
480
|
|
|
464
481
|
Setup asks the user to connect at least one coding agent:
|
|
465
482
|
|
|
466
|
-
- Codex can
|
|
483
|
+
- Codex can use a ChatGPT login, an OpenAI API key, or a model provider
|
|
484
|
+
connection for OpenRouter, Vercel AI Gateway or a compatible custom endpoint.
|
|
467
485
|
- Claude Code can be connected with Claude login or an API key.
|
|
468
486
|
|
|
469
487
|
Users can connect both, but only one is required to start. If auth was skipped
|
|
@@ -471,11 +489,20 @@ for one agent, or if auth later breaks, use Configure agents in the desktop app
|
|
|
471
489
|
or **Settings → Agent accounts** in the mobile app to add another account or API
|
|
472
490
|
key, choose the active credential, edit an API
|
|
473
491
|
key, re-auth, remove a saved credential, or disconnect an agent. The active
|
|
474
|
-
|
|
475
|
-
devboxes. On macOS, Configure agents is in the boxes.dev app menu. Saving a new
|
|
492
|
+
OpenAI and Claude account choices are independent and apply globally across
|
|
493
|
+
the user's devboxes. On macOS, Configure agents is in the boxes.dev app menu. Saving a new
|
|
476
494
|
API key does not replace a working subscription that is already selected; the
|
|
477
495
|
user selects the key to switch to it.
|
|
478
496
|
|
|
497
|
+
Codex model provider connections coexist with those accounts and have no
|
|
498
|
+
global selection radio. Add one through Codex's **Add → Model provider**
|
|
499
|
+
action, or on the website under **Account → Codex model providers**. Choose
|
|
500
|
+
the connection above a new Codex thread's reply box; it will stay fixed for
|
|
501
|
+
that thread while its model and reasoning can change. These connections do
|
|
502
|
+
not take part in OpenAI subscription switching. See
|
|
503
|
+
[Codex model providers](threads-and-agents.md#codex-model-providers) for
|
|
504
|
+
available models, custom endpoints, key replacement and removal.
|
|
505
|
+
|
|
479
506
|
**Log in with Claude** saves a claude.ai login, the same kind of sign-in
|
|
480
507
|
Claude Code gets from `/login` on a computer. Claude on Template boxes and
|
|
481
508
|
devboxes then has the account's claude.ai features: skills and plugins synced
|
|
@@ -698,6 +725,8 @@ or starting services. Leaving it blank skips those extra commands and keeps the
|
|
|
698
725
|
branch default. If a default branch is unknown, confirm the intended starting
|
|
699
726
|
branch and choose **Use default branch**. Setup can continue without one, but
|
|
700
727
|
then new devboxes inherit the saved checkout unless a thread selects a branch.
|
|
728
|
+
The user can add one later under **Default branch** in Project settings ›
|
|
729
|
+
Devbox lifecycle.
|
|
701
730
|
|
|
702
731
|
GitHub creation clones committed Git contents and Git LFS objects. It does not
|
|
703
732
|
copy uncommitted local work, scan local configuration, install dependencies, or
|
|
@@ -928,7 +957,8 @@ When desktop local-folder setup detects a Git remote, **Finalize Bundle** shows
|
|
|
928
957
|
**Startup script**. boxes.dev prepares the selected branch before running the
|
|
929
958
|
script. If the default branch cannot be detected, confirm the intended starting
|
|
930
959
|
branch and choose **Use default branch**. Continuing without one preserves the
|
|
931
|
-
saved checkout unless a thread selects a branch
|
|
960
|
+
saved checkout unless a thread selects a branch, and the user can add one later
|
|
961
|
+
under **Default branch** in Project settings › Devbox lifecycle. The script field saves shell commands
|
|
932
962
|
in the project settings; it does not create a script file on the Template box.
|
|
933
963
|
Leaving it blank skips extra startup commands and does not remove a branch
|
|
934
964
|
default already shown in the review.
|
|
@@ -47,6 +47,15 @@ Claude's fast speed is fast mode. The assistant can choose from the models the
|
|
|
47
47
|
boxes.dev model picker lists for the account, and the start receipt reports
|
|
48
48
|
what the agent was launched with.
|
|
49
49
|
|
|
50
|
+
For Codex, saved OpenRouter, Vercel, and custom model connections appear under
|
|
51
|
+
`codex.providers` in `get_start_options`. Pass the chosen `connectionId` as
|
|
52
|
+
`provider_connection_id` to `start_thread`, with a model from that connection.
|
|
53
|
+
Pass `null` to explicitly select OpenAI. When the saved default names a provider
|
|
54
|
+
connection, carry that ID into the start request; omitting the field retains
|
|
55
|
+
the older OpenAI selection behavior. A newly selected connection without a
|
|
56
|
+
model uses its first listed model. Models without a reasoning control accept
|
|
57
|
+
`reasoning_effort: null`. Continuing an existing thread keeps its provider.
|
|
58
|
+
|
|
50
59
|
Follow-ups queue by default while an agent is working. Codex also supports
|
|
51
60
|
steering to redirect current work; Claude steering is unavailable through this
|
|
52
61
|
connection. Claude follow-ups go directly to its session and do not appear in
|
|
@@ -28,6 +28,13 @@ Optional language runtimes and project-specific services are not guaranteed.
|
|
|
28
28
|
Check actual versions before relying on them. Reuse suitable installed tools,
|
|
29
29
|
and install only the missing dependencies the project needs.
|
|
30
30
|
|
|
31
|
+
The installed `claude` command uses the Claude account connected in boxes.dev
|
|
32
|
+
settings. Occasionally a project needs Claude Code to use other credentials,
|
|
33
|
+
such as a team's Amazon Bedrock account. For that case, set
|
|
34
|
+
`ANTHROPIC_API_KEY` or the Claude Code variable for that cloud provider when
|
|
35
|
+
you run `claude`, and that run will use those credentials instead.
|
|
36
|
+
`claude --version` and `claude --help` work without an account.
|
|
37
|
+
|
|
31
38
|
boxes.dev installs Ubuntu security updates on every Template box and devbox
|
|
32
39
|
automatically. Only security updates are installed, and the box never
|
|
33
40
|
restarts for them. They run in the background once a day, and shortly after a
|
|
@@ -116,6 +116,65 @@ Template tracks exactly one repo below the project directory, new threads start
|
|
|
116
116
|
in that repo, whether they run on a new or an existing devbox. Existing threads
|
|
117
117
|
continue in the working directory they were originally started with.
|
|
118
118
|
|
|
119
|
+
## Codex model providers
|
|
120
|
+
|
|
121
|
+
Codex can use OpenAI, OpenRouter, Vercel AI Gateway, or a compatible custom
|
|
122
|
+
endpoint while keeping its devbox, file and command tools, skills, and
|
|
123
|
+
configured MCPs. A model provider connection is separate from the selected
|
|
124
|
+
OpenAI account. Several connections can coexist; adding one does not select
|
|
125
|
+
it globally or replace a ChatGPT subscription.
|
|
126
|
+
|
|
127
|
+
In desktop **Settings → Agents**, choose **Add** beside Codex, then **Model
|
|
128
|
+
provider**. Select OpenRouter or Vercel AI Gateway, enter its key, optionally
|
|
129
|
+
name the connection, and choose **Save**. The website also offers these forms
|
|
130
|
+
under **Account → Codex model providers**, without requiring the desktop app.
|
|
131
|
+
On mobile, open **Settings → Agent accounts**, tap Codex's **Add → Model
|
|
132
|
+
provider**, then tap **Provider** to select the host. Enter its key and save.
|
|
133
|
+
Saved providers appear below the OpenAI accounts; tap a row for its maintenance
|
|
134
|
+
actions. The selected OpenAI account remains independent.
|
|
135
|
+
Saving validates the configuration without making an inference request. The
|
|
136
|
+
first message will use the provider and its credits, billed separately from
|
|
137
|
+
boxes.dev box-hours. Up to ten provider connections can be saved.
|
|
138
|
+
|
|
139
|
+
For a new Codex thread, choose **Provider** above the reply box. The ordinary
|
|
140
|
+
model and reasoning menus will show choices from that connection. After the
|
|
141
|
+
thread starts, the provider stays fixed and appears in the header; the model
|
|
142
|
+
and supported reasoning level can still change within the connection.
|
|
143
|
+
**Start new thread with…** in the provider menu opens a fresh conversation on
|
|
144
|
+
the same devbox without sending the old conversation to the new provider.
|
|
145
|
+
OpenAI's account selection and automatic subscription switching apply to
|
|
146
|
+
OpenAI threads only.
|
|
147
|
+
|
|
148
|
+
The reviewed OpenRouter and Vercel choices are GLM-5.3 and Kimi K3; OpenRouter
|
|
149
|
+
also offers their Exacto routes. Kimi K3 accepts image input. GLM-5.3 and
|
|
150
|
+
advanced custom endpoints use text input. An unsupported image stays in the
|
|
151
|
+
draft; choose an image-capable model or remove the image before sending.
|
|
152
|
+
Models without reasoning options have no reasoning control. OpenAI speed
|
|
153
|
+
tiers, subscription quotas, built-in web search and image generation are not
|
|
154
|
+
enabled for these connections. Configured MCP tools can still provide those
|
|
155
|
+
capabilities. A gateway may select different serving hosts or quantizations
|
|
156
|
+
for the same model. Exacto does not pin a host; use the provider's routing
|
|
157
|
+
settings when a specific host matters.
|
|
158
|
+
|
|
159
|
+
For an advanced endpoint, select **Custom endpoint (advanced)** and enter its
|
|
160
|
+
base URL, model ID and context size in tokens. Leave the key blank only when
|
|
161
|
+
the endpoint requires no authentication. Localhost means the devbox. The
|
|
162
|
+
endpoint must accept Codex's streaming Responses protocol, including
|
|
163
|
+
namespaced tools, parallel calls and requests for encrypted reasoning, and
|
|
164
|
+
finish successful responses with `response.completed`. Chat Completions alone
|
|
165
|
+
is insufficient. This profile uses text input and omits reasoning effort and
|
|
166
|
+
summary parameters. Its URL, model, context size and authentication mode stay
|
|
167
|
+
fixed; add another connection to change them.
|
|
168
|
+
|
|
169
|
+
The connection's **⋯** menu offers **Rename**, **Replace key**, and
|
|
170
|
+
**Disconnect**. Disconnecting removes the key but keeps thread identity and
|
|
171
|
+
history. **Reconnect** with a replacement key will let those threads continue.
|
|
172
|
+
After disconnecting, **Remove connection** frees its saved slot; old threads
|
|
173
|
+
remain readable but need a new thread to continue working. No-auth endpoints
|
|
174
|
+
offer removal directly. Keys belong to their owner and are not shared by
|
|
175
|
+
sharing a project or thread. Repair a provider-key error on that connection;
|
|
176
|
+
check the provider's dashboard for credit, limit or billing issues.
|
|
177
|
+
|
|
119
178
|
## Machine Hooks And Permissions
|
|
120
179
|
|
|
121
180
|
On an updated managed machine, edit `/etc/boxes/agents/codex/` or
|
|
@@ -188,6 +247,14 @@ thread is known but whose account cannot be matched safely. The dialog discloses
|
|
|
188
247
|
that uncertain account amount without assigning it to the selected account. A
|
|
189
248
|
known extraction gap is partial history, not zero usage.
|
|
190
249
|
|
|
250
|
+
For a Codex model provider thread, recorded activity belongs to its bound
|
|
251
|
+
provider connection. It is not attributed to the selected OpenAI account.
|
|
252
|
+
Choose the **View usage** chart button beside the context indicator to open
|
|
253
|
+
the same dialog, without an OpenAI account or quota section.
|
|
254
|
+
Token and context data depend on what the provider reports; missing data is
|
|
255
|
+
unavailable. Credits, quotas and invoice totals remain in the provider's
|
|
256
|
+
dashboard.
|
|
257
|
+
|
|
191
258
|
The usage-details dialog reads a 24-hour or seven-day point-in-time snapshot
|
|
192
259
|
and shows when it was recorded. The 24-hour chart is hourly; the seven-day
|
|
193
260
|
chart can show one-hour or one-day bars. Refreshing requests a new snapshot; it
|
|
@@ -279,24 +346,28 @@ from any browser. Choose a project; the page offers the same
|
|
|
279
346
|
list, **Add MCP**, agent chips, and row menus, but not **Template-managed
|
|
280
347
|
MCPs**. To sign in to an OAuth MCP there, choose **Open sign-in page** in the
|
|
281
348
|
sign-in dialog and approve access in the new tab. The provider will then send
|
|
282
|
-
that tab to an address starting with `http://127.0.0.1
|
|
283
|
-
that tab's full address, paste it into
|
|
284
|
-
sign-in**. Each sign-in needs to be finished
|
|
285
|
-
works only once. The dialog also shows the
|
|
286
|
-
people who prefer to sign in from a terminal on
|
|
287
|
-
only a private network can reach can't be signed
|
|
288
|
-
desktop app or `dvb mcp authorize` for it.
|
|
289
|
-
|
|
290
|
-
|
|
349
|
+
that tab to an address starting with `http://127.0.0.1:`, which will show a
|
|
350
|
+
connection error. That's expected. Copy that tab's full address, paste it into
|
|
351
|
+
the dialog, and choose **Finish sign-in**. Each sign-in needs to be finished
|
|
352
|
+
within 10 minutes, and its address works only once. The dialog also shows the
|
|
353
|
+
`dvb mcp authorize` command for people who prefer to sign in from a terminal on
|
|
354
|
+
their own computer. An MCP that only a private network can reach can't be signed
|
|
355
|
+
in from the website; use the desktop app or `dvb mcp authorize` for it.
|
|
356
|
+
|
|
357
|
+
Sign-in links from a Template box or devbox, for example after `codex mcp add`,
|
|
358
|
+
will open this page in a normal browser with that connection's sign-in ready.
|
|
359
|
+
When you open one from a thread or terminal in the desktop app, it will open
|
|
360
|
+
**Integrations → MCPs** in that connection's project instead. After you approve
|
|
361
|
+
access, the app will finish signing in automatically, with no address to paste.
|
|
291
362
|
|
|
292
363
|
Supported remote HTTP commands are another entry point to the same list. Running
|
|
293
364
|
a command such as `codex mcp add <name> --url <url>` or `claude mcp add
|
|
294
365
|
--transport http <name> <url>` in a Template box or devbox creates the central
|
|
295
366
|
current-project connection. It does not create a separate machine-only copy.
|
|
296
367
|
When the server uses OAuth, the command will print a boxes.dev sign-in link
|
|
297
|
-
and a `dvb mcp authorize` command, and it will try to open the link
|
|
298
|
-
|
|
299
|
-
|
|
368
|
+
and a `dvb mcp authorize` command, and it will try to open the link. If nothing
|
|
369
|
+
opens, open the link yourself, or run that command in a terminal on your own
|
|
370
|
+
computer, not on the box. An agent that runs
|
|
300
371
|
the command for you will give you the link. To enable both agents, run each
|
|
301
372
|
agent's setup command with the same name, URL, and authentication details,
|
|
302
373
|
including any API-key headers.
|
|
@@ -366,6 +437,12 @@ in the service's browser flow. If you cannot finish, stop the agent and ask
|
|
|
366
437
|
it to try again. Claude browser requests and unsupported forms
|
|
367
438
|
are currently canceled or declined so the agent can continue.
|
|
368
439
|
|
|
440
|
+
Codex will keep a supported form or browser request pending while no app is
|
|
441
|
+
connected, including through a service update on the box. Reopen the thread
|
|
442
|
+
to answer, or stop the turn. Automated turns can wait for an answer too;
|
|
443
|
+
don't rely on an unanswered request timing out. If an older app cannot show
|
|
444
|
+
the request, update boxes.dev and reopen the thread.
|
|
445
|
+
|
|
369
446
|
## Plugins
|
|
370
447
|
|
|
371
448
|
Open **Integrations → Codex/Claude Plugins** in the desktop app. The page talks
|
|
@@ -605,10 +682,11 @@ the thread may show a start-over path.
|
|
|
605
682
|
## Composer Basics
|
|
606
683
|
|
|
607
684
|
Type a prompt and send it from the composer. The desktop composer supports text
|
|
608
|
-
plus file or image attachments when the selected agent and thread
|
|
609
|
-
attachments; add files from the attachment menu or by
|
|
610
|
-
images directly into the composer. The composer can
|
|
611
|
-
the project when the agent surface supports file
|
|
685
|
+
plus file, folder, or image attachments when the selected agent and thread
|
|
686
|
+
state allow attachments; add files or folders from the attachment menu or by
|
|
687
|
+
drag-and-drop, and paste images directly into the composer. The composer can
|
|
688
|
+
also reference files from the project when the agent surface supports file
|
|
689
|
+
search.
|
|
612
690
|
|
|
613
691
|
On mobile, managed Codex and Claude Code conversations support both photos and
|
|
614
692
|
general files, including ZIP archives, from the composer attachment menu.
|
|
@@ -624,6 +702,13 @@ Desktop file attachments are staged into the selected box and can be up to
|
|
|
624
702
|
5 GiB each, with up to 10 GiB of active uploads per user at a time. Image
|
|
625
703
|
attachments still follow the selected agent's image input limits.
|
|
626
704
|
|
|
705
|
+
Desktop folder attachments are compressed on the user's computer and unpacked
|
|
706
|
+
into a folder on the selected box, so the agent receives a folder path. A folder
|
|
707
|
+
can be up to 5 GiB after compression. Everything in the folder is included
|
|
708
|
+
except `.DS_Store` and `._*` files, and symbolic links stay links. A box that
|
|
709
|
+
hasn't updated yet receives a `.tar.gz` file instead, which the agent can
|
|
710
|
+
unpack.
|
|
711
|
+
|
|
627
712
|
For a connected box, boxes.dev checks free disk space before accepting new
|
|
628
713
|
attachments. Files for a new or sleeping devbox can upload while the box
|
|
629
714
|
prepares. Free space is checked again before the files are copied onto the
|
|
@@ -801,8 +886,17 @@ screen and add one page at a time.
|
|
|
801
886
|
|
|
802
887
|
Codex can have a saved goal. A goal tells Codex what to keep working toward
|
|
803
888
|
across turns. Users can start a goal from goal mode or with `/goal ...`, then
|
|
804
|
-
edit, pause, resume, replace, or clear it. Goal
|
|
805
|
-
|
|
889
|
+
edit, pause, resume, replace, or clear it. Choosing **Goal** from the slash
|
|
890
|
+
menu keeps the text and attachments already in the composer; when sent, the
|
|
891
|
+
whole composer becomes the goal, including attached files, images, review
|
|
892
|
+
comments, and browser element selections. A goal over 4,000 Unicode code
|
|
893
|
+
points is saved to a `goal-objective.md` file in the thread's attachments on
|
|
894
|
+
the box, and the goal tells Codex to read that file, so the goal panel shows
|
|
895
|
+
that instruction. **Edit goal** opens the file's full text unless the file is
|
|
896
|
+
larger than 1 MB. Saving a long objective writes a new file; an objective
|
|
897
|
+
shortened to 4,000 code points or fewer is saved as plain text. Goal statuses
|
|
898
|
+
include Pursuing goal, Paused goal, Goal blocked, Goal usage limited, Goal
|
|
899
|
+
limited, and Goal achieved.
|
|
806
900
|
|
|
807
901
|
An idle Codex thread can be branched into a separate conversation. Use exact
|
|
808
902
|
`/fork` to branch from the current tip on the current Template box or devbox.
|
|
@@ -850,6 +944,31 @@ list leaves out `/model` and `/fast`, which the model menu covers. On desktop, `
|
|
|
850
944
|
`/model <model>` switches directly to a known model. Older supported model generations appear
|
|
851
945
|
under **More models** in the picker.
|
|
852
946
|
|
|
947
|
+
`/clear`, `/new`, and `/reset` are unavailable in a Claude thread. The command
|
|
948
|
+
list leaves them out, and desktop, mobile, the CLI, and other agents can't send
|
|
949
|
+
them. Start a new thread to clear Claude's context. A message is refused only
|
|
950
|
+
when one of these names is its first word, so text that mentions them sends
|
|
951
|
+
normally. A custom skill named `clear`, `new`, or `reset` can't run in a thread
|
|
952
|
+
either.
|
|
953
|
+
|
|
954
|
+
Claude Code's own `/goal` command sets a condition that Claude keeps working
|
|
955
|
+
toward across turns until it judges the condition met. `/goal <condition>`
|
|
956
|
+
sets or replaces it, bare `/goal` shows it, and `/goal clear` (or `stop`,
|
|
957
|
+
`off`, `reset`, `none`, `cancel`) removes it. Choosing **/goal** from the slash
|
|
958
|
+
list moves it to the start of the message and uses the text already in the
|
|
959
|
+
reply box as the condition. A condition is limited to 4,000 UTF-16 code
|
|
960
|
+
units (some emoji count as two), including appended attachment paths. A `/goal` message can't include images or
|
|
961
|
+
review content, a status check or clear can't include attachments, and any
|
|
962
|
+
`/goal` message needs Claude to be stopped first. On a new devbox thread,
|
|
963
|
+
`/goal` is unavailable while the project has a **First prompt prefix**.
|
|
964
|
+
In the desktop app, a Goal panel above the composer shows the saved condition
|
|
965
|
+
and, after a check that found it unmet, Claude's reason (`Last check: ...`).
|
|
966
|
+
**Edit goal** fills an empty composer with `/goal <condition>`; if the
|
|
967
|
+
composer has a draft, it keeps the draft and shows a notice. The panel has no
|
|
968
|
+
pause or clear buttons, and the mobile app doesn't show it. While Claude
|
|
969
|
+
Code's hooks are disabled, Claude doesn't restore or run goals, so the panel
|
|
970
|
+
stays hidden.
|
|
971
|
+
|
|
853
972
|
Fast mode runs Claude faster at a higher usage rate on models that support it,
|
|
854
973
|
such as Opus 5.5. On desktop, the model menu has an **Enable fast mode** switch
|
|
855
974
|
and shows a lightning icon beside the model name while fast mode is on; `/fast`
|
|
@@ -1040,9 +1159,9 @@ stop the turn first.
|
|
|
1040
1159
|
|
|
1041
1160
|
A managed Claude Code CLI stays bound to the boxes.dev thread and working
|
|
1042
1161
|
directory it opened. Claude's Agent View and Remote Control are unavailable in
|
|
1043
|
-
that CLI. Commands that would replace or move its session—`/clear`,
|
|
1044
|
-
`/resume`, `/continue`, `/branch`, `/teleport`, `/tp`, and `/cd`—are
|
|
1045
|
-
open or create the intended boxes.dev thread instead. Use `/add-dir` when Claude
|
|
1162
|
+
that CLI. Commands that would replace or move its session—`/clear`, `/new`,
|
|
1163
|
+
`/reset`, `/resume`, `/continue`, `/branch`, `/teleport`, `/tp`, and `/cd`—are
|
|
1164
|
+
rejected; open or create the intended boxes.dev thread instead. Use `/add-dir` when Claude
|
|
1046
1165
|
only needs access to another directory. Session-preserving controls such as
|
|
1047
1166
|
`/compact`, rewind/checkpoint controls, ordinary subagents, and `/fork` remain
|
|
1048
1167
|
available. An ordinary `claude` started in a separate machine shell keeps its
|
|
@@ -1152,6 +1271,23 @@ The order applies to recent threads, folders, devbox groups, the Template box
|
|
|
1152
1271
|
section, and archived threads. Pinned threads keep their own order. In the
|
|
1153
1272
|
activity orders, each row's time and date group show its last activity.
|
|
1154
1273
|
|
|
1274
|
+
**Group devboxes started by agents**, below **Sort threads**, lists each devbox
|
|
1275
|
+
an agent started under the devbox that started it. It is off by default and
|
|
1276
|
+
saved on the account, so every computer and phone follows it. A slim row under
|
|
1277
|
+
the parent shows whether any of those devboxes are working, unread, or need the
|
|
1278
|
+
user, and selecting the row opens them. On desktop the row also counts them.
|
|
1279
|
+
When a devbox started only one, that devbox shows directly under its parent
|
|
1280
|
+
without the row.
|
|
1281
|
+
Devboxes nest under the devbox that started them at every level, and in the
|
|
1282
|
+
main list a group moves up with its newest thread.
|
|
1283
|
+
|
|
1284
|
+
A pinned devbox stays under **Pinned**, and a devbox in a different folder from
|
|
1285
|
+
its parent stays in its folder. A devbox in the same folder as its parent nests
|
|
1286
|
+
under it there. Threads an agent starts on an existing devbox stay on that
|
|
1287
|
+
devbox. If the parent is destroyed, the devboxes it started return to the main
|
|
1288
|
+
list and keep running. Devboxes started from the Template box stay in the main
|
|
1289
|
+
list, as do those started by a coordinator or an automation on desktop.
|
|
1290
|
+
|
|
1155
1291
|
Rows show status indicators for draft, starting, active, unread, idle, archived,
|
|
1156
1292
|
and cold-storage states. Devbox rows also show devbox context and devbox runtime
|
|
1157
1293
|
status where relevant.
|
|
@@ -1410,3 +1546,10 @@ pending request for input stays until it is answered. **Mark unread** on a
|
|
|
1410
1546
|
muted thread lasts until the thread is opened or its next turn finishes.
|
|
1411
1547
|
**Unmute notifications** restores normal behavior. The setting belongs to the thread, so desktop,
|
|
1412
1548
|
mobile, `dvb`, and `dvb-onbox` all show and change the same value.
|
|
1549
|
+
|
|
1550
|
+
When a devbox has two or more muted threads besides its first thread, they
|
|
1551
|
+
collapse into a slim row below its other threads, closed by default. The row
|
|
1552
|
+
shows whether any of them are working, and selecting it opens them. On desktop
|
|
1553
|
+
the row also counts them. A muted thread stays in the main list while it needs
|
|
1554
|
+
input or is unread, and on desktop so does the open thread. The row applies to
|
|
1555
|
+
devboxes in the thread list. The Template box lists its muted threads normally.
|