@boxes-dev/dvb-runtime 1.0.1063 → 1.0.1064

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -26,6 +26,13 @@ is hardware-backed.
26
26
  This is a one-line decision in the manifest; the machinery (key detection,
27
27
  staging, warnings) runs during `run` and surfaces problems in its output.
28
28
 
29
+ For OpenPGP signing, install GnuPG on the local machine before `run`; both
30
+ `gpg` and `gpgconf` must be on PATH. On macOS with Homebrew, run
31
+ `brew install gnupg`. If `run` reports a missing tool, install it and retry
32
+ `run`. An existing SSH signing profile uses SSH tools instead of GnuPG.
33
+ To continue without signing, set `gitSigning.mode: skip`, re-run `check`,
34
+ and get approval for the updated launch summary before running again.
35
+
29
36
  `run` prints the public signing key and registration instructions for its Git
30
37
  host. Relay those to the user. Retrieve them again with `dvb agent-init status`
31
38
  (or `status --json`). Only public keys belong in this handoff; never print
package/dist/bin/dvb.mjs CHANGED
@@ -1,6 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
 
3
- !function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="53e072fd-857f-5a39-b752-3d50837dc8a2")}catch(e){}}();
3
+ !function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="939eaffd-82e2-5968-8550-2416e4b967e9")}catch(e){}}();
4
4
  import { createRequire as __dvbCreateRequire } from "node:module";
5
5
  import { dirname as __dvbDirname } from "node:path";
6
6
  import { fileURLToPath as __dvbFileURLToPath } from "node:url";
@@ -69709,9 +69709,9 @@ var init_sentry = __esm({
69709
69709
  uncaughtExceptionMonitorInstalled = false;
69710
69710
  currentDevboxSentryUser = null;
69711
69711
  readBuildMetadata = () => {
69712
- const rawPackageVersion = "1.0.1063";
69713
- const rawGitSha = "7fce98b7b0c6b137390c46333d712985e8e3e69e";
69714
- const rawSentryRelease = "boxes-dev-dvb@1.0.1063+7fce98b7b0c6b137390c46333d712985e8e3e69e";
69712
+ const rawPackageVersion = "1.0.1064";
69713
+ const rawGitSha = "29f88cda72014ceed9419cc5b1ce95333682be41";
69714
+ const rawSentryRelease = "boxes-dev-dvb@1.0.1064+29f88cda72014ceed9419cc5b1ce95333682be41";
69715
69715
  const packageVersion = typeof rawPackageVersion === "string" ? rawPackageVersion : void 0;
69716
69716
  const gitSha = typeof rawGitSha === "string" ? rawGitSha : void 0;
69717
69717
  const sentryRelease = typeof rawSentryRelease === "string" ? rawSentryRelease : void 0;
@@ -75095,7 +75095,7 @@ var init_packageVersion = __esm({
75095
75095
  return path18.join(process.cwd(), "dvb");
75096
75096
  };
75097
75097
  readEmbeddedPackageVersion = () => {
75098
- const raw = "1.0.1063";
75098
+ const raw = "1.0.1064";
75099
75099
  return trimVersion(raw);
75100
75100
  };
75101
75101
  readNearestPackageMetadata = (basePath) => {
@@ -237889,7 +237889,7 @@ import { createHash as createHash15, randomUUID as randomUUID23 } from "node:cry
237889
237889
  import fs41 from "node:fs/promises";
237890
237890
  import os22 from "node:os";
237891
237891
  import path51 from "node:path";
237892
- var uniqueStrings2, trim9, buildSpawnEnv2, runLocalCommand2, runCommandOrThrow, isMissingCommandError, readEffectiveGitConfig, normalizeGitSigningFormat, buildIdentityWarnings, buildProfileId, normalizeOpenPgpSelector, openPgpKeyMatchesSelector, openPgpKeyMatchesEmail, parseGpgSecretKeyListing, detectOpenPgpPassphraseProtected, inspectOpenPgpKeys, getOpenPgpCopyAvailability, expandUserPath, resolveSigningKeyPath, readFileIfExists3, isPublicSshKeyLine, parseSshPublicKey, missingSshPrivateKeyCopyAvailability, inspectLiteralSshPublicKey, inspectPublicSshKeyFile, inspectPrivateSshKeyFile, inspectSshSigningKey, buildIncompleteRepoPlan, detectOpenPgpRepoPlan, detectSshRepoPlan, detectGitSigningRepoPlan, profileKey, collectProfiles, computeRemoteConfigScope, deriveSetupStatus, collectCopyUnavailableReasons, collectWarnings, detectDesktopGitSigningSetup, parseGitRemoteHost2, hostsByProfile, dedupePublicKeys, registrationStatusFor, buildProfilePublicKey, buildSigningPublicKeys, createDesktopGitSigningDecisionFromPlan, validateModeSelection, buildSelectedDesktopGitSigningDecision, ensureFreshDir, throwSourceMissing, normalizeArchivePath, shouldExcludeGpgEntry, copyFileStrict, copyGpgHome, hashFile, assertCopyAvailable, prepareOpenPgpProfile, prepareSshProfile, prepareGitSigningPayload, relativeFromStagingRoot, stageDesktopGitSigningPayload;
237892
+ var uniqueStrings2, trim9, buildSpawnEnv2, runLocalCommand2, runCommandOrThrow, isMissingCommandError, readEffectiveGitConfig, normalizeGitSigningFormat, buildIdentityWarnings, buildProfileId, normalizeOpenPgpSelector, openPgpKeyMatchesSelector, openPgpKeyMatchesEmail, parseGpgSecretKeyListing, detectOpenPgpPassphraseProtected, inspectOpenPgpKeys, getOpenPgpCopyAvailability, expandUserPath, resolveSigningKeyPath, readFileIfExists3, isPublicSshKeyLine, parseSshPublicKey, missingSshPrivateKeyCopyAvailability, inspectLiteralSshPublicKey, inspectPublicSshKeyFile, inspectPrivateSshKeyFile, inspectSshSigningKey, buildIncompleteRepoPlan, detectOpenPgpRepoPlan, detectSshRepoPlan, detectGitSigningRepoPlan, profileKey, collectProfiles, computeRemoteConfigScope, deriveSetupStatus, collectCopyUnavailableReasons, collectWarnings, detectDesktopGitSigningSetup, parseGitRemoteHost2, hostsByProfile, dedupePublicKeys, registrationStatusFor, buildProfilePublicKey, buildSigningPublicKeys, createDesktopGitSigningDecisionFromPlan, assertOpenPgpToolsAvailable, validateModeSelection, buildSelectedDesktopGitSigningDecision, ensureFreshDir, throwSourceMissing, normalizeArchivePath, shouldExcludeGpgEntry, copyFileStrict, copyGpgHome, hashFile, assertCopyAvailable, prepareOpenPgpProfile, prepareSshProfile, prepareGitSigningPayload, relativeFromStagingRoot, stageDesktopGitSigningPayload;
237893
237893
  var init_gitSigning2 = __esm({
237894
237894
  "../../../../shared/initPrep/src/gitSigning.mjs"() {
237895
237895
  "use strict";
@@ -239001,13 +239001,50 @@ var init_gitSigning2 = __esm({
239001
239001
  payloadArchivePath: null,
239002
239002
  updatedAt
239003
239003
  });
239004
- validateModeSelection = ({ copyConfirmed, mode, plan }) => {
239004
+ assertOpenPgpToolsAvailable = async ({ env: env3, projectLayout }) => {
239005
+ for (const command of ["gpg", "gpgconf"]) {
239006
+ let result;
239007
+ try {
239008
+ result = await runLocalCommand2(
239009
+ projectLayout.projectRoot,
239010
+ command,
239011
+ ["--version"],
239012
+ { env: env3 }
239013
+ );
239014
+ } catch (error55) {
239015
+ if (!isMissingCommandError(error55)) throw error55;
239016
+ throw new Error(
239017
+ `OpenPGP Git signing requires GnuPG, but ${command} was not found. Install GnuPG (on macOS: brew install gnupg), make sure ${command} is on PATH, and retry. Or skip Git signing setup.`
239018
+ );
239019
+ }
239020
+ if (result.exitCode !== 0) {
239021
+ throw new Error(
239022
+ `GnuPG command ${command} --version failed with exit code ${result.exitCode}. Repair your GnuPG installation and retry. Or skip Git signing setup.`
239023
+ );
239024
+ }
239025
+ }
239026
+ };
239027
+ validateModeSelection = async ({
239028
+ copyConfirmed,
239029
+ env: env3,
239030
+ mode,
239031
+ plan,
239032
+ projectLayout
239033
+ }) => {
239005
239034
  if (mode !== "create" && mode !== "copy" && mode !== "skip") {
239006
239035
  throw new Error("Desktop Git signing setup mode is invalid.");
239007
239036
  }
239008
239037
  if (mode === "skip") return;
239038
+ const formats = plan ? plan.profiles.length > 0 ? plan.profiles.map((profile) => profile.format) : plan.repos.map(
239039
+ (repo) => normalizeGitSigningFormat(repo.rawFormat).format
239040
+ ) : [];
239041
+ if (formats.includes("openpgp")) {
239042
+ await assertOpenPgpToolsAvailable({ env: env3, projectLayout });
239043
+ }
239009
239044
  if (!plan || plan.status !== "ready" || plan.profiles.length === 0) {
239010
- throw new Error("Git signing setup is not ready for key preparation.");
239045
+ throw new Error(
239046
+ "No complete local Git signing profile was found. Configure local commit signing first, then retry. Or skip Git signing setup."
239047
+ );
239011
239048
  }
239012
239049
  if (mode === "copy") {
239013
239050
  if (copyConfirmed !== true) {
@@ -239034,8 +239071,21 @@ var init_gitSigning2 = __esm({
239034
239071
  previousDecision,
239035
239072
  projectLayout
239036
239073
  }) => {
239037
- const plan = previousDecision?.plan ?? null;
239038
- validateModeSelection({ copyConfirmed, mode, plan });
239074
+ let plan = previousDecision?.plan ?? null;
239075
+ if (mode !== "skip" && plan && plan.profiles.length === 0) {
239076
+ plan = await detectDesktopGitSigningSetup({
239077
+ env: env3,
239078
+ homeDir: homeDir2,
239079
+ projectLayout
239080
+ });
239081
+ }
239082
+ await validateModeSelection({
239083
+ copyConfirmed,
239084
+ env: env3,
239085
+ mode,
239086
+ plan,
239087
+ projectLayout
239088
+ });
239039
239089
  const selectedPlan = plan ? { ...plan, selectedMode: mode } : null;
239040
239090
  const publicKeys = await buildSigningPublicKeys({
239041
239091
  accountScope,
@@ -263031,6 +263081,9 @@ var init_github = __esm({
263031
263081
  print(
263032
263082
  "After GitHub is connected, re-run `dvb agent-init check` to verify repository access."
263033
263083
  );
263084
+ print(
263085
+ "GitHub App access covers pull, push, pull requests, and limited CLI commands. For more GitHub CLI access, authorize optional personal access on the connection page or run `gh auth login` on a managed box."
263086
+ );
263034
263087
  };
263035
263088
  runAgentInitGithub = async (args) => {
263036
263089
  const action = args[0] === "cli" ? args[1] : null;
@@ -263214,6 +263267,11 @@ var init_github = __esm({
263214
263267
  print(
263215
263268
  "This account setting controls whether boxes.dev will sign the gh command into your connected GitHub account on your boxes. It applies across projects and is separate from Git pull and push access."
263216
263269
  );
263270
+ if (connection.runtimeGhProjectionEnabled === true) {
263271
+ print(
263272
+ "Managed gh will prefer connected personal access. Run `gh auth login` on a managed box to authorize optional personal repository, read-only organization, gist, and workflow access."
263273
+ );
263274
+ }
263217
263275
  if ("runtimeGhProjectionStatus" in connection && connection.runtimeGhProjectionStatus === "error") {
263218
263276
  print(
263219
263277
  "GitHub command-line access needs attention. Review your GitHub connection in account settings."
@@ -297222,4 +297280,4 @@ react/cjs/react-jsx-runtime.development.js:
297222
297280
  *)
297223
297281
  */
297224
297282
 
297225
- //# debugId=53e072fd-857f-5a39-b752-3d50837dc8a2
297283
+ //# debugId=939eaffd-82e2-5968-8550-2416e4b967e9
package/dist/bin/dvbd.mjs CHANGED
@@ -64674,9 +64674,9 @@ var init_sentry = __esm({
64674
64674
  uncaughtExceptionMonitorInstalled = false;
64675
64675
  currentDevboxSentryUser = null;
64676
64676
  readBuildMetadata = () => {
64677
- const rawPackageVersion = "1.0.1063";
64678
- const rawGitSha = "7fce98b7b0c6b137390c46333d712985e8e3e69e";
64679
- const rawSentryRelease = "boxes-dev-dvb@1.0.1063+7fce98b7b0c6b137390c46333d712985e8e3e69e";
64677
+ const rawPackageVersion = "1.0.1064";
64678
+ const rawGitSha = "29f88cda72014ceed9419cc5b1ce95333682be41";
64679
+ const rawSentryRelease = "boxes-dev-dvb@1.0.1064+29f88cda72014ceed9419cc5b1ce95333682be41";
64680
64680
  const packageVersion = typeof rawPackageVersion === "string" ? rawPackageVersion : void 0;
64681
64681
  const gitSha = typeof rawGitSha === "string" ? rawGitSha : void 0;
64682
64682
  const sentryRelease = typeof rawSentryRelease === "string" ? rawSentryRelease : void 0;
@@ -66893,7 +66893,7 @@ var init_packageVersion = __esm({
66893
66893
  return path8.join(process.cwd(), "dvb");
66894
66894
  };
66895
66895
  readEmbeddedPackageVersion = () => {
66896
- const raw = "1.0.1063";
66896
+ const raw = "1.0.1064";
66897
66897
  return trimVersion(raw);
66898
66898
  };
66899
66899
  readNearestPackageMetadata = (basePath) => {
@@ -25,9 +25,14 @@ coding agent running inside a boxes.dev Template box or devbox, read only the
25
25
  relevant section of `references/onbox-agent-tools.md` before completing setup,
26
26
  taking a snapshot, delegating work, reading or changing the current thread
27
27
  title, moving devboxes to project folders, creating a Git commit with
28
- optional thread attribution, or using Team Template commands. The documented
29
- command is authoritative about whether an
30
- optional capability is enabled; a disabled or unavailable result is normal and
28
+ optional thread attribution, or using Team Template commands.
29
+ For Project settings, Team Template settings, or the source of inherited Agent
30
+ Guidance, read **Project And Team Template Settings** in that reference and use
31
+ its settings commands. Read the project's captured creation input before
32
+ comparing current template defaults. Settings reads need no editing grant.
33
+
34
+ The documented command is authoritative about whether an optional capability
35
+ is enabled; a disabled or unavailable result is normal and
31
36
  must not block unrelated work. Do not read `agent-tools.md`, probe workstation
32
37
  `dvb`, or look up project inventory from a managed box; those are not part of
33
38
  the on-box tool surface. For other product questions, read
@@ -76,9 +76,11 @@ Template box, they operate on the Template box.
76
76
  ## Snapshot
77
77
 
78
78
  A snapshot is a saved state of an ordinary project's Template box that future
79
- devboxes can start from. A snapshot preserves the saved filesystem and local
80
- development data. New devboxes start their own processes; they do not continue
81
- copied agent or user processes from the Template box. Team Template
79
+ devboxes can start from. A snapshot preserves the saved filesystem, local
80
+ development data, and memory. Apps that run independently of agents and
81
+ terminals, such as Docker containers and system services, keep running on new
82
+ devboxes. Copied agents, terminals, and processes started from them do not
83
+ continue, and background services from setup start again. Team Template
82
84
  member projects use the Team Template's current saved version instead; team
83
85
  admins update it from the Team Template editor.
84
86
 
@@ -373,20 +373,50 @@ An explicitly cleared identity will stay off until you configure it again.
373
373
 
374
374
  ## GitHub CLI In Terminals And Agents
375
375
 
376
- Connecting or reconnecting GitHub turns on **GitHub CLI in devboxes** by
376
+ Connecting or reconnecting GitHub turns on **GitHub CLI access** by
377
377
  default. For supported GitHub repositories, first-run desktop setup shows the
378
378
  checked **Allow GitHub CLI in devboxes** choice in **Finalize Bundle → GitHub
379
379
  access**. Keep it selected to let terminal commands and coding agents use `gh`,
380
380
  or clear it before continuing to turn the grant back off. Later, open
381
381
  **Integrations → GitHub** to change the account-wide choice at any time.
382
382
  Commands such as `gh pr`, `gh run`, and `gh api` use the connected user's
383
- identity. boxes.dev prefers GitHub App access and limits it to repositories
384
- available to both that user and the App. If the App cannot access one of the
385
- project's repositories, **Use personal access** authorizes the official GitHub
386
- CLI once and makes that access available to the user's boxes.dev machines.
387
- Personal access is used only for project repositories the App cannot reach and
388
- still follows the connected user's GitHub permissions. GitHub Actions log
389
- commands also require the connection's Actions permission.
383
+ identity. Managed `gh` prefers connected personal access, subject to the user's
384
+ GitHub permissions and organization authorization. Without personal access, it
385
+ uses GitHub App access after checking every known project repository; that
386
+ credential can reach repositories available to both the user and the App.
387
+ GitHub will enforce the active credential's permissions on each command.
388
+
389
+ Personal sign-in is optional even when App repository access works. Choose
390
+ **Enable** under **Full GitHub CLI access (optional)** in Account, Integrations →
391
+ GitHub, or the optional follow-up in onboarding or project setup, or run `gh auth login` inside a
392
+ managed machine. The App covers pull, push, pull requests, and CLI commands
393
+ within its permissions; personal authorization enables broader CLI use,
394
+ including starting workflows, within the approved scopes and the user's
395
+ permissions. Login will show a
396
+ one-time code and GitHub approval URL and wait for approval with the same GitHub
397
+ account connected to boxes.dev. GitHub will request the official GitHub CLI's
398
+ `repo`, `read:org`, `gist`, and `workflow` scopes, including GitHub Actions
399
+ access. boxes.dev will store the
400
+ authorization centrally and reuse it across the user's Template boxes and
401
+ devboxes; it will not create a native machine-local login.
402
+
403
+ After authorization, Integrations and setup surfaces with selected repositories
404
+ will check personal access to those repositories. A red warning will name any
405
+ repository it cannot reach and explain that GitHub CLI commands for it will
406
+ fail. Open **GitHub permissions** to authorize the official GitHub CLI for the
407
+ organization, complete any required SSO sign-in, and choose **Check again**.
408
+ Alternatively, choose **Disconnect personal access** to return managed `gh` to
409
+ App access. This check won't switch credentials or block setup. It confirms
410
+ repository access, while GitHub enforces each command's permissions. A provider
411
+ outage or rate limit will show that access couldn't be checked rather than
412
+ claiming that permission is missing.
413
+
414
+ When the App has read-only Actions access, reviewed `gh workflow run` and
415
+ `gh run rerun` commands will suggest personal sign-in. This advice does not
416
+ block, retry, or replay the command. After approval, rerun the command explicitly.
417
+ Other GitHub failures do not automatically start authorization. If approval is
418
+ denied, a code expires, or the wrong account was used, run `gh auth login` again
419
+ and approve with the displayed account.
390
420
 
391
421
  For a GitHub-backed project, **Integrations → GitHub** also checks whether the
392
422
  boxes.dev GitHub App can access that project's repositories. If access is
@@ -394,11 +424,14 @@ missing, the page names the affected repository and opens the applicable
394
424
  GitHub grant or management flow. Request or add the repository there, then
395
425
  return to boxes.dev for an automatic recheck or choose **Check again**. An
396
426
  organization admin may need to approve the request. Reconnect GitHub only when
397
- the page says the account connection needs it. If App approval is unavailable,
427
+ the page says the account connection needs it. The ready **Repository access**
428
+ row shows checkmarked capabilities, with push and workflow-file edits shown
429
+ only where the live repository and installation grants allow them. Viewing
430
+ Actions does not grant permission to start a run. If App approval is unavailable,
398
431
  choose **Use personal access**, copy the one-time code, and approve the official
399
- GitHub CLI on GitHub. The GitHub App remains the preferred route because App
400
- access preserves webhook-driven features and can be limited to selected
401
- repositories. Personal access supports GitHub CLI, eligible HTTPS Git, and
432
+ GitHub CLI on GitHub. Personal access takes priority for managed CLI commands;
433
+ Git and explicit pull-request credential selection still prefers App access
434
+ where it works. Personal access supports eligible HTTPS Git and
402
435
  explicit pull-request actions, but it does not add App webhook delivery for a
403
436
  repository the App cannot access. You can disconnect personal access without
404
437
  disconnecting the main GitHub connection.
@@ -407,13 +440,14 @@ This setting is separate from automatic Git pull/push access. It does not
407
440
  change repository remotes, switch a project between HTTPS and SSH, or affect
408
441
  commit authorship. When the setting is off, or GitHub is not connected to
409
442
  boxes.dev, `gh` stays in ordinary user-managed mode and uses the CLI's existing
410
- local configuration and environment. When the setting is on, boxes.dev manages
411
- the CLI identity after confirming access to every known repository in the
412
- current project; do not run `gh auth login`, `gh auth logout`, or another
413
- `gh auth` command that changes that managed account. If neither the App nor
414
- authorized personal access can reach every known repository in the project,
415
- `gh` stays in ordinary machine-local mode even while the account-wide choice
416
- is on. Aliases and extensions run as ordinary code owned by the same machine
443
+ local configuration and environment, including native `gh auth login`. When
444
+ managed access is on, `gh auth login` connects personal access through the
445
+ central approval flow. Manage disconnects in **Integrations → GitHub**; native
446
+ logout, token display, token upload, custom scopes, enterprise hosts, and local
447
+ credential changes are unavailable with managed access. When personal access
448
+ is connected, GitHub enforces repository permission on each CLI request;
449
+ personal CLI access does not require App access to the project's repositories.
450
+ Aliases and extensions run as ordinary code owned by the same machine
417
451
  user and can use the effective managed or local identity.
418
452
 
419
453
  Open **Project settings** in the desktop app, then expand **Git** to choose the
@@ -498,7 +532,7 @@ it opens that pull request in your browser.
498
532
 
499
533
  For an open pull request, open its actions menu and choose **Automate
500
534
  follow-ups**. Select **Failed checks**, **Bot review feedback**, or both. The
501
- selected devbox or Template box needs **GitHub CLI in devboxes** access before
535
+ selected devbox or Template box needs **GitHub CLI access** before
502
536
  you can turn the feature on. The boxes.dev GitHub App also needs access to the
503
537
  repository so GitHub can send the selected events; personal GitHub CLI access
504
538
  alone cannot provide those webhooks.
@@ -271,6 +271,13 @@ directly from the thread. Image previews fit the available
271
271
  screen and support pinch zoom and panning with inertial flings and elastic edge
272
272
  settling.
273
273
 
274
+ In a devbox thread, tapping the **Devbox** pill in the header opens a read-only
275
+ list of the devbox's Git changes: each repository's branch, merge conflicts,
276
+ commits that haven't been pushed, and changed files with added and removed line
277
+ counts. Tapping a changed file opens its diff in the file viewer. A warning
278
+ icon in the pill or the thread row means a repository has unresolved merge
279
+ conflicts.
280
+
274
281
  Large downloads may open through the browser, and they arrive with the file's
275
282
  real name and extension so your phone can open them in the right app. Full
276
283
  file browsing, uploads, inline review, Git staging, commits, and history are
@@ -30,7 +30,8 @@ and request disabled access. Its presence grants nothing; the exact operation
30
30
  and permission-request commands still enforce the source box, thread, owner,
31
31
  and current setting.
32
32
 
33
- The Team Template commands are the exception to the settings model. Their
33
+ Settings reads are available without an editing grant. The Team Template
34
+ checkout commands use their own editing authority. Their
34
35
  skill is available in Team Template editing sessions and can also be present
35
36
  on a project Template box without Team Template access. Direct editing uses
36
37
  the current editing session; remote work from an ordinary Template box needs
@@ -152,6 +153,142 @@ to write files on the Template box. `snapshot` waits for the new snapshot that
152
153
  future devboxes will use. Take one only when the user wants the change to reach
153
154
  future devboxes. Ordinary shell commands still act on the current devbox.
154
155
 
156
+ ## Project And Team Template Settings
157
+
158
+ Read the current project's settings from any of its boxes. No editing
159
+ permission is needed for reads:
160
+
161
+ ```bash
162
+ dvb-onbox project settings get --json
163
+ dvb-onbox team-template settings get --json
164
+ dvb-onbox team-template settings get --template <team-template-id> --json
165
+ ```
166
+
167
+ Project output includes Agent Guidance, prompt prefix, startup/teardown scripts
168
+ and timeouts, Git preferences, port forwarding, storage, environment metadata,
169
+ member-file requirements and supplied state, maintenance where applicable, and
170
+ agent permission defaults. `effectiveGitAction` includes the account's default
171
+ when no project preference is set. `autoWake` reports the account-wide
172
+ preference shown in Project settings. `permissionDefaultsEditable` is always false.
173
+
174
+ Inspect `origin` to identify the source Team Template and saved version, the
175
+ captured `projectConfigurationInput`, and its `configurationSource` when
176
+ recorded. These show what was copied when the project was created. Compare
177
+ those inputs with `team-template settings get` to explain inherited guidance;
178
+ changing template defaults will not replace an existing project's copy.
179
+ Older projects without recorded creation inputs report a null origin.
180
+
181
+ Team Template output includes its identity, description, source/repositories,
182
+ machine size, active saved version, project defaults and save epochs, setup
183
+ instructions, integration requirements, member-project policy, cleanup,
184
+ maintenance and watches, Project URL/MCP definitions, environment definitions,
185
+ and member-file requirements. Omit `--template` to select the current editing
186
+ box's template or the project's source template. An explicit ID must belong to
187
+ the caller's team. Reading does not open or wake a template editing machine.
188
+ Environment/file metadata never includes saved secret values or file contents.
189
+
190
+ To save one section, write an operation to a regular JSON file inside
191
+ `/home/boxes` (at most 512 KiB), then run:
192
+
193
+ ```bash
194
+ dvb-onbox project settings set --settings-file /home/boxes/settings-edit.json --json
195
+ dvb-onbox team-template settings set --settings-file /home/boxes/settings-edit.json --json
196
+ ```
197
+
198
+ Project writes need the current thread's three-hour `edit-project-settings`
199
+ grant. An active `edit-template-box` or `edit-team-template` grant also covers
200
+ that thread's project settings. Team Template writes need team-admin authority
201
+ and `edit-team-template`, or an existing authorized template editing host or
202
+ association. A grant for the source template works without an editing session,
203
+ including from an ordinary project created from it. Request only the minimum
204
+ permission returned by a denied write. Agent permission defaults remain
205
+ user-only even with an editing grant.
206
+
207
+ For example, preserve every lifecycle field returned by `get`, then change
208
+ only the intended value in this operation:
209
+
210
+ ```json
211
+ {
212
+ "section": "lifecycle",
213
+ "settings": {
214
+ "agentGuidance": "Run focused tests before committing.",
215
+ "promptPrefix": "",
216
+ "startupScript": "",
217
+ "startupTimeoutSeconds": 60,
218
+ "teardownScript": "",
219
+ "teardownTimeoutSeconds": 30
220
+ }
221
+ }
222
+ ```
223
+
224
+ Project operations use these fields in addition to `section`:
225
+
226
+ | Section | Fields |
227
+ | --- | --- |
228
+ | `lifecycle` | `settings`: all six lifecycle fields shown above. |
229
+ | `git` | `settings`: `preferredAction` (`pull_request`, `direct_push`, or null) and `threadAttributionEnabled`. |
230
+ | `ports_enabled` | `enabled`. |
231
+ | `ports` | `expectedConfigurationRevision`; `configuration` with `defaultAction` and `rules` from the read result. |
232
+ | `storage` | `enabled`. |
233
+ | `auto_wake` | `enabled` (boolean or null to use the product default); affects the owner's account across projects. |
234
+ | `maintenance` | `script`, `timeoutSeconds`, and the complete schedule fields listed below. |
235
+ | `maintenance_delete` | No additional fields. |
236
+ | `maintenance_watches` | `expectedRevision` from `maintenance.revision`, `confirmWatchRemovals`, `script`, `timeoutSeconds`, `watches` with `repository`, `enabled`, and `paths`; preserves the schedule. |
237
+ | `member_files` | `expectedDefinitionScopeId`, `expectedDefinitionDesiredRevision`, `expectedMemberDesiredRevision` from `memberFilesRevision`; `updates` with `fileId` and `valueAction` (`kind: "delete"`, `kind: "accept"`, or `kind: "replace"` with `plaintextBase64` and `byteLength`). |
238
+ | `environment_file` | `draft` for an ordinary project's environment file, as described below. For a managed project's personal values, use `env set|remove`. |
239
+ | `environment_file_delete` | `contextId`, `expectedContextRevision` for an ordinary project's environment file. |
240
+
241
+ Team Template operations use these fields in addition to `section`:
242
+
243
+ | Section | Fields |
244
+ | --- | --- |
245
+ | `metadata` | `name`, `description` (text; empty clears it). |
246
+ | `defaults` | `expectedSaveEpoch` from `defaults.saveEpoch`; complete `defaults` with optional `lifecycle`, `git`, and `portForwarding` sections. Omitted sections are cleared. |
247
+ | `setup` | `expectedVersion` from `setup.version`, `instructions`. |
248
+ | `integrations` | `expectedSaveEpoch` from `integrations.saveEpoch`, complete `requirements` array. |
249
+ | `member_projects` | `expectedRevision` from `memberProjects.revision`; `policy` with `creationEnabled`, `startupScript`, `startupTimeoutSeconds`, `teardownScript`, and `teardownTimeoutSeconds`. |
250
+ | `cleanup` | `script`. |
251
+ | `maintenance` | `expectedConfigurationVersion`, `script`, `timeoutSeconds`, and all schedule fields. |
252
+ | `maintenance_delete` | `expectedConfigurationVersion`. |
253
+ | `watch_save` | `repositoryId`, `expectedConfigurationVersion` (null for a new watch), `enabled`, `watchedPaths`. |
254
+ | `watch_delete` | `watchId`, `expectedConfigurationVersion`. |
255
+ | `url_create` | `definition` with `displayName`, `targetPort`, `defaultDelivery`, `deliveryRules`, and `state`. |
256
+ | `url_update` | `projectUrlDefinitionId`, `expectedSaveEpoch`, complete `definition`. |
257
+ | `url_delete` | `projectUrlDefinitionId`, `expectedSaveEpoch`. |
258
+ | `mcp_create` | `definition` with `displayName`, `nativeName`, `url`, `authMode` (`oauth`, `static_headers`, or `none`), and `staticHeaderNames`. |
259
+ | `mcp_update` | `mcpDefinitionId`, `expectedSaveEpoch`, complete `definition`. |
260
+ | `mcp_delete` | `mcpDefinitionId`, `expectedSaveEpoch`. |
261
+ | `environment_file` | `draft` for a Team Template environment file, as described below. |
262
+ | `environment_file_delete` | `contextId`, `expectedContextRevision`. |
263
+
264
+ An environment `draft` contains `contextId`, `expectedContextRevision`, `path`,
265
+ `displayOrder`, `adoptionRevision`, `adoptionSourceSha256`,
266
+ `adoptionManagedNames`, `adoptionRemovedNames`, and the complete `rows` array.
267
+ Read these file fields before editing; for a new file use null IDs/revisions,
268
+ empty adoption arrays, and a new relative path. Ordinary project drafts also
269
+ need `state: "active"` or `"pending_adoption"`.
270
+ Each row contains `rowId`, `displayOrder`, `name`, `inlineComment`,
271
+ `description`, and `valueAction`. Team Template rows also need `provider`
272
+ (`team` or `member`), `required`, and `memberInstructions`.
273
+ Use null for a new row ID or absent comment/description/instructions.
274
+ To preserve saved values while changing metadata, use
275
+ `valueAction: {"kind":"keep"}`. Replacements use
276
+ `{"kind":"replace","plaintext":"..."}`; deletion uses `{"kind":"delete"}`.
277
+ Omitted rows are removed. Saved values never appear in the read result.
278
+
279
+ Maintenance schedule fields are `scheduleEnabled`, `schedulePreset`,
280
+ `scheduleTimezone`, `scheduleLocalTime` (text or null), and `scheduleWeekday`
281
+ (number or null). Use the existing desktop editor's allowed schedule values
282
+ from the current read result. Read IDs and revisions before updating a
283
+ definition. After a conflict or uncertain result, read again and reconcile.
284
+ Updates preserve definition identity and use the same validation as desktop
285
+ saves. `set` does not publish a filesystem version. Source identity and machine
286
+ size are creation settings; snapshots, publishing, account sign-in, and machine
287
+ lifecycle retain their existing commands.
288
+
289
+ Use `env set|remove` for environment values and `team-template member-files`
290
+ for requirement definitions. These retain their own input and revision rules.
291
+
155
292
  ## Environment Variables
156
293
 
157
294
  An agent can list, set, and remove the centrally managed environment variables
@@ -170,12 +307,12 @@ What these commands change depends on the project:
170
307
 
171
308
  - In a project with its own Template box, they edit the project's variables.
172
309
  On the Template box they need no extra permission. On a devbox, the current
173
- thread needs the `edit-template-box` permission.
310
+ thread needs `edit-project-settings` or `edit-template-box`.
174
311
  - In a Team Template project, they edit the user's own variables: values for
175
312
  Member rows the team defined, and variables the user added to any file.
176
313
  Team values belong to the team and cannot be changed here. The current
177
- thread needs `edit-personal-environment`, or `edit-team-template` for a team
178
- admin.
314
+ thread needs `edit-project-settings`, `edit-personal-environment`, or
315
+ `edit-team-template` for a team admin.
179
316
 
180
317
  `--file` is relative to the folder the result reports as `pathBase`.
181
318
  `set` replaces the variable if it exists, adds it if it doesn't, and creates
@@ -188,7 +325,7 @@ Environment files**.
188
325
 
189
326
  `--value-stdin` reads the value from standard input and drops one trailing
190
327
  newline. `list` returns names, where each value comes from, and whether a value
191
- is saved; it never returns values. Saved changes reach running machines within
328
+ is saved; it needs no editing grant and never returns values. Saved changes reach running machines within
192
329
  about a minute. After an uncertain response, run `list` before retrying.
193
330
 
194
331
  ## Automations
@@ -450,7 +587,7 @@ The request values are `create-devboxes-and-threads`,
450
587
  `edit-devbox-lifecycle`, `edit-template-maintenance`, `destroy-devbox`,
451
588
  `destroy-created-devboxes`, `read-project-threads`, `read-user-threads`, `read-shared-threads`,
452
589
  `read-team-threads`, `message-agents`, `edit-template-box`,
453
- `edit-team-template`, `edit-personal-environment`, and `edit-automations`.
590
+ `edit-team-template`, `edit-project-settings`, `edit-personal-environment`, and `edit-automations`.
454
591
  Add `--json` for a stable structured result.
455
592
 
456
593
  The command creates one request for the exact managed thread and source box,
@@ -461,19 +598,22 @@ for every agent on that source box until the owner turns it off; it is not a
461
598
  one-operation grant. **Deny** declines this request without changing permission
462
599
  settings. An agent cannot answer its own request.
463
600
 
464
- `edit-template-box`, `edit-team-template`, and `edit-personal-environment`
601
+ `edit-template-box`, `edit-team-template`, `edit-project-settings`, and `edit-personal-environment`
465
602
  work differently. They apply only to the agent in the requesting thread, and
466
603
  the owner sees **Deny** and **Allow for 3 hours**. The grant expires 3 hours
467
604
  after approval. Other threads and boxes never receive it, and no Agent
468
605
  permissions switch or project setting can enable it. Request
469
606
  `edit-template-box` from a devbox in a project with its own Template box to
470
- edit that Template box and the project's environment variables. Request
471
- `edit-team-template` from a devbox in a Team Template project to edit that
472
- Team Template, including its environment variables; only a team admin can
607
+ edit that Template box and the project's settings and environment variables. Request
608
+ `edit-project-settings` from any box in the project to edit its settings,
609
+ including the user's own environment and member-file values. It cannot change
610
+ agent permission defaults. Request
611
+ `edit-team-template` from a box in a project created from a Team Template to edit that
612
+ Team Template's settings, including environment and member-file definitions; only a team admin can
473
613
  receive it. Request `edit-personal-environment` from a devbox in a Team
474
614
  Template project to edit the user's own environment variables for that
475
615
  project; any member can receive it, and a thread that already has
476
- `edit-team-template` does not need it. A thread holds one of these grants at a
616
+ `edit-team-template` or `edit-project-settings` does not need it. A thread holds one of these grants at a
477
617
  time. After the grant expires, the next command reports the missing permission
478
618
  and the agent needs a new request.
479
619
 
@@ -646,12 +786,19 @@ Treat it as the authority for the current box; do not guess from an older
646
786
  list. Discovery reads only the source box and does not create, wake, or
647
787
  inspect a destination devbox.
648
788
 
789
+ For worker threads whose results you will review and include in your own reply,
790
+ prefer `--muted`, as in the start examples below. This will keep each worker's
791
+ completion from notifying the user. Keep notifications enabled when you expect
792
+ the user to review or continue the thread directly, and follow any explicit
793
+ notification preference.
794
+
649
795
  From an authorized ordinary devbox, start another thread on that same devbox:
650
796
 
651
797
  ```bash
652
798
  dvb-onbox threads start \
653
799
  --target current-devbox \
654
800
  --agent codex \
801
+ --muted \
655
802
  --prompt-file <path> \
656
803
  --idempotency-key <caller-key> \
657
804
  --json
@@ -670,6 +817,7 @@ From an authorized source box, start a Codex or Claude thread on a new devbox:
670
817
  dvb-onbox threads start \
671
818
  --target new-devbox \
672
819
  --agent codex \
820
+ --muted \
673
821
  --prompt-file <path> \
674
822
  --idempotency-key <caller-key> \
675
823
  --json
@@ -682,6 +830,7 @@ when supported, one of that model's reasoning efforts and a Codex speed:
682
830
  dvb-onbox threads start \
683
831
  --target new-devbox \
684
832
  --agent codex \
833
+ --muted \
685
834
  --prompt-file <path> \
686
835
  --idempotency-key <caller-key> \
687
836
  --model <model-id> \
@@ -716,6 +865,7 @@ To start another thread on an ordinary devbox, use its instance ID:
716
865
  dvb-onbox threads start \
717
866
  --target devbox:<instance-id> \
718
867
  --agent claude \
868
+ --muted \
719
869
  --prompt-file <path> \
720
870
  --idempotency-key <caller-key> \
721
871
  --json
@@ -731,12 +881,11 @@ Retry an uncertain result with the same idempotency key and identical
731
881
  arguments, including model and reasoning effort and any explicit speed;
732
882
  changed arguments under the same key fail.
733
883
 
734
- Add `--muted` to any start form when the user wants a quiet worker thread or
735
- asks not to be notified about it. A muted thread will not send notifications or
736
- become unread when its turns finish, fail, or are interrupted. It will still
737
- notify the user and show that it needs input when its agent asks a question or
738
- needs an approval, because only the user can answer those. `--muted` is a start
739
- argument, so a retry with the same idempotency key must repeat it.
884
+ A muted thread will not send notifications or become unread when its turns
885
+ finish, fail, or are interrupted. It will still notify the user and show that
886
+ it needs input when its agent asks a question or needs an approval, because
887
+ only the user can answer those. `--muted` is a start argument, so a retry with
888
+ the same idempotency key must repeat it.
740
889
 
741
890
  The source box can continue and inspect only the delegated children it created
742
891
  through this command. It cannot target another same-project thread. The default
@@ -1344,8 +1493,10 @@ environment; do not assume arbitrary home files are excluded.
1344
1493
 
1345
1494
  ### Member-file requirements
1346
1495
 
1347
- An admin can list, add, update, and remove the files members need to provide for
1348
- a Team Template. Run these commands in its current editing box. From an ordinary
1496
+ Read requirements without an editing grant from a project box or the current
1497
+ editing box. A team admin can add, update, and remove requirements from a
1498
+ project created from the template with `edit-team-template`, without an editing
1499
+ session. Run these commands in its current editing box too. From an ordinary
1349
1500
  Template box with an active editor association, add `--template <team-template-id>`
1350
1501
  to select that associated Team Template. Every operation edits the Team
1351
1502
  Template; it does not add requirements to the caller's ordinary project.
@@ -1381,9 +1532,9 @@ upload or read a member's file contents.
1381
1532
 
1382
1533
  ### Team Template environment variables
1383
1534
 
1384
- An admin can define the Team Template's environment variables from the same
1385
- places as member-file requirements, or from a member devbox whose thread has
1386
- the `edit-team-template` permission. A member devbox does not need an open
1535
+ Read the Team Template's environment definitions without an editing grant.
1536
+ An admin can define them from the same places as member-file requirements.
1537
+ A project box whose thread has `edit-team-template` does not need an open
1387
1538
  editing session for these commands.
1388
1539
 
1389
1540
  ```bash
@@ -37,7 +37,9 @@ Signing in on the website before any project exists lands on **Get started**,
37
37
  which has three steps:
38
38
 
39
39
  1. **Connect GitHub**, which is optional and shows as done once GitHub is
40
- connected.
40
+ connected. The completed step offers optional personal GitHub CLI access
41
+ for commands that need the user's own permissions. It can be skipped and
42
+ connected later in Integrations or with `gh auth login`.
41
43
  2. **Set up your project with your coding agent**: a ready-made prompt to
42
44
  paste into Codex or Claude Code in the project folder, which has the agent
43
45
  run the agent-driven terminal setup. The prompt includes a login code that
@@ -76,7 +78,11 @@ The desktop local-folder setup wizard usually moves through these stages:
76
78
 
77
79
  1. Account: sign in to boxes.dev, then optionally connect GitHub and Slack on
78
80
  **Connect your accounts**. GitHub here is sign-in only; boxes.dev asks for
79
- repository access later, once it knows the project's repositories. Team
81
+ repository access later, once it knows the project's repositories. After
82
+ connecting, choose optional personal authorization for CLI commands beyond
83
+ the App's permissions, including starting workflows; it never blocks setup.
84
+ The same follow-up appears in Account, GitHub project setup, local Git access
85
+ setup, and Team Template repository selection. Team
80
86
  admins on a team without a Slack workspace see **Connect Slack** to install
81
87
  it, anyone on a team with a workspace can link their Slack account, and
82
88
  other members see no Slack row. Neither connection is required to continue.
@@ -386,20 +392,34 @@ or **Settings → Agent accounts** in the mobile app to add another account or A
386
392
  key, choose the active credential, edit an API
387
393
  key, re-auth, remove a saved credential, or disconnect an agent. The active
388
394
  Codex and Claude choices are independent and apply globally across the user's
389
- devboxes. On macOS, Configure agents is in the boxes.dev app menu.
395
+ devboxes. On macOS, Configure agents is in the boxes.dev app menu. Saving a new
396
+ API key does not replace a working subscription that is already selected; the
397
+ user selects the key to switch to it.
398
+
399
+ Each saved subscription row in desktop Configure agents shows a small bar for
400
+ the weekly limit's remaining usage. A 5-hour bar appears below it only when
401
+ that limit is low (below 20% left) or the account has no weekly limit. Hovering
402
+ over the bars shows the same quota details as the thread composer, plus when
403
+ the reading was taken if it is more than 15 minutes old. Opening Configure
404
+ agents asks the providers for fresh readings of saved subscriptions; an
405
+ account whose saved sign-in has expired keeps its last reading until an agent
406
+ uses it again. API key rows show when the key was last used and today's tokens,
407
+ including cached tokens, from agent threads on boxes.dev.
390
408
 
391
409
  With multiple subscriptions saved for an agent, desktop Configure agents offers
392
410
  **Automatically rotate subscriptions when usage depleted**. Selecting a
393
411
  subscription radio chooses the **Default** account while automatic selection
394
- is enabled; **Active** marks the account currently in use. boxes.dev prefers
412
+ is enabled; **Default** appears only while an automatic option is on, and
413
+ **Active** marks the account currently in use. boxes.dev prefers
395
414
  the default whenever its usage is available, switches to another subscription
396
415
  when it is exhausted, and returns after quota resets. A saved API key also
397
416
  exposes **Automatically switch to API when all subscriptions are exhausted**,
398
417
  which requires a separate opt-in and incurs the API provider's charges. Unknown
399
418
  quota and authentication failures alone do not authorize API switching.
400
- Choosing an API row directly returns that agent to manual selection. Codex and
401
- Claude settings are independent, global,
402
- and affect conversations started from either desktop or mobile. Mobile can
419
+ Choosing an API row directly returns that agent to manual selection. Turning
420
+ on either automatic option while an API key is selected moves the agent to a
421
+ subscription unless every subscription is exhausted and API switching is on.
422
+ Codex and Claude settings are independent, global, and affect conversations started from either desktop or mobile. Mobile can
403
423
  still select accounts manually; these automatic controls are configured on
404
424
  desktop. Account changes retain conversation history; an agent already working
405
425
  may finish its current turn first. They do not automatically replay a turn that
@@ -417,18 +437,18 @@ because OAuth providers authorize those agents separately.
417
437
 
418
438
  For supported GitHub repositories, first-run desktop setup offers the GitHub
419
439
  CLI choice in **Finalize Bundle → GitHub access**. Connecting or reconnecting
420
- GitHub turns on **GitHub CLI in devboxes**, and the checkbox is selected by
440
+ GitHub turns on **GitHub CLI access**, and the checkbox is selected by
421
441
  default; clear it before continuing to turn the grant back off. The same
422
442
  account-wide choice remains manageable under **Integrations → GitHub → GitHub
423
443
  CLI in devboxes** and applies to all current and future Template boxes and
424
- devboxes. Effective managed access remains project-specific: boxes.dev issues
425
- no managed token when its connected GitHub App credential cannot access every
426
- known repository in the current project. It does not change repository remotes
427
- or the project's Git pull/push access method.
428
- While managed access is effective, users should not run `gh auth login` or `gh
429
- auth logout`. When the choice is disabled, GitHub is not connected to boxes.dev,
430
- or project repository access is missing, `gh` uses its ordinary machine-local
431
- configuration and environment.
444
+ devboxes. Managed `gh` prefers connected personal access. Without it, boxes.dev
445
+ checks App access to every known project repository before supplying the App
446
+ credential. Optional personal sign-in is offered after the GitHub onboarding
447
+ step and in Integrations; `gh auth login` starts the same GitHub approval flow.
448
+ Manage disconnects in Integrations. This does not change repository remotes or
449
+ the project's Git pull/push access method. When the CLI choice is disabled or
450
+ GitHub is not connected, `gh` uses ordinary machine-local configuration and
451
+ native login behavior.
432
452
 
433
453
  boxes.dev stores centrally managed remote MCP definitions and credentials,
434
454
  refreshes OAuth when the provider supports it, and applies the current version
@@ -157,25 +157,26 @@ checks. Team Template editing uses repository-restricted App installation
157
157
  credentials rather than an administrator's broad user credential.
158
158
 
159
159
  Optional personal access uses the official GitHub CLI authorization the user
160
- approved. Before boxes.dev issues this credential, the personal authorization
161
- must match the main GitHub identity and pass the exact repository checks for the
162
- operation. Those checks do not narrow the credential itself: code running on
163
- the machine can inspect the full token, whose permissions come from the GitHub
164
- CLI authorization rather than the GitHub App grants. Personal tokens can be
160
+ approved. The personal authorization must match the main GitHub identity.
161
+ Git and explicit pull-request operations retain their repository checks;
162
+ managed CLI commands use personal access and let GitHub enforce the user's
163
+ permissions on each request. These checks do not narrow the credential itself:
164
+ code running on the machine can inspect the full token, whose permissions come
165
+ from the GitHub CLI authorization rather than the GitHub App grants. Personal tokens can be
165
166
  expiring or non-expiring. **Disconnect personal access** removes the saved
166
167
  authorization and schedules its revocation with GitHub; a copy can remain
167
168
  usable until GitHub completes the revocation.
168
169
 
169
- Connecting or reconnecting GitHub enables **GitHub CLI in devboxes** by default
170
+ Connecting or reconnecting GitHub enables **GitHub CLI access** by default
170
171
  under **Integrations → GitHub**. This account-wide preference lets `gh`, coding
171
172
  agents, aliases, extensions, and other same-user code request the connected
172
- identity on current and future Template boxes and devboxes. Before issuing a
173
- managed credential, boxes.dev checks that one authorization can access every
174
- known GitHub repository in the current project. It prefers App access and can
175
- use the user's separately authorized personal access when the App does not
176
- provide the required repository access. If neither authorization passes those
177
- checks, boxes.dev returns no managed token and leaves `gh` in ordinary
178
- machine-local mode for that project.
173
+ identity on current and future Template boxes and devboxes. Managed `gh` prefers
174
+ the user's separately approved personal access. Without personal access,
175
+ boxes.dev checks that the App can reach every known project repository before
176
+ issuing its credential. Personal sign-in is optional and available from
177
+ onboarding, **Integrations → GitHub**, or `gh auth login`; it requests the
178
+ official GitHub CLI's broad repository, organization, gist, and workflow scopes.
179
+ Organization authorization and the user's GitHub permissions still apply.
179
180
 
180
181
  boxes.dev does not write the managed credential to native `gh` configuration
181
182
  or a managed credential file, but it can exist in the local service, `gh`,
@@ -58,16 +58,15 @@ for long-running processes and stop only the processes you started.
58
58
 
59
59
  GitHub CLI authentication is an explicit user choice in **Finalize Bundle →
60
60
  GitHub access** during first-run desktop setup for supported GitHub repositories
61
- and remains manageable from **Integrations → GitHub → GitHub CLI in devboxes**.
61
+ and remains manageable from **Integrations → GitHub → GitHub CLI access**.
62
62
  Connecting or reconnecting GitHub turns it on by default; clear the setup
63
- checkbox or turn off the Integrations setting to disable it. When enabled and
64
- the App credential can access every known repository in the current project,
65
- ordinary `gh` commands and agent workflows can use the connected GitHub
66
- identity. While managed access is effective, do not run `gh auth login`, `gh
67
- auth logout`, `gh auth refresh`, or `gh auth switch`, and do not add another
68
- ambient GitHub token. When disabled, GitHub is not connected to boxes.dev, or a
69
- known project repository is unavailable to the App credential, `gh` uses the
70
- user's ordinary machine-local configuration and environment. Aliases and
63
+ checkbox or turn off the Integrations setting to disable it. When enabled,
64
+ managed `gh` prefers connected personal access. Without personal access,
65
+ boxes.dev checks App access to every known project repository before supplying
66
+ its credential. Run `gh auth login` to connect optional personal access through
67
+ the GitHub approval code; manage disconnects in **Integrations → GitHub**.
68
+ When disabled or GitHub is not connected to boxes.dev, `gh` uses the user's
69
+ ordinary machine-local configuration and native login behavior. Aliases and
71
70
  extensions run as ordinary same-user code with the effective managed or local
72
71
  identity, so install only ones the user trusts. This CLI grant is separate from
73
72
  the project's Git remote and automatic pull/push access.
@@ -186,6 +185,13 @@ This saves the Template box state used by future Devboxes. Do not snapshot a
186
185
  partially working setup as though it were complete. If setup cannot be
187
186
  completed, report the blocker and the exact remaining requirements instead.
188
187
 
188
+ Apps that run independently of agent and terminal sessions, such as Docker
189
+ containers and system services, keep running on new devboxes created from the
190
+ snapshot. Processes started from an agent command or a terminal do not
191
+ continue there. If every new devbox needs a service, run it independently of a
192
+ session, for example as a Docker container with a restart policy, or start it
193
+ from the project's startup script.
194
+
189
195
  Codex and Claude plugins whose scope is **Template box** are part of that
190
196
  machine state. A change is available on the live Template box immediately, but
191
197
  future devboxes receive it only after a new snapshot; existing devboxes remain
@@ -300,10 +300,25 @@ connection without replacing its sign-in; other personal connections remain.
300
300
  An account-wide source stays available in other projects. See
301
301
  `team-template.md` for matching and template-update behavior.
302
302
 
303
- A connected service can ask Claude for a simple confirmation in the thread.
304
- Choose **Allow** to approve the request or **Deny** to reject it. Requests for
305
- other form input or a separate confirmation URL are canceled so Claude can
306
- continue.
303
+ A connected service can ask Claude or Codex for information in the thread.
304
+ Review the server name and request, fill in the form, and choose **Submit**.
305
+ Forms support text, numbers, Yes/No answers, and single or multiple choices.
306
+ Choose **Clear** to leave an optional field out. A **No** answer is a value
307
+ you can submit; choose **Decline** to refuse the request or **Cancel** to
308
+ dismiss it. Simple confirmations may still use **Allow** and **Deny**.
309
+
310
+ Your unfinished answers will remain available when you leave and return to
311
+ the thread in the same running app. Restarting the app may restore only the
312
+ request and its defaults. If sending fails, your edits will remain available
313
+ for **Retry**.
314
+
315
+ Codex can also ask you to complete a service request in your browser. Review
316
+ the destination, choose **Open in browser**, and finish the service's flow
317
+ there. Opening the page will send your consent; the agent will continue
318
+ after the service reports completion. Enter passwords and credentials only
319
+ in the service's browser flow. If you cannot finish, stop the agent and ask
320
+ it to try again. Claude browser requests and unsupported forms
321
+ are currently canceled or declined so the agent can continue.
307
322
 
308
323
  ## Plugins
309
324
 
@@ -590,9 +605,15 @@ action.
590
605
  The Codex rate-limit indicator shows remaining session, weekly, and available
591
606
  model-specific quotas with countdowns to their resets. Limits for the selected
592
607
  model use warning colors; quotas for other models remain visible in muted
593
- colors. When the connected ChatGPT account has banked limit reset credits, the
594
- same indicator shows how many are available and when they expire; that section
595
- is omitted when credit inventory is unavailable.
608
+ colors. When the connected ChatGPT account has credits, the indicator also
609
+ shows the credit balance. Codex keeps working on credits after the ordinary
610
+ session or weekly limit runs out, so that limit shows an amber warning instead
611
+ of the red alert, and the balance is marked in use. When the account has banked
612
+ usage limit resets, the same indicator shows how many are available and when
613
+ the next three expire; that row is omitted when reset inventory is unavailable.
614
+ The indicator's details name the account the limits belong to. When Codex is
615
+ using an API key, the indicator shows a key icon instead, with today's token
616
+ usage for that key when available.
596
617
 
597
618
  Codex transcript activity keeps tool work readable after it finishes. A model
598
619
  that reads or searches files and runs several foreground commands can settle
@@ -758,7 +779,9 @@ session and weekly quota with reset times. That quota is shared across
758
779
  Template boxes and devboxes using the same Anthropic organization and account.
759
780
  If a thread is still connected with credentials from before a re-authentication,
760
781
  it continues to show the quota for the account scope that thread is actually
761
- using.
782
+ using. The quota details name that account. When Claude Code is using an API
783
+ key, the composer shows a key icon instead, with today's token usage for that
784
+ key when available.
762
785
 
763
786
  Claude Code transcripts can be shown in two transcript styles, chosen from the
764
787
  thread action menu's Transcript style submenu: CLI style (a terminal-style
@@ -340,27 +340,27 @@ First confirm that the selected Template box or devbox is awake and ready.
340
340
  First-run desktop setup may already have connected GitHub while leaving its
341
341
  separate CLI checkbox cleared in **Finalize Bundle → GitHub access**. Open
342
342
  **Integrations → GitHub**, connect or reconnect the account if needed, and turn
343
- on **GitHub CLI in devboxes** when `gh` should use that connected identity. If
343
+ on **GitHub CLI access** when `gh` should use that connected identity. If
344
344
  the switch is unavailable, finish the shown GitHub reconnect step first. An
345
345
  older machine may need to finish its boxes.dev update before managed `gh`
346
346
  commands become available.
347
347
 
348
- When the setting is on and the current project's repository access is ready,
349
- do not repair authentication by running `gh auth login`, `gh auth logout`, `gh
350
- auth refresh`, or `gh auth switch`; manage that identity from boxes.dev. When
351
- the setting is off, GitHub is not connected to boxes.dev, or neither the App nor
352
- authorized personal access can reach every known repository in this project,
353
- `gh` uses its ordinary local configuration and environment instead. In the
354
- missing-access case, it is safe to run `gh auth login` on that machine.
348
+ When the setting is on, run `gh auth login` to connect optional personal access
349
+ through GitHub's approval code. Approve with the account connected to boxes.dev;
350
+ managed `gh` will prefer that personal access. Manage disconnects in
351
+ **Integrations → GitHub**. When the setting is off or GitHub is not connected,
352
+ `gh` uses its ordinary local configuration and native login behavior.
355
353
  Disabling GitHub CLI does not disable automatic Git fetch, pull, or push for a
356
354
  project that uses that separate access method.
357
355
 
358
356
  If a repository or API request is still rejected while `gh` is enabled, use
359
357
  **Manage repository access** to check App access, and reconnect GitHub if the
360
358
  page requests it. If your organization cannot approve the App, choose **Use
361
- personal access** and authorize the official GitHub CLI. boxes.dev can manage
362
- the CLI identity only when either the App or personal authorization can access
363
- every known repository in the project.
359
+ personal access** and authorize the official GitHub CLI. Personal access is
360
+ also available when App repository access works but a command needs broader
361
+ permissions. Without personal access, boxes.dev checks that the App can reach
362
+ every known project repository before issuing its credential. With personal
363
+ access, GitHub enforces the user's permissions on each CLI command.
364
364
 
365
365
  ## Billing Or Limit Blocks
366
366
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@boxes-dev/dvb-runtime",
3
- "version": "1.0.1063",
3
+ "version": "1.0.1064",
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-10T18:25:21Z"
80
+ "devboxReleasedAt": "2026-10-10T22:39:43Z"
81
81
  }