@boxes-dev/dvb-runtime 1.0.1105 → 1.0.1107
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 +1689 -1155
- 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 +8 -2
- package/dist/product-docs/references/environment-setup-validation.md +12 -4
- package/dist/product-docs/references/fork-workflows.md +9 -5
- package/dist/product-docs/references/getting-started.md +3 -0
- package/dist/product-docs/references/mobile.md +33 -10
- package/dist/product-docs/references/onbox-agent-tools.md +80 -21
- package/dist/product-docs/references/ports-terminal-and-runtime.md +7 -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 +102 -2
- package/dist/product-docs/references/troubleshooting.md +4 -0
- 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,13 @@ 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
|
+
A row says **privileged port** when the computer refuses its local port. macOS
|
|
328
|
+
and Linux normally reserve localhost ports below 1024, such as 80 and 443, for
|
|
329
|
+
root, so the desktop app cannot forward to them. For these rows, **Use next
|
|
330
|
+
available** searches from 8000 ports higher, such as 8080 for 80 or 8443 for
|
|
331
|
+
443. A project rule that maps the port to a higher local port avoids the
|
|
332
|
+
prompt.
|
|
333
|
+
|
|
327
334
|
When available, choose **Use next available** to approve forwarding that remote
|
|
328
335
|
port to a different local port. The chosen local port stays pinned for the
|
|
329
336
|
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
|
|
@@ -366,6 +433,12 @@ in the service's browser flow. If you cannot finish, stop the agent and ask
|
|
|
366
433
|
it to try again. Claude browser requests and unsupported forms
|
|
367
434
|
are currently canceled or declined so the agent can continue.
|
|
368
435
|
|
|
436
|
+
Codex will keep a supported form or browser request pending while no app is
|
|
437
|
+
connected, including through a service update on the box. Reopen the thread
|
|
438
|
+
to answer, or stop the turn. Automated turns can wait for an answer too;
|
|
439
|
+
don't rely on an unanswered request timing out. If an older app cannot show
|
|
440
|
+
the request, update boxes.dev and reopen the thread.
|
|
441
|
+
|
|
369
442
|
## Plugins
|
|
370
443
|
|
|
371
444
|
Open **Integrations → Codex/Claude Plugins** in the desktop app. The page talks
|
|
@@ -801,8 +874,17 @@ screen and add one page at a time.
|
|
|
801
874
|
|
|
802
875
|
Codex can have a saved goal. A goal tells Codex what to keep working toward
|
|
803
876
|
across turns. Users can start a goal from goal mode or with `/goal ...`, then
|
|
804
|
-
edit, pause, resume, replace, or clear it. Goal
|
|
805
|
-
|
|
877
|
+
edit, pause, resume, replace, or clear it. Choosing **Goal** from the slash
|
|
878
|
+
menu keeps the text and attachments already in the composer; when sent, the
|
|
879
|
+
whole composer becomes the goal, including attached files, images, review
|
|
880
|
+
comments, and browser element selections. A goal over 4,000 Unicode code
|
|
881
|
+
points is saved to a `goal-objective.md` file in the thread's attachments on
|
|
882
|
+
the box, and the goal tells Codex to read that file, so the goal panel shows
|
|
883
|
+
that instruction. **Edit goal** opens the file's full text unless the file is
|
|
884
|
+
larger than 1 MB. Saving a long objective writes a new file; an objective
|
|
885
|
+
shortened to 4,000 code points or fewer is saved as plain text. Goal statuses
|
|
886
|
+
include Pursuing goal, Paused goal, Goal blocked, Goal usage limited, Goal
|
|
887
|
+
limited, and Goal achieved.
|
|
806
888
|
|
|
807
889
|
An idle Codex thread can be branched into a separate conversation. Use exact
|
|
808
890
|
`/fork` to branch from the current tip on the current Template box or devbox.
|
|
@@ -850,6 +932,24 @@ list leaves out `/model` and `/fast`, which the model menu covers. On desktop, `
|
|
|
850
932
|
`/model <model>` switches directly to a known model. Older supported model generations appear
|
|
851
933
|
under **More models** in the picker.
|
|
852
934
|
|
|
935
|
+
Claude Code's own `/goal` command sets a condition that Claude keeps working
|
|
936
|
+
toward across turns until it judges the condition met. `/goal <condition>`
|
|
937
|
+
sets or replaces it, bare `/goal` shows it, and `/goal clear` (or `stop`,
|
|
938
|
+
`off`, `reset`, `none`, `cancel`) removes it. Choosing **/goal** from the slash
|
|
939
|
+
list moves it to the start of the message and uses the text already in the
|
|
940
|
+
reply box as the condition. A condition is limited to 4,000 UTF-16 code
|
|
941
|
+
units (some emoji count as two), including appended attachment paths. A `/goal` message can't include images or
|
|
942
|
+
review content, a status check or clear can't include attachments, and any
|
|
943
|
+
`/goal` message needs Claude to be stopped first. On a new devbox thread,
|
|
944
|
+
`/goal` is unavailable while the project has a **First prompt prefix**.
|
|
945
|
+
In the desktop app, a Goal panel above the composer shows the saved condition
|
|
946
|
+
and, after a check that found it unmet, Claude's reason (`Last check: ...`).
|
|
947
|
+
**Edit goal** fills an empty composer with `/goal <condition>`; if the
|
|
948
|
+
composer has a draft, it keeps the draft and shows a notice. The panel has no
|
|
949
|
+
pause or clear buttons, and the mobile app doesn't show it. While Claude
|
|
950
|
+
Code's hooks are disabled, Claude doesn't restore or run goals, so the panel
|
|
951
|
+
stays hidden.
|
|
952
|
+
|
|
853
953
|
Fast mode runs Claude faster at a higher usage rate on models that support it,
|
|
854
954
|
such as Opus 5.5. On desktop, the model menu has an **Enable fast mode** switch
|
|
855
955
|
and shows a lightning icon beside the model name while fast mode is on; `/fast`
|
|
@@ -356,6 +356,10 @@ If a visible port is not forwarded because the local port is already in use,
|
|
|
356
356
|
use **Use next available** when offered, or stop the local process that is
|
|
357
357
|
holding the port.
|
|
358
358
|
|
|
359
|
+
If the row says **privileged port**, the local port is below 1024, and macOS
|
|
360
|
+
and Linux normally reserve it for root. Use **Use next available** to forward it
|
|
361
|
+
8000 ports higher, or add a project rule that maps it to a higher local port.
|
|
362
|
+
|
|
359
363
|
If there are no forwarded ports, make sure the app or service is actually
|
|
360
364
|
running inside the selected box.
|
|
361
365
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@boxes-dev/dvb-runtime",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.1107",
|
|
4
4
|
"description": "Runtime for the boxes.dev CLI. Install @boxes-dev/dvb to use the CLI.",
|
|
5
5
|
"homepage": "https://boxes.dev",
|
|
6
6
|
"type": "module",
|
|
@@ -77,5 +77,5 @@
|
|
|
77
77
|
"e2b": "^2.18.0",
|
|
78
78
|
"ink-testing-library": "^4.0.0"
|
|
79
79
|
},
|
|
80
|
-
"devboxReleasedAt": "2026-10-
|
|
80
|
+
"devboxReleasedAt": "2026-10-30T06:49:33Z"
|
|
81
81
|
}
|