runcloud 0.1.5 → 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,15 +1,18 @@
 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) {
     try {
-        const detail = JSON.parse(body).detail;
+        const parsed = JSON.parse(body);
+        const detail = parsed.detail ?? parsed.error ?? parsed.message;
         if (typeof detail === 'string')
             return detail;
         if (detail !== undefined)
@@ -37,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;
@@ -60,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;
@@ -82,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;
@@ -97,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;
@@ -109,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());
     }
@@ -120,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) {
@@ -161,12 +164,21 @@ function detailSuffix(err) {
 }
 function headline(err) {
     if (err instanceof ApiError) {
-        if (err.status === 401)
-            return 'Session expired or invalid — run `newly login`.';
+        if (err.status === 401) {
+            const command = (process.argv[1] ?? '').includes('run-cloud') ? 'runcloud login' : 'newly login';
+            return `Session expired or invalid — run \`${command}\`.`;
+        }
         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)
@@ -176,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,11 +11,15 @@ 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',
         'Access-Control-Allow-Headers': 'content-type',
+        'Access-Control-Allow-Private-Network': 'true',
     };
     const server = http.createServer((req, res) => {
         if (req.method === 'OPTIONS') {
@@ -37,6 +42,22 @@ export async function startCallbackServer(state, appOrigin, timeoutMs) {
                     res.end('state mismatch');
                     return;
                 }
+                if (typeof parsed.token !== 'string' ||
+                    parsed.token.length === 0 ||
+                    typeof parsed.expiresIn !== 'number' ||
+                    !Number.isFinite(parsed.expiresIn) ||
+                    parsed.expiresIn <= 0 ||
+                    typeof parsed.apiUrl !== 'string') {
+                    res.writeHead(400, corsHeaders);
+                    res.end('invalid credential payload');
+                    return;
+                }
+                const apiUrl = new URL(parsed.apiUrl);
+                if (!['http:', 'https:'].includes(apiUrl.protocol)) {
+                    res.writeHead(400, corsHeaders);
+                    res.end('invalid API URL');
+                    return;
+                }
                 res.writeHead(200, { ...corsHeaders, 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ ok: true }));
                 clearTimeout(timer);
@@ -74,6 +95,12 @@ function openBrowser(url) {
     });
     child.unref();
 }
+export function cliAuthUrl(appUrl, port, state) {
+    const url = new URL('/cli-auth', appUrl);
+    url.searchParams.set('port', String(port));
+    url.searchParams.set('state', state);
+    return url.toString();
+}
 export function parseManualCredential(blob) {
     let parsed;
     try {
@@ -89,13 +116,27 @@ 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 defaultAppUrl = program.name() === 'runcloud'
+    const isRunCloud = program.name() === 'runcloud';
+    const defaultAppUrl = isRunCloud
         ? process.env.RUN_CLOUD_APP_URL ?? 'https://run.cloud'
         : process.env.NEWLY_APP_URL ?? 'https://newly.app';
     program
         .command('login')
-        .description('Log in with your Newly account via the browser')
+        .description(`Log in with your ${isRunCloud ? 'run.cloud' : 'Newly'} account via the browser`)
         .option('--app-url <url>', 'product web app URL', defaultAppUrl)
         .option('--manual', 'paste the credential from the browser instead of using the local callback', false)
         .option('--api-url <url>', 'explicit API URL (skips browser; use with --token)')
@@ -105,31 +146,46 @@ export function registerLogin(program) {
         try {
             const hasApiUrl = typeof opts.apiUrl === 'string' && opts.apiUrl.length > 0;
             const hasToken = typeof opts.token === 'string' && opts.token.length > 0;
-            if (hasApiUrl !== hasToken) {
+            if (!isRunCloud && hasApiUrl !== hasToken) {
                 throw new Error('--api-url and --token must be provided together for headless login.');
             }
-            if (hasApiUrl && hasToken) {
+            if (isRunCloud && hasApiUrl && !hasToken) {
+                throw new Error('--api-url requires --token for headless login.');
+            }
+            if (hasToken) {
+                const apiUrl = isRunCloud
+                    ? opts.apiUrl ?? process.env.RUN_CLOUD_API_URL ?? 'https://api.newly.app'
+                    : opts.apiUrl;
                 try {
-                    new URL(opts.apiUrl);
+                    new URL(apiUrl);
                 }
                 catch {
-                    throw new Error(`--api-url is not a valid URL: ${opts.apiUrl}`);
+                    throw new Error(`--api-url is not a valid URL: ${apiUrl}`);
                 }
                 saveCredentials({
                     token: opts.token,
-                    apiUrl: opts.apiUrl,
+                    apiUrl,
                     appUrl: opts.appUrl,
-                    expiresAt: Math.floor(Date.now() / 1000) + opts.expiresIn,
+                    expiresAt: isRunCloud
+                        ? Number.MAX_SAFE_INTEGER
+                        : Math.floor(Date.now() / 1000) + opts.expiresIn,
                 });
-                console.log(`Logged in headlessly. Credentials written for API ${opts.apiUrl}.`);
+                console.log(`Logged in headlessly. Credentials written for API ${apiUrl}.`);
                 return;
             }
             if (opts.manual) {
+                if (isRunCloud) {
+                    const manualUrl = `${opts.appUrl.replace(/\/$/, '')}/cli-auth?manual=1`;
+                    console.log(`Opening your browser to authorize the CLI…\n  ${manualUrl}\n`);
+                    openBrowser(manualUrl);
+                }
                 const { createInterface } = await import('node:readline/promises');
                 const rl = createInterface({ input: process.stdin, output: process.stdout });
                 const blob = await rl.question('Paste the credential from the browser: ');
                 rl.close();
                 const parsed = parseManualCredential(blob);
+                if (isRunCloud)
+                    await verifyRunCloudCredential(parsed.apiUrl, parsed.token);
                 saveCredentials({
                     token: parsed.token,
                     apiUrl: parsed.apiUrl,
@@ -142,12 +198,14 @@ export function registerLogin(program) {
             const state = crypto.randomBytes(16).toString('hex');
             const appOrigin = new URL(opts.appUrl).origin;
             const { port, waitForToken, close } = await startCallbackServer(state, appOrigin, LOGIN_TIMEOUT_MS);
-            const loginUrl = `${opts.appUrl}/cli-auth?port=${port}&state=${state}`;
+            const loginUrl = cliAuthUrl(opts.appUrl, port, state);
             console.log(`Opening your browser to authorize the CLI…\n  ${loginUrl}\n`);
             console.log("If the browser doesn't open, paste the URL above into it manually.");
             openBrowser(loginUrl);
             try {
                 const payload = await waitForToken();
+                if (isRunCloud)
+                    await verifyRunCloudCredential(payload.apiUrl, payload.token);
                 saveCredentials({
                     token: payload.token,
                     apiUrl: payload.apiUrl,