runcloud 0.1.15 → 0.1.17

package/dist/commands/sandbox.js

@@ -1,21 +1,30 @@
-import { InvalidArgumentError } from 'commander';
+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_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) {
-        console.log(JSON.stringify(value, null, 2));
+        printJson(value);
         return;
     }
     if (Array.isArray(value)) {
@@ -25,6 +34,53 @@ function print(value, opts) {
     }
     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);
@@ -73,6 +129,20 @@ function parseIdlePauseSeconds(value) {
     }
     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) {
@@ -80,6 +150,66 @@ function parsePort(value) {
     }
     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.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) {
+    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) {
@@ -105,8 +235,43 @@ async function findBoxForSandbox(api, 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')
@@ -118,8 +283,14 @@ export function registerSandbox(program) {
         .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; 0 disables the lifetime timer', parseTimeoutSeconds, 0)
         .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)).action((opts) => run(async () => {
+        .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');
@@ -144,20 +315,44 @@ export function registerSandbox(program) {
             body.memory = memory;
         if (opts.disk !== undefined)
             body.disk = opts.disk;
+        body.timeoutSeconds = opts.timeout;
         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();
-        const created = await api.post('/run-cloud/sandboxes', body);
+        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) {
-            print(created, opts);
+            if (opts.json)
+                printJson(created);
+            else
+                console.log(renderSandbox(created, 'created'));
             return;
         }
-        if (typeof created?.id !== 'string')
-            throw new Error('sandbox create response did not include an id');
         const box = await attachHostname(api, created.id, opts.name, opts.expose);
-        print({ ...created, box }, opts);
+        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)}` : '';
@@ -175,7 +370,10 @@ export function registerSandbox(program) {
             const box = bySandbox.get(item.id);
             return box ? { ...item, hostname: box.hostname, exposedPort: box.port } : item;
         });
-        print(items, opts);
+        if (opts.json)
+            printJson(items);
+        else
+            console.log(renderSandboxList(items));
     }));
     withOutput(sandbox
         .command('get')
@@ -186,7 +384,43 @@ export function registerSandbox(program) {
             api.get(`/run-cloud/sandboxes/${encodeURIComponent(id)}`),
             findBoxForSandbox(api, id),
         ]);
-        print(box ? { ...record, box } : record, opts);
+        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')
@@ -227,33 +461,70 @@ export function registerSandbox(program) {
         .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')).action((id, cmdParts, opts) => run(async () => {
-        const r = await runCloudApi().post(`/run-cloud/sandboxes/${encodeURIComponent(id)}/exec`, {
-            cmd: ['/bin/sh', '-c', cmdParts.join(' ')],
+        .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));
         }
-        else {
-            if (r.stdout)
-                process.stdout.write(r.stdout);
-            if (r.stderr)
-                process.stderr.write(r.stderr);
-        }
         process.exitCode = r.exit_code ?? 0;
     }));
     sandbox
         .command('shell')
-        .description('Open an interactive shell in a running sandbox')
+        .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 recent sandbox logs (one-shot journalctl tail; streaming is a follow-up)')
@@ -341,7 +612,8 @@ export function registerSandbox(program) {
     }));
     withOutput(sandbox
         .command('rm')
-        .description('Destroy a sandbox, along with its public hostname when exposed')
+        .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 {
@@ -356,18 +628,32 @@ export function registerSandbox(program) {
             await api.delete(`/run-cloud/boxes/${encodeURIComponent(box.id)}`);
         }
         if (!opts.json)
-            console.log(`destroyed ${id}`);
+            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')).action((id, opts) => run(async () => {
+        .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;
-        print(await runCloudApi().post(`/run-cloud/sandboxes/${encodeURIComponent(id)}/snapshots`, body), opts);
+        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')
@@ -387,16 +673,33 @@ export function registerSandbox(program) {
         .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')).action((snapshotId, opts) => run(async () => {
+        .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;
-        print(await runCloudApi().post(`/run-cloud/snapshots/${encodeURIComponent(snapshotId)}/restore`, body), opts);
+        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

package/dist/commands/sandboxOutput.js

@@ -0,0 +1,70 @@
+import { formatAge, formatCpu, formatMib, formatSeconds, formatState, renderDetails, renderTable, shortDigest, style, } from '../terminal.js';
+function resources(record) {
+    const memory = formatMib(record.mem_mb);
+    const disk = formatMib(record.disk_mb);
+    return [
+        formatCpu(record.milli_cpu),
+        memory ? `${memory} memory` : undefined,
+        disk ? `${disk} disk` : undefined,
+    ]
+        .filter(Boolean)
+        .join(' · ') || undefined;
+}
+function hostname(record) {
+    const host = record.hostname ?? record.box?.hostname;
+    const port = record.exposedPort ?? record.box?.port;
+    return host && port ? `${host}:${port}` : host;
+}
+function title(record, verb) {
+    if (verb === 'details')
+        return 'Sandbox';
+    if (record.state === 'running')
+        return `✓ Sandbox ${verb === 'restored' ? 'restored' : 'ready'}`;
+    if (record.state === 'building_image')
+        return '◐ Sandbox is building its image';
+    if (record.state === 'paused' || record.state === 'archived')
+        return '○ Sandbox paused';
+    return verb === 'restored' ? 'Sandbox restored' : 'Sandbox created';
+}
+export function renderSandbox(record, verb = 'details') {
+    const next = verb === 'details'
+        ? undefined
+        : record.state === 'running'
+            ? `${style.dim('Next:')}  runcloud sandbox shell ${record.id}`
+            : `${style.dim('Follow:')}  runcloud sandbox get ${record.id}`;
+    return renderDetails(title(record, verb), [
+        { label: 'ID', value: record.id },
+        { label: 'Name', value: record.name },
+        { label: 'State', value: formatState(record.state) },
+        { label: 'Image', value: record.image },
+        { label: 'Resources', value: resources(record) },
+        { label: 'Idle pause', value: formatSeconds(record.idle_pause_seconds) },
+        { label: 'Timeout', value: formatSeconds(record.timeout_seconds) },
+        { label: 'Hostname', value: hostname(record) },
+        { label: 'Image digest', value: shortDigest(record.image_digest) },
+        { label: 'Created', value: formatAge(record.created_at) },
+        { label: 'Last active', value: verb === 'details' ? formatAge(record.last_active_at) : undefined },
+    ], next);
+}
+export function renderSandboxList(records) {
+    if (records.length === 0) {
+        return `${style.bold('Sandboxes')}\n\nNo sandboxes found.\n\n${style.dim('Create one:')}  runcloud sandbox create`;
+    }
+    return renderTable(`Sandboxes (${records.length})`, [
+        { key: 'id', label: 'ID', maxWidth: 24 },
+        { key: 'name', label: 'NAME / HOSTNAME', maxWidth: 20 },
+        { key: 'state', label: 'STATE', maxWidth: 14 },
+        { key: 'image', label: 'IMAGE', maxWidth: 20 },
+        { key: 'resources', label: 'CPU / MEMORY', maxWidth: 18 },
+        { key: 'age', label: 'AGE' },
+    ], records.map((record) => ({
+        id: record.id,
+        name: hostname(record) ?? record.name ?? '—',
+        state: formatState(record.state),
+        image: record.image ?? '—',
+        resources: [formatCpu(record.milli_cpu)?.replace(' CPU', ''), formatMib(record.mem_mb)]
+            .filter(Boolean)
+            .join(' / ') || '—',
+        age: formatAge(record.created_at) ?? '—',
+    })));
+}