runcloud 0.1.2 → 0.1.4

package/dist/commands/run-cloud.js

@@ -1,46 +1,141 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { basename, join, resolve } from 'node:path';
+import { Option } from 'commander';
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { ApiClient, friendlyApiError } from '../api.js';
 import { requireCredentials } from '../config.js';
-const RUN_CLOUD_SKILL = `---
+export const RUN_CLOUD_SKILL = `---
 name: run-cloud-ios-simulator
-description: Build, install, and inspect iOS apps with run.cloud remote simulator sessions.
-version: 0.1.0
+description: Use run.cloud SDK and CLI workflows for iOS simulator and Android emulator sessions.
+version: 0.5.0
 ---
 
-# run.cloud iOS Simulator
+# run.cloud Mobile Sessions
 
-Use this skill when a user asks an agent to run, inspect, smoke test, or debug an iOS app in a remote simulator through run.cloud.
+Use this skill when a user asks an agent to create, inspect, smoke test, debug, or release an iOS simulator or Android emulator through run.cloud.
 
 ## Requirements
 
-- The user must be authenticated with \`runcloud login\`.
-- The account must have run.cloud access and a positive run.cloud balance.
-- App artifacts should be simulator-compatible builds. Device App Store IPAs may fail to install on iOS Simulator.
+- Read SDK credentials from \`RUN_CLOUD_API_KEY\`. Never print it, commit it, or write it into a skill file. The SDK uses \`RUN_CLOUD_API_URL\` when set and otherwise defaults to \`https://api.newly.app\`.
+- Authenticate the CLI with either a saved \`runcloud login\` credential or \`RUN_CLOUD_API_KEY\` together with \`RUN_CLOUD_API_URL\`. Do not require both a saved login and an API key.
+- The TypeScript SDK requires Node.js 20 or newer.
+- The account must have run.cloud access, available capacity, and a positive run.cloud balance.
+- App artifacts must match the target platform. iOS sessions need simulator-compatible builds; Android sessions need Android-compatible artifacts such as APKs.
 
-## Workflow
+## TypeScript SDK
 
-1. Check access with \`runcloud account --json\`.
-2. Create a simulator with \`runcloud ios create --install ./build/MyApp.tar.gz --json\`.
-3. Save the returned session id and URL.
-4. Use \`runcloud ios open-url <url> --id <session-id>\` when a URL or deep link must be opened.
-5. Release the session with \`runcloud ios delete <session-id>\`.
+Prefer \`@run-cloud/sdk\` for applications, CI, and agent code:
+
+\`\`\`bash
+npm install @run-cloud/sdk
+\`\`\`
+
+Use the platform client when the platform is known, and always release metered sessions in \`finally\`:
+
+\`\`\`ts
+import { Client } from "@run-cloud/sdk";
+
+const cloud = new Client();
+const session = await cloud.ios.create({
+  displayName: "Agent smoke",
+  labels: { owner: "agent" },
+  inactivityTimeout: "60s",
+});
+
+try {
+  await cloud.ios.openUrl(session.id, "https://run.cloud");
+  console.log(session.url);
+} finally {
+  await cloud.ios.delete(session.id);
+}
+\`\`\`
+
+Use \`cloud.android\` for Android. When the platform is selected at runtime, use \`cloud.simulators\` and pass \`session.platform\` to \`get\`, \`openUrl\`, or \`delete\`.
+
+The implemented SDK surface is:
+
+- \`cloud.account()\`;
+- \`cloud.ios\` and \`cloud.android\`: \`create\`, \`list\`, \`get\`, \`openUrl\`, \`delete\`;
+- \`cloud.simulators\`: the same lifecycle with a runtime \`platform\` option;
+- \`cloud.assets\`: \`upload\`, \`list\`, \`delete\`.
+
+Do not invent screenshot, tap, typing, recording, app lifecycle, sandbox, build, or compatibility-adapter methods. Check the installed package types and https://run.cloud/cli/typescript-sdk before using a method not listed here.
+
+## CLI Workflow
+
+Use the CLI for interactive terminal work. Authenticate with a saved login:
+
+\`\`\`bash
+npm install -g runcloud
+runcloud login
+\`\`\`
+
+Or authenticate non-interactively with both required environment variables:
+
+\`\`\`bash
+export RUN_CLOUD_API_KEY="rc_live_..."
+export RUN_CLOUD_API_URL="https://api.newly.app"
+\`\`\`
+
+Then inspect the account:
+
+\`\`\`bash
+runcloud account --json
+\`\`\`
+
+Create, inspect, open a URL, and release an iOS session:
+
+\`\`\`bash
+runcloud ios create --install ./build/MyApp.tar.gz --json
+runcloud ios get "$SESSION_ID" --json
+runcloud ios open-url myapp://settings --id "$SESSION_ID"
+runcloud ios delete "$SESSION_ID" --json
+\`\`\`
+
+Use the corresponding \`runcloud android\` commands with an Android artifact for Android emulator sessions.
+
+## Runnable SDK Example
+
+The maintained example checks account state, creates iOS and Android sessions, opens a URL on each, and releases both sessions:
+
+\`\`\`bash
+git clone --depth 1 https://github.com/newly-app/run-cloud-examples.git
+cd run-cloud-examples/sdk-ios-android
+npm install
+npm run demo -- --platform both --open
+\`\`\`
+
+Use \`--platform ios\` or \`--platform android\` for one platform. Use \`--json\` for machine-readable output. The example releases sessions on completion, failure, SIGINT, and SIGTERM unless the user explicitly passes \`--keep\`.
+
+## Bundled CLI Demos
+
+These published demos exercise multi-simulator workflows:
+
+\`\`\`bash
+runcloud demo run parallel-simulators --open
+runcloud demo run eight-device-mosaic --open
+runcloud demo run live-camera-relay --open
+\`\`\`
+
+They use the same CLI authentication choices described above and release every session automatically.
 
 ## Embedded Iframes
 
-- Use \`runcloud ios create --inactivity-timeout 60s --json\` when the embed should auto-close after user inactivity.
-- Omit \`--inactivity-timeout\` or pass \`none\` when the user needs a metered session without idle auto-close.
-- Iframes post \`ios-simulator:status\`, \`ios-simulator:auth-error\`, \`ios-simulator:session-ended\`, and \`ios-simulator:session-restart-requested\` to the parent window. Verify \`event.source\` before acting.
-- If \`ios-simulator:session-restart-requested\` arrives, create a fresh run.cloud session; do not reuse the ended iframe URL.
+- Use \`inactivityTimeout: "60s"\` in the SDK, or \`--inactivity-timeout 60s\` in the CLI, when an embed should auto-close after user inactivity.
+- Omit the option or pass \`null\`/\`none\` when the user needs a metered session without idle auto-close.
+- Treat the returned signed session URL as a secret. Do not publish it in logs.
+- Iframes post \`ios-simulator:status\`, \`ios-simulator:auth-error\`, \`ios-simulator:session-ended\`, and \`ios-simulator:session-restart-requested\` messages to the parent window.
+- Verify \`event.source\` before acting on iframe messages.
+- When \`ios-simulator:session-restart-requested\` arrives, create a fresh session; do not reuse the ended iframe URL.
 
 ## Rules
 
-- Prefer \`--json\` for parsed output.
+- Prefer the SDK for code and \`--json\` CLI output for shell automation.
 - Always release sessions you create unless the user asks to keep them open.
-- If installation fails, verify that the artifact is a simulator build before attempting code changes.
+- If installation fails, verify that the artifact matches the target platform before attempting code changes.
 - Do not assume a local tunnel is installed on the user's machine.
-- Do not expose iOS simulator tokens in logs or screenshots.
+- Do not expose API keys, CLI tokens, signed simulator URLs, or simulator tokens in logs or screenshots.
 `;
 function client() {
     const creds = requireCredentials();
@@ -123,6 +218,61 @@ function installSkill(opts) {
     }
     return results;
 }
+const RUN_CLOUD_DEMOS = [
+    'parallel-simulators',
+    'eight-device-mosaic',
+    'live-camera-relay',
+];
+function experimentalWebRtcEnabled() {
+    return ['1', 'true', 'yes', 'on'].includes((process.env.RUN_CLOUD_EXPERIMENTAL_WEBRTC ?? '').trim().toLowerCase());
+}
+function assertDevHostAllowed(devHost) {
+    if (devHost && process.env.RUN_CLOUD_DEV_FEATURES !== '1') {
+        throw new Error('--dev-host is dev-only; set RUN_CLOUD_DEV_FEATURES=1 to use it');
+    }
+}
+function requestedCodec(codec) {
+    const value = codec?.trim().toLowerCase() || 'auto';
+    if (value === 'webrtc' && !experimentalWebRtcEnabled()) {
+        throw new Error('--codec webrtc is experimental; set RUN_CLOUD_EXPERIMENTAL_WEBRTC=1 to use it');
+    }
+    return value;
+}
+function demoDirectory(name) {
+    if (!RUN_CLOUD_DEMOS.some((demoName) => demoName === name)) {
+        throw new Error(`Unknown demo: ${name}. Available demos: ${RUN_CLOUD_DEMOS.join(', ')}`);
+    }
+    const source = resolve(dirname(fileURLToPath(import.meta.url)), '../../examples', name);
+    if (!existsSync(source))
+        throw new Error(`The ${name} demo is missing from this runcloud package.`);
+    return source;
+}
+export function initRunCloudDemo(name = 'parallel-simulators', directory, opts = {}) {
+    const source = demoDirectory(name);
+    const target = resolve(directory ?? `run-cloud-${name}`);
+    if (existsSync(target)) {
+        if (!opts.force)
+            throw new Error(`${target} already exists. Pass --force to overwrite it.`);
+        rmSync(target, { recursive: true, force: true });
+    }
+    cpSync(source, target, { recursive: true });
+    return { example: name, path: target, status: 'created' };
+}
+export async function runCloudDemo(name = 'parallel-simulators', opts = {}, loadDemo = async (url) => (await import(url))) {
+    if (name === 'eight-device-mosaic' && opts.duration) {
+        throw new Error('The eight-device mosaic uses a fixed 10-minute lease and does not accept --duration.');
+    }
+    const args = [];
+    if (opts.count)
+        args.push('--count', opts.count);
+    if (opts.duration)
+        args.push('--duration', opts.duration);
+    if (opts.open)
+        args.push('--open');
+    const source = join(demoDirectory(name), 'demo.mjs');
+    const demo = await loadDemo(pathToFileURL(source).href);
+    await demo.runDemo(args);
+}
 async function pushAsset(path, opts = {}) {
     const { blob, name } = fileBlob(path);
     const form = new FormData();
@@ -131,92 +281,162 @@ async function pushAsset(path, opts = {}) {
         form.set('name', opts.name);
     return (await client().uploadForm('/run-cloud/assets', form));
 }
-async function action(fn) {
-    try {
-        await fn();
-    }
-    catch (err) {
-        console.error(friendlyApiError(err));
-        process.exitCode = 1;
-    }
+async function createSimulatorSession(platform, opts) {
+    assertDevHostAllowed(opts.devHost);
+    const uploadedAssets = [];
+    for (const file of opts.install ?? [])
+        uploadedAssets.push(await pushAsset(file));
+    const installAssets = [
+        ...(opts.installAsset ?? []),
+        ...uploadedAssets
+            .map((asset) => asset.id)
+            .filter((id) => typeof id === 'string' && id.length > 0),
+    ];
+    return await client().post(`/run-cloud/${platform}`, {
+        model: opts.model,
+        region: opts.region,
+        displayName: opts.displayName,
+        labels: parseLabels(opts.label),
+        installAssets,
+        inactivityTimeout: opts.inactivityTimeout,
+        hardTimeout: opts.hardTimeout,
+        autoDelete: opts.rm,
+        codec: requestedCodec(opts.codec),
+        ...(opts.devHost ? { devHost: opts.devHost } : {}),
+    });
 }
-export function registerRunCloud(program) {
-    program
-        .command('account')
-        .description('Show run.cloud entitlement and metered balance')
-        .option('--json', 'output JSON', false)
-        .action((opts) => action(async () => {
-        print(await client().get('/run-cloud/account'), opts);
-    }));
-    const ios = program.command('ios').description('Create, list, inspect, and delete iOS simulator sessions');
-    ios
+function registerSimulatorCommands(program, platform) {
+    const label = platform === 'android' ? 'Android emulator' : 'iOS simulator';
+    const article = platform === 'android' ? 'an' : 'an';
+    const simulator = program.command(platform).description(`Create, list, inspect, and delete ${label} sessions`);
+    simulator
         .command('create')
-        .description('Create a remote iOS simulator session')
-        .option('--model <iphone|ipad>', 'simulator model', 'iphone')
+        .description(`Create a remote ${label} session`)
+        .option('--model <model>', platform === 'ios' ? 'simulator model' : 'emulator model', platform === 'ios' ? 'iphone' : 'pixel')
         .option('--region <region>', 'fleet region')
         .option('--display-name <name>', 'human-readable name')
         .option('--label <key=value>', 'label to attach to the session', (v, p) => [...p, v], [])
-        .option('--install <file>', 'local .ipa, .zip, .tar.gz, or simulator .app archive to upload and install', (v, p) => [...p, v], [])
+        .option('--install <file>', 'local app artifact to upload and install', (v, p) => [...p, v], [])
         .option('--install-asset <name-or-id>', 'previously uploaded asset to install', (v, p) => [...p, v], [])
         .option('--inactivity-timeout <duration>', 'auto-close idle timeout, e.g. 60s, 3m, or none')
         .option('--hard-timeout <duration>', 'maximum lifetime, e.g. 10m or 1h')
+        .option('--codec <auto|mjpeg|webrtc>', 'force the simulator viewer stream codec', 'auto')
         .option('--rm', 'release the session when this command exits', false)
         .option('--json', 'output JSON', false)
+        .addOption(new Option('--dev-host <host>', 'dev-only: target a specific serve-sim fleet host').hideHelp())
         .action((opts) => action(async () => {
-        const uploadedAssets = [];
-        for (const file of opts.install ?? [])
-            uploadedAssets.push(await pushAsset(file));
-        const installAssets = [
-            ...(opts.installAsset ?? []),
-            ...uploadedAssets
-                .map((asset) => asset.id)
-                .filter((id) => typeof id === 'string' && id.length > 0),
-        ];
-        const session = await client().post('/run-cloud/ios', {
-            model: opts.model,
-            region: opts.region,
-            displayName: opts.displayName,
-            labels: parseLabels(opts.label),
-            installAssets,
-            inactivityTimeout: opts.inactivityTimeout,
-            hardTimeout: opts.hardTimeout,
-            autoDelete: opts.rm,
-        });
-        print(session, opts);
+        print(await createSimulatorSession(platform, opts), opts);
     }));
-    ios
+    simulator
         .command('list')
-        .description('List active iOS simulator sessions')
+        .description(`List active ${label} sessions`)
         .option('--all', 'include released sessions', false)
         .option('--json', 'output JSON', false)
         .action((opts) => action(async () => {
         const qs = opts.all ? '?all=1' : '';
-        print(await client().get(`/run-cloud/ios${qs}`), opts);
+        print(await client().get(`/run-cloud/${platform}${qs}`), opts);
     }));
-    ios
+    simulator
         .command('get')
-        .description('Show an iOS simulator session')
+        .description(`Show ${article} ${label} session`)
         .argument('<id>')
         .option('--json', 'output JSON', false)
         .action((id, opts) => action(async () => {
-        print(await client().get(`/run-cloud/ios/${encodeURIComponent(id)}`), opts);
+        print(await client().get(`/run-cloud/${platform}/${encodeURIComponent(id)}`), opts);
     }));
-    ios
+    simulator
         .command('delete')
-        .description('Release an iOS simulator session')
+        .description(`Release ${article} ${label} session`)
         .argument('<id>')
         .option('--json', 'output JSON', false)
         .action((id, opts) => action(async () => {
-        print(await client().delete(`/run-cloud/ios/${encodeURIComponent(id)}`), opts);
+        print(await client().delete(`/run-cloud/${platform}/${encodeURIComponent(id)}`), opts);
     }));
-    ios
+    simulator
         .command('open-url')
-        .description('Open a URL or deep link in an iOS simulator session')
+        .description(`Open a URL or deep link in ${article} ${label} session`)
         .argument('<url>')
         .requiredOption('--id <id>', 'session id')
         .option('--json', 'output JSON', false)
         .action((url, opts) => action(async () => {
-        print(await client().post(`/run-cloud/ios/${encodeURIComponent(opts.id)}/open-url`, { url }), opts);
+        print(await client().post(`/run-cloud/${platform}/${encodeURIComponent(opts.id)}/open-url`, { url }), opts);
+    }));
+    return simulator;
+}
+async function action(fn) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        console.error(friendlyApiError(err));
+        process.exitCode = 1;
+    }
+}
+export function registerRunCloud(program) {
+    const demo = program.command('demo').description('Create and run run.cloud demo projects');
+    demo
+        .command('init')
+        .description('Scaffold a standalone demo project')
+        .argument('[name]', 'demo to create', 'parallel-simulators')
+        .argument('[directory]', 'output directory')
+        .option('--force', 'overwrite an existing output directory', false)
+        .option('--json', 'output JSON', false)
+        .action((name, directory, opts) => action(async () => {
+        print(initRunCloudDemo(name, directory, opts), opts);
+    }));
+    demo
+        .command('run')
+        .description('Run a bundled demo without scaffolding a project')
+        .argument('[name]', 'demo to run', 'parallel-simulators')
+        .option('--count <2|3>', 'number of sessions (parallel-simulators only)')
+        .option('--duration <seconds>', 'duration for parallel-simulators and live-camera-relay')
+        .option('--open', 'open the demo viewer or live sessions in the browser', false)
+        .action((name, opts) => action(async () => {
+        await runCloudDemo(name, opts);
+    }));
+    program
+        .command('account')
+        .description('Show run.cloud entitlement and metered balance')
+        .option('--json', 'output JSON', false)
+        .action((opts) => action(async () => {
+        print(await client().get('/run-cloud/account'), opts);
+    }));
+    const ios = registerSimulatorCommands(program, 'ios');
+    registerSimulatorCommands(program, 'android');
+    ios
+        .command('tunnel')
+        .description('Connect a local service to a remote iOS simulator session')
+        .argument('<id>')
+        .requiredOption('--local-port <port>', 'local service port, for example Metro on 8081')
+        .option('--service <name>', 'service name shown in status', 'metro')
+        .option('--local-host <host>', 'loopback service host', '127.0.0.1')
+        .option('--sidecar-url <url>', 'Newly sidecar URL', 'http://127.0.0.1:4500')
+        .option('--json', 'output JSON', false)
+        .action((id, opts) => action(async () => {
+        const localPort = Number(opts.localPort);
+        if (!Number.isInteger(localPort) || localPort < 1 || localPort > 65535)
+            throw new Error('--local-port must be a valid TCP port');
+        const allocation = await client().post(`/sessions/${encodeURIComponent(id)}/tunnel`, {
+            localService: opts.service, localHost: opts.localHost, localPort,
+        });
+        if (!allocation.tunnel)
+            throw new Error('Control plane did not return tunnel credentials');
+        const sidecarResponse = await fetch(`${opts.sidecarUrl.replace(/\/$/, '')}/run-cloud/tunnel`, {
+            method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(allocation.tunnel),
+        });
+        const status = await sidecarResponse.json();
+        if (!sidecarResponse.ok)
+            throw new Error(`Local tunnel failed: ${status.error ?? sidecarResponse.statusText}`);
+        print(status, opts);
+    }));
+    ios
+        .command('tunnel-status')
+        .description('Show the local tunnel sidecar status')
+        .option('--sidecar-url <url>', 'Newly sidecar URL', 'http://127.0.0.1:4500')
+        .option('--json', 'output JSON', false)
+        .action((opts) => action(async () => {
+        const response = await fetch(`${opts.sidecarUrl.replace(/\/$/, '')}/run-cloud/tunnel`);
+        print(await response.json(), opts);
     }));
     const asset = program
         .command('asset')
@@ -260,7 +480,7 @@ export function registerRunCloud(program) {
     const skills = program.command('skills').description('Install run.cloud skills for AI coding agents');
     skills
         .command('install')
-        .description('Install the run.cloud iOS simulator skill')
+        .description('Install the run.cloud agent runtime skill')
         .option('--agents <agent>', 'agent to install for: claude, codex, cursor', (v, p) => [...p, v], [])
         .option('--scope <project|global>', 'install scope', 'project')
         .option('--force', 'overwrite existing skill', false)

package/dist/commands/sandbox.js

@@ -0,0 +1,136 @@
+import { friendlyApiError } from '../api.js';
+class CpClient {
+    baseUrl;
+    token;
+    constructor(baseUrl, token) {
+        this.baseUrl = baseUrl;
+        this.token = token;
+    }
+    async request(method, path, body) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: { Authorization: `Bearer ${this.token}`, 'Content-Type': 'application/json' },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            let msg = text;
+            try {
+                msg = JSON.parse(text).error ?? text;
+            }
+            catch {
+            }
+            throw new Error(`control plane ${res.status}: ${msg}`);
+        }
+        return text ? JSON.parse(text) : null;
+    }
+}
+function cp(opts) {
+    const baseUrl = (opts.cpUrl || process.env.SBX_API_URL || 'http://127.0.0.1:8080').replace(/\/+$/, '');
+    const token = opts.cpToken || process.env.SBX_TOKEN;
+    if (!token) {
+        throw new Error('No control-plane token: set SBX_TOKEN or pass --cp-token.');
+    }
+    return new CpClient(baseUrl, token);
+}
+function print(value, opts) {
+    if (opts.json) {
+        console.log(JSON.stringify(value, null, 2));
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            console.log(formatRecord(item));
+        return;
+    }
+    console.log(formatRecord(value));
+}
+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 withCp(cmd) {
+    return cmd
+        .option('--cp-url <url>', 'control-plane base URL (default $SBX_API_URL or http://127.0.0.1:8080)')
+        .option('--cp-token <token>', 'control-plane org token (or $SBX_TOKEN; required)')
+        .option('--json', 'output JSON', false);
+}
+export function registerSandbox(program) {
+    const sandbox = program.command('sandbox').description('Spawn and control microVM sandboxes');
+    withCp(sandbox
+        .command('create')
+        .description('Spawn a microVM sandbox')
+        .option('--image <ref>', 'base image', 'newly/agent-base')
+        .option('--size <class>', 'size preset', 's-2')
+        .option('--region <region>', 'placement region')
+        .option('--name <name>', 'human-readable name')).action((opts) => run(async () => {
+        const body = { size_class: opts.size, image: opts.image };
+        if (opts.name)
+            body.name = opts.name;
+        if (opts.region)
+            body.region = opts.region;
+        print(await cp(opts).request('POST', '/v1/sandboxes', body), opts);
+    }));
+    withCp(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 data = await cp(opts).request('GET', `/v1/sandboxes${qs}`);
+        print(data?.items ?? [], opts);
+    }));
+    withCp(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')).action((id, cmdParts, opts) => run(async () => {
+        const r = await cp(opts).request('POST', `/v1/sandboxes/${encodeURIComponent(id)}/exec`, {
+            cmd: ['/bin/sh', '-c', cmdParts.join(' ')],
+        });
+        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;
+    }));
+    withCp(sandbox
+        .command('logs')
+        .description('Show recent sandbox logs (one-shot journalctl tail; streaming is a follow-up)')
+        .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 r = await cp(opts).request('POST', `/v1/sandboxes/${encodeURIComponent(id)}/exec`, {
+            cmd: [
+                '/bin/sh',
+                '-c',
+                `j="$(journalctl -n ${n} --no-pager 2>/dev/null)"; if [ -n "$j" ]; then printf "%s\\n" "$j"; else tail -n ${n} /root/.natively/expo_server.log 2>&1 || echo '(no logs available)'; fi`,
+            ],
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(r, null, 2));
+            return;
+        }
+        process.stdout.write(r.stdout ?? '');
+        process.stderr.write(r.stderr ?? '');
+    }));
+    withCp(sandbox.command('rm').description('Destroy a sandbox').argument('<id>', 'sandbox id')).action((id, opts) => run(async () => {
+        await cp(opts).request('DELETE', `/v1/sandboxes/${encodeURIComponent(id)}`);
+        if (!opts.json)
+            console.log(`destroyed ${id}`);
+    }));
+}