runcloud 0.1.5 → 0.1.8

package/dist/commands/run-cloud.js

@@ -3,6 +3,7 @@ import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFil
 import { basename, dirname, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 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 = `---
@@ -20,7 +21,7 @@ Use this skill when a user asks an agent to create, inspect, smoke test, debug,
 - 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.
+- 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
@@ -95,6 +96,17 @@ 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:
@@ -113,7 +125,6 @@ Use \`--platform ios\` or \`--platform android\` for one platform. Use \`--json\
 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
 \`\`\`
@@ -219,10 +230,58 @@ function installSkill(opts) {
     return results;
 }
 const RUN_CLOUD_DEMOS = [
-    'parallel-simulators',
     'eight-device-mosaic',
     'live-camera-relay',
 ];
+export const RUN_CLOUD_SAMPLES = {
+    ios: {
+        filename: 'run-cloud-sample-ios.app.tar.gz',
+        url: 'https://run.cloud/downloads/run-cloud-sample-ios.app.tar.gz',
+        sha256: '09c437b1f299d41f79a8453611d99b8b1e4a3f5198dd871f4dad183362f944b3',
+        byteSize: 19_516,
+    },
+    android: {
+        filename: 'run-cloud-sample-android.apk',
+        url: 'https://run.cloud/downloads/run-cloud-sample-android.apk',
+        sha256: '892d4441a24757fc88852d29abe87d42d14f04921cbe89802e369dad6e46edba',
+        byteSize: 6_521_225,
+    },
+};
+function samplePlatform(value) {
+    if (value === 'ios' || value === 'android')
+        return value;
+    throw new Error(`Unknown sample platform: ${value}. Choose ios or android.`);
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+export async function downloadRunCloudSample(rawPlatform, opts = {}, fetchSample = fetch, samples = RUN_CLOUD_SAMPLES) {
+    const platform = samplePlatform(rawPlatform);
+    const sample = samples[platform];
+    const target = resolve(opts.output ?? sample.filename);
+    if (existsSync(target) && !opts.force) {
+        throw new Error(`${target} already exists. Pass --force to overwrite it.`);
+    }
+    const response = await fetchSample(sample.url);
+    if (!response.ok) {
+        throw new Error(`Could not download the ${platform} sample: HTTP ${response.status}`);
+    }
+    const body = Buffer.from(await response.arrayBuffer());
+    const sha256 = createHash('sha256').update(body).digest('hex');
+    if (body.byteLength !== sample.byteSize || sha256 !== sample.sha256) {
+        throw new Error(`The ${platform} sample failed its checksum verification.`);
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, body);
+    return {
+        platform,
+        path: target,
+        url: sample.url,
+        sha256,
+        byteSize: body.byteLength,
+        next: `runcloud ${platform} create --install ${shellQuote(target)}`,
+    };
+}
 function experimentalWebRtcEnabled() {
     return ['1', 'true', 'yes', 'on'].includes((process.env.RUN_CLOUD_EXPERIMENTAL_WEBRTC ?? '').trim().toLowerCase());
 }
@@ -247,7 +306,7 @@ function demoDirectory(name) {
         throw new Error(`The ${name} demo is missing from this runcloud package.`);
     return source;
 }
-export function initRunCloudDemo(name = 'parallel-simulators', directory, opts = {}) {
+export function initRunCloudDemo(name = 'eight-device-mosaic', directory, opts = {}) {
     const source = demoDirectory(name);
     const target = resolve(directory ?? `run-cloud-${name}`);
     if (existsSync(target)) {
@@ -258,13 +317,11 @@ export function initRunCloudDemo(name = 'parallel-simulators', directory, opts =
     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))) {
+export async function runCloudDemo(name = 'eight-device-mosaic', 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)
@@ -323,7 +380,7 @@ function registerSimulatorCommands(program, platform) {
         .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())
+        .addOption(new Option('--dev-host <host>', 'dev-only: target a specific simulator fleet host').hideHelp())
         .action((opts) => action(async () => {
         print(await createSimulatorSession(platform, opts), opts);
     }));
@@ -373,11 +430,25 @@ async function action(fn) {
     }
 }
 export function registerRunCloud(program) {
+    const sample = program
+        .command('sample')
+        .alias('samples')
+        .description('Download installable onboarding sample apps');
+    sample
+        .command('download')
+        .description('Download a checksum-verified iOS or Android sample app')
+        .argument('<ios|android>', 'sample platform')
+        .option('-o, --output <path>', 'output file')
+        .option('--force', 'overwrite an existing output file', false)
+        .option('--json', 'output JSON', false)
+        .action((platform, opts) => action(async () => {
+        print(await downloadRunCloudSample(platform, opts), opts);
+    }));
     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('[name]', 'demo to create', 'eight-device-mosaic')
         .argument('[directory]', 'output directory')
         .option('--force', 'overwrite an existing output directory', false)
         .option('--json', 'output JSON', false)
@@ -387,16 +458,15 @@ export function registerRunCloud(program) {
     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')
+        .argument('[name]', 'demo to run', 'eight-device-mosaic')
+        .option('--duration <seconds>', 'duration for 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')
+        .description('Show run.cloud account and organization access')
         .option('--json', 'output JSON', false)
         .action((opts) => action(async () => {
         print(await client().get('/run-cloud/account'), opts);

package/dist/commands/sandbox.js

@@ -1,37 +1,16 @@
-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);
+import { InvalidArgumentError } from 'commander';
+import { execFileSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { ApiClient, friendlyApiError } from '../api.js';
+import { requireCredentials } from '../config.js';
+import { registerBoxAccessCommands } from './boxAccess.js';
+const MAX_SANDBOX_DISK_GIB = 2048;
+const DEFAULT_BOX_CPU_CORES = 2;
+const DEFAULT_BOX_MEMORY_MIB = 24 * 1024;
+function runCloudApi() {
+    const credentials = requireCredentials();
+    return new ApiClient(credentials.apiUrl, credentials.token);
 }
 function print(value, opts) {
     if (opts.json) {
@@ -62,39 +41,103 @@ async function run(fn) {
         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);
+function withOutput(cmd) {
+    return cmd.option('--json', 'output JSON', false);
+}
+function parseCpuCores(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new InvalidArgumentError('--cpu must be a positive number of cores, e.g. 0.5');
+    }
+    return n;
+}
+function parseMemoryMb(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new InvalidArgumentError('--memory must be a positive integer of MiB, e.g. 1024');
+    }
+    return n;
+}
+function parseDiskGb(value) {
+    const n = Number(value);
+    if (!Number.isSafeInteger(n) || n <= 0 || n > MAX_SANDBOX_DISK_GIB) {
+        throw new InvalidArgumentError(`--disk must be an integer from 1 to ${MAX_SANDBOX_DISK_GIB} GiB`);
+    }
+    return n;
+}
+function parseIdlePauseSeconds(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 0) {
+        throw new InvalidArgumentError('--idle-pause must be a non-negative integer of seconds');
+    }
+    return n;
+}
+function parsePort(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1 || n > 65535) {
+        throw new InvalidArgumentError('--port must be an integer from 1 to 65535');
+    }
+    return n;
+}
+function parseCoordinate(value) {
+    const n = Number(value);
+    if (!Number.isSafeInteger(n) || n < 0) {
+        throw new InvalidArgumentError('coordinates must be non-negative integers');
+    }
+    return n;
+}
+export function openBrowserUrl(url, platform = process.platform) {
+    if (platform === 'darwin') {
+        execFileSync('open', [url], { stdio: 'ignore' });
+        return;
+    }
+    if (platform === 'win32') {
+        execFileSync('cmd', ['/c', 'start', '', url], { stdio: 'ignore' });
+        return;
+    }
+    execFileSync('xdg-open', [url], { stdio: 'ignore' });
 }
 export function registerSandbox(program) {
     const sandbox = program.command('sandbox').description('Spawn and control microVM sandboxes');
-    withCp(sandbox
+    withOutput(sandbox
         .command('create')
         .description('Spawn a microVM sandbox')
-        .option('--image <ref>', 'base image', 'newly/agent-base')
-        .option('--size <class>', 'size preset', 's-2')
+        .option('--image <ref>', 'base image', 'runcloud/agent-base')
         .option('--region <region>', 'placement region')
-        .option('--name <name>', 'human-readable name')).action((opts) => run(async () => {
-        const body = { size_class: opts.size, image: opts.image };
+        .option('--name <name>', 'human-readable name')
+        .option('--org <id>', 'billing and ownership organization')
+        .option('--cpu <cores>', 'fractional vCPU allocation, e.g. 0.5', parseCpuCores)
+        .option('--memory <mb>', 'memory allocation in MiB', parseMemoryMb)
+        .option('--disk <gb>', 'root disk capacity in GiB', parseDiskGb)
+        .option('--idle-pause <seconds>', 'pause after inactivity; 0 keeps it running', parseIdlePauseSeconds)).action((opts) => run(async () => {
+        const body = { 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);
+        if (opts.org)
+            body.orgId = opts.org;
+        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.idlePause !== undefined)
+            body.idlePauseSeconds = opts.idlePause;
+        print(await runCloudApi().post('/run-cloud/sandboxes', body), opts);
     }));
-    withCp(sandbox.command('list').description('List sandboxes').option('--state <state>', 'filter by state')).action((opts) => run(async () => {
+    withOutput(sandbox.command('list').description('List sandboxes').option('--state <state>', 'filter by state')).action((opts) => run(async () => {
         const qs = opts.state ? `?state=${encodeURIComponent(opts.state)}` : '';
-        const data = await cp(opts).request('GET', `/v1/sandboxes${qs}`);
+        const data = await runCloudApi().get(`/run-cloud/sandboxes${qs}`);
         print(data?.items ?? [], opts);
     }));
-    withCp(sandbox
+    withOutput(sandbox
         .command('exec')
         .description('Run a command in a sandbox (via /bin/sh -c)')
         .argument('<id>', 'sandbox id')
         .argument('<cmd...>', 'command to run, e.g. npm run build')).action((id, cmdParts, opts) => run(async () => {
-        const r = await cp(opts).request('POST', `/v1/sandboxes/${encodeURIComponent(id)}/exec`, {
+        const r = await runCloudApi().post(`/run-cloud/sandboxes/${encodeURIComponent(id)}/exec`, {
             cmd: ['/bin/sh', '-c', cmdParts.join(' ')],
         });
         if (opts.json) {
@@ -108,13 +151,13 @@ export function registerSandbox(program) {
         }
         process.exitCode = r.exit_code ?? 0;
     }));
-    withCp(sandbox
+    withOutput(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`, {
+        const r = await runCloudApi().post(`/run-cloud/sandboxes/${encodeURIComponent(id)}/exec`, {
             cmd: [
                 '/bin/sh',
                 '-c',
@@ -128,9 +171,183 @@ export function registerSandbox(program) {
         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)}`);
+    withOutput(sandbox
+        .command('desktop')
+        .description('Open a signed browser desktop for a runcloud/desktop sandbox')
+        .argument('<id>', 'sandbox id')
+        .option('--url', 'print the signed noVNC URL instead of opening it', false)
+        .option('--view-only', 'disable keyboard and pointer input', false)).action((id, opts) => run(async () => {
+        const desktop = await runCloudApi().post(`/run-cloud/sandboxes/${encodeURIComponent(id)}/desktop`, { viewOnly: opts.viewOnly });
+        if (typeof desktop?.url !== 'string' || !desktop.url.startsWith('https://')) {
+            throw new Error('sandbox desktop response did not include a secure URL');
+        }
+        if (opts.url) {
+            console.log(desktop.url);
+            return;
+        }
+        if (opts.json) {
+            print(desktop, opts);
+            return;
+        }
+        openBrowserUrl(desktop.url);
+        console.log(`Opened ${opts.viewOnly ? 'view-only ' : ''}desktop for ${id}`);
+    }));
+    withOutput(sandbox
+        .command('screenshot')
+        .description('Capture the sandbox desktop as a PNG')
+        .argument('<id>', 'sandbox id')
+        .option('--output <path>', 'PNG output path', 'screen.png')).action((id, opts) => run(async () => {
+        const result = await runCloudApi().post(`/run-cloud/sandboxes/${encodeURIComponent(id)}/computer`, { action: 'screenshot' });
+        if (typeof result?.image !== 'string' || !result.image) {
+            throw new Error('sandbox screenshot response did not include a PNG image');
+        }
+        const image = Buffer.from(result.image, 'base64');
+        const pngSignature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+        if (image.length < pngSignature.length ||
+            !image.subarray(0, pngSignature.length).equals(pngSignature)) {
+            throw new Error('sandbox screenshot response was not a valid PNG');
+        }
+        const output = resolve(opts.output);
+        writeFileSync(output, image, { mode: 0o600 });
+        print({ sandboxId: id, output, bytes: image.length }, opts);
+    }));
+    withOutput(sandbox
+        .command('click')
+        .description('Click a desktop pixel coordinate')
+        .argument('<id>', 'sandbox id')
+        .argument('<x>', 'horizontal pixel coordinate', parseCoordinate)
+        .argument('<y>', 'vertical pixel coordinate', parseCoordinate)).action((id, x, y, opts) => run(async () => {
+        const result = await runCloudApi().post(`/run-cloud/sandboxes/${encodeURIComponent(id)}/computer`, { action: 'click', x, y });
+        print(result ?? { ok: true }, opts);
+    }));
+    withOutput(sandbox
+        .command('type')
+        .description('Type text into the sandbox desktop')
+        .argument('<id>', 'sandbox id')
+        .argument('<text>', 'text to type')).action((id, text, opts) => run(async () => {
+        const result = await runCloudApi().post(`/run-cloud/sandboxes/${encodeURIComponent(id)}/computer`, { action: 'type', text });
+        print(result ?? { ok: true }, opts);
+    }));
+    withOutput(sandbox
+        .command('key')
+        .description('Send an xdotool key chord to the sandbox desktop')
+        .argument('<id>', 'sandbox id')
+        .argument('<keys>', 'key or chord, e.g. ctrl+l')).action((id, keys, opts) => run(async () => {
+        const result = await runCloudApi().post(`/run-cloud/sandboxes/${encodeURIComponent(id)}/computer`, { action: 'key', keys });
+        print(result ?? { ok: true }, opts);
+    }));
+    withOutput(sandbox.command('rm').description('Destroy a sandbox').argument('<id>', 'sandbox id')).action((id, opts) => run(async () => {
+        await runCloudApi().delete(`/run-cloud/sandboxes/${encodeURIComponent(id)}`);
         if (!opts.json)
             console.log(`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 () => {
+        const body = {};
+        if (opts.label)
+            body.label = opts.label;
+        print(await runCloudApi().post(`/run-cloud/sandboxes/${encodeURIComponent(id)}/snapshots`, body), opts);
+    }));
+    withOutput(snapshot
+        .command('list')
+        .description('List snapshots')
+        .option('--sandbox <id>', 'only snapshots taken from this sandbox')).action((opts) => run(async () => {
+        const qs = opts.sandbox ? `?sandbox_id=${encodeURIComponent(opts.sandbox)}` : '';
+        const data = await runCloudApi().get(`/run-cloud/snapshots${qs}`);
+        print(data?.items ?? [], opts);
+    }));
+    withOutput(snapshot.command('rm').description('Delete a snapshot').argument('<id>', 'snapshot id')).action((id, opts) => run(async () => {
+        await runCloudApi().delete(`/run-cloud/snapshots/${encodeURIComponent(id)}`);
+        if (!opts.json)
+            console.log(`deleted ${id}`);
+    }));
+    withOutput(sandbox
+        .command('restore')
+        .description('Fork a new sandbox from a snapshot (warm start)')
+        .argument('<snapshot-id>', 'snapshot id to restore from')
+        .option('--name <name>', 'human-readable name for the new sandbox')
+        .option('--disk <gb>', 'root disk capacity in GiB (may only grow)', parseDiskGb)
+        .option('--region <region>', 'placement region')).action((snapshotId, opts) => run(async () => {
+        const body = {};
+        if (opts.name)
+            body.name = opts.name;
+        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);
+    }));
+    const box = program.command('box').description('Run a persistent sandbox at a stable public URL');
+    withOutput(box
+        .command('create')
+        .description('Create a persistent box or attach a hostname to an existing sandbox')
+        .argument('<name>', 'hostname prefix: <name>-box.run.cloud')
+        .option('--sandbox <id>', 'attach an existing sandbox created with --idle-pause 0')
+        .option('--port <port>', 'guest port to publish', parsePort, 3000)
+        .option('--image <ref>', 'base image for a new sandbox (runcloud/box or runcloud/box-agent)', 'runcloud/box')
+        .option('--region <region>', 'placement region for a new sandbox')
+        .option('--org <id>', 'billing and ownership organization for a new sandbox')
+        .option('--cpu <cores>', 'vCPU allocation for a new box', parseCpuCores, DEFAULT_BOX_CPU_CORES)
+        .option('--memory <mb>', 'memory allocation in MiB for a new box', parseMemoryMb, DEFAULT_BOX_MEMORY_MIB)
+        .option('--disk <gb>', 'root disk capacity in GiB', parseDiskGb)).action((name, opts) => run(async () => {
+        const api = runCloudApi();
+        let sandboxId = opts.sandbox;
+        if (!sandboxId) {
+            const sandboxBody = {
+                image: opts.image,
+                name,
+                idlePauseSeconds: 0,
+            };
+            if (opts.region)
+                sandboxBody.region = opts.region;
+            if (opts.org)
+                sandboxBody.orgId = opts.org;
+            sandboxBody.cpu = opts.cpu;
+            sandboxBody.memory = opts.memory;
+            if (opts.disk !== undefined)
+                sandboxBody.disk = opts.disk;
+            const created = await api.post('/run-cloud/sandboxes', sandboxBody);
+            sandboxId = typeof created?.id === 'string' ? created.id : undefined;
+            if (!sandboxId)
+                throw new Error('sandbox create response did not include an id');
+        }
+        print(await api.post('/run-cloud/boxes', {
+            sandboxId,
+            name,
+            port: opts.port,
+        }), opts);
+    }));
+    withOutput(box.command('list').description('List persistent boxes')).action((opts) => run(async () => {
+        const data = await runCloudApi().get('/run-cloud/boxes');
+        print(data?.items ?? [], opts);
+    }));
+    withOutput(box.command('get').description('Inspect a persistent box').argument('<id>', 'box id')).action((id, opts) => run(async () => {
+        print(await runCloudApi().get(`/run-cloud/boxes/${encodeURIComponent(id)}`), opts);
+    }));
+    withOutput(box
+        .command('port')
+        .description('Move a box hostname to another guest port')
+        .argument('<id>', 'box id')
+        .argument('<port>', 'guest port', parsePort)).action((id, port, opts) => run(async () => {
+        print(await runCloudApi().patch(`/run-cloud/boxes/${encodeURIComponent(id)}`, { port }), opts);
+    }));
+    withOutput(box
+        .command('route')
+        .description('Retry or reconcile a box hostname')
+        .argument('<id>', 'box id')).action((id, opts) => run(async () => {
+        print(await runCloudApi().post(`/run-cloud/boxes/${encodeURIComponent(id)}/route`), opts);
+    }));
+    withOutput(box
+        .command('rm')
+        .description('Remove a box hostname and destroy its sandbox')
+        .argument('<id>', 'box id')).action((id, opts) => run(async () => {
+        await runCloudApi().delete(`/run-cloud/boxes/${encodeURIComponent(id)}`);
+        if (!opts.json)
+            console.log(`destroyed box ${id}`);
+    }));
+    registerBoxAccessCommands(box);
 }

package/dist/config.js

@@ -41,10 +41,10 @@ export function loadCredentials() {
     const envApiUrl = isRunCloud()
         ? process.env.RUN_CLOUD_API_URL
         : process.env.NEWLY_API_URL;
-    if (envToken?.trim() && envApiUrl?.trim()) {
+    if (envToken?.trim() && (isRunCloud() || envApiUrl?.trim())) {
         return {
             token: envToken.trim(),
-            apiUrl: normalizeApiUrl(envApiUrl.trim()),
+            apiUrl: normalizeApiUrl(envApiUrl?.trim() || 'https://api.newly.app'),
             appUrl: isRunCloud()
                 ? process.env.RUN_CLOUD_APP_URL ?? 'https://run.cloud'
                 : process.env.NEWLY_APP_URL ?? 'https://newly.app',

package/examples/eight-device-mosaic/README.md

@@ -12,7 +12,7 @@ interrupted local process.
 - `runcloud` 0.1.3 or newer: `npm install -g runcloud`
 - A simulator account authenticated either with `runcloud login` or with both
   `RUN_CLOUD_API_KEY` and `RUN_CLOUD_API_URL`
-- run.cloud simulator access, capacity, and enough balance for eight sessions
+- run.cloud simulator access, capacity, and enough organization credit for eight sessions
 
 The local viewer binds only to `127.0.0.1`. Signed simulator URLs remain in the
 viewer process and are not printed to the terminal.

package/examples/eight-device-mosaic/demo.mjs

@@ -73,7 +73,7 @@ function escapeHtml(value) {
 
 function embedUrl(value) {
   const url = new URL(value);
-  url.searchParams.set('loadingGuard', '1');
+  url.searchParams.set('embed', '1');
   return url.toString();
 }
 

package/examples/eight-device-mosaic/verify.mjs

@@ -35,7 +35,8 @@ test('renders eight signed embeds without printing them into the viewer URL', as
   }));
   const html = mosaicViewerHtml(sessions, 601_000);
   assert.equal((html.match(/<iframe /g) || []).length, 8);
-  assert.match(html, /loadingGuard=1/);
+  assert.match(html, /embed=1/);
+  assert.doesNotMatch(html, /loadingGuard=1/);
   assert.match(html, /const deadline = 601000/);
 
   const viewer = await startMosaicViewer(sessions, 601_000);

package/examples/live-camera-relay/App.tsx

@@ -239,13 +239,13 @@ export default function App() {
     let stream: MediaStream;
     try {
       stream = await navigator.mediaDevices.getUserMedia({
-        video: { facingMode: 'user', width: { ideal: 1280 }, height: { ideal: 720 } },
+        video: true,
         audio: true,
       });
     } catch (withAudioError) {
       try {
         stream = await navigator.mediaDevices.getUserMedia({
-          video: { facingMode: 'user', width: { ideal: 1280 }, height: { ideal: 720 } },
+          video: true,
           audio: false,
         });
       } catch (videoError) {

package/examples/live-camera-relay/README.md

@@ -11,7 +11,7 @@ and sends the real WebRTC video stream to both receiver simulators.
 - `runcloud` 0.1.3 or newer: `npm install -g runcloud`
 - A simulator account authenticated either with `runcloud login` or with both
   `RUN_CLOUD_API_KEY` and `RUN_CLOUD_API_URL`
-- run.cloud simulator access, capacity, and enough balance for three sessions
+- run.cloud simulator access, capacity, and enough organization credit for three sessions
 - A browser with webcam permission
 
 The local viewer binds only to `127.0.0.1`. Signed simulator URLs and camera

package/examples/live-camera-relay/demo.mjs

@@ -86,7 +86,7 @@ function scriptData(value) {
 
 function embedUrl(value) {
   const url = new URL(value);
-  url.searchParams.set('loadingGuard', '1');
+  url.searchParams.set('embed', '1');
   return url.toString();
 }
 

package/examples/live-camera-relay/verify.mjs

@@ -67,6 +67,8 @@ test('renders three signed embeds while keeping credentials out of the local URL
   const demoSessions = sessions();
   const html = cameraViewerHtml(demoSessions, 60, 'room-12345678', 1_000);
   assert.equal((html.match(/<iframe /g) || []).length, 3);
+  assert.match(html, /embed=1/);
+  assert.doesNotMatch(html, /loadingGuard=1/);
   assert.match(html, /Connect webcam/);
   assert.match(html, /com\.apple\.mobilesafari/);
   assert.match(html, /audio: false/);