@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.
@@ -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|remove`. |
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. Both agents also take
545
- `serviceTier` `standard` (the default) or `fast`; for Claude, `fast` is fast
546
- mode and needs a model that supports it.
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 worker threads whose results you will review and include in your own reply,
1232
- prefer `--muted`, as in the start examples below. This will keep each worker's
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 make an explicit selection, add a model returned by `threads options` and,
1269
- when supported, one of that model's reasoning efforts and speeds:
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. Reasoning effort or speed
1288
- without a model is invalid. When all execution controls are omitted, the child
1289
- inherits the source box's saved model, reasoning, and speed defaults for the
1290
- selected agent.
1291
- If that source box has no saved defaults for the agent, the managed catalog
1292
- default is used.
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 and reasoning effort and any explicit speed;
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 worker threads created there by agents on that same devbox,
2072
- such as a worker started with `threads start --target current-devbox`:
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 worker; it doesn't
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 workers.
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. **Done** becomes available once a coding agent is connected,
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 be connected with ChatGPT login or an API key.
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
- Codex and Claude choices are independent and apply globally across the user's
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. The script field saves shell commands
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:` that can't load. Copy
283
- that tab's full address, paste it into the dialog, and choose **Finish
284
- sign-in**. Each sign-in needs to be finished within 10 minutes, and its address
285
- works only once. The dialog also shows the `dvb mcp authorize` command for
286
- people who prefer to sign in from a terminal on their own computer. An MCP that
287
- only a private network can reach can't be signed in from the website; use the
288
- desktop app or `dvb mcp authorize` for it. Sign-in links opened from a Template
289
- box or devbox, for example after `codex mcp add`, will open this page in a
290
- normal browser with that connection's sign-in ready.
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 in your
298
- browser. If the browser doesn't open, open the link yourself, or run that
299
- command in a terminal on your own computer, not on the box. An agent that runs
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 state allow
609
- attachments; add files from the attachment menu or by drag-and-drop, and paste
610
- images directly into the composer. The composer can also reference files from
611
- the project when the agent surface supports file search.
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 statuses include Pursuing goal,
805
- Paused goal, Goal blocked, Goal usage limited, Goal limited, and Goal achieved.
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 rejected;
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.