@newly/cli 0.1.2 → 0.1.91

package/dist/commands/sandbox.js

@@ -0,0 +1,787 @@
+import { Help, InvalidArgumentError } from 'commander';
+import { execFileSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { ApiClient, ApiError, friendlyApiError } from '../api.js';
+import { requireCredentials } from '../config.js';
+import { runSandboxCommand, shellCommand } from '../sandboxExec.js';
+import { runSandboxShell } from '../shellSession.js';
+import { printJson, StatusLine, style } from '../terminal.js';
+import { noteDeprecated, registerAccessCommands } from './boxAccess.js';
+import { renderSandbox, renderSandboxList, } from './sandboxOutput.js';
+const MAX_SANDBOX_DISK_GIB = 2048;
+const DEFAULT_SANDBOX_TIMEOUT_SECONDS = 300;
+const DEFAULT_BOX_CPU_CORES = 2;
+const DEFAULT_BOX_MEMORY_MIB = 24 * 1024;
+const SANDBOX_POLL_INTERVAL_MS = 1_000;
+const SANDBOX_WAIT_TIMEOUT_MS = 20 * 60 * 1_000;
+const READY_STATES = new Set(['running']);
+const FAILED_STATES = new Set(['interrupted', 'stopped', 'destroyed']);
+const METRIC_RANGES = new Set(['1h', '6h', '24h', '7d', '30d', 'all']);
+const BYTE_UNITS = ['B', 'KiB', 'MiB', 'GiB', 'TiB'];
+function runCloudApi() {
+    const credentials = requireCredentials();
+    return new ApiClient(credentials.apiUrl, credentials.token);
+}
+function print(value, opts) {
+    if (opts.json) {
+        printJson(value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            console.log(formatRecord(item));
+        return;
+    }
+    console.log(formatRecord(value));
+}
+function sandboxStatusMessage(state) {
+    if (state === 'building_image')
+        return 'Building image';
+    if (state === 'pending')
+        return 'Waiting for capacity';
+    if (state === 'starting')
+        return 'Starting sandbox';
+    if (state === 'archived')
+        return 'Restoring sandbox';
+    return `Sandbox is ${state.replaceAll('_', ' ')}`;
+}
+export async function pollSandboxReady(api, id, opts = {}) {
+    const intervalMs = opts.intervalMs ?? SANDBOX_POLL_INTERVAL_MS;
+    const timeoutMs = opts.timeoutMs ?? SANDBOX_WAIT_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const record = (await api.get(`/run-cloud/sandboxes/${encodeURIComponent(id)}`));
+        const state = record.state ?? 'unknown';
+        opts.onState?.(state);
+        if (READY_STATES.has(state))
+            return record;
+        if (FAILED_STATES.has(state)) {
+            throw new Error(`sandbox ${id} entered ${state.replaceAll('_', ' ')} state`);
+        }
+        if (Date.now() > deadline) {
+            throw new Error(`Timed out after ${Math.round(timeoutMs / 1000)}s waiting for sandbox ${id} to start`);
+        }
+        await new Promise((done) => setTimeout(done, intervalMs));
+    }
+}
+export async function prepareSandboxShell(api, id, status = new StatusLine()) {
+    let record = (await api.get(`/run-cloud/sandboxes/${encodeURIComponent(id)}`));
+    if (record.state === 'paused' || record.state === 'archived') {
+        status.update(`Resuming ${id}`);
+        record = (await api.post(`/run-cloud/sandboxes/${encodeURIComponent(id)}/resume`));
+        if (record.state !== 'running') {
+            record = await pollSandboxReady(api, id, {
+                onState: (state) => status.update(sandboxStatusMessage(state)),
+            });
+        }
+        status.succeed(`Resumed ${id}`);
+    }
+    if (record.state !== 'running') {
+        status.clear();
+        throw new Error(`sandbox ${id} is ${String(record.state).replaceAll('_', ' ')}; wait until it is running`);
+    }
+}
+function formatRecord(value) {
+    if (!value || typeof value !== 'object')
+        return String(value);
+    return Object.entries(value)
+        .filter(([, v]) => v !== undefined && v !== null)
+        .map(([k, v]) => `${k}: ${typeof v === 'object' ? JSON.stringify(v) : String(v)}`)
+        .join('\n');
+}
+async function run(fn) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        console.error(friendlyApiError(err));
+        process.exitCode = 1;
+    }
+}
+function withOutput(cmd) {
+    return cmd.option('--json', 'output JSON', false);
+}
+function parseCpuCores(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new InvalidArgumentError('--cpu must be a positive number of cores, e.g. 0.5');
+    }
+    return n;
+}
+function parseMemoryMb(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new InvalidArgumentError('--memory must be a positive integer of MiB, e.g. 1024');
+    }
+    return n;
+}
+function parseDiskGb(value) {
+    const n = Number(value);
+    if (!Number.isSafeInteger(n) || n <= 0 || n > MAX_SANDBOX_DISK_GIB) {
+        throw new InvalidArgumentError(`--disk must be an integer from 1 to ${MAX_SANDBOX_DISK_GIB} GiB`);
+    }
+    return n;
+}
+function parseIdlePauseSeconds(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 0) {
+        throw new InvalidArgumentError('--idle-pause must be a non-negative integer of seconds');
+    }
+    return n;
+}
+function parseTimeoutSeconds(value) {
+    const timeout = Number(value);
+    if (!Number.isSafeInteger(timeout) || timeout < 0 || timeout > 86_400) {
+        throw new InvalidArgumentError('timeout must be an integer from 0 to 86400 seconds');
+    }
+    return timeout;
+}
+function parseExecTimeoutSeconds(value) {
+    const timeout = parseTimeoutSeconds(value);
+    if (timeout === 0) {
+        throw new InvalidArgumentError('command timeout must be between 1 and 86400 seconds');
+    }
+    return timeout;
+}
+function parsePort(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1 || n > 65535) {
+        throw new InvalidArgumentError('--port must be an integer from 1 to 65535');
+    }
+    return n;
+}
+function parseMetricRange(value) {
+    if (!METRIC_RANGES.has(value)) {
+        throw new InvalidArgumentError('range must be one of 1h, 6h, 24h, 7d, 30d, all');
+    }
+    return value;
+}
+function parseMetricInterval(value) {
+    const seconds = Number(value);
+    if (!Number.isFinite(seconds) || seconds < 1) {
+        throw new InvalidArgumentError('--interval must be at least 1 second');
+    }
+    return seconds;
+}
+function formatMetricBytes(value) {
+    if (!Number.isFinite(value) || value <= 0)
+        return '0 B';
+    const unit = Math.max(0, Math.min(Math.floor(Math.log(value) / Math.log(1024)), BYTE_UNITS.length - 1));
+    const amount = value / 1024 ** unit;
+    return `${amount.toFixed(amount >= 10 || unit === 0 ? 0 : 1)} ${BYTE_UNITS[unit]}`;
+}
+function formatMetricCpu(millicores) {
+    if (!Number.isFinite(millicores) || millicores <= 0)
+        return '0m';
+    return millicores >= 1000
+        ? `${(millicores / 1000).toFixed(2).replace(/\.?0+$/, '')} cores`
+        : `${Math.round(millicores)}m`;
+}
+function metricPercent(used, total) {
+    return total > 0 ? `${((used / total) * 100).toFixed(1)}%` : '—';
+}
+function metricSparkline(values) {
+    if (values.length === 0)
+        return '—';
+    const blocks = '▁▂▃▄▅▆▇█';
+    const max = Math.max(...values, 1);
+    const stride = Math.max(1, Math.ceil(values.length / 48));
+    return values
+        .filter((_, index) => index % stride === 0 || index === values.length - 1)
+        .map((value) => blocks[Math.min(blocks.length - 1, Math.floor((Math.max(0, value) / max) * (blocks.length - 1)))])
+        .join('');
+}
+export function renderSandboxMetrics(id, metrics) {
+    const point = metrics.current;
+    if (!point)
+        return `Sandbox metrics · ${id}\nNo samples recorded yet.`;
+    const history = metrics.history;
+    return [
+        `Sandbox metrics · ${id} · ${metrics.range}`,
+        `State     ${point.state} · ${new Date(point.timestamp).toLocaleString()}`,
+        `CPU       ${formatMetricCpu(point.cpu_millicores)}`,
+        `Memory    ${formatMetricBytes(point.memory_bytes)}`,
+        `Network   ↓ ${formatMetricBytes(point.network_rx_bytes_per_second)}/s · ↑ ${formatMetricBytes(point.network_tx_bytes_per_second)}/s`,
+        `           totals ↓ ${formatMetricBytes(point.network_rx_bytes)} · ↑ ${formatMetricBytes(point.network_tx_bytes)}`,
+        `Disk      ${formatMetricBytes(point.disk_used_bytes)} / ${formatMetricBytes(point.disk_total_bytes)} (${metricPercent(point.disk_used_bytes, point.disk_total_bytes)})`,
+        `History   ${history.length} samples`,
+        `CPU       ${metricSparkline(history.map((sample) => sample.cpu_millicores))}`,
+        `Memory    ${metricSparkline(history.map((sample) => sample.memory_bytes))}`,
+        `Network ↓ ${metricSparkline(history.map((sample) => sample.network_rx_bytes_per_second))}`,
+        `Network ↑ ${metricSparkline(history.map((sample) => sample.network_tx_bytes_per_second))}`,
+        `Disk      ${metricSparkline(history.map((sample) => sample.disk_used_bytes))}`,
+    ].join('\n');
+}
+function parseCoordinate(value) {
+    const n = Number(value);
+    if (!Number.isSafeInteger(n) || n < 0) {
+        throw new InvalidArgumentError('coordinates must be non-negative integers');
+    }
+    return n;
+}
+export function openBrowserUrl(url, platform = process.platform) {
+    if (platform === 'darwin') {
+        execFileSync('open', [url], { stdio: 'ignore' });
+        return;
+    }
+    if (platform === 'win32') {
+        execFileSync('cmd', ['/c', 'start', '', url], { stdio: 'ignore' });
+        return;
+    }
+    execFileSync('xdg-open', [url], { stdio: 'ignore' });
+}
+async function findBoxForSandbox(api, sandboxId) {
+    const data = await api.get('/run-cloud/boxes');
+    return (data?.items ?? []).find((box) => box.sandboxId === sandboxId);
+}
+function attachHostname(api, sandboxId, name, port) {
+    return api.post('/run-cloud/boxes', { sandboxId, name, port });
+}
+function secretSelector(opts) {
+    const ordered = [...(opts.secretGroup ?? []), ...(opts.secret ?? [])];
+    const env = {};
+    for (const pair of opts.env ?? []) {
+        const eq = pair.indexOf('=');
+        if (eq <= 0)
+            throw new Error(`--env expects NAME=VALUE, got "${pair}"`);
+        env[pair.slice(0, eq)] = pair.slice(eq + 1);
+    }
+    if (opts.noSecrets) {
+        if (ordered.length > 0) {
+            throw new Error('--no-secrets cannot be combined with --secret-group or --secret');
+        }
+        return Object.keys(env).length > 0 ? { secrets: 'none', env } : { secrets: 'none' };
+    }
+    const out = {};
+    if (ordered.length > 0)
+        out.secrets = ordered;
+    if (Object.keys(env).length > 0)
+        out.env = env;
+    return out;
+}
+function collectRepeatable(value, previous) {
+    return [...previous, value];
+}
+export function registerSandbox(program) {
+    const sandbox = program.command('sandbox').description('Spawn and control microVM sandboxes');
+    const defaultHelp = new Help();
+    sandbox.configureHelp({
+        subcommandTerm: (command) => {
+            const term = defaultHelp.subcommandTerm(command);
+            const aliases = command.aliases();
+            if (aliases.length < 2)
+                return term;
+            return term.replace(`${command.name()}|${aliases[0]}`, `${command.name()}|${aliases.join('|')}`);
+        },
+    });
+    withOutput(sandbox
+        .command('create')
+        .description('Spawn a microVM sandbox')
+        .option('--image <ref>', 'base image (default runcloud/agent-base, or runcloud/box with --expose)')
+        .option('--region <region>', 'placement region')
+        .option('--name <name>', 'human-readable name; with --expose, the hostname prefix <name>-box.run.cloud')
+        .option('--org <id>', 'billing and ownership organization')
+        .option('--cpu <cores>', 'fractional vCPU allocation, e.g. 0.5', parseCpuCores)
+        .option('--memory <mb>', 'memory allocation in MiB', parseMemoryMb)
+        .option('--disk <gb>', 'root disk capacity in GiB', parseDiskGb)
+        .option('--idle-pause <seconds>', 'pause after inactivity; 0 keeps it running', parseIdlePauseSeconds)
+        .option('--timeout <seconds>', 'maximum sandbox lifetime; defaults to 300, or 0 for persistent sandboxes', parseTimeoutSeconds)
+        .option('--persistent', 'never pause when idle (same as --idle-pause 0)', false)
+        .option('--expose <port>', 'publish a guest port at <name>-box.run.cloud; implies --persistent', parsePort)
+        .option('--secret-group <group>', 'attach a secret group; repeatable and ORDER MATTERS (a later group wins on a name collision)', collectRepeatable, [])
+        .option('--secret <group/name>', 'attach one secret out of a group; repeatable, same ordering', collectRepeatable, [])
+        .option('--env <NAME=VALUE>', 'literal value for this sandbox; applied last, so it wins; repeatable', collectRepeatable, [])
+        .option('--no-secrets', 'state explicitly that the sandbox holds no secrets')
+        .option('--no-wait', 'return before the sandbox finishes building and starting')).action((opts) => run(async () => {
+        const exposed = opts.expose !== undefined;
+        if (exposed && !opts.name) {
+            throw new Error('--expose needs --name <name>, the hostname prefix for <name>-box.run.cloud');
+        }
+        if ((exposed || opts.persistent) && opts.idlePause !== undefined && opts.idlePause !== 0) {
+            throw new Error('--persistent and --expose keep the sandbox running; drop the non-zero --idle-pause');
+        }
+        const body = {
+            image: opts.image ?? (exposed ? 'runcloud/box' : 'runcloud/agent-base'),
+        };
+        if (opts.name)
+            body.name = opts.name;
+        if (opts.region)
+            body.region = opts.region;
+        if (opts.org)
+            body.orgId = opts.org;
+        const cpu = opts.cpu ?? (exposed ? DEFAULT_BOX_CPU_CORES : undefined);
+        const memory = opts.memory ?? (exposed ? DEFAULT_BOX_MEMORY_MIB : undefined);
+        if (cpu !== undefined)
+            body.cpu = cpu;
+        if (memory !== undefined)
+            body.memory = memory;
+        if (opts.disk !== undefined)
+            body.disk = opts.disk;
+        const persistent = exposed || opts.persistent || opts.idlePause === 0;
+        body.timeoutSeconds = opts.timeout ?? (persistent ? 0 : DEFAULT_SANDBOX_TIMEOUT_SECONDS);
+        if (exposed || opts.persistent)
+            body.idlePauseSeconds = 0;
+        else if (opts.idlePause !== undefined)
+            body.idlePauseSeconds = opts.idlePause;
+        Object.assign(body, secretSelector({ ...opts, noSecrets: opts.secrets === false }));
+        const api = runCloudApi();
+        let created = (await api.post('/run-cloud/sandboxes', body));
+        if (typeof created.id !== 'string') {
+            throw new Error('sandbox create response did not include an id');
+        }
+        if (!opts.json && opts.wait && created.state && !READY_STATES.has(created.state)) {
+            const status = new StatusLine();
+            status.update(sandboxStatusMessage(created.state));
+            try {
+                created = await pollSandboxReady(api, created.id, {
+                    onState: (state) => status.update(sandboxStatusMessage(state)),
+                });
+                status.clear();
+            }
+            catch (err) {
+                status.fail('Sandbox failed to start');
+                throw err;
+            }
+        }
+        if (!exposed) {
+            if (opts.json)
+                printJson(created);
+            else
+                console.log(renderSandbox(created, 'created'));
+            return;
+        }
+        const box = await attachHostname(api, created.id, opts.name, opts.expose);
+        const exposedRecord = { ...created, box };
+        if (opts.json)
+            printJson(exposedRecord);
+        else
+            console.log(renderSandbox(exposedRecord, 'created'));
+    }));
+    withOutput(sandbox.command('list').description('List sandboxes').option('--state <state>', 'filter by state')).action((opts) => run(async () => {
+        const qs = opts.state ? `?state=${encodeURIComponent(opts.state)}` : '';
+        const api = runCloudApi();
+        const [data, boxes] = await Promise.all([
+            api.get(`/run-cloud/sandboxes${qs}`),
+            api.get('/run-cloud/boxes').catch(() => ({ items: [] })),
+        ]);
+        const bySandbox = new Map((boxes?.items ?? []).map((box) => [box.sandboxId, box]));
+        const items = (data?.items ?? []).map((item) => {
+            const box = bySandbox.get(item.id);
+            return box ? { ...item, hostname: box.hostname, exposedPort: box.port } : item;
+        });
+        if (opts.json)
+            printJson(items);
+        else
+            console.log(renderSandboxList(items));
+    }));
+    withOutput(sandbox
+        .command('get')
+        .description('Inspect a sandbox, including its public hostname when exposed')
+        .argument('<id>', 'sandbox id')).action((id, opts) => run(async () => {
+        const api = runCloudApi();
+        const [record, box] = await Promise.all([
+            api.get(`/run-cloud/sandboxes/${encodeURIComponent(id)}`),
+            findBoxForSandbox(api, id),
+        ]);
+        const sandboxRecord = (box ? { ...record, box } : record);
+        if (opts.json)
+            printJson(sandboxRecord);
+        else
+            console.log(renderSandbox(sandboxRecord));
+    }));
+    withOutput(sandbox
+        .command('metrics')
+        .description('Show current and historical CPU, memory, network, and disk usage')
+        .argument('<id>', 'sandbox id')
+        .option('--range <range>', 'history range: 1h, 6h, 24h, 7d, 30d, all', parseMetricRange, '24h')
+        .option('--watch', 'refresh continuously', false)
+        .option('--interval <seconds>', 'watch refresh interval', parseMetricInterval, 5)).action((id, opts) => run(async () => {
+        const api = runCloudApi();
+        for (;;) {
+            const metrics = (await api.get(`/run-cloud/sandboxes/${encodeURIComponent(id)}/metrics?range=${encodeURIComponent(opts.range)}`));
+            if (opts.json) {
+                console.log(opts.watch ? JSON.stringify(metrics) : JSON.stringify(metrics, null, 2));
+            }
+            else {
+                console.log(renderSandboxMetrics(id, metrics));
+            }
+            if (!opts.watch)
+                return;
+            await new Promise((resolveDelay) => setTimeout(resolveDelay, opts.interval * 1_000));
+        }
+    }));
+    withOutput(sandbox
+        .command('secrets')
+        .description('Replace the secrets a running sandbox holds (a full replacement, not a merge)')
+        .argument('<id>', 'sandbox id')
+        .option('--secret-group <group>', 'attach a secret group; repeatable and ORDER MATTERS (a later group wins on a name collision)', collectRepeatable, [])
+        .option('--secret <group/name>', 'attach one secret out of a group; repeatable, same ordering', collectRepeatable, [])
+        .option('--env <NAME=VALUE>', 'literal value; applied last, so it wins; repeatable', collectRepeatable, [])).action((id, opts) => run(async () => {
+        const body = secretSelector(opts);
+        await runCloudApi().put(`/run-cloud/sandboxes/${encodeURIComponent(id)}/secrets`, body);
+        console.log(`${id}: secrets replaced`);
+    }));
+    withOutput(sandbox
+        .command('expose')
+        .description('Publish a sandbox guest port at a stable hostname, or change the published port')
+        .argument('<id>', 'sandbox id')
+        .option('--port <port>', 'guest port to publish (default 3000)', parsePort)
+        .option('--name <name>', 'hostname prefix for a first exposure: <name>-box.run.cloud (defaults to the sandbox name)')
+        .option('--reconcile', 'retry or reconcile hostname routing', false)).action((id, opts) => run(async () => {
+        const api = runCloudApi();
+        const existing = await findBoxForSandbox(api, id);
+        if (!existing) {
+            if (opts.reconcile)
+                throw new Error(`sandbox ${id} has no hostname to reconcile`);
+            let name = opts.name;
+            if (!name) {
+                const record = await api.get(`/run-cloud/sandboxes/${encodeURIComponent(id)}`);
+                name = typeof record?.name === 'string' && record.name ? record.name : undefined;
+            }
+            if (!name)
+                throw new Error('this sandbox has no name; pass --name <name> to mint <name>-box.run.cloud');
+            print(await attachHostname(api, id, name, opts.port ?? 3000), opts);
+            return;
+        }
+        if (opts.name && opts.name !== existing.name) {
+            throw new Error(`hostname is fixed at ${existing.hostname}; run 'sandbox rm ${id}' and expose again to rename`);
+        }
+        if (opts.reconcile) {
+            print(await api.post(`/run-cloud/boxes/${encodeURIComponent(existing.id)}/route`), opts);
+            return;
+        }
+        if (opts.port !== undefined) {
+            print(await api.patch(`/run-cloud/boxes/${encodeURIComponent(existing.id)}`, { port: opts.port }), opts);
+            return;
+        }
+        print(existing, opts);
+    }));
+    withOutput(sandbox
+        .command('exec')
+        .description('Run a command in a sandbox (via /bin/sh -c)')
+        .argument('<id>', 'sandbox id')
+        .argument('<cmd...>', 'command to run, e.g. npm run build')
+        .option('--timeout <seconds>', 'command timeout', parseExecTimeoutSeconds)
+        .allowUnknownOption(true)).action((id, cmdParts, opts) => run(async () => {
+        const credentials = requireCredentials();
+        const r = await runSandboxCommand({
+            apiUrl: credentials.apiUrl,
+            token: credentials.token,
+            sandboxId: id,
+            request: {
+                cmd: ['/bin/sh', '-c', shellCommand(cmdParts)],
+                ...(opts.timeout === undefined ? {} : { timeout_seconds: opts.timeout }),
+            },
+            ...(opts.json
+                ? {}
+                : {
+                    onStdout: (chunk) => process.stdout.write(chunk),
+                    onStderr: (chunk) => process.stderr.write(chunk),
+                }),
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(r, null, 2));
+        }
+        process.exitCode = r.exit_code ?? 0;
+    }));
+    sandbox
+        .command('shell')
+        .description('Open an interactive shell (resumes paused sandboxes)')
+        .argument('<id>', 'sandbox id')
+        .action((id) => run(async () => {
+        const credentials = requireCredentials();
+        const api = new ApiClient(credentials.apiUrl, credentials.token);
+        await prepareSandboxShell(api, id);
+        process.exitCode = await runSandboxShell({
+            apiUrl: credentials.apiUrl,
+            token: credentials.token,
+            sandboxId: id,
+        });
+    }));
+    for (const lifecycle of [
+        {
+            name: 'pause',
+            alias: 'stop',
+            description: 'Pause a sandbox so it can be resumed later',
+            pastTense: 'Paused',
+        },
+        {
+            name: 'resume',
+            alias: 'start',
+            description: 'Resume a paused sandbox',
+            pastTense: 'Resumed',
+        },
+    ]) {
+        withOutput(sandbox
+            .command(lifecycle.name)
+            .alias(lifecycle.alias)
+            .description(lifecycle.description)
+            .argument('<id>', 'sandbox id')).action((id, opts) => run(async () => {
+            const record = await runCloudApi().post(`/run-cloud/sandboxes/${encodeURIComponent(id)}/${lifecycle.name}`);
+            if (opts.json)
+                printJson(record);
+            else
+                console.log(`${style.green('✓')} ${lifecycle.pastTense} ${id}`);
+        }));
+    }
+    withOutput(sandbox
+        .command('logs')
+        .description('Show saved console logs (available after a sandbox is deleted)')
+        .argument('<id>', 'sandbox id')
+        .option('--lines <n>', 'number of lines to tail', '200')).action((id, opts) => run(async () => {
+        const n = Number(opts.lines) || 200;
+        const saved = await runCloudApi().getText(`/run-cloud/sandboxes/${encodeURIComponent(id)}/logs`);
+        const lines = saved.split('\n');
+        const logs = lines.slice(Math.max(0, lines.length - n - (saved.endsWith('\n') ? 1 : 0))).join('\n');
+        if (opts.json) {
+            printJson({ sandboxId: id, logs });
+            return;
+        }
+        process.stdout.write(logs);
+    }));
+    withOutput(sandbox
+        .command('desktop')
+        .description('Open a signed browser desktop for a runcloud/desktop sandbox')
+        .argument('<id>', 'sandbox id')
+        .option('--url', 'print the signed noVNC URL instead of opening it', false)
+        .option('--view-only', 'disable keyboard and pointer input', false)).action((id, opts) => run(async () => {
+        const desktop = await runCloudApi().post(`/run-cloud/sandboxes/${encodeURIComponent(id)}/desktop`, { viewOnly: opts.viewOnly });
+        if (typeof desktop?.url !== 'string' || !desktop.url.startsWith('https://')) {
+            throw new Error('sandbox desktop response did not include a secure URL');
+        }
+        if (opts.url) {
+            console.log(desktop.url);
+            return;
+        }
+        if (opts.json) {
+            print(desktop, opts);
+            return;
+        }
+        openBrowserUrl(desktop.url);
+        console.log(`Opened ${opts.viewOnly ? 'view-only ' : ''}desktop for ${id}`);
+    }));
+    withOutput(sandbox
+        .command('screenshot')
+        .description('Capture the sandbox desktop as a PNG')
+        .argument('<id>', 'sandbox id')
+        .option('--output <path>', 'PNG output path', 'screen.png')).action((id, opts) => run(async () => {
+        const result = await runCloudApi().post(`/run-cloud/sandboxes/${encodeURIComponent(id)}/computer`, { action: 'screenshot' });
+        if (typeof result?.image !== 'string' || !result.image) {
+            throw new Error('sandbox screenshot response did not include a PNG image');
+        }
+        const image = Buffer.from(result.image, 'base64');
+        const pngSignature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+        if (image.length < pngSignature.length ||
+            !image.subarray(0, pngSignature.length).equals(pngSignature)) {
+            throw new Error('sandbox screenshot response was not a valid PNG');
+        }
+        const output = resolve(opts.output);
+        writeFileSync(output, image, { mode: 0o600 });
+        print({ sandboxId: id, output, bytes: image.length }, opts);
+    }));
+    withOutput(sandbox
+        .command('click')
+        .description('Click a desktop pixel coordinate')
+        .argument('<id>', 'sandbox id')
+        .argument('<x>', 'horizontal pixel coordinate', parseCoordinate)
+        .argument('<y>', 'vertical pixel coordinate', parseCoordinate)).action((id, x, y, opts) => run(async () => {
+        const result = await runCloudApi().post(`/run-cloud/sandboxes/${encodeURIComponent(id)}/computer`, { action: 'click', x, y });
+        print(result ?? { ok: true }, opts);
+    }));
+    withOutput(sandbox
+        .command('type')
+        .description('Type text into the sandbox desktop')
+        .argument('<id>', 'sandbox id')
+        .argument('<text>', 'text to type')).action((id, text, opts) => run(async () => {
+        const result = await runCloudApi().post(`/run-cloud/sandboxes/${encodeURIComponent(id)}/computer`, { action: 'type', text });
+        print(result ?? { ok: true }, opts);
+    }));
+    withOutput(sandbox
+        .command('key')
+        .description('Send an xdotool key chord to the sandbox desktop')
+        .argument('<id>', 'sandbox id')
+        .argument('<keys>', 'key or chord, e.g. ctrl+l')).action((id, keys, opts) => run(async () => {
+        const result = await runCloudApi().post(`/run-cloud/sandboxes/${encodeURIComponent(id)}/computer`, { action: 'key', keys });
+        print(result ?? { ok: true }, opts);
+    }));
+    withOutput(sandbox
+        .command('rm')
+        .aliases(['kill', 'terminate'])
+        .description('Permanently destroy a sandbox and its public hostname when exposed')
+        .argument('<id>', 'sandbox id')).action((id, opts) => run(async () => {
+        const api = runCloudApi();
+        try {
+            await api.delete(`/run-cloud/sandboxes/${encodeURIComponent(id)}`);
+        }
+        catch (err) {
+            if (!(err instanceof ApiError) || err.status !== 409)
+                throw err;
+            const box = await findBoxForSandbox(api, id);
+            if (!box)
+                throw err;
+            await api.delete(`/run-cloud/boxes/${encodeURIComponent(box.id)}`);
+        }
+        if (!opts.json)
+            console.log(`${style.green('✓')} Destroyed ${id}`);
+    }));
+    const snapshot = sandbox.command('snapshot').description('Capture and manage sandbox snapshots');
+    withOutput(snapshot
+        .command('create')
+        .description('Snapshot a sandbox for later restore')
+        .argument('<id>', 'sandbox id to snapshot')
+        .option('--label <label>', 'human-readable label')
+        .option('--timeout <seconds>', 'maximum time to wait for snapshot completion', parseExecTimeoutSeconds, 3600)).action((id, opts) => run(async () => {
+        const body = {};
+        if (opts.label)
+            body.label = opts.label;
+        const api = runCloudApi();
+        let result = await api.post(`/run-cloud/sandboxes/${encodeURIComponent(id)}/snapshots`, body);
+        const deadline = Date.now() + opts.timeout * 1000;
+        while (result.state === 'pending') {
+            if (!result.id)
+                throw new Error('snapshot job did not return an id');
+            if (Date.now() >= deadline)
+                throw new Error(`snapshot ${result.id} did not finish before the timeout`);
+            await new Promise((resolve) => setTimeout(resolve, 1000));
+            result = await api.get(`/run-cloud/snapshots/${encodeURIComponent(result.id)}`);
+        }
+        if (result.state === 'failed')
+            throw new Error(`snapshot ${result.id ?? ''} failed`);
+        print(result, opts);
+    }));
+    withOutput(snapshot
+        .command('list')
+        .description('List snapshots')
+        .option('--sandbox <id>', 'only snapshots taken from this sandbox')).action((opts) => run(async () => {
+        const qs = opts.sandbox ? `?sandbox_id=${encodeURIComponent(opts.sandbox)}` : '';
+        const data = await runCloudApi().get(`/run-cloud/snapshots${qs}`);
+        print(data?.items ?? [], opts);
+    }));
+    withOutput(snapshot.command('rm').description('Delete a snapshot').argument('<id>', 'snapshot id')).action((id, opts) => run(async () => {
+        await runCloudApi().delete(`/run-cloud/snapshots/${encodeURIComponent(id)}`);
+        if (!opts.json)
+            console.log(`deleted ${id}`);
+    }));
+    withOutput(sandbox
+        .command('restore')
+        .description('Fork a new sandbox from a snapshot (warm start)')
+        .argument('<snapshot-id>', 'snapshot id to restore from')
+        .option('--name <name>', 'human-readable name for the new sandbox')
+        .option('--size <size>', 'size preset for the restored sandbox')
+        .option('--cpu <cores>', 'CPU cores, including fractional values', parseCpuCores)
+        .option('--memory <mb>', 'memory in MiB', parseMemoryMb)
+        .option('--disk <gb>', 'root disk capacity in GiB (may only grow)', parseDiskGb)
+        .option('--region <region>', 'placement region')
+        .option('--secret-group <group>', 'attach a secret group to the fork; a fork inherits NONE by default (secrets live in memory, so a snapshot cannot carry them)', collectRepeatable, [])
+        .option('--secret <group/name>', 'attach one secret out of a group; repeatable, order matters', collectRepeatable, [])
+        .option('--env <NAME=VALUE>', 'literal value for the fork; applied last; repeatable', collectRepeatable, [])).action((snapshotId, opts) => run(async () => {
+        const body = {};
+        if (opts.name)
+            body.name = opts.name;
+        if (opts.size)
+            body.size = opts.size;
+        if (opts.cpu !== undefined)
+            body.cpu = opts.cpu;
+        if (opts.memory !== undefined)
+            body.memory = opts.memory;
+        if (opts.disk !== undefined)
+            body.disk = opts.disk;
+        if (opts.region)
+            body.region = opts.region;
+        Object.assign(body, secretSelector(opts));
+        const restored = await runCloudApi().post(`/run-cloud/snapshots/${encodeURIComponent(snapshotId)}/restore`, body);
+        if (opts.json)
+            printJson(restored);
+        else
+            console.log(renderSandbox(restored, 'restored'));
+    }));
+    registerAccessCommands(sandbox);
+    const box = program
+        .command('box')
+        .description('Deprecated: a box is a sandbox with --persistent and --expose — use `runcloud sandbox`');
+    withOutput(box
+        .command('create')
+        .description('Deprecated: use `sandbox create --expose <port> --name <name>`')
+        .argument('<name>', 'hostname prefix: <name>-box.run.cloud')
+        .option('--sandbox <id>', 'attach an existing sandbox created with --idle-pause 0')
+        .option('--port <port>', 'guest port to publish', parsePort, 3000)
+        .option('--image <ref>', 'base image for a new sandbox (runcloud/box or runcloud/box-agent)', 'runcloud/box')
+        .option('--region <region>', 'placement region for a new sandbox')
+        .option('--org <id>', 'billing and ownership organization for a new sandbox')
+        .option('--cpu <cores>', 'vCPU allocation for a new box', parseCpuCores, DEFAULT_BOX_CPU_CORES)
+        .option('--memory <mb>', 'memory allocation in MiB for a new box', parseMemoryMb, DEFAULT_BOX_MEMORY_MIB)
+        .option('--disk <gb>', 'root disk capacity in GiB', parseDiskGb)).action((name, opts) => {
+        noteDeprecated('box create', opts.sandbox
+            ? `sandbox expose ${opts.sandbox} --name ${name}`
+            : `sandbox create --expose ${opts.port} --name ${name}`);
+        return run(async () => {
+            const api = runCloudApi();
+            let sandboxId = opts.sandbox;
+            if (!sandboxId) {
+                const sandboxBody = {
+                    image: opts.image,
+                    name,
+                    idlePauseSeconds: 0,
+                };
+                if (opts.region)
+                    sandboxBody.region = opts.region;
+                if (opts.org)
+                    sandboxBody.orgId = opts.org;
+                sandboxBody.cpu = opts.cpu;
+                sandboxBody.memory = opts.memory;
+                if (opts.disk !== undefined)
+                    sandboxBody.disk = opts.disk;
+                const created = await api.post('/run-cloud/sandboxes', sandboxBody);
+                sandboxId = typeof created?.id === 'string' ? created.id : undefined;
+                if (!sandboxId)
+                    throw new Error('sandbox create response did not include an id');
+            }
+            print(await attachHostname(api, sandboxId, name, opts.port), opts);
+        });
+    });
+    withOutput(box.command('list').description('Deprecated: use `sandbox list`')).action((opts) => {
+        noteDeprecated('box list', 'sandbox list');
+        return run(async () => {
+            const data = await runCloudApi().get('/run-cloud/boxes');
+            print(data?.items ?? [], opts);
+        });
+    });
+    withOutput(box.command('get').description('Deprecated: use `sandbox get <sandbox-id>`').argument('<id>', 'box id')).action((id, opts) => {
+        noteDeprecated('box get', 'sandbox get <sandbox-id>');
+        return run(async () => {
+            print(await runCloudApi().get(`/run-cloud/boxes/${encodeURIComponent(id)}`), opts);
+        });
+    });
+    withOutput(box
+        .command('port')
+        .description('Deprecated: use `sandbox expose <sandbox-id> --port <port>`')
+        .argument('<id>', 'box id')
+        .argument('<port>', 'guest port', parsePort)).action((id, port, opts) => {
+        noteDeprecated('box port', `sandbox expose <sandbox-id> --port ${port}`);
+        return run(async () => {
+            print(await runCloudApi().patch(`/run-cloud/boxes/${encodeURIComponent(id)}`, { port }), opts);
+        });
+    });
+    withOutput(box
+        .command('route')
+        .description('Deprecated: use `sandbox expose <sandbox-id> --reconcile`')
+        .argument('<id>', 'box id')).action((id, opts) => {
+        noteDeprecated('box route', 'sandbox expose <sandbox-id> --reconcile');
+        return run(async () => {
+            print(await runCloudApi().post(`/run-cloud/boxes/${encodeURIComponent(id)}/route`), opts);
+        });
+    });
+    withOutput(box
+        .command('rm')
+        .description('Deprecated: use `sandbox rm <sandbox-id>`')
+        .argument('<id>', 'box id')).action((id, opts) => {
+        noteDeprecated('box rm', 'sandbox rm <sandbox-id>');
+        return run(async () => {
+            await runCloudApi().delete(`/run-cloud/boxes/${encodeURIComponent(id)}`);
+            if (!opts.json)
+                console.log(`destroyed box ${id}`);
+        });
+    });
+    registerAccessCommands(box, { deprecated: true });
+}