runcloud 0.1.6 → 0.1.8

package/README.md

@@ -0,0 +1,135 @@
+# runcloud
+
+Create and control **remote mobile simulators** and **cloud sandboxes** from your terminal.
+
+- **Simulators** — boot real iOS simulators and Android emulators in the cloud, install your app, open deep links, and tunnel a local dev server into them.
+- **Sandboxes** — start a fresh, isolated Linux environment in seconds, run commands in it, snapshot a ready setup, and restore it later as a warm start.
+
+## Install
+
+```bash
+npm i -g runcloud
+```
+
+Installs the `runcloud` binary. Requires **Node ≥ 20**.
+
+## Log in
+
+```bash
+runcloud login          # authenticate in the browser; stores a token in ~/.run-cloud/credentials
+runcloud login --manual # paste the credential instead of using the browser callback
+runcloud logout         # delete the stored credential
+runcloud account        # show your entitlement and metered balance
+```
+
+The token expires — re-run `runcloud login` when a command reports you're logged out.
+
+## Remote simulators
+
+```bash
+# iOS
+runcloud ios create --model iphone --install ./MyApp.app   # boot a simulator and install an app
+runcloud ios list                                          # list active sessions
+runcloud ios get <id>                                      # inspect a session (viewer URL, status)
+runcloud ios open-url myapp://path --id <id>               # open a URL or deep link
+runcloud ios delete <id>                                   # release the session
+
+# Android works the same under `runcloud android …`
+runcloud android create --model pixel
+```
+
+Useful `create` flags: `--region`, `--display-name`, `--inactivity-timeout 3m`, `--hard-timeout 1h`, `--rm` (release when the command exits), `--json`.
+
+### Tunnel a local dev server into a simulator
+
+```bash
+runcloud tunnel <id> --service metro   # expose your local Metro/dev server to the remote iOS session
+runcloud tunnel-status
+```
+
+## Sandboxes
+
+```bash
+runcloud sandbox create                          # start a sandbox (default image: runcloud/agent-base)
+runcloud sandbox create --cpu 0.5 --memory 1024  # allocate CPU cores and memory in MiB
+runcloud sandbox create --disk 80                # request an 80 GiB root filesystem
+runcloud sandbox exec <id> npm run build         # run a command inside it
+runcloud sandbox logs <id> -n 200                # tail its logs
+runcloud sandbox list
+runcloud sandbox rm <id>                          # destroy it
+```
+
+### Browser desktops and computer use
+
+Create a desktop sandbox, then open its short-lived signed noVNC URL:
+
+```bash
+SANDBOX_ID=$(runcloud sandbox create --image runcloud/desktop --json | jq -r '.id')
+
+runcloud sandbox desktop "$SANDBOX_ID"               # open the desktop in a browser
+runcloud sandbox desktop "$SANDBOX_ID" --url         # print the signed URL
+runcloud sandbox desktop "$SANDBOX_ID" --view-only   # open without keyboard or pointer input
+```
+
+Agents can capture and control the same desktop:
+
+```bash
+runcloud sandbox screenshot "$SANDBOX_ID" --output screen.png
+runcloud sandbox click "$SANDBOX_ID" 420 300
+runcloud sandbox type "$SANDBOX_ID" "hello world"
+runcloud sandbox key "$SANDBOX_ID" "ctrl+l"
+```
+
+Treat a signed desktop URL as a secret. It grants temporary access to that
+desktop without asking the browser to send your CLI credential.
+
+### Snapshot warm-start
+
+Freeze a "repo + deps ready" sandbox, then fork a new one from it in a fraction of a second instead of re-cloning and re-installing:
+
+```bash
+runcloud sandbox snapshot create <id> --label warm   # snapshot a sandbox
+runcloud sandbox snapshot list --sandbox <id>
+runcloud sandbox restore <snapshot-id> --name fork   # fork a NEW sandbox from the snapshot
+runcloud sandbox snapshot rm <snapshot-id>
+```
+
+## Demos
+
+```bash
+runcloud demo run --open                         # run the default mosaic from any directory
+runcloud demo run live-camera-relay --open       # run the camera relay from any directory
+runcloud demo init eight-device-mosaic           # optionally scaffold a standalone project
+```
+
+Bundled demos: `eight-device-mosaic`, `live-camera-relay`.
+
+## Onboarding sample apps
+
+Download checksum-verified apps that are ready for the remote runtimes:
+
+```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
+```
+
+## AI coding agents
+
+```bash
+runcloud skills   # install run.cloud skills for AI coding agents
+```
+
+Every command accepts `--json` for scripting.
+
+## Credentials & environment
+
+- `~/.run-cloud/credentials` — your session token (mode `600`).
+
+| Env var | Effect |
+|---|---|
+| `RUN_CLOUD_API_TOKEN` / `RUN_CLOUD_API_KEY` | Use this token instead of the stored credential (CI / headless). |
+| `RUN_CLOUD_API_URL` | Override the control-plane API base URL. |
+| `RUN_CLOUD_APP_URL` | Override the web app URL used for browser login (default `https://run.cloud`). |

package/dist/api.js

@@ -1,10 +1,12 @@
 export class ApiError extends Error {
     status;
     detail;
-    constructor(status, detail) {
+    path;
+    constructor(status, detail, path) {
         super(`API ${status}: ${detail}`);
         this.status = status;
         this.detail = detail;
+        this.path = path;
     }
 }
 function parsedErrorDetail(body) {
@@ -38,7 +40,7 @@ export class ApiClient {
         });
         if (!res.ok) {
             const detail = parsedErrorDetail(await res.text());
-            throw new ApiError(res.status, detail);
+            throw new ApiError(res.status, detail, path);
         }
         const contentType = res.headers.get('content-type') ?? '';
         return contentType.includes('application/json') ? res.json() : res;
@@ -61,7 +63,7 @@ export class ApiClient {
         });
         if (!res.ok) {
             const detail = parsedErrorDetail(await res.text());
-            throw new ApiError(res.status, detail);
+            throw new ApiError(res.status, detail, path);
         }
         const contentType = res.headers.get('content-type') ?? '';
         return contentType.includes('application/json') ? res.json() : res;
@@ -83,7 +85,7 @@ export class ApiClient {
         });
         if (!res.ok) {
             const detail = parsedErrorDetail(await res.text());
-            throw new ApiError(res.status, detail);
+            throw new ApiError(res.status, detail, path);
         }
         const contentType_ = res.headers.get('content-type') ?? '';
         return contentType_.includes('application/json') ? res.json() : res;
@@ -98,7 +100,7 @@ export class ApiClient {
         });
         if (!res.ok) {
             const detail = parsedErrorDetail(await res.text());
-            throw new ApiError(res.status, detail);
+            throw new ApiError(res.status, detail, path);
         }
         const contentType = res.headers.get('content-type') ?? '';
         return contentType.includes('application/json') ? res.json() : res;
@@ -110,7 +112,7 @@ export class ApiClient {
         });
         if (!res.ok) {
             const detail = await res.text().catch(() => '');
-            throw new ApiError(res.status, detail || res.statusText);
+            throw new ApiError(res.status, detail || res.statusText, path);
         }
         return Buffer.from(await res.arrayBuffer());
     }
@@ -121,7 +123,7 @@ export class ApiClient {
         });
         if (!res.ok) {
             const detail = parsedErrorDetail(await res.text().catch(() => ''));
-            throw new ApiError(res.status, detail || res.statusText);
+            throw new ApiError(res.status, detail || res.statusText, path);
         }
         const decoder = new TextDecoder();
         for await (const chunk of res.body) {
@@ -168,8 +170,15 @@ function headline(err) {
         }
         if (err.status === 403)
             return err.detail ? `Forbidden: ${err.detail}` : 'Forbidden.';
-        if (err.status === 404)
-            return `Not found: ${err.detail}`;
+        if (err.status === 404) {
+            const sandboxMatch = err.path?.match(/^\/run-cloud\/sandboxes\/([^/]+)/);
+            if (sandboxMatch) {
+                return `Sandbox ID not found: ${decodeURIComponent(sandboxMatch[1])}.`;
+            }
+            if (!err.detail || /^not found$/i.test(err.detail.trim()))
+                return 'Resource not found.';
+            return err.detail;
+        }
         if (err.status === 409)
             return err.detail;
         if (err.status === 503)
@@ -179,5 +188,6 @@ function headline(err) {
     return networkError(err) ?? (err instanceof Error ? err.message : String(err));
 }
 export function friendlyApiError(err) {
-    return `${headline(err)}${detailSuffix(err)}`;
+    const message = headline(err);
+    return err instanceof ApiError ? message : `${message}${detailSuffix(err)}`;
 }

package/dist/commands/boxAccess.js

@@ -0,0 +1,246 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { homedir, hostname as localHostname } from 'node:os';
+import { join } from 'node:path';
+import WebSocket, { createWebSocketStream } from 'ws';
+import { ApiClient, friendlyApiError } from '../api.js';
+import { requireCredentials } from '../config.js';
+function api() {
+    const credentials = requireCredentials();
+    return new ApiClient(credentials.apiUrl, credentials.token);
+}
+async function resolveBox(client, reference) {
+    const response = await client.get('/run-cloud/boxes');
+    const boxes = (response?.items ?? []);
+    const box = boxes.find((item) => item.id === reference ||
+        item.name === reference ||
+        item.hostname === reference);
+    if (!box)
+        throw new Error(`Box not found: ${reference}`);
+    return box;
+}
+function sshHome() {
+    const base = process.env.RUN_CLOUD_HOME || join(homedir(), '.run-cloud');
+    return join(base, 'ssh');
+}
+function keyPath() {
+    return join(sshHome(), 'id_ed25519');
+}
+function exec(command, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: 'inherit' });
+        child.once('error', reject);
+        child.once('exit', (code, signal) => {
+            if (signal)
+                reject(new Error(`${command} exited on signal ${signal}`));
+            else
+                resolve(code ?? 1);
+        });
+    });
+}
+async function ensureSshKey(client, box) {
+    mkdirSync(sshHome(), { recursive: true, mode: 0o700 });
+    const privateKey = keyPath();
+    const publicKey = `${privateKey}.pub`;
+    if (!existsSync(privateKey) || !existsSync(publicKey)) {
+        const generated = spawnSync('ssh-keygen', ['-q', '-t', 'ed25519', '-N', '', '-C', `runcloud@${localHostname()}`, '-f', privateKey], { stdio: 'inherit' });
+        if (generated.error)
+            throw generated.error;
+        if (generated.status !== 0)
+            throw new Error(`ssh-keygen failed (${generated.status})`);
+    }
+    chmodSync(privateKey, 0o600);
+    await client.post(`/run-cloud/boxes/${encodeURIComponent(box.id)}/ssh-keys`, {
+        publicKey: readFileSync(publicKey, 'utf8').trim(),
+        label: `${localHostname()} (Run Cloud CLI)`,
+    });
+    return privateKey;
+}
+function sshAlias(box) {
+    return `runcloud-${box.name}`;
+}
+function writeSshConfig(box, privateKey) {
+    const sshDir = join(homedir(), '.ssh');
+    const configPath = join(sshDir, 'config');
+    mkdirSync(sshDir, { recursive: true, mode: 0o700 });
+    const current = existsSync(configPath) ? readFileSync(configPath, 'utf8') : '';
+    const start = `# BEGIN RUN CLOUD ${box.id}`;
+    const end = `# END RUN CLOUD ${box.id}`;
+    const block = [
+        start,
+        `Host ${sshAlias(box)}`,
+        `  HostName ${box.hostname}`,
+        '  User runcloud',
+        `  IdentityFile "${privateKey}"`,
+        '  IdentitiesOnly yes',
+        '  StrictHostKeyChecking accept-new',
+        `  UserKnownHostsFile "${join(sshHome(), 'known_hosts')}"`,
+        `  ProxyCommand runcloud box proxy ${box.id}`,
+        end,
+    ].join('\n');
+    const pattern = new RegExp(`${start.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${end.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\n?`, 'g');
+    const next = `${current.replace(pattern, '').trimEnd()}${current.trim() ? '\n\n' : ''}${block}\n`;
+    writeFileSync(configPath, next, { mode: 0o600 });
+    chmodSync(configPath, 0o600);
+    return sshAlias(box);
+}
+async function setupSsh(reference) {
+    const client = api();
+    const box = await resolveBox(client, reference);
+    const privateKey = await ensureSshKey(client, box);
+    return { box, alias: writeSshConfig(box, privateKey) };
+}
+function output(value, opts) {
+    if (opts.json)
+        console.log(JSON.stringify(value, null, 2));
+    else if (typeof value === 'string')
+        console.log(value);
+    else {
+        for (const [key, item] of Object.entries(value)) {
+            console.log(`${key}: ${typeof item === 'object' ? JSON.stringify(item) : String(item)}`);
+        }
+    }
+}
+function action(fn) {
+    return fn().catch((error) => {
+        console.error(friendlyApiError(error));
+        process.exitCode = 1;
+    });
+}
+function openUrl(url) {
+    if (process.platform === 'darwin')
+        return exec('open', [url]);
+    if (process.platform === 'win32')
+        return exec('cmd', ['/c', 'start', '', url]);
+    return exec('xdg-open', [url]);
+}
+export function registerBoxAccessCommands(box) {
+    box
+        .command('setup-ssh')
+        .description('Install a dedicated key and write this box to ~/.ssh/config')
+        .argument('<box>', 'box id, name, or hostname')
+        .action((reference) => action(async () => {
+        const configured = await setupSsh(reference);
+        console.log(`SSH configured: ssh ${configured.alias}`);
+    }));
+    box
+        .command('proxy', { hidden: true })
+        .description('Authenticated WebSocket transport used by SSH ProxyCommand')
+        .argument('<box>', 'box id, name, or hostname')
+        .action((reference) => action(async () => {
+        const client = api();
+        const resolved = await resolveBox(client, reference);
+        const access = (await client.post(`/run-cloud/boxes/${encodeURIComponent(resolved.id)}/access-tickets`, { purpose: 'ssh' }));
+        if (!access.websocketUrl)
+            throw new Error('SSH ticket response has no WebSocket URL');
+        const socket = new WebSocket(access.websocketUrl, {
+            headers: { 'x-run-cloud-access-ticket': access.ticket },
+        });
+        const stream = createWebSocketStream(socket, { encoding: undefined });
+        process.stdin.pipe(stream);
+        stream.pipe(process.stdout);
+        await new Promise((resolve, reject) => {
+            stream.once('close', resolve);
+            stream.once('error', reject);
+            socket.once('error', reject);
+        });
+    }));
+    box
+        .command('ssh')
+        .description('Open a shell in a box')
+        .argument('<box>', 'box id, name, or hostname')
+        .argument('[command...]', 'optional remote command')
+        .action((reference, command) => action(async () => {
+        const configured = await setupSsh(reference);
+        const code = await exec('ssh', [configured.alias, ...command]);
+        if (code !== 0)
+            process.exitCode = code;
+    }));
+    box
+        .command('cp')
+        .description('Copy files with scp; prefix the remote path with a colon')
+        .argument('<box>', 'box id, name, or hostname')
+        .argument('<source>', 'local path or :/remote/path')
+        .argument('<destination>', 'local path or :/remote/path')
+        .option('-r, --recursive', 'copy directories recursively', false)
+        .action((reference, source, destination, opts) => action(async () => {
+        if (source.startsWith(':') === destination.startsWith(':')) {
+            throw new Error('Exactly one path must be remote (prefix it with :)');
+        }
+        const configured = await setupSsh(reference);
+        const remote = (path) => path.startsWith(':') ? `${configured.alias}:${path.slice(1)}` : path;
+        const args = [
+            ...(opts.recursive ? ['-r'] : []),
+            '--',
+            remote(source),
+            remote(destination),
+        ];
+        const code = await exec('scp', args);
+        if (code !== 0)
+            process.exitCode = code;
+    }));
+    box
+        .command('code')
+        .description('Open a box in VS Code Remote SSH')
+        .argument('<box>', 'box id, name, or hostname')
+        .argument('[path]', 'remote folder', '/workspace')
+        .option('--no-open', 'print the VS Code URL without opening it')
+        .action((reference, path, opts) => action(async () => {
+        const configured = await setupSsh(reference);
+        const remotePath = path.startsWith('/') ? path : `/${path}`;
+        const url = `vscode://vscode-remote/ssh-remote+${encodeURIComponent(configured.alias)}` +
+            remotePath.split('/').map(encodeURIComponent).join('/');
+        if (opts.open === false)
+            console.log(url);
+        else
+            await openUrl(url);
+    }));
+    const domain = box.command('domain').description('Manage custom domains');
+    domain
+        .command('add')
+        .argument('<box>', 'box id, name, or hostname')
+        .argument('<hostname>', 'custom hostname')
+        .option('--json', 'output JSON', false)
+        .action((reference, hostname, opts) => action(async () => {
+        const client = api();
+        const resolved = await resolveBox(client, reference);
+        output(await client.post(`/run-cloud/boxes/${encodeURIComponent(resolved.id)}/domains`, {
+            hostname,
+        }), opts);
+    }));
+    domain
+        .command('list')
+        .argument('<box>', 'box id, name, or hostname')
+        .option('--json', 'output JSON', false)
+        .action((reference, opts) => action(async () => {
+        const client = api();
+        const resolved = await resolveBox(client, reference);
+        const response = await client.get(`/run-cloud/boxes/${encodeURIComponent(resolved.id)}/domains`);
+        const items = response?.items ?? [];
+        if (opts.json)
+            console.log(JSON.stringify(items, null, 2));
+        else
+            for (const item of items)
+                output(item, opts);
+    }));
+    domain
+        .command('status')
+        .argument('<box>', 'box id, name, or hostname')
+        .argument('<domain-id>', 'domain id from `box domain list`')
+        .option('--json', 'output JSON', false)
+        .action((reference, domainId, opts) => action(async () => {
+        const client = api();
+        const resolved = await resolveBox(client, reference);
+        output(await client.post(`/run-cloud/boxes/${encodeURIComponent(resolved.id)}/domains/${encodeURIComponent(domainId)}/refresh`), opts);
+    }));
+    domain
+        .command('rm')
+        .argument('<box>', 'box id, name, or hostname')
+        .argument('<domain-id>', 'domain id from `box domain list`')
+        .action((reference, domainId) => action(async () => {
+        const client = api();
+        const resolved = await resolveBox(client, reference);
+        await client.delete(`/run-cloud/boxes/${encodeURIComponent(resolved.id)}/domains/${encodeURIComponent(domainId)}`);
+        console.log(`removed custom domain ${domainId}`);
+    }));
+}

package/dist/commands/login.js

@@ -1,7 +1,8 @@
 import http from 'node:http';
 import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { clearCredentials, credentialsDisplayPath, saveCredentials } from '../config.js';
+import { ApiClient, ApiError } from '../api.js';
+import { clearCredentials, credentialsDisplayPath, normalizeApiUrl, saveCredentials } from '../config.js';
 const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
 export async function startCallbackServer(state, appOrigin, timeoutMs) {
     let resolvePayload;
@@ -10,7 +11,10 @@ export async function startCallbackServer(state, appOrigin, timeoutMs) {
         resolvePayload = resolve;
         rejectPayload = reject;
     });
-    const timer = setTimeout(() => rejectPayload(new Error(`Login timed out after ${timeoutMs / 1000}s`)), timeoutMs);
+    const timer = setTimeout(() => rejectPayload(new Error(`Login timed out after ${timeoutMs / 1000}s.\n` +
+        "If the browser said the local handoff was blocked, Chrome gates HTTPS→localhost behind a permission: " +
+        'click the icon at the left of the address bar, allow "access to apps on this device", ' +
+        'then run login again (or use --manual).')), timeoutMs);
     const corsHeaders = {
         'Access-Control-Allow-Origin': appOrigin,
         'Access-Control-Allow-Methods': 'POST, OPTIONS',
@@ -112,6 +116,19 @@ export function parseManualCredential(blob) {
     }
     return { token: c.token, expiresIn: c.expiresIn, apiUrl: c.apiUrl };
 }
+export async function verifyRunCloudCredential(apiUrl, token) {
+    try {
+        await new ApiClient(normalizeApiUrl(apiUrl), token).get('/run-cloud/account');
+    }
+    catch (e) {
+        if (e instanceof ApiError && (e.status === 401 || e.status === 403)) {
+            throw new Error(`${apiUrl} rejected this credential (${e.status}). Make sure you signed in to the account ` +
+                'you want the CLI to use, then run login again.');
+        }
+        console.warn(`Warning: could not verify the credential against ${apiUrl} ` +
+            `(${e instanceof Error ? e.message : String(e)}). Saving it anyway.`);
+    }
+}
 export function registerLogin(program) {
     const isRunCloud = program.name() === 'runcloud';
     const defaultAppUrl = isRunCloud
@@ -136,9 +153,6 @@ export function registerLogin(program) {
                 throw new Error('--api-url requires --token for headless login.');
             }
             if (hasToken) {
-                if (isRunCloud && !opts.token.startsWith('rc_live_')) {
-                    throw new Error('runcloud login requires a Better Auth API key beginning with rc_live_.');
-                }
                 const apiUrl = isRunCloud
                     ? opts.apiUrl ?? process.env.RUN_CLOUD_API_URL ?? 'https://api.newly.app'
                     : opts.apiUrl;
@@ -170,16 +184,13 @@ export function registerLogin(program) {
                 const blob = await rl.question('Paste the credential from the browser: ');
                 rl.close();
                 const parsed = parseManualCredential(blob);
-                if (isRunCloud && !parsed.token.startsWith('rc_live_')) {
-                    throw new Error('The browser did not return a Better Auth run.cloud API key.');
-                }
+                if (isRunCloud)
+                    await verifyRunCloudCredential(parsed.apiUrl, parsed.token);
                 saveCredentials({
                     token: parsed.token,
                     apiUrl: parsed.apiUrl,
                     appUrl: opts.appUrl,
-                    expiresAt: isRunCloud
-                        ? Number.MAX_SAFE_INTEGER
-                        : Math.floor(Date.now() / 1000) + parsed.expiresIn,
+                    expiresAt: Math.floor(Date.now() / 1000) + parsed.expiresIn,
                 });
                 console.log('Logged in.');
                 return;
@@ -193,16 +204,13 @@ export function registerLogin(program) {
             openBrowser(loginUrl);
             try {
                 const payload = await waitForToken();
-                if (isRunCloud && !payload.token.startsWith('rc_live_')) {
-                    throw new Error('The browser did not return a Better Auth run.cloud API key.');
-                }
+                if (isRunCloud)
+                    await verifyRunCloudCredential(payload.apiUrl, payload.token);
                 saveCredentials({
                     token: payload.token,
                     apiUrl: payload.apiUrl,
                     appUrl: opts.appUrl,
-                    expiresAt: isRunCloud
-                        ? Number.MAX_SAFE_INTEGER
-                        : Math.floor(Date.now() / 1000) + payload.expiresIn,
+                    expiresAt: Math.floor(Date.now() / 1000) + payload.expiresIn,
                 });
                 console.log(`Logged in. Credentials saved to ${credentialsDisplayPath()}`);
             }