windows-development-sandbox 1.18.4 → 1.23.0

package/dist/core/disk.js

@@ -59,22 +59,7 @@ export function sizeWithin(p, ms) {
         throw e;
     }
 }
-/**
- * Free bytes on the drive that holds `dir` (which may not exist yet: the nearest existing parent is asked); null if
- * unknown.
- */
-export function freeBytesAt(dir) {
-    let at = path.resolve(dir);
-    while (!fs.existsSync(at) && path.dirname(at) !== at)
-        at = path.dirname(at);
-    try {
-        const s = fs.statfsSync(at);
-        return s.bavail * s.bsize;
-    }
-    catch {
-        return null;
-    }
-}
+export { freeBytesAt } from '../shared/io/disk.js';
 /** Every local drive's size and free space, and which one holds the sandbox storage. */
 export function diskUsage(storageRoot) {
     const storageDrive = path.parse(path.resolve(storageRoot)).root.toUpperCase();

package/dist/core/schema/accounts.d.ts

@@ -24,4 +24,10 @@ export declare const AccountsSchema: z.ZodObject<{
     appstore: z.ZodObject<{
         share: z.ZodBoolean;
     }, z.core.$strict>;
+    perplexity: z.ZodObject<{
+        share: z.ZodBoolean;
+    }, z.core.$strict>;
+    comet: z.ZodObject<{
+        share: z.ZodBoolean;
+    }, z.core.$strict>;
 }, z.core.$strict>;

package/dist/core/schema/accounts.js

@@ -1,7 +1,7 @@
 // accounts: which saved service sign-ins sandboxes get (the sign-ins themselves are not settings: they are kept
 // encrypted by `sandbox account import|login`, or come back from a sandbox you signed in in).
 import { z } from 'zod';
-import { SERVICE_SPECS } from '../../shared/accounts/kinds.js';
+import { SERVICE_SPECS, usedByText } from '../../shared/accounts/kinds.js';
 function share(kind, how) {
     const spec = SERVICE_SPECS[kind];
     return z.strictObject({
@@ -10,7 +10,7 @@ function share(kind, how) {
             .describe('Hand your saved ' +
             spec.label +
             ' sign-in to sandboxes that use ' +
-            spec.usedBy.join(' or ') +
+            usedByText(spec.usedBy) +
             ' (' +
             how +
             '). Kept encrypted on this PC; ' +
@@ -20,13 +20,15 @@ function share(kind, how) {
 }
 export const AccountsSchema = z
     .strictObject({
-    epic: share('epic', "sign in to the launcher once in a sandbox, or take this PC's: sandbox account import epic"),
-    steam: share('steam', 'sign in once with sbx-steam login, or: sandbox account import steam --from <steamcmd folder>'),
-    unity: share('unity', "sign in once in a sandbox, or take this PC's licence: sandbox account import unity"),
-    cfx: share('cfx', 'sandbox account login cfx'),
-    keystore: share('keystore', 'sandbox account import keystore --from <upload.jks>'),
-    play: share('play', 'sandbox account import play --from <service-account.json>'),
-    expo: share('expo', 'sandbox account login expo'),
-    appstore: share('appstore', 'sandbox account import appstore --from <AuthKey.p8>'),
+    epic: share('epic', "sign in to the launcher once in a sandbox, or take this PC's from Accounts"),
+    steam: share('steam', 'sign in once with sbx-steam login, or take it from a SteamCMD folder in Accounts'),
+    unity: share('unity', "sign in once in a sandbox, or take this PC's licence from Accounts"),
+    cfx: share('cfx', 'type the key in Accounts'),
+    keystore: share('keystore', 'import the upload.jks file in Accounts'),
+    play: share('play', 'import the service-account.json file in Accounts'),
+    expo: share('expo', 'type the token in Accounts'),
+    appstore: share('appstore', 'import the AuthKey.p8 file in Accounts'),
+    perplexity: share('perplexity', 'type the API key in Accounts, or import it from a .env file'),
+    comet: share('comet', 'sign in to Comet once in a sandbox: it cannot be taken from this PC'),
 })
-    .describe('Service sign-ins for sandboxes (game stores, engines, app signing). Manage them in Accounts: sandbox account status.');
+    .describe('Service sign-ins for sandboxes (game stores, engines, app signing, Perplexity). Manage them in Accounts.');

package/dist/core/schema/codex.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+export declare const CodexSchema: z.ZodObject<{
+    sandboxMode: z.ZodEnum<{
+        "danger-full-access": "danger-full-access";
+        "workspace-write": "workspace-write";
+        "read-only": "read-only";
+    }>;
+    approvalPolicy: z.ZodEnum<{
+        never: "never";
+        "on-request": "on-request";
+        "on-failure": "on-failure";
+        untrusted: "untrusted";
+    }>;
+    model: z.ZodString;
+    reasoningEffort: z.ZodEnum<{
+        default: "default";
+        minimal: "minimal";
+        low: "low";
+        medium: "medium";
+        high: "high";
+        xhigh: "xhigh";
+    }>;
+    windowsSandbox: z.ZodEnum<{
+        off: "off";
+        unelevated: "unelevated";
+        elevated: "elevated";
+    }>;
+    mcpLoginsInFile: z.ZodBoolean;
+}, z.core.$strict>;

package/dist/core/schema/codex.js

@@ -0,0 +1,24 @@
+// How Codex runs inside the sandbox. Yours only: a project file (.sandbox-config.json) cannot change it.
+import { z } from 'zod';
+export const CodexSchema = z.strictObject({
+    sandboxMode: z
+        .enum(['danger-full-access', 'workspace-write', 'read-only'])
+        .describe("Codex's own sandbox. Inside Windows Sandbox Codex's own sandbox only slows it down (it re-grants file permissions over your profile at every boot), so the default is danger-full-access: Windows Sandbox is the sandbox."),
+    approvalPolicy: z
+        .enum(['never', 'on-request', 'on-failure', 'untrusted'])
+        .describe('When Codex asks before it runs a command. "never" with danger-full-access starts it with no questions.'),
+    model: z
+        .string()
+        .max(100)
+        .regex(/^[A-Za-z0-9._:/-]*$/, 'letters, digits and . _ : / - only')
+        .describe("The model Codex uses. Empty = Codex's own default."),
+    reasoningEffort: z
+        .enum(['default', 'minimal', 'low', 'medium', 'high', 'xhigh'])
+        .describe('How hard Codex thinks. "default" = Codex\'s own default.'),
+    windowsSandbox: z
+        .enum(['off', 'unelevated', 'elevated'])
+        .describe('Codex\'s Windows sandbox mode in its config.toml. "off" removes the setting so Codex does not set up its sandbox users and firewall rules at every boot.'),
+    mcpLoginsInFile: z
+        .boolean()
+        .describe('Keep the sign-ins of Codex\'s MCP servers in a file in the saved Codex folder (mcp_oauth_credentials_store = "file"), so they survive between sandboxes. A value you set in config.toml is kept.'),
+});

package/dist/core/schema/config.d.ts

@@ -121,6 +121,12 @@ export declare const ConfigSchema: z.ZodObject<{
         appstore: z.ZodObject<{
             share: z.ZodBoolean;
         }, z.core.$strict>;
+        perplexity: z.ZodObject<{
+            share: z.ZodBoolean;
+        }, z.core.$strict>;
+        comet: z.ZodObject<{
+            share: z.ZodBoolean;
+        }, z.core.$strict>;
     }, z.core.$strict>;
     pcInstalls: z.ZodObject<{
         steamGames: z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodNumber>]>;
@@ -190,6 +196,10 @@ export declare const ConfigSchema: z.ZodObject<{
             acceptLicense: z.ZodBoolean;
             components: z.ZodArray<z.ZodString>;
             keepInstallFiles: z.ZodBoolean;
+            visualStudio: z.ZodEnum<{
+                full: "full";
+                autosdk: "autosdk";
+            }>;
             persistEngines: z.ZodBoolean;
             derivedDataCache: z.ZodEnum<{
                 persisted: "persisted";
@@ -444,6 +454,34 @@ export declare const ConfigSchema: z.ZodObject<{
         resumeArguments: z.ZodOptional<z.ZodArray<z.ZodString>>;
         resumeOneArguments: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
+    codex: z.ZodObject<{
+        sandboxMode: z.ZodEnum<{
+            "danger-full-access": "danger-full-access";
+            "workspace-write": "workspace-write";
+            "read-only": "read-only";
+        }>;
+        approvalPolicy: z.ZodEnum<{
+            never: "never";
+            "on-request": "on-request";
+            "on-failure": "on-failure";
+            untrusted: "untrusted";
+        }>;
+        model: z.ZodString;
+        reasoningEffort: z.ZodEnum<{
+            default: "default";
+            minimal: "minimal";
+            low: "low";
+            medium: "medium";
+            high: "high";
+            xhigh: "xhigh";
+        }>;
+        windowsSandbox: z.ZodEnum<{
+            off: "off";
+            unelevated: "unelevated";
+            elevated: "elevated";
+        }>;
+        mcpLoginsInFile: z.ZodBoolean;
+    }, z.core.$strict>;
     hooks: z.ZodObject<{
         failFast: z.ZodBoolean;
     }, z.core.$strict>;
@@ -534,6 +572,12 @@ export declare const LocalOverridesSchema: z.ZodObject<{
         appstore: z.ZodOptional<z.ZodObject<{
             share: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
+        perplexity: z.ZodOptional<z.ZodObject<{
+            share: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        comet: z.ZodOptional<z.ZodObject<{
+            share: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
     }, z.core.$strict>>;
     provisioning: z.ZodOptional<z.ZodObject<{
         copyFromHost: z.ZodOptional<z.ZodBoolean>;
@@ -556,7 +600,7 @@ export declare const LocalOverridesSchema: z.ZodObject<{
     }, z.core.$strict>>;
     toolchains: z.ZodOptional<z.ZodObject<{
         environment: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-        node: z.ZodOptional<z.ZodObject<{
+        unity: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict> | z.ZodObject<{
             version: z.ZodOptional<z.ZodString>;
@@ -571,7 +615,7 @@ export declare const LocalOverridesSchema: z.ZodObject<{
             zstd: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
             openssl: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
         }, z.core.$strict>>;
-        go: z.ZodOptional<z.ZodObject<{
+        godot: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict> | z.ZodObject<{
             version: z.ZodOptional<z.ZodString>;
@@ -586,7 +630,7 @@ export declare const LocalOverridesSchema: z.ZodObject<{
             zstd: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
             openssl: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
         }, z.core.$strict>>;
-        python: z.ZodOptional<z.ZodObject<{
+        android: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict> | z.ZodObject<{
             version: z.ZodOptional<z.ZodString>;
@@ -601,7 +645,7 @@ export declare const LocalOverridesSchema: z.ZodObject<{
             zstd: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
             openssl: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
         }, z.core.$strict>>;
-        rust: z.ZodOptional<z.ZodObject<{
+        flutter: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict> | z.ZodObject<{
             version: z.ZodOptional<z.ZodString>;
@@ -616,7 +660,7 @@ export declare const LocalOverridesSchema: z.ZodObject<{
             zstd: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
             openssl: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
         }, z.core.$strict>>;
-        msvc: z.ZodOptional<z.ZodObject<{
+        dart: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict> | z.ZodObject<{
             version: z.ZodOptional<z.ZodString>;
@@ -631,7 +675,7 @@ export declare const LocalOverridesSchema: z.ZodObject<{
             zstd: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
             openssl: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
         }, z.core.$strict>>;
-        unreal: z.ZodOptional<z.ZodObject<{
+        reactNative: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict> | z.ZodObject<{
             version: z.ZodOptional<z.ZodString>;
@@ -646,7 +690,7 @@ export declare const LocalOverridesSchema: z.ZodObject<{
             zstd: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
             openssl: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
         }, z.core.$strict>>;
-        unity: z.ZodOptional<z.ZodObject<{
+        unreal: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict> | z.ZodObject<{
             version: z.ZodOptional<z.ZodString>;
@@ -661,7 +705,7 @@ export declare const LocalOverridesSchema: z.ZodObject<{
             zstd: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
             openssl: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
         }, z.core.$strict>>;
-        godot: z.ZodOptional<z.ZodObject<{
+        node: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict> | z.ZodObject<{
             version: z.ZodOptional<z.ZodString>;
@@ -676,7 +720,7 @@ export declare const LocalOverridesSchema: z.ZodObject<{
             zstd: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
             openssl: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
         }, z.core.$strict>>;
-        steam: z.ZodOptional<z.ZodObject<{
+        go: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict> | z.ZodObject<{
             version: z.ZodOptional<z.ZodString>;
@@ -691,7 +735,7 @@ export declare const LocalOverridesSchema: z.ZodObject<{
             zstd: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
             openssl: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
         }, z.core.$strict>>;
-        fivem: z.ZodOptional<z.ZodObject<{
+        python: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict> | z.ZodObject<{
             version: z.ZodOptional<z.ZodString>;
@@ -706,7 +750,7 @@ export declare const LocalOverridesSchema: z.ZodObject<{
             zstd: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
             openssl: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
         }, z.core.$strict>>;
-        android: z.ZodOptional<z.ZodObject<{
+        rust: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict> | z.ZodObject<{
             version: z.ZodOptional<z.ZodString>;
@@ -721,7 +765,7 @@ export declare const LocalOverridesSchema: z.ZodObject<{
             zstd: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
             openssl: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
         }, z.core.$strict>>;
-        flutter: z.ZodOptional<z.ZodObject<{
+        msvc: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict> | z.ZodObject<{
             version: z.ZodOptional<z.ZodString>;
@@ -736,7 +780,7 @@ export declare const LocalOverridesSchema: z.ZodObject<{
             zstd: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
             openssl: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
         }, z.core.$strict>>;
-        dart: z.ZodOptional<z.ZodObject<{
+        steam: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict> | z.ZodObject<{
             version: z.ZodOptional<z.ZodString>;
@@ -751,7 +795,7 @@ export declare const LocalOverridesSchema: z.ZodObject<{
             zstd: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
             openssl: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>>;
         }, z.core.$strict>>;
-        reactNative: z.ZodOptional<z.ZodObject<{
+        fivem: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict> | z.ZodObject<{
             version: z.ZodOptional<z.ZodString>;

package/dist/core/schema/config.js

@@ -4,6 +4,7 @@ import _ from 'lodash';
 import { z } from 'zod';
 import { NameSchema, SchemaRefSchema, StringsSchema, toggle } from './common.js';
 import { DatabasesSchema } from './databases.js';
+import { CodexSchema } from './codex.js';
 import { HarnessSchema } from './harness.js';
 import { AgentCommandsSchema, AttachSchema, ClaudeProfileSchema, SecretsSchema } from './profile.js';
 import { AuditSchema, DownloadsSchema, SharingSchema, GitSchema, GuestWorkspaceSchema, MappingSchema, NetworkSchema, ProvisioningSchema, SandboxSchema, WorkspaceFilterSchema, } from './sandbox.js';
@@ -52,7 +53,7 @@ export function reservedEnvName(name) {
 export const ConfigSchema = z
     .strictObject({
     $schema: SchemaRefSchema.optional(),
-    defaultHarness: NameSchema.describe('Agent started by `sandbox launch` (sandbox claude always runs claude).'),
+    defaultHarness: NameSchema.describe('The agent that starts when you do not name one (starting claude by name always runs claude).'),
     guestWorkspace: GuestWorkspaceSchema,
     readOnly: z.boolean().describe('Map the workspace read-only.'),
     workspaceFilter: WorkspaceFilterSchema,
@@ -64,7 +65,7 @@ export const ConfigSchema = z
         root: z
             .string()
             .min(1)
-            .describe('Where everything is kept on this PC (tools, databases, logins, launches). The default is a private folder for you under %ProgramData%\\AgentSandbox\\users, which works for installs for one user and for everyone. sandbox storage move <folder> moves it.'),
+            .describe('Where everything is kept on this PC (tools, databases, logins, launches). The default is a private folder for you under %ProgramData%\\AgentSandbox\\users, which works for installs for one user and for everyone. Maintenance > Storage moves it.'),
         persistAgentState: z.boolean().describe('Keep agent logins and history between sandboxes.'),
         dataName: NameSchema.describe('Name of the persistent data set (C:\\AgentData) shared by all workspaces.'),
         markSandboxFiles: z
@@ -72,7 +73,7 @@ export const ConfigSchema = z
             .describe('Programs and scripts (.exe, .ps1, .bat, .cmd, .msi, .lnk ...) that appear or change in your project while a sandbox runs get Windows\' "downloaded from the internet" mark, so SmartScreen and PowerShell ask before they run on this PC.'),
         contained: z
             .enum(['off', 'vhdx'])
-            .describe('(beta) Keep the sandbox tools, state and logs inside one disk image file (vhdx) instead of loose folders, so scanning programs on this PC see one file. Not yet tried on a real PC. Turn it on with sandbox storage contained on (it moves your files and asks first); Windows asks for permission to mount the image when a sandbox starts. "off" = loose folders, as always. Yours only: a project file (.sandbox-config.json) cannot set it.'),
+            .describe('(beta) Keep the sandbox tools, state and logs inside one disk image file (vhdx) instead of loose folders, so scanning programs on this PC see one file. Not yet tried on a real PC. Turn it on in Maintenance > Storage (it moves your files and asks first); Windows asks for permission to mount the image when a sandbox starts. "off" = loose folders, as always. Yours only: a project file (.sandbox-config.json) cannot set it.'),
         containedMaxGb: z
             .number()
             .int()
@@ -82,7 +83,7 @@ export const ConfigSchema = z
         warnDataGb: z
             .number()
             .min(0)
-            .describe('Say at launch when the persisted data (tools, databases, logins) is bigger than this many GB; 0 = never. sandbox data shows what takes the space.'),
+            .describe('Say at launch when the persisted data (tools, databases, logins) is bigger than this many GB; 0 = never. Maintenance > Data shows what takes the space.'),
     }),
     network: NetworkSchema,
     vpn: VpnSchema,
@@ -101,6 +102,7 @@ export const ConfigSchema = z
     apps: AppsSchema,
     claudeProfile: ClaudeProfileSchema,
     harnesses: z.record(NameSchema, HarnessSchema).describe('Agents that can run in the sandbox.'),
+    codex: CodexSchema,
     hooks: z.strictObject({ failFast: z.boolean().describe('Stop when a hook script fails.') }),
     projects: ProjectsSchema.describe('Several projects in one sandbox: folders of projects mapped at every start, and adding folders while it runs.'),
     resume: ResumeSchema.describe('Reopening the sessions of the last sandbox when a new one starts.'),

package/dist/core/schema/github.js

@@ -3,5 +3,5 @@ import { z } from 'zod';
 export const GithubSchema = z.strictObject({
     shareToken: z
         .boolean()
-        .describe('Give each sandbox the GitHub token you saved with `sandbox github login` (best a fine-grained token limited to some repositories and permissions), so gh and https git work there without logging in. Only with provisioning.git.access "full". The agent in the sandbox can read the token and use it for whatever it allows. A project file (.sandbox-config.json) cannot turn this on.'),
+        .describe('Give each sandbox the GitHub token you saved in Accounts (best a fine-grained token limited to some repositories and permissions), so gh and https git work there without logging in. Only with provisioning.git.access "full". The agent in the sandbox can read the token and use it for whatever it allows. A project file (.sandbox-config.json) cannot turn this on.'),
 });

package/dist/core/schema/index.d.ts

@@ -2,6 +2,7 @@ export { GitAccessSchema, NameSchema, secret } from './common.js';
 export { REDACTED, redactSecrets, scrubSecrets, secretPaths, secretValues } from './redact.js';
 export { ConfigSchema, LocalOverridesSchema } from './config.js';
 export { HarnessSchema } from './harness.js';
+export { CodexSchema } from './codex.js';
 export { describeIssues, jsonSchemas } from './json-schema.js';
 export { MappingSchema } from './sandbox.js';
 export { ToolchainsSchema } from './toolchains.js';

package/dist/core/schema/index.js

@@ -4,6 +4,7 @@ export { GitAccessSchema, NameSchema, secret } from './common.js';
 export { REDACTED, redactSecrets, scrubSecrets, secretPaths, secretValues } from './redact.js';
 export { ConfigSchema, LocalOverridesSchema } from './config.js';
 export { HarnessSchema } from './harness.js';
+export { CodexSchema } from './codex.js';
 export { describeIssues, jsonSchemas } from './json-schema.js';
 export { MappingSchema } from './sandbox.js';
 export { ToolchainsSchema } from './toolchains.js';

package/dist/core/schema/profile.js

@@ -12,16 +12,18 @@ export const SecretsSchema = z.strictObject({
         .describe('Warn at launch about files in the workspace that usually hold secrets (.env, *.pem, credentials.json, ...). The agent CAN read them: Windows Sandbox maps the whole folder.'),
 });
 export const AttachSchema = z.strictObject({
-    enabled: z.boolean().describe('Allow sandbox claude --terminal / sandbox attach from this PC.'),
+    enabled: z
+        .boolean()
+        .describe("Allow attaching this PC's terminal to a session (the terminal option when starting an agent, and attach)."),
     reuseSession: z
         .boolean()
-        .describe("sandbox claude -t in a running sandbox reattaches to this folder's session when no terminal on this PC is attached to it (--new always starts another)."),
+        .describe("Starting an agent with a terminal in a running sandbox reattaches to this folder's session when no terminal on this PC is attached to it (starting a new session on purpose always starts another)."),
     auto: z
         .boolean()
         .describe('Starting an agent attaches this terminal automatically, as if you passed -t (only in an interactive terminal).'),
     autoHide: z
         .boolean()
-        .describe('Hide the Windows Sandbox window whenever this terminal attaches; it keeps running (sandbox show brings it back).'),
+        .describe('Hide the Windows Sandbox window whenever this terminal attaches; it keeps running (Sandbox > Status shows it again).'),
     confirmCtrlC: z
         .boolean()
         .describe('In an attached terminal and the sandbox window, a single Ctrl+C is held back (the title says so) and only a second one within 1.5 seconds reaches the agent: a Ctrl+C meant as "copy" no longer stops it. Esc still stops an agent.'),
@@ -39,7 +41,9 @@ export const ClaudeProfileSchema = z.strictObject({
     hostDir: z.string().describe('Your Claude folder, or "auto" (~/.claude or CLAUDE_CONFIG_DIR).'),
     include: z.array(z.string().regex(/^[A-Za-z0-9._-]+$/)).describe('Files and folders copied from it.'),
     globalStateFile: z.string().describe('Your .claude.json, or "auto". Empty string = do not copy.'),
-    copyCredentials: z.boolean().describe('Copy your Claude LOGIN into the sandbox. Prefer sandbox account instead.'),
+    copyCredentials: z
+        .boolean()
+        .describe('Copy your Claude LOGIN into the sandbox. Prefer saving the login in Accounts instead.'),
     overwrite: z.boolean().describe('Refresh these settings from this PC on every launch.'),
     sharePluginsAcrossAccounts: z
         .boolean()

package/dist/core/schema/resume.js

@@ -5,7 +5,7 @@ export const RESUME_SESSIONS = ['ask', 'always', 'afterCrash', 'never'];
 export const ResumeSchema = z.strictObject({
     sessions: z
         .enum(RESUME_SESSIONS)
-        .describe('When a sandbox starts after one that had agent sessions: "ask" lists them and asks whether to reopen them (without a terminal it prints the command sandbox resume), "always" reopens them, "afterCrash" reopens them only when the last sandbox ended unexpectedly, "never" leaves it to sandbox resume. Terminal tabs you opened yourself in the sandbox are never reopened.'),
+        .describe('When a sandbox starts after one that had agent sessions: "ask" lists them and asks whether to reopen them (without a terminal it only says they can be reopened), "always" reopens them, "afterCrash" reopens them only when the last sandbox ended unexpectedly, "never" leaves it to you (Sessions reopens them). Terminal tabs you opened yourself in the sandbox are never reopened.'),
     restartAfterCrash: z
         .boolean()
         .describe('When the sandbox ends because Windows Sandbox crashed or ran out of memory, start it again by itself and reopen its sessions (at most 3 times in 6 hours).'),

package/dist/core/schema/sandbox.js

@@ -18,7 +18,7 @@ export const MappingSchema = z.strictObject({
 export const SandboxSchema = z.strictObject({
     engine: z
         .enum(['windows-sandbox', 'hcs'])
-        .describe('(alpha) What runs the sandbox. "windows-sandbox" = Windows Sandbox (the default: desktop, Windows Terminal, GPU, clipboard, audio, printers). "hcs" = a headless Hyper-V isolated Server Core container for agents (no desktop, GPU or clipboard); it needs Windows features and an image on this PC (sandbox engine check hcs lists what is missing), and starting it is not enabled yet in this alpha. sandbox engine shows what each engine can do. Yours only: a project file (.sandbox-config.json) cannot set it.'),
+        .describe('(alpha) What runs the sandbox. "windows-sandbox" = Windows Sandbox (the default: desktop, Windows Terminal, GPU, clipboard, audio, printers). "hcs" = a headless Hyper-V isolated Server Core container for agents (no desktop, GPU or clipboard); it needs Windows features and an image on this PC (Maintenance > Engine lists what is missing), and starting it is not enabled yet in this alpha. Maintenance > Engine shows what each engine can do. Yours only: a project file (.sandbox-config.json) cannot set it.'),
     memoryMb: z
         .union([z.literal('auto'), z.number().int().min(2048)])
         .describe('Sandbox RAM in MB (>= 2048), or "auto": free RAM minus reserveHostMb, capped at maxMemoryMb. Never more than this PC can keep in RAM for it (its RAM minus the larger of reserveHostMb and 25 %, 4 GB more with vGPU): a bigger value is lowered.'),
@@ -55,7 +55,7 @@ export const SandboxSchema = z.strictObject({
     networking: z.boolean().describe('Internet access. false is the only hard network isolation Windows Sandbox offers.'),
     clipboard: z
         .boolean()
-        .describe("Shared clipboard between this PC and the sandbox. Also lets an agent's copy (in sandbox attach) reach this PC's clipboard."),
+        .describe("Shared clipboard between this PC and the sandbox. Also lets an agent's copy (in an attached terminal) reach this PC's clipboard."),
     audioInput: z.boolean().describe('Microphone access.'),
     videoInput: z.boolean().describe('Camera access.'),
     printerRedirection: z.boolean().describe('Printers from this PC.'),
@@ -108,7 +108,7 @@ export const NetworkSchema = z.strictObject({
 export const AuditSchema = z.strictObject({
     enabled: z
         .boolean()
-        .describe('Keep an audit log on this PC of what your agents did: programs started (with their command lines, secrets hidden), files changed in the projects, git commits, sessions, and what the repo guard caught, each linked to the agent session that did it where that can be known. The sandbox cannot change it. Read it with sandbox audit or on the Activity page.'),
+        .describe('Keep an audit log on this PC of what your agents did: programs started (with their command lines, secrets hidden), files changed in the projects, git commits, sessions, and what the repo guard caught, each linked to the agent session that did it where that can be known. The sandbox cannot change it. Read it on the Activity page.'),
     days: z
         .number()
         .int()

package/dist/core/schema/toolchains.d.ts

@@ -39,6 +39,10 @@ export declare const ToolchainsSchema: z.ZodObject<{
         acceptLicense: z.ZodBoolean;
         components: z.ZodArray<z.ZodString>;
         keepInstallFiles: z.ZodBoolean;
+        visualStudio: z.ZodEnum<{
+            full: "full";
+            autosdk: "autosdk";
+        }>;
         persistEngines: z.ZodBoolean;
         derivedDataCache: z.ZodEnum<{
             persisted: "persisted";

package/dist/core/schema/toolchains.js

@@ -62,6 +62,9 @@ export const ToolchainsSchema = z.strictObject({
         keepInstallFiles: z
             .boolean()
             .describe('Keep an offline copy of the Visual Studio install files in tools\\visualstudio (~10 GB, made once), so later boots install without downloading them again. Skipped while that disk has too little room.'),
+        visualStudio: z
+            .enum(['full', 'autosdk'])
+            .describe('"full": install Visual Studio Community (the engine finds it through the Setup API; ~10 GB, redone every boot). "autosdk" (experimental): skip Visual Studio and build an Unreal AutoSDK tree from the portable MSVC in tools\\unreal\\autosdk (kept between sandboxes); UnrealBuildTool finds MSVC through AutoSDK, but the editor\'s Visual Studio integration is not available. Needs toolchains.msvc (turned on for you).'),
         persistEngines: z
             .boolean()
             .describe('Engines the Epic Games Launcher installs go to tools\\unreal\\engines (kept between sandboxes, 40-60 GB each) and are registered with the launcher again every boot. Off: they go on the sandbox disk and are lost when it closes. Engines installed on this PC can be mapped instead (pcInstalls.unrealEngines).'),

package/dist/core/schema/vpn.js

@@ -4,7 +4,7 @@ export const VPN_PROVIDERS = ['nordvpn', 'openvpn-file', 'wireguard-file'];
 export const VpnSchema = z.strictObject({
     enabled: z
         .boolean()
-        .describe("(Alpha: not yet tried on a real PC) Send the sandbox's traffic through a VPN. Only the sandbox: your PC's own connection is untouched. Needs a saved login first (sandbox vpn login). The agent in the sandbox can read that login and can turn the tunnel off (it is the administrator there)."),
+        .describe("(Alpha: not yet tried on a real PC) Send the sandbox's traffic through a VPN. Only the sandbox: your PC's own connection is untouched. Needs a saved login first (Settings > Network > VPN). The agent in the sandbox can read that login and can turn the tunnel off (it is the administrator there)."),
     provider: z
         .enum(VPN_PROVIDERS)
         .describe('nordvpn: a recommended NordVPN server is picked at every launch. openvpn-file: your own .ovpn file (configFile). wireguard-file: your own WireGuard .conf (configFile), e.g. from your company.'),

package/dist/core/schema/web.js

@@ -20,7 +20,7 @@ export const RemoteUserSchema = z.strictObject({
 export const WebLanSchema = z.strictObject({
     enabled: z
         .boolean()
-        .describe('(Beta) Devices on your network (a phone): an HTTPS address on this PC for devices you pair with a one-time code (sandbox web pair). Needs a firewall rule (sandbox web lan on asks Windows once). Off: every paired device is signed out.'),
+        .describe('(Beta) Devices on your network (a phone): an HTTPS address on this PC for devices you pair with a one-time code (Remote access). Needs a firewall rule (turning it on asks Windows once). Off: every paired device is signed out.'),
     port: z.number().int().min(1024).max(65535).describe('HTTPS port for paired devices on your network.'),
     address: z
         .string()
@@ -32,7 +32,7 @@ export const WebLanSchema = z.strictObject({
 export const WebRemoteSchema = z.strictObject({
     windowsSignIn: z
         .boolean()
-        .describe('(Beta) Other Windows users of this PC named in web.remote.users sign in to your web UI (and sandbox remote) with their own Windows account: no password, no link.'),
+        .describe('(Beta) Other Windows users of this PC named in web.remote.users sign in to your web UI (and the remote menu) with their own Windows account: no password, no link.'),
     users: z
         .array(RemoteUserSchema)
         .max(32)
@@ -48,7 +48,7 @@ export const WebRemoteSchema = z.strictObject({
 export const WebSchema = z.strictObject({
     enabled: z
         .boolean()
-        .describe('(Beta) The web UI: your sandbox sessions in a browser on this PC (http://127.0.0.1:<port>, this PC only). On: every sandbox start also starts it in the background (it keeps running until sandbox web stop or a restart of the PC). Off: only sandbox web start runs it. Open it signed in with sandbox web open.'),
+        .describe('(Beta) The web UI: your sessions in a browser on this PC (http://127.0.0.1:<port>, this PC only). On: every start of a sandbox also starts it in the background (it keeps running until you stop it in Maintenance > Web UI or restart the PC). Off: it runs only when you start it there. Open it signed in from the same page.'),
     port: z
         .number()
         .int()

package/dist/core/types.d.ts

@@ -225,6 +225,12 @@ export interface GuestSession {
      */
     projectsDir?: string;
     roots?: string[];
+    /** The same folders with the PC folder each shows (roots first), for the sandbox guide. */
+    mappedProjects?: {
+        host: string;
+        guest: string;
+        root?: boolean;
+    }[];
     /** false: start no agent session at boot (a restart that adds a project opens its sessions itself). */
     autoSession?: boolean;
     harnessName: string;
@@ -284,6 +290,8 @@ export interface GuestSession {
      * creates.
      */
     agentBackstop?: 'auto' | 'none' | number;
+    /** The codex settings: the flags every Codex start gets and what boot writes to its config.toml. */
+    codex?: Config['codex'];
     /** "gentle" when vGPU is on: the governor and the watchdog act earlier, compilers run below normal. */
     loadProfile?: 'normal' | 'gentle';
     /** sandbox.pressureResponse: the daemon slows builds down when memory runs low. */

package/dist/core/util/errors.d.ts

@@ -1,8 +1,18 @@
+/** A step that fixes a problem: the menu and the web offer `op` as a button, the command line prints `cli`. */
+export interface ErrorAction {
+    readonly op: string;
+    readonly input?: Readonly<Record<string, unknown>>;
+    readonly label: string;
+    readonly cli: string;
+}
 /** An expected problem the user can act on: what went wrong, and (optionally) how to fix it. */
 export declare class UserError extends Error {
     readonly fix?: string | undefined;
-    constructor(message: string, fix?: string | undefined);
+    readonly action?: ErrorAction | undefined;
+    constructor(message: string, fix?: string | undefined, action?: ErrorAction | undefined);
 }
 /** Throws a UserError. Typed explicitly so TypeScript narrows after calls (arrow functions need it to act as never). */
 export declare const fail: (message: string, fix?: string) => never;
+/** Throws a UserError whose fix is also a button (menu, web) and a command line (CLI). */
+export declare const failWith: (message: string, fix: string, action: ErrorAction) => never;
 export declare function errMsg(e: unknown): string;

package/dist/core/util/errors.js

@@ -1,9 +1,11 @@
 /** An expected problem the user can act on: what went wrong, and (optionally) how to fix it. */
 export class UserError extends Error {
     fix;
-    constructor(message, fix) {
+    action;
+    constructor(message, fix, action) {
         super(message);
         this.fix = fix;
+        this.action = action;
         this.name = 'UserError';
     }
 }
@@ -11,6 +13,10 @@ export class UserError extends Error {
 export const fail = (message, fix) => {
     throw new UserError(message, fix);
 };
+/** Throws a UserError whose fix is also a button (menu, web) and a command line (CLI). */
+export const failWith = (message, fix, action) => {
+    throw new UserError(message, fix, action);
+};
 export function errMsg(e) {
     return e instanceof Error ? e.message : String(e);
 }

package/dist/core/util/index.d.ts

@@ -1,5 +1,5 @@
 export { isWin, sleep, captureOutput } from './process.js';
-export { UserError, fail, errMsg } from './errors.js';
+export { UserError, fail, failWith, errMsg, type ErrorAction } from './errors.js';
 export { parseJsonc, readJsonc } from './jsonc.js';
 export { ensureDir, dirExists, fileExists, fileExistsAsync, readJson, readSmallFile, tryReadJson, writeJson, realPath, } from './fs.js';
 export { xmlEscape, safeText, plainText } from './text.js';