runcloud 0.1.16 → 0.1.17

package/dist/api.js

@@ -21,6 +21,9 @@ function parsedErrorDetail(body) {
     }
     catch {
     }
+    if (/<(?:!doctype|html)\b/i.test(body)) {
+        return 'the API edge returned an HTML error page; retry the request or use the streaming/direct-transfer command';
+    }
     return body;
 }
 export class ApiClient {
@@ -69,6 +72,9 @@ export class ApiClient {
         const contentType = res.headers.get('content-type') ?? '';
         return contentType.includes('application/json') ? res.json() : res;
     }
+    put(path, body) {
+        return this.request('PUT', path, body);
+    }
     patch(path, body) {
         return this.request('PATCH', path, body);
     }

package/dist/commands/boxAccess.js

@@ -24,6 +24,54 @@ async function resolveBox(client, reference) {
     }
     return box;
 }
+async function resolveSandboxId(client, reference) {
+    const response = await client.get('/run-cloud/sandboxes');
+    const sandboxes = (response?.items ?? []);
+    const sandbox = sandboxes.find((item) => item.id === reference || item.name === reference);
+    if (sandbox?.id)
+        return sandbox.id;
+    return (await resolveBox(client, reference)).sandboxId ?? reference;
+}
+async function writeSandboxFile(client, sandboxId, path, content) {
+    const chunkSize = 512 * 1024;
+    const count = Math.max(1, Math.ceil(content.byteLength / chunkSize));
+    for (let index = 0; index < count; index += 1) {
+        const offset = index * chunkSize;
+        const chunk = content.subarray(offset, Math.min(content.byteLength, offset + chunkSize));
+        const response = await client.post(`/run-cloud/sandboxes/${encodeURIComponent(sandboxId)}/fs`, {
+            op: 'write',
+            path,
+            offset,
+            content: chunk.toString('base64'),
+            truncate: index === 0,
+        });
+        if (response?.error)
+            throw new Error(String(response.error));
+    }
+}
+async function readSandboxFile(client, sandboxId, path) {
+    const chunks = [];
+    let offset = 0;
+    for (;;) {
+        const response = await client.post(`/run-cloud/sandboxes/${encodeURIComponent(sandboxId)}/fs`, {
+            op: 'read',
+            path,
+            offset,
+            length: 512 * 1024,
+        });
+        if (response?.error)
+            throw new Error(String(response.error));
+        const chunk = Buffer.from(String(response?.content ?? ''), 'base64');
+        chunks.push(chunk);
+        const next = Number(response?.next_offset ?? offset + chunk.byteLength);
+        if (response?.eof === true || chunk.byteLength === 0)
+            break;
+        if (!Number.isSafeInteger(next) || next <= offset)
+            throw new Error('file read did not advance');
+        offset = next;
+    }
+    return Buffer.concat(chunks);
+}
 function sshHome() {
     const base = process.env.RUN_CLOUD_HOME || join(homedir(), '.run-cloud');
     return join(base, 'ssh');
@@ -174,7 +222,7 @@ export function registerAccessCommands(parent, opts = {}) {
     });
     parent
         .command('cp')
-        .description('Copy files with scp; prefix the remote path with a colon')
+        .description('Copy a file directly; prefix the remote path with a colon')
         .argument('<sandbox>', REFERENCE_HELP)
         .argument('<source>', 'local path or :/remote/path')
         .argument('<destination>', 'local path or :/remote/path')
@@ -185,6 +233,17 @@ export function registerAccessCommands(parent, opts = {}) {
             if (source.startsWith(':') === destination.startsWith(':')) {
                 throw new Error('Exactly one path must be remote (prefix it with :)');
             }
+            if (!cmdOpts.recursive) {
+                const client = api();
+                const sandboxId = await resolveSandboxId(client, reference);
+                if (source.startsWith(':')) {
+                    writeFileSync(destination, await readSandboxFile(client, sandboxId, source.slice(1)));
+                }
+                else {
+                    await writeSandboxFile(client, sandboxId, destination.slice(1), readFileSync(source));
+                }
+                return;
+            }
             const configured = await setupSsh(reference);
             const remote = (path) => path.startsWith(':') ? `${configured.alias}:${path.slice(1)}` : path;
             const args = [

package/dist/commands/run-cloud.js

@@ -6,148 +6,20 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createHash } from 'node:crypto';
 import { ApiClient, friendlyApiError } from '../api.js';
 import { requireCredentials } from '../config.js';
-export const RUN_CLOUD_SKILL = `---
-name: run-cloud-ios-simulator
-description: Use run.cloud SDK and CLI workflows for iOS simulator and Android emulator sessions.
-version: 0.5.1
----
-
-# run.cloud Mobile Sessions
-
-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
-
-- 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.run.cloud\`.
-- 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 organization credit.
-- App artifacts must match the target platform. iOS sessions need simulator-compatible builds; Android sessions need Android-compatible artifacts such as APKs.
-
-## TypeScript SDK
-
-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);
+const RUN_CLOUD_SKILL_FILENAME = 'run-cloud-ios-simulator/SKILL.md';
+function loadRunCloudSkill() {
+    const commandDirectory = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        resolve(commandDirectory, '../../skills', RUN_CLOUD_SKILL_FILENAME),
+        resolve(commandDirectory, '../../../.claude/skills', RUN_CLOUD_SKILL_FILENAME),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return readFileSync(candidate, 'utf8');
+    }
+    throw new Error('run.cloud agent skill is missing from the package; reinstall runcloud or use npx skills add newly-app/run-cloud-examples --skill run-cloud-ios-simulator');
 }
-\`\`\`
-
-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://docs.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.run.cloud"
-\`\`\`
-
-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.
-
-Download checksum-verified onboarding artifacts when no local build is
-available:
-
-\`\`\`bash
-runcloud sample download ios
-runcloud ios create --install ./run-cloud-sample-ios.app.tar.gz
-
-runcloud sample download android
-runcloud android create --install ./run-cloud-sample-android.apk
-\`\`\`
-
-## 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 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 \`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 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 matches the target platform before attempting code changes.
-- Do not assume a local tunnel is installed on the user's machine.
-- Do not expose API keys, CLI tokens, signed simulator URLs, or simulator tokens in logs or screenshots.
-`;
+export const RUN_CLOUD_SKILL = loadRunCloudSkill();
 function client() {
     const creds = requireCredentials();
     return new ApiClient(creds.apiUrl, creds.token);
@@ -332,11 +204,29 @@ export async function runCloudDemo(name = 'eight-device-mosaic', opts = {}, load
 }
 async function pushAsset(path, opts = {}) {
     const { blob, name } = fileBlob(path);
-    const form = new FormData();
-    form.set('file', blob, name);
-    if (opts.name)
-        form.set('name', opts.name);
-    return (await client().uploadForm('/run-cloud/assets', form));
+    const api = client();
+    const prepared = await api.post('/run-cloud/assets/uploads', {
+        filename: name,
+        ...(opts.name ? { name: opts.name } : {}),
+        contentType: blob.type || 'application/octet-stream',
+        byteSize: blob.size,
+    });
+    try {
+        const uploaded = await fetch(prepared.upload.url, {
+            method: 'PUT',
+            headers: prepared.upload.headers,
+            body: blob,
+        });
+        if (!uploaded.ok)
+            throw new Error(`asset storage upload failed with HTTP ${uploaded.status}`);
+    }
+    catch (error) {
+        if (prepared.asset.id) {
+            await api.delete(`/run-cloud/assets/${encodeURIComponent(prepared.asset.id)}`).catch(() => undefined);
+        }
+        throw error;
+    }
+    return prepared.asset;
 }
 async function createSimulatorSession(platform, opts) {
     assertDevHostAllowed(opts.devHost);

package/dist/commands/sandbox.js

@@ -4,6 +4,7 @@ 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';
@@ -15,6 +16,8 @@ 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);
@@ -126,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) {
@@ -133,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) {
@@ -158,6 +235,31 @@ 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();
@@ -181,8 +283,13 @@ 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)
+        .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) {
@@ -208,10 +315,12 @@ 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();
         let created = (await api.post('/run-cloud/sandboxes', body));
         if (typeof created.id !== 'string') {
@@ -281,6 +390,38 @@ export function registerSandbox(program) {
         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')
@@ -320,19 +461,28 @@ 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
@@ -485,11 +635,25 @@ export function registerSandbox(program) {
         .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')
@@ -509,15 +673,28 @@ 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;
+        Object.assign(body, secretSelector(opts));
         const restored = await runCloudApi().post(`/run-cloud/snapshots/${encodeURIComponent(snapshotId)}/restore`, body);
         if (opts.json)
             printJson(restored);

package/dist/commands/secrets.js

@@ -0,0 +1,203 @@
+import { readFileSync } from 'node:fs';
+import { ApiClient, friendlyApiError } from '../api.js';
+import { requireCredentials } from '../config.js';
+import { promptHidden } from '../prompt.js';
+function api() {
+    const credentials = requireCredentials();
+    return new ApiClient(credentials.apiUrl, credentials.token);
+}
+async function run(fn) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        console.error(friendlyApiError(err));
+        process.exitCode = 1;
+    }
+}
+function orgQuery(org, extra = {}) {
+    const params = new URLSearchParams(extra);
+    if (org)
+        params.set('orgId', org);
+    const qs = params.toString();
+    return qs ? `?${qs}` : '';
+}
+export function parseDotenv(text) {
+    const entries = {};
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const withoutExport = line.startsWith('export ') ? line.slice('export '.length).trim() : line;
+        const eq = withoutExport.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const name = withoutExport.slice(0, eq).trim();
+        let value = withoutExport.slice(eq + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"') && value.length >= 2) ||
+            (value.startsWith("'") && value.endsWith("'") && value.length >= 2)) {
+            value = value.slice(1, -1);
+        }
+        entries[name] = value;
+    }
+    return entries;
+}
+export function parseJsonEntries(text) {
+    const parsed = JSON.parse(text);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('--from-json needs a JSON object of name → value');
+    }
+    const entries = {};
+    for (const [name, value] of Object.entries(parsed)) {
+        if (typeof value !== 'string') {
+            throw new Error(`--from-json: "${name}" is not a string; secrets are strings`);
+        }
+        entries[name] = value;
+    }
+    return entries;
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf8');
+}
+export function registerSecrets(program) {
+    const groups = program
+        .command('secret-group')
+        .description('Create and manage secret groups a sandbox can attach');
+    groups
+        .command('create')
+        .description('Create a group together with its contents')
+        .argument('<group>', 'group name, e.g. aws')
+        .argument('[unsupported...]', 'not accepted: a value cannot be passed as an argument')
+        .option('--from-dotenv <path>', 'read KEY=VALUE lines from a .env file')
+        .option('--from-json <path>', 'read a JSON object of name → value')
+        .option('--key <name>', 'prompt for this value (hidden); repeatable', collect, [])
+        .option('--force', 'replace the group if it already exists', false)
+        .option('--org <id>', 'organization to store it in')
+        .action((group, unsupported, opts) => run(async () => {
+        if (unsupported.length > 0) {
+            throw new Error(`values cannot be passed as arguments (got "${unsupported[0]?.split('=')[0]}=…"). ` +
+                'An argument lands in your shell history, in `ps` output, and in CI logs. ' +
+                'Use --from-dotenv <path>, --from-json <path>, or --key <name> for a hidden prompt.');
+        }
+        const entries = {};
+        if (opts.fromDotenv)
+            Object.assign(entries, parseDotenv(readFileSync(opts.fromDotenv, 'utf8')));
+        if (opts.fromJson)
+            Object.assign(entries, parseJsonEntries(readFileSync(opts.fromJson, 'utf8')));
+        for (const name of opts.key) {
+            entries[name] = await promptHidden(`${name}: `);
+        }
+        if (Object.keys(entries).length === 0) {
+            throw new Error('nothing to store: pass --from-dotenv <path>, --from-json <path>, or --key <name>. ' +
+                'A value cannot be given as an argument — it would land in your shell history.');
+        }
+        const body = { entries };
+        if (opts.force)
+            body.force = true;
+        await api().put(`/run-cloud/secret-groups/${encodeURIComponent(group)}${orgQuery(opts.org)}`, body);
+        console.log(`secret group ${group}: ${Object.keys(entries).length} secret(s) stored`);
+    }));
+    groups
+        .command('list')
+        .description('List secret groups')
+        .option('--json', 'output JSON', false)
+        .option('--org <id>', 'organization to read from')
+        .action((opts) => run(async () => {
+        const data = await api().get(`/run-cloud/secret-groups${orgQuery(opts.org)}`);
+        const rows = (data?.groups ?? []);
+        if (opts.json) {
+            console.log(JSON.stringify(rows, null, 2));
+            return;
+        }
+        if (rows.length === 0) {
+            console.log('no secret groups yet — runcloud secret-group create <name> --from-dotenv <path>');
+            return;
+        }
+        for (const row of rows)
+            console.log(`${row.group}\t${row.secretCount} secret(s)\t${row.updatedAt}`);
+    }));
+    groups
+        .command('show')
+        .description('List the names in a group (never values)')
+        .argument('<group>', 'group name')
+        .option('--json', 'output JSON', false)
+        .option('--org <id>', 'organization to read from')
+        .action((group, opts) => run(async () => {
+        const data = await api().get(`/run-cloud/secrets${orgQuery(opts.org)}`);
+        const rows = (data?.secrets ?? []).filter((row) => row.group === group);
+        if (opts.json) {
+            console.log(JSON.stringify(rows, null, 2));
+            return;
+        }
+        if (rows.length === 0) {
+            console.log(`no secret group ${group}`);
+            return;
+        }
+        for (const row of rows) {
+            console.log(row.kind === 'file' ? `${row.name}\tfile → ${row.filePath}` : `${row.name}\tenv`);
+        }
+    }));
+    groups
+        .command('rm')
+        .description('Delete a group and every secret in it')
+        .argument('<group>', 'group name')
+        .option('--org <id>', 'organization to delete from')
+        .action((group, opts) => run(async () => {
+        await api().delete(`/run-cloud/secret-groups/${encodeURIComponent(group)}${orgQuery(opts.org)}`);
+        console.log(`secret group ${group} deleted`);
+    }));
+    const secrets = program
+        .command('secrets')
+        .description('Set and remove individual secrets inside a group');
+    secrets
+        .command('set')
+        .description('Store one environment-variable secret, reading the value from stdin')
+        .argument('<name>', 'secret name, e.g. AWS_SESSION_TOKEN')
+        .requiredOption('--group <group>', 'group to store it in')
+        .option('--stdin', 'read the value from stdin', false)
+        .option('--org <id>', 'organization to store it in')
+        .action((name, opts) => run(async () => {
+        const value = opts.stdin ? (await readStdin()).replace(/\n$/, '') : await promptHidden(`${name}: `);
+        if (!value)
+            throw new Error(`no value read for ${name}`);
+        await api().put(`/run-cloud/secrets/${encodeURIComponent(name)}${orgQuery(opts.org)}`, {
+            group: opts.group,
+            value,
+            kind: 'env',
+        });
+        console.log(`${opts.group}/${name} stored`);
+    }));
+    secrets
+        .command('set-file')
+        .description('Store a file secret, written into the sandbox at --path')
+        .argument('<name>', 'secret name, e.g. sa.json')
+        .requiredOption('--group <group>', 'group to store it in')
+        .requiredOption('--path <path>', 'path inside the sandbox, relative to its home')
+        .requiredOption('--from-file <path>', 'local file to read the contents from')
+        .option('--org <id>', 'organization to store it in')
+        .action((name, opts) => run(async () => {
+        await api().put(`/run-cloud/secrets/${encodeURIComponent(name)}${orgQuery(opts.org)}`, {
+            group: opts.group,
+            value: readFileSync(opts.fromFile, 'utf8'),
+            kind: 'file',
+            filePath: opts.path,
+        });
+        console.log(`${opts.group}/${name} stored → ${opts.path}`);
+    }));
+    secrets
+        .command('rm')
+        .description('Remove one secret from a group')
+        .argument('<name>', 'secret name')
+        .requiredOption('--group <group>', 'group it lives in')
+        .option('--org <id>', 'organization to delete from')
+        .action((name, opts) => run(async () => {
+        await api().delete(`/run-cloud/secrets/${encodeURIComponent(name)}${orgQuery(opts.org, { group: opts.group })}`);
+        console.log(`${opts.group}/${name} deleted`);
+    }));
+}
+function collect(value, previous) {
+    return [...previous, value];
+}

package/dist/prompt.js

@@ -150,3 +150,47 @@ export async function ask(question, options = {}) {
         rl.close();
     }
 }
+export async function promptHidden(label) {
+    const acquired = acquirePromptIO();
+    if (!acquired) {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(Buffer.from(chunk));
+        return chunks.join('').replace(/\n$/, '');
+    }
+    const { io, close } = acquired;
+    const input = io.input;
+    const output = io.output;
+    output.write(label);
+    input.setRawMode?.(true);
+    emitKeypressEvents(input);
+    input.resume();
+    return await new Promise((resolve, reject) => {
+        let value = '';
+        const finish = (fn) => {
+            input.setRawMode?.(false);
+            input.pause();
+            input.removeListener('keypress', onKeypress);
+            output.write('\n');
+            close();
+            fn();
+        };
+        function onKeypress(_str, key) {
+            if (key.ctrl && key.name === 'c') {
+                finish(() => reject(new Error('cancelled')));
+                return;
+            }
+            if (key.name === 'return' || key.name === 'enter') {
+                finish(() => resolve(value));
+                return;
+            }
+            if (key.name === 'backspace') {
+                value = value.slice(0, -1);
+                return;
+            }
+            if (key.sequence && !key.ctrl && !key.meta)
+                value += key.sequence;
+        }
+        input.on('keypress', onKeypress);
+    });
+}

package/dist/run-cloud.js

@@ -4,6 +4,7 @@ import { registerImage } from './commands/image.js';
 import { registerLogin } from './commands/login.js';
 import { registerRunCloud } from './commands/run-cloud.js';
 import { registerSandbox } from './commands/sandbox.js';
+import { registerSecrets } from './commands/secrets.js';
 import { CLI_VERSION } from './version.js';
 const program = new Command('runcloud')
     .description('Create and control remote mobile simulators and microVM sandboxes')
@@ -11,5 +12,6 @@ const program = new Command('runcloud')
 registerLogin(program);
 registerRunCloud(program);
 registerSandbox(program);
+registerSecrets(program);
 registerImage(program);
 await program.parseAsync(process.argv);

package/dist/sandboxExec.js

@@ -0,0 +1,91 @@
+import WebSocket from 'ws';
+export function streamExitCode(frame) {
+    const code = frame.code ?? frame.exit_code ?? 0;
+    return Number.isSafeInteger(code) ? code : undefined;
+}
+export function shellCommand(argv) {
+    if (argv.length === 1)
+        return argv[0] ?? '';
+    return argv
+        .map((part) => `'${part.replaceAll("'", "'\"'\"'")}'`)
+        .join(' ');
+}
+export function runSandboxCommand(input) {
+    const url = new URL(`/run-cloud/sandboxes/${encodeURIComponent(input.sandboxId)}/exec/stream?mode=command`, input.apiUrl);
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    const socket = input.createSocket?.(url.toString(), {
+        headers: { Authorization: `Bearer ${input.token}` },
+    }) ??
+        new WebSocket(url, {
+            headers: { Authorization: `Bearer ${input.token}` },
+        });
+    return new Promise((resolve, reject) => {
+        const stdout = [];
+        const stderr = [];
+        let exitCode;
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            if (error) {
+                reject(error);
+                return;
+            }
+            if (exitCode === undefined) {
+                reject(new Error('sandbox exec stream closed before reporting an exit code'));
+                return;
+            }
+            resolve({
+                exit_code: exitCode,
+                stdout: Buffer.concat(stdout).toString('utf8'),
+                stderr: Buffer.concat(stderr).toString('utf8'),
+            });
+        };
+        socket.once('open', () => socket.send(JSON.stringify(input.request)));
+        socket.on('message', (raw) => {
+            let frame;
+            try {
+                frame = JSON.parse(raw.toString());
+            }
+            catch {
+                socket.close(1002, 'invalid exec frame');
+                finish(new Error('sandbox exec stream returned invalid JSON'));
+                return;
+            }
+            if (frame.stream === 'stdout' || frame.stream === 'stderr') {
+                if (typeof frame.data !== 'string')
+                    return;
+                const chunk = Buffer.from(frame.data, 'base64');
+                if (frame.stream === 'stdout') {
+                    stdout.push(chunk);
+                    input.onStdout?.(chunk);
+                }
+                else {
+                    stderr.push(chunk);
+                    input.onStderr?.(chunk);
+                }
+                return;
+            }
+            if (frame.stream === 'exit') {
+                const code = streamExitCode(frame);
+                if (code === undefined) {
+                    socket.close(1002, 'invalid exit code');
+                    finish(new Error('sandbox exec stream returned an invalid exit code'));
+                    return;
+                }
+                exitCode = code;
+                socket.close(1000);
+            }
+        });
+        socket.once('error', (error) => finish(error));
+        socket.once('close', (code, reason) => {
+            if (exitCode !== undefined)
+                finish();
+            else {
+                finish(new Error(reason.toString() ||
+                    `sandbox exec stream closed before completion (${code})`));
+            }
+        });
+    });
+}

package/dist/shellSession.js

@@ -46,8 +46,10 @@ export async function runShellSession(input) {
                     const target = frame.stream === 'stderr' ? stderr : stdout;
                     target.write(Buffer.from(frame.data, 'base64'));
                 }
-                else if (frame.stream === 'exit' && typeof frame.exit_code === 'number') {
-                    exitCode = frame.exit_code;
+                else if (frame.stream === 'exit') {
+                    const code = frame.code ?? frame.exit_code ?? 0;
+                    if (Number.isSafeInteger(code))
+                        exitCode = code;
                 }
             }
             catch {

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = '0.1.16';
+export const CLI_VERSION = '0.1.17';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcloud",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Create and control run.cloud remote mobile simulators and cloud sandboxes",
   "license": "Apache-2.0",
   "keywords": [

package/skills/run-cloud-ios-simulator/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: run-cloud-ios-simulator
+description: Operate run.cloud iOS simulator and Android emulator sessions with the CLI or TypeScript SDK. Use for creating, installing, inspecting, embedding, smoke-testing, connecting local Metro, capturing iOS screenshots, injecting iOS media, or releasing remote mobile sessions.
+---
+
+# Operate run.cloud Mobile Sessions
+
+Use run.cloud through the `runcloud` CLI for terminal workflows and
+`@run-cloud/sdk` for application, CI, or agent code.
+
+## Authenticate
+
+- Install the CLI with `npm install -g runcloud`.
+- Use `runcloud login` for an interactive browser handoff. Use
+  `runcloud login --manual` when a local callback cannot open.
+- In CI, set `RUN_CLOUD_API_KEY`. `RUN_CLOUD_API_TOKEN` is an equivalent alias.
+- Set `RUN_CLOUD_API_URL` only to override the production default
+  `https://api.run.cloud`.
+- Never print, commit, or place credentials in a skill file.
+- Treat signed simulator URLs and tunnel URLs as bearer secrets.
+- Require Node.js 20 or newer for the CLI and TypeScript SDK.
+
+Inspect account and organization credit before starting metered work:
+
+```bash
+runcloud account --json
+```
+
+Sessions require product access, organization credit below its ceiling, and
+available fleet capacity. A create request may queue while capacity is full.
+
+## Choose the Interface
+
+- Prefer CLI commands with `--json` for shell automation.
+- Prefer `@run-cloud/sdk` for TypeScript applications and CI.
+- Inspect `runcloud <command> --help` or installed SDK types before using a
+  method not documented here.
+
+## Use the CLI
+
+Create an iOS session, capture its ID, open a deep link, and release it:
+
+```bash
+SESSION_ID=$(runcloud ios create \
+  --install ./build/MyApp.tar.gz \
+  --inactivity-timeout 60s \
+  --hard-timeout 10m \
+  --json | jq -r '.id')
+
+trap 'runcloud ios delete "$SESSION_ID" >/dev/null 2>&1 || true' EXIT
+
+runcloud ios get "$SESSION_ID" --json
+runcloud ios open-url myapp://settings --id "$SESSION_ID" --json
+```
+
+Use the corresponding `runcloud android` commands for Android artifacts.
+
+The shared mobile lifecycle is:
+
+- `runcloud ios|android create`
+- `runcloud ios|android list [--all]`
+- `runcloud ios|android get <id>`
+- `runcloud ios|android open-url <url> --id <id>`
+- `runcloud ios|android delete <id>`
+
+Create accepts `--model`, `--region`, `--display-name`, repeatable `--label`,
+repeatable `--install`, repeatable `--install-asset`,
+`--inactivity-timeout`, `--hard-timeout`, `--codec`, `--rm`, and `--json`.
+
+Use assets and samples when no local artifact is ready:
+
+```bash
+runcloud sample download ios
+runcloud ios create --install ./run-cloud-sample-ios.app.tar.gz --json
+
+runcloud asset push ./build/MyApp.tar.gz --name my-app --json
+runcloud ios create --install-asset my-app --json
+runcloud asset list --json
+runcloud asset pull <asset-id> --output ./MyApp.tar.gz
+runcloud asset delete <asset-id> --json
+```
+
+iOS needs an Apple Silicon simulator-compatible `.app`, `.zip`, `.tar.gz`, or
+`.ipa` artifact. A device-signed App Store IPA is not a substitute. Android
+needs an emulator-compatible artifact such as an APK.
+
+## Connect Local Development
+
+Connect a local Metro or mock server to an active iOS session:
+
+```bash
+runcloud ios tunnel "$SESSION_ID" \
+  --local-port 8081 \
+  --service metro \
+  --json
+
+runcloud ios tunnel-status --json
+```
+
+Use the run.cloud sidecar flow. Do not install or expose an unauthenticated
+third-party tunnel. If the sidecar is unavailable, report that requirement
+instead of guessing a public URL.
+
+## Use the TypeScript SDK
+
+Install the SDK:
+
+```bash
+npm install @run-cloud/sdk
+```
+
+Always release metered sessions in `finally`:
+
+```ts
+import { writeFile } from "node:fs/promises";
+import { Client } from "@run-cloud/sdk";
+
+const cloud = new Client();
+const session = await cloud.ios.create({
+  displayName: "Agent smoke",
+  labels: { owner: "agent" },
+  inactivityTimeout: "60s",
+  hardTimeout: "10m",
+  codec: "auto",
+});
+
+try {
+  await cloud.ios.openUrl(session.id, "https://run.cloud");
+  const screenshot = await cloud.ios.screenshot(session.id);
+  await writeFile("run-cloud.png", screenshot);
+} finally {
+  await cloud.ios.delete(session.id);
+}
+```
+
+The mobile SDK surface is:
+
+- `cloud.account()` and `cloud.usage({ orgId? })`
+- `cloud.ios`: `create`, `list`, `get`, `openUrl`, `screenshot`,
+  `uploadVideo`, `uploadMicrophoneAudio`, `delete`
+- `cloud.android`: `create`, `list`, `get`, `openUrl`, `delete`
+- `cloud.simulators`: runtime-platform `create`, `list`, `get`, `openUrl`,
+  `delete`
+- `cloud.assets`: `upload`, `list`, `delete`
+
+Create options include `model`, `region`, `displayName`, `labels`,
+`installAssets`, `inactivityTimeout`, `hardTimeout`, and `codec`.
+
+Do not invent SDK methods for scripted taps, typing, recording, app lifecycle,
+or Android screenshots. Browser-stream interaction and iframe commands are
+separate from the public SDK.
+
+## Inject iOS Media
+
+Use `cloud.ios.uploadVideo(id, video, options)` for MP4 or QuickTime video. It
+stores a user-owned asset and imports it into Photos.
+
+Use `cloud.ios.uploadMicrophoneAudio(id, audio, options)` for AAC, M4A, MP3,
+MP4-audio, or WAV. Pass an optional `bundleId`; otherwise it targets the
+foreground app. The operation relaunches the target app with microphone
+permission and loops the decoded audio through `AVAudioEngine`.
+
+Delete uploaded assets when they are no longer needed.
+
+## Embed a Session
+
+- Add `embed=1` to the signed session URL for the clean iframe UI.
+- Add `loadingGuard=1` when the iframe should block interaction until streaming
+  and app launch are ready.
+- Verify `event.source` is the expected iframe before processing messages.
+- Handle `ios-simulator:status`, `ios-simulator:auth-error`,
+  `ios-simulator:session-ended`, and
+  `ios-simulator:session-restart-requested`.
+- Create a new session after a restart request; never reuse an ended URL.
+- Use `ios-simulator:command` for `reload`, `home`, `rotate`, `screenshot`, and
+  `toggleAccessibility`.
+
+## Run Maintained Demos
+
+```bash
+runcloud demo run eight-device-mosaic --open
+runcloud demo run live-camera-relay --open
+```
+
+The bundled demos release their sessions automatically.
+
+## Guardrails
+
+- Release every session created during a task unless the user explicitly asks
+  to keep it open.
+- Use inactivity and hard timeouts for unattended work.
+- Verify platform compatibility before changing application code after an
+  install failure.
+- Do not expose credentials, signed viewer URLs, tunnel URLs, or simulator
+  tokens in logs, screenshots, PR comments, or chat output.
+- Do not claim that browser iframe controls are public SDK methods.

package/skills/run-cloud-ios-simulator/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Run Cloud Mobile Sessions"
+  short_description: "Operate remote iOS and Android sessions"
+  default_prompt: "Use $run-cloud-ios-simulator to create, inspect, test, and clean up run.cloud mobile sessions."