windows-development-sandbox 1.5.0 → 1.9.0

package/dist/core/config/defaults.js

@@ -6,12 +6,15 @@ export const DEFAULTS = {
     audit: { enabled: false, days: 14, maxMb: 100, processes: true, files: true },
     mappings: [],
     sandbox: {
+        engine: 'windows-sandbox',
         memoryMb: 'auto',
         maxMemoryMb: 32768,
         maxMemoryPercent: 80,
         cpuLimit: 80,
         pageFileMb: 16384,
         reserveHostMb: 8192,
+        agentMemoryHeadroomMb: 'auto',
+        pressureResponse: true,
         vGpu: false,
         networking: true,
         clipboard: true,
@@ -24,13 +27,16 @@ export const DEFAULTS = {
     },
     sharing: { otherUsers: false },
     storage: {
-        root: '%LOCALAPPDATA%\\AgentSandbox',
+        root: '%ProgramData%\\AgentSandbox\\users\\%USERNAME%',
         persistAgentState: true,
         dataName: 'default',
         markSandboxFiles: true,
+        contained: 'off',
+        containedMaxGb: 64,
         warnDataGb: 50,
     },
     network: { blockPrivateRanges: true, allowOnly: [], blockHosts: [], forwardPorts: [], dns: [], proxy: '' },
+    vpn: { enabled: false, provider: 'nordvpn', protocol: 'udp', country: '', configFile: '', killSwitch: true },
     provisioning: {
         copyFromHost: true,
         fallbackToInstall: true,
@@ -88,6 +94,7 @@ export const DEFAULTS = {
         sqlserver: { enabled: 'auto' },
     },
     attach: { enabled: true, reuseSession: true, auto: false, autoHide: false },
+    web: { enabled: false, port: 47800 },
     agentCommands: { enabled: false, agents: 'auto' },
     secrets: { strip: true, allow: [], patterns: [], warnFiles: true },
     personalization: { enabled: true },
@@ -99,6 +106,7 @@ export const DEFAULTS = {
         globalStateFile: 'auto',
         copyCredentials: false,
         overwrite: true,
+        sharePluginsAcrossAccounts: false,
         syncHistory: true,
         historyScope: 'project',
         syncClaudeMem: true,
@@ -122,6 +130,10 @@ export const DEFAULTS = {
             arguments: [],
             environment: {},
             home: { env: { CODEX_HOME: 'codex' }, loginFiles: ['auth.json'], hostDir: '~/.codex' },
+            localState: { CODEX_SQLITE_HOME: 'sqlite' },
+            // Its own command sandbox keeps local users' passwords sealed with DPAPI: unreadable in the next sandbox
+            // ("CryptUnprotectData" on every command), so it sets that sandbox up again at each boot.
+            bootReset: ['.sandbox-secrets', '.sandbox\\setup_marker.json', '.sandbox\\deny_read_acl_state.json'],
             resumeArguments: ['resume', '--last'],
         },
         gemini: {

package/dist/core/config/loader.js

@@ -23,8 +23,18 @@ export function machineConfigPath(env = process.env) {
  * folders in it must be full paths (after %VARIABLES% expand), never relative to someone's folder.
  */
 function readMachineConfig(file) {
-    if (!fs.existsSync(file))
-        return null;
+    // existsSync says false on "access denied": a user not yet in the group would silently get the defaults.
+    try {
+        fs.accessSync(file, fs.constants.R_OK);
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return null;
+        if (code === 'EACCES' || code === 'EPERM')
+            fail('Cannot read the settings for this PC in ' + file + '.', 'Sign out of Windows and in again after being added to the Agent Sandbox Users group.');
+        throw e;
+    }
     const raw = readJsonc(file);
     const config = validateConfig(mergeConfig(DEFAULTS, raw), file);
     const folders = config.mappings.map((m, i) => ['mappings[' + i + '].host', m.host]);

package/dist/core/local-config/overrides.js

@@ -49,6 +49,7 @@ export const ON_IS_SAFER = [
     'network.blockPrivateRanges',
     'sandbox.protectedClient',
     'downloads.requireChecksum',
+    'vpn.killSwitch',
 ];
 export const OFF_IS_SAFER = [
     'sandbox.networking',

package/dist/core/prompt.d.ts

@@ -1,4 +1,23 @@
+/** One entry of a list question; `description` is shown under the highlighted entry. */
+export interface PromptChoice<T> {
+    readonly name: string;
+    readonly value: T;
+    readonly description?: string;
+}
 /** A yes/no question (default no). */
 export declare function askYesNo(question: string, defaultYes?: boolean): Promise<boolean>;
+/** A yes/no question the command needs answered: no terminal fails (`--yes` answers yes on the command line). */
+export declare function askRequired(question: string, fix?: string, defaultYes?: boolean): Promise<boolean>;
 /** Asks the user to type `expected` (a stronger confirmation than yes/no). */
 export declare function askTyped(question: string, expected: string): Promise<boolean>;
+/** Pick one entry from a list (for an argument that was left out); `fix` says what to type instead. */
+export declare function askChoice<T>(message: string, choices: readonly PromptChoice<T>[], fix: string): Promise<T>;
+/** Tick any number of entries from a list; `fix` says what to type instead. */
+export declare function askChoices<T>(message: string, choices: readonly PromptChoice<T>[], fix: string): Promise<T[]>;
+/** Type a name or a path. `validate` returns true, or the problem to show. */
+export declare function askName(message: string, fix: string, validate?: (value: string) => true | string): Promise<string>;
+/**
+ * Type a secret (a password, an API key) with each character shown as *. Never echoed, never kept; `fix` says what to
+ * do without a terminal.
+ */
+export declare function askSecret(message: string, fix: string): Promise<string>;

package/dist/core/prompt.js

@@ -1,12 +1,24 @@
-// Questions asked on the terminal, all through @inquirer/prompts. Without an interactive terminal the answer is always
-// "no".
-import { confirm, input } from '@inquirer/prompts';
+// Questions asked on the terminal, all through @inquirer/prompts. askYesNo is for optional offers: without an
+// interactive terminal the answer is "no". askRequired, askChoice and askName are for questions a command cannot go on
+// without: with no terminal they fail and say how to answer on the command line.
+import { checkbox, confirm, input, password, select } from '@inquirer/prompts';
+import { fail } from './util/errors.js';
+/** The terminal check every required question starts with. */
+function requireTerminal(fix) {
+    if (!process.stdin.isTTY)
+        fail('Cannot ask here (no terminal).', fix);
+}
 /** A yes/no question (default no). */
 export async function askYesNo(question, defaultYes = false) {
     if (!process.stdin.isTTY)
         return false;
     return confirm({ message: question, default: defaultYes });
 }
+/** A yes/no question the command needs answered: no terminal fails (`--yes` answers yes on the command line). */
+export async function askRequired(question, fix = 'Add --yes to answer yes.', defaultYes = false) {
+    requireTerminal(fix);
+    return confirm({ message: question, default: defaultYes });
+}
 /** Asks the user to type `expected` (a stronger confirmation than yes/no). */
 export async function askTyped(question, expected) {
     if (!process.stdin.isTTY)
@@ -14,3 +26,31 @@ export async function askTyped(question, expected) {
     const answer = await input({ message: question + ' Type "' + expected + '" to confirm:' });
     return answer.trim().toLowerCase() === expected;
 }
+/** Pick one entry from a list (for an argument that was left out); `fix` says what to type instead. */
+export async function askChoice(message, choices, fix) {
+    requireTerminal(fix);
+    return select({ message, choices: [...choices] });
+}
+/** Tick any number of entries from a list; `fix` says what to type instead. */
+export async function askChoices(message, choices, fix) {
+    requireTerminal(fix);
+    return checkbox({ message, choices: [...choices] });
+}
+/** Type a name or a path. `validate` returns true, or the problem to show. */
+export async function askName(message, fix, validate) {
+    requireTerminal(fix);
+    const answer = await input({ message, validate: validate ? (v) => validate(v.trim()) : undefined });
+    return answer.trim();
+}
+/**
+ * Type a secret (a password, an API key) with each character shown as *. Never echoed, never kept; `fix` says what to
+ * do without a terminal.
+ */
+export async function askSecret(message, fix) {
+    requireTerminal(fix);
+    return password({
+        message,
+        mask: '*',
+        validate: (v) => (v.length > 0 ? true : 'Type it, or press Ctrl+C to cancel.'),
+    });
+}

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

@@ -18,3 +18,9 @@ export declare const GitAccessSchema: z.ZodEnum<{
 export declare const EnabledSchema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
 export declare function enabled(what: string, markers: string): typeof EnabledSchema;
 export declare function Packages(what: string, example: string): typeof StringsSchema;
+/**
+ * Marks a setting whose value is a secret (an API key in an agent's environment): config show / get, the menu, doctor
+ * and every --json print *** for it (core/schema/redact.ts), and it is never written to session.json or the launch
+ * folder (it travels in a one-shot file, see shared/channel/secrets.ts).
+ */
+export declare function secret<T extends z.ZodType>(schema: T): T;

package/dist/core/schema/common.js

@@ -25,3 +25,11 @@ export function enabled(what, markers) {
 export function Packages(what, example) {
     return StringsSchema.describe(what + ', installed once and kept (e.g. ' + example + ').');
 }
+/**
+ * Marks a setting whose value is a secret (an API key in an agent's environment): config show / get, the menu, doctor
+ * and every --json print *** for it (core/schema/redact.ts), and it is never written to session.json or the launch
+ * folder (it travels in a one-shot file, see shared/channel/secrets.ts).
+ */
+export function secret(schema) {
+    return schema.meta({ secret: true });
+}

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

@@ -23,12 +23,18 @@ export declare const ConfigSchema: z.ZodObject<{
         optional: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     sandbox: z.ZodObject<{
+        engine: z.ZodEnum<{
+            "windows-sandbox": "windows-sandbox";
+            hcs: "hcs";
+        }>;
         memoryMb: z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodNumber]>;
         maxMemoryMb: z.ZodNumber;
         maxMemoryPercent: z.ZodNumber;
         cpuLimit: z.ZodUnion<readonly [z.ZodLiteral<"none">, z.ZodNumber]>;
         pageFileMb: z.ZodNumber;
         reserveHostMb: z.ZodNumber;
+        agentMemoryHeadroomMb: z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodLiteral<"none">, z.ZodNumber]>;
+        pressureResponse: z.ZodBoolean;
         vGpu: z.ZodBoolean;
         networking: z.ZodBoolean;
         clipboard: z.ZodBoolean;
@@ -47,6 +53,11 @@ export declare const ConfigSchema: z.ZodObject<{
         persistAgentState: z.ZodBoolean;
         dataName: z.ZodString;
         markSandboxFiles: z.ZodBoolean;
+        contained: z.ZodEnum<{
+            off: "off";
+            vhdx: "vhdx";
+        }>;
+        containedMaxGb: z.ZodNumber;
         warnDataGb: z.ZodNumber;
     }, z.core.$strict>;
     network: z.ZodObject<{
@@ -60,6 +71,21 @@ export declare const ConfigSchema: z.ZodObject<{
         dns: z.ZodArray<z.ZodString>;
         proxy: z.ZodString;
     }, z.core.$strict>;
+    vpn: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        provider: z.ZodEnum<{
+            nordvpn: "nordvpn";
+            "openvpn-file": "openvpn-file";
+            "wireguard-file": "wireguard-file";
+        }>;
+        protocol: z.ZodEnum<{
+            udp: "udp";
+            tcp: "tcp";
+        }>;
+        country: z.ZodString;
+        configFile: z.ZodString;
+        killSwitch: z.ZodBoolean;
+    }, z.core.$strict>;
     provisioning: z.ZodObject<{
         copyFromHost: z.ZodBoolean;
         fallbackToInstall: z.ZodBoolean;
@@ -218,6 +244,10 @@ export declare const ConfigSchema: z.ZodObject<{
         auto: z.ZodBoolean;
         autoHide: z.ZodBoolean;
     }, z.core.$strict>;
+    web: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        port: z.ZodNumber;
+    }, z.core.$strict>;
     agentCommands: z.ZodObject<{
         enabled: z.ZodBoolean;
         agents: z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodArray<z.ZodString>]>;
@@ -258,6 +288,7 @@ export declare const ConfigSchema: z.ZodObject<{
         globalStateFile: z.ZodString;
         copyCredentials: z.ZodBoolean;
         overwrite: z.ZodBoolean;
+        sharePluginsAcrossAccounts: z.ZodBoolean;
         syncHistory: z.ZodBoolean;
         historyScope: z.ZodEnum<{
             project: "project";
@@ -281,6 +312,8 @@ export declare const ConfigSchema: z.ZodObject<{
             loginFiles: z.ZodArray<z.ZodString>;
             hostDir: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
+        localState: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        bootReset: z.ZodOptional<z.ZodArray<z.ZodString>>;
         resumeArguments: z.ZodOptional<z.ZodArray<z.ZodString>>;
         resumeOneArguments: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
@@ -345,6 +378,9 @@ export declare const LocalOverridesSchema: z.ZodObject<{
         blockPrivateRanges: z.ZodOptional<z.ZodBoolean>;
         blockHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
+    vpn: z.ZodOptional<z.ZodObject<{
+        killSwitch: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
     provisioning: z.ZodOptional<z.ZodObject<{
         copyFromHost: z.ZodOptional<z.ZodBoolean>;
         fallbackToInstall: z.ZodOptional<z.ZodBoolean>;

package/dist/core/schema/config.js

@@ -11,6 +11,8 @@ import { ToolchainsSchema } from './toolchains.js';
 import { AppsSchema } from './apps.js';
 import { ProjectsSchema } from './projects.js';
 import { ResumeSchema } from './resume.js';
+import { WebSchema } from './web.js';
+import { VpnSchema } from './vpn.js';
 export const ConfigSchema = z
     .strictObject({
     $schema: SchemaRefSchema.optional(),
@@ -23,23 +25,37 @@ export const ConfigSchema = z
     sandbox: SandboxSchema,
     sharing: SharingSchema,
     storage: z.strictObject({
-        root: z.string().min(1).describe('Where everything is kept on this PC (tools, databases, logins, launches).'),
+        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.'),
         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
             .boolean()
             .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.'),
+        containedMaxGb: z
+            .number()
+            .int()
+            .min(8)
+            .max(4096)
+            .describe('(beta) Largest size, in GB, the disk image of storage.contained may grow to.'),
         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.'),
     }),
     network: NetworkSchema,
+    vpn: VpnSchema,
     provisioning: ProvisioningSchema,
     downloads: DownloadsSchema,
     toolchains: ToolchainsSchema,
     databases: DatabasesSchema.describe('Databases running inside the sandbox. Data persists in C:\\AgentData\\databases; each one starts at boot.'),
     attach: AttachSchema,
+    web: WebSchema,
     agentCommands: AgentCommandsSchema,
     secrets: SecretsSchema,
     personalization: toggle('Copy your desktop look (theme, accent, taskbar, wallpaper, ...) into the sandbox.'),
@@ -71,9 +87,17 @@ export const LocalOverridesSchema = z
         .describe('Extra folders (relative paths are relative to this file), e.g. a read-only data folder at another place in the sandbox. Folders outside the project are used only as your projects.allowOutsideMappings setting allows (by default you are asked once).'),
     scripts: StringsSchema.describe('Scripts (.ps1 / .mjs / .cmd, relative to this file) run inside the sandbox before the agent.'),
     // This PC's resources are yours to share: CPU and paging file (this PC's disk) are not a project's to set.
-    sandbox: SandboxSchema.omit({ cpuLimit: true, pageFileMb: true }).partial(),
+    sandbox: SandboxSchema.omit({
+        cpuLimit: true,
+        pageFileMb: true,
+        engine: true,
+        agentMemoryHeadroomMb: true,
+        pressureResponse: true,
+    }).partial(),
     // A project may block more (the LAN, hosts); it never opens hosts, ports, DNS or a proxy.
     network: NetworkSchema.pick({ blockPrivateRanges: true, blockHosts: true }).partial(),
+    // A project may turn the kill switch on, never off, and never choose a VPN, a server, a file or a login.
+    vpn: VpnSchema.pick({ killSwitch: true }).partial(),
     provisioning: ProvisioningSchema.pick({ copyFromHost: true, fallbackToInstall: true, refresh: true })
         .extend({ git: GitSchema.partial(), terminal: toggle('Windows Terminal as the sandbox window.').partial() })
         .partial(),

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

@@ -21,6 +21,8 @@ export declare const HarnessSchema: z.ZodObject<{
         loginFiles: z.ZodArray<z.ZodString>;
         hostDir: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
+    localState: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    bootReset: z.ZodOptional<z.ZodArray<z.ZodString>>;
     resumeArguments: z.ZodOptional<z.ZodArray<z.ZodString>>;
     resumeOneArguments: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;

package/dist/core/schema/harness.js

@@ -1,6 +1,6 @@
 // An agent (claude, codex, ...) the sandbox can run.
 import { z } from 'zod';
-import { StringsSchema } from './common.js';
+import { secret, StringsSchema } from './common.js';
 /** A folder below the agent's state folder: plain names only, no drive, no "..". */
 const SubfolderSchema = z
     .string()
@@ -41,8 +41,19 @@ export const HarnessSchema = z
         .describe('Python package installed with `uv tool install` inside the sandbox (e.g. aider-chat).'),
     uvBin: z.string().optional().describe('Command the uv package provides.'),
     arguments: StringsSchema.describe('Arguments always passed to the agent.'),
-    environment: z.record(z.string(), z.string()).describe('Environment variables for the agent.'),
+    environment: z
+        .record(z.string(), secret(z.string()))
+        .describe('Environment variables for the agent (API keys go here). Their values are shown as *** and are handed to the sandbox in a one-shot file, never kept in the launch folder. The agent can read its own environment.'),
     home: HarnessHomeSchema.optional().describe('Where its login lives inside the sandbox; leave out when the agent cannot be pointed at a folder (then its login is not kept between sandboxes).'),
+    localState: z
+        .record(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/), SubfolderSchema)
+        .optional()
+        .describe("Environment variable -> folder below the agent's own state folder (state\\<agent>) for SQLite databases. SQLite cannot run in a mapped folder, so the agent runs from a copy on the sandbox's disk (the variable points to it) that is copied from and back to that folder."),
+    bootReset: z
+        .array(SubfolderSchema)
+        .max(32)
+        .optional()
+        .describe("Files and folders below the agent's own state folder (state\\<agent>) that only work on the machine that wrote them (keys sealed with Windows DPAPI, local accounts it created). Every sandbox is a new machine, so they are deleted at each boot and the agent sets them up again."),
     resumeArguments: StringsSchema.optional().describe('Arguments used when the agent is restarted in place (e.g. after an account switch) so it resumes the conversation.'),
     resumeOneArguments: StringsSchema.optional().describe('Arguments that reopen one conversation, with {id} where its id goes (claude: --resume {id}). Used instead of resumeArguments when the conversation of a session is known.'),
 })

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

@@ -1,6 +1,8 @@
-export { GitAccessSchema } from './common.js';
+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 { describeIssues, jsonSchemas } from './json-schema.js';
 export { MappingSchema } from './sandbox.js';
 export { ToolchainsSchema } from './toolchains.js';
+export { VpnSchema, VPN_PROVIDERS, type VpnProvider } from './vpn.js';

package/dist/core/schema/index.js

@@ -1,8 +1,10 @@
 // Every setting, defined once with zod, split by area in schema/. This file is the one place the rest of the code (and
 // scripts/schemas.mjs, which generates the JSON Schema files) imports them from.
-export { GitAccessSchema } from './common.js';
+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 { describeIssues, jsonSchemas } from './json-schema.js';
 export { MappingSchema } from './sandbox.js';
 export { ToolchainsSchema } from './toolchains.js';
+export { VpnSchema, VPN_PROVIDERS } from './vpn.js';

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

@@ -22,6 +22,7 @@ export declare const ClaudeProfileSchema: z.ZodObject<{
     globalStateFile: z.ZodString;
     copyCredentials: z.ZodBoolean;
     overwrite: z.ZodBoolean;
+    sharePluginsAcrossAccounts: z.ZodBoolean;
     syncHistory: z.ZodBoolean;
     historyScope: z.ZodEnum<{
         project: "project";

package/dist/core/schema/profile.js

@@ -38,6 +38,9 @@ export const ClaudeProfileSchema = z.strictObject({
     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.'),
     overwrite: z.boolean().describe('Refresh these settings from this PC on every launch.'),
+    sharePluginsAcrossAccounts: z
+        .boolean()
+        .describe('When you switch Claude accounts, copy your Claude plugins (and which ones are enabled) into a data set that has none yet. Off by default: plugins are code that runs in your sessions.'),
     syncHistory: z.boolean().describe('Bring conversation history in, and sync new history back (path-translated).'),
     historyScope: z
         .enum(['project', 'all'])

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

@@ -0,0 +1,13 @@
+/** What is printed instead of a secret. */
+export declare const REDACTED = "***";
+/** A path through a config; "*" stands for any key of a map or any item of a list. */
+type SecretPath = readonly string[];
+/** Every setting marked secret, found from the schema itself (so a new secret setting needs no list). */
+export declare function secretPaths(): readonly SecretPath[];
+/** A copy of `config` with every secret value replaced by ***. */
+export declare function redactSecrets<T>(config: T): T;
+/** The secret values in `config` (for scrubbing text that was built from it). */
+export declare function secretValues(config: unknown): string[];
+/** `text` with every secret value of `config` replaced by *** (a last safety net for output built from a config). */
+export declare function scrubSecrets(text: string, config: unknown): string;
+export {};

package/dist/core/schema/redact.js

@@ -0,0 +1,75 @@
+// Secrets in settings: which values are marked `secret` in the schemas, and printing a config without them.
+import { z } from 'zod';
+import { ConfigSchema } from './config.js';
+/** What is printed instead of a secret. */
+export const REDACTED = '***';
+let cached = null;
+const walk = (node, at, out) => {
+    if (typeof node !== 'object' || node === null)
+        return;
+    const n = node;
+    if (n.secret === true)
+        out.push(at);
+    for (const [k, v] of Object.entries(n.properties ?? {}))
+        walk(v, [...at, k], out);
+    if (typeof n.additionalProperties === 'object')
+        walk(n.additionalProperties, [...at, '*'], out);
+    if (n.items)
+        walk(n.items, [...at, '*'], out);
+    for (const key of ['anyOf', 'oneOf', 'allOf'])
+        if (Array.isArray(n[key]))
+            for (const v of n[key])
+                walk(v, at, out);
+};
+/** Every setting marked secret, found from the schema itself (so a new secret setting needs no list). */
+export function secretPaths() {
+    if (!cached) {
+        const out = [];
+        walk(z.toJSONSchema(ConfigSchema, { io: 'input', unrepresentable: 'any' }), [], out);
+        cached = out;
+    }
+    return cached;
+}
+const blank = (value, path) => {
+    if (path.length === 0)
+        return typeof value === 'string' && value !== '' ? REDACTED : value;
+    if (typeof value !== 'object' || value === null)
+        return value;
+    const [head, ...rest] = path;
+    if (Array.isArray(value))
+        return value.map((v) => (head === '*' ? blank(v, rest) : v));
+    const o = value;
+    return Object.fromEntries(Object.entries(o).map(([k, v]) => [k, head === '*' || head === k ? blank(v, rest) : v]));
+};
+/** A copy of `config` with every secret value replaced by ***. */
+export function redactSecrets(config) {
+    return secretPaths().reduce((value, path) => blank(value, path), config);
+}
+const collect = (value, path, out) => {
+    if (path.length === 0) {
+        if (typeof value === 'string' && value !== '')
+            out.push(value);
+        return;
+    }
+    if (typeof value !== 'object' || value === null)
+        return;
+    const [head, ...rest] = path;
+    const o = value;
+    for (const [k, v] of Object.entries(o))
+        if (head === '*' || head === k)
+            collect(v, rest, out);
+};
+/** The secret values in `config` (for scrubbing text that was built from it). */
+export function secretValues(config) {
+    const out = [];
+    for (const path of secretPaths())
+        collect(config, path, out);
+    return [...new Set(out)];
+}
+/** `text` with every secret value of `config` replaced by *** (a last safety net for output built from a config). */
+export function scrubSecrets(text, config) {
+    return secretValues(config)
+        .filter((v) => v.length >= 4)
+        .sort((a, b) => b.length - a.length)
+        .reduce((t, v) => t.split(v).join(REDACTED).split(JSON.stringify(v).slice(1, -1)).join(REDACTED), text);
+}

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

@@ -7,12 +7,18 @@ export declare const MappingSchema: z.ZodObject<{
     optional: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export declare const SandboxSchema: z.ZodObject<{
+    engine: z.ZodEnum<{
+        "windows-sandbox": "windows-sandbox";
+        hcs: "hcs";
+    }>;
     memoryMb: z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodNumber]>;
     maxMemoryMb: z.ZodNumber;
     maxMemoryPercent: z.ZodNumber;
     cpuLimit: z.ZodUnion<readonly [z.ZodLiteral<"none">, z.ZodNumber]>;
     pageFileMb: z.ZodNumber;
     reserveHostMb: z.ZodNumber;
+    agentMemoryHeadroomMb: z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodLiteral<"none">, z.ZodNumber]>;
+    pressureResponse: z.ZodBoolean;
     vGpu: z.ZodBoolean;
     networking: z.ZodBoolean;
     clipboard: z.ZodBoolean;

package/dist/core/schema/sandbox.js

@@ -16,6 +16,9 @@ export const MappingSchema = z.strictObject({
     optional: z.boolean().optional().describe('true = skip it quietly when the host folder does not exist.'),
 });
 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.'),
     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.'),
@@ -35,10 +38,24 @@ export const SandboxSchema = z.strictObject({
         .min(0)
         .max(262144)
         .describe('Size of the sandbox\'s paging file in MB, created at full size when it starts so it never grows while builds run (8 GB of its disk always stays free). Windows Sandbox starts with about 1 GB: parallel builds then fail with "The paging file is too small", and Windows grows the file under load. 0 = leave Windows\' own.'),
-    reserveHostMb: z.number().int().nonnegative().describe('RAM always left for this PC when memoryMb is "auto".'),
-    vGpu: z.boolean().describe('Virtual GPU. Off by default: Microsoft notes it widens the sandbox attack surface.'),
+    reserveHostMb: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe('Memory always left for this PC when memoryMb is "auto": the sandbox gets at most (free RAM, and RAM plus paging file still unused) minus this.'),
+    agentMemoryHeadroomMb: z
+        .union([z.literal('auto'), z.literal('none'), z.number().int().min(0)])
+        .describe('Memory kept out of the agents reach inside the sandbox, in MB: everything the agents start (their builds, tests, tools) together may use at most the sandbox memory minus this; a runaway parallel build then gets out-of-memory errors in its own session instead of freezing or crashing the whole sandbox. "auto" = the larger of 2048 MB and 10 % of the sandbox memory; "none" = no limit. Yours only: a project file cannot change it.'),
+    pressureResponse: z
+        .boolean()
+        .describe('When the sandbox (or this PC) runs low on memory, slow the heaviest build programs down (lower priority) and, if that is not enough, pause the biggest compiler for a few seconds at a time, so heavy parallel builds slow down instead of closing the sandbox. Never touches the agents themselves. Yours only: a project file cannot change it.'),
+    vGpu: z
+        .boolean()
+        .describe("Virtual GPU. Off by default: Microsoft notes it widens the sandbox attack surface. The sandbox then uses this PC's graphics card, and with some graphics drivers heavy use can freeze the whole PC: turn it on only when a program in the sandbox needs the GPU (the mesa toolchain gives software OpenGL without it)."),
     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.'),
+    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."),
     audioInput: z.boolean().describe('Microphone access.'),
     videoInput: z.boolean().describe('Camera access.'),
     printerRedirection: z.boolean().describe('Printers from this PC.'),
@@ -85,6 +102,7 @@ export const NetworkSchema = z.strictObject({
     proxy: z
         .string()
         .regex(/^(https?:\/\/[^\s]+)?$/, 'http://host:port')
+        .refine((v) => !/^https?:\/\/[^/?#]*@/i.test(v), 'no user name or password in the address (it would be stored in plain text and visible to the agent): use a proxy that needs no login')
         .describe('An HTTP proxy the sandbox uses to reach the internet (HTTP_PROXY / HTTPS_PROXY for everything in it), e.g. http://proxy.corp:8080. Empty = none.'),
 });
 export const AuditSchema = z.strictObject({

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

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+export declare const VPN_PROVIDERS: readonly ["nordvpn", "openvpn-file", "wireguard-file"];
+export declare const VpnSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    provider: z.ZodEnum<{
+        nordvpn: "nordvpn";
+        "openvpn-file": "openvpn-file";
+        "wireguard-file": "wireguard-file";
+    }>;
+    protocol: z.ZodEnum<{
+        udp: "udp";
+        tcp: "tcp";
+    }>;
+    country: z.ZodString;
+    configFile: z.ZodString;
+    killSwitch: z.ZodBoolean;
+}, z.core.$strict>;
+export type VpnProvider = (typeof VPN_PROVIDERS)[number];

package/dist/core/schema/vpn.js

@@ -0,0 +1,22 @@
+// The VPN setting (inside the sandbox only; the login is not a setting: it is kept encrypted by `sandbox vpn login`).
+import { z } from 'zod';
+export const VPN_PROVIDERS = ['nordvpn', 'openvpn-file', 'wireguard-file'];
+export const VpnSchema = z.strictObject({
+    enabled: z
+        .boolean()
+        .describe("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)."),
+    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.'),
+    protocol: z.enum(['udp', 'tcp']).describe('udp is faster; tcp gets through networks that block udp.'),
+    country: z
+        .string()
+        .regex(/^([A-Za-z][A-Za-z .'-]{0,39})?$/, 'a country name or code like uk or Germany')
+        .describe('nordvpn: the country of the server, e.g. uk, us or Germany. Empty = the best server anywhere.'),
+    configFile: z
+        .string()
+        .describe("openvpn-file / wireguard-file: the .ovpn or .conf file on this PC (an .ovpn has its certificates inside it). Files that run programs (script-security, up, down, plugin, PostUp ...) are refused. A WireGuard file holds your private key: it is read when a sandbox starts and handed over in a one-shot file. A project's file can never set this."),
+    killSwitch: z
+        .boolean()
+        .describe('Block all traffic that does not go through the tunnel: when the tunnel cannot start, the sandbox stays offline instead of using your normal connection. A project can only turn this on, never off.'),
+});