runcloud 0.1.9 → 0.1.11

package/README.md

@@ -16,12 +16,15 @@ 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 login   # sign in with email, Google, or GitHub; stores a token in ~/.run-cloud/credentials
+runcloud logout  # delete the stored credential
 runcloud account        # show your entitlement and metered balance
 ```
 
+Email signs you in without leaving the terminal. Google and GitHub open a browser and
+show a short code to confirm, so login works over SSH and on headless machines too —
+pick with `--email`, `--google`, or `--github` to skip the prompt.
+
 The token expires — re-run `runcloud login` when a command reports you're logged out.
 
 ## Remote simulators
@@ -83,6 +86,31 @@ 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.
 
+### Persistence and a public hostname
+
+A sandbox pauses when idle by default. Turn persistence on with `--persistent`,
+and publish a guest port at a stable `<name>-box.run.cloud` hostname with
+`--expose`:
+
+```bash
+runcloud sandbox create --name my-project --persistent      # never pauses
+runcloud sandbox create --name my-project --expose 3000     # persistent + https://my-project-box.run.cloud
+runcloud sandbox expose <id> --port 8080                    # expose later, or move the published port
+runcloud sandbox get <id>                                   # inspect, including the hostname
+```
+
+Exposed sandboxes support SSH, file transfer, VS Code, and custom domains:
+
+```bash
+runcloud sandbox ssh my-project                  # shell over authenticated SSH (no public port 22)
+runcloud sandbox cp my-project ./f :/workspace/f # scp; prefix the remote path with :
+runcloud sandbox code my-project                 # VS Code Remote SSH
+runcloud sandbox domain add my-project app.example.com
+```
+
+`runcloud box …` from earlier releases keeps working as a deprecated alias for
+these commands.
+
 ### 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:

package/dist/commands/boxAccess.js

@@ -5,6 +5,9 @@ import { join } from 'node:path';
 import WebSocket, { createWebSocketStream } from 'ws';
 import { ApiClient, friendlyApiError } from '../api.js';
 import { requireCredentials } from '../config.js';
+export function noteDeprecated(oldCommand, replacement) {
+    process.stderr.write(`runcloud: '${oldCommand}' is deprecated — use '${replacement}'\n`);
+}
 function api() {
     const credentials = requireCredentials();
     return new ApiClient(credentials.apiUrl, credentials.token);
@@ -13,10 +16,12 @@ 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.sandboxId === reference ||
         item.name === reference ||
         item.hostname === reference);
-    if (!box)
-        throw new Error(`Box not found: ${reference}`);
+    if (!box) {
+        throw new Error(`No exposed sandbox matches ${reference} — publish a hostname first: runcloud sandbox expose <id>`);
+    }
     return box;
 }
 function sshHome() {
@@ -75,7 +80,7 @@ function writeSshConfig(box, privateKey) {
         '  IdentitiesOnly yes',
         '  StrictHostKeyChecking accept-new',
         `  UserKnownHostsFile "${join(sshHome(), 'known_hosts')}"`,
-        `  ProxyCommand runcloud box proxy ${box.id}`,
+        `  ProxyCommand runcloud sandbox proxy ${box.id}`,
         end,
     ].join('\n');
     const pattern = new RegExp(`${start.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${end.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\n?`, 'g');
@@ -114,19 +119,27 @@ function openUrl(url) {
         return exec('cmd', ['/c', 'start', '', url]);
     return exec('xdg-open', [url]);
 }
-export function registerBoxAccessCommands(box) {
-    box
+const REFERENCE_HELP = 'sandbox id, box id, name, or hostname';
+export function registerAccessCommands(parent, opts = {}) {
+    const note = (verb) => {
+        if (opts.deprecated)
+            noteDeprecated(`box ${verb}`, `sandbox ${verb}`);
+    };
+    parent
         .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
+        .description('Install a dedicated key and write this host to ~/.ssh/config')
+        .argument('<sandbox>', REFERENCE_HELP)
+        .action((reference) => {
+        note('setup-ssh');
+        return action(async () => {
+            const configured = await setupSsh(reference);
+            console.log(`SSH configured: ssh ${configured.alias}`);
+        });
+    });
+    parent
         .command('proxy', { hidden: true })
         .description('Authenticated WebSocket transport used by SSH ProxyCommand')
-        .argument('<box>', 'box id, name, or hostname')
+        .argument('<sandbox>', REFERENCE_HELP)
         .action((reference) => action(async () => {
         const client = api();
         const resolved = await resolveBox(client, reference);
@@ -145,102 +158,127 @@ export function registerBoxAccessCommands(box) {
             socket.once('error', reject);
         });
     }));
-    box
+    parent
         .command('ssh')
-        .description('Open a shell in a box')
-        .argument('<box>', 'box id, name, or hostname')
+        .description('Open a shell in an exposed sandbox')
+        .argument('<sandbox>', REFERENCE_HELP)
         .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
+        .action((reference, command) => {
+        note('ssh');
+        return action(async () => {
+            const configured = await setupSsh(reference);
+            const code = await exec('ssh', [configured.alias, ...command]);
+            if (code !== 0)
+                process.exitCode = code;
+        });
+    });
+    parent
         .command('cp')
         .description('Copy files with scp; prefix the remote path with a colon')
-        .argument('<box>', 'box id, name, or hostname')
+        .argument('<sandbox>', REFERENCE_HELP)
         .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
+        .action((reference, source, destination, cmdOpts) => {
+        note('cp');
+        return 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 = [
+                ...(cmdOpts.recursive ? ['-r'] : []),
+                '--',
+                remote(source),
+                remote(destination),
+            ];
+            const code = await exec('scp', args);
+            if (code !== 0)
+                process.exitCode = code;
+        });
+    });
+    parent
         .command('code')
-        .description('Open a box in VS Code Remote SSH')
-        .argument('<box>', 'box id, name, or hostname')
+        .description('Open an exposed sandbox in VS Code Remote SSH')
+        .argument('<sandbox>', REFERENCE_HELP)
         .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');
+        .action((reference, path, cmdOpts) => {
+        note('code');
+        return 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 (cmdOpts.open === false)
+                console.log(url);
+            else
+                await openUrl(url);
+        });
+    });
+    const domain = parent.command('domain').description('Manage custom domains');
+    const domainNote = (verb) => {
+        if (opts.deprecated)
+            noteDeprecated(`box domain ${verb}`, `sandbox domain ${verb}`);
+    };
     domain
         .command('add')
-        .argument('<box>', 'box id, name, or hostname')
+        .argument('<sandbox>', REFERENCE_HELP)
         .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);
-    }));
+        .action((reference, hostname, cmdOpts) => {
+        domainNote('add');
+        return action(async () => {
+            const client = api();
+            const resolved = await resolveBox(client, reference);
+            output(await client.post(`/run-cloud/boxes/${encodeURIComponent(resolved.id)}/domains`, {
+                hostname,
+            }), cmdOpts);
+        });
+    });
     domain
         .command('list')
-        .argument('<box>', 'box id, name, or hostname')
+        .argument('<sandbox>', REFERENCE_HELP)
         .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);
-    }));
+        .action((reference, cmdOpts) => {
+        domainNote('list');
+        return 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 (cmdOpts.json)
+                console.log(JSON.stringify(items, null, 2));
+            else
+                for (const item of items)
+                    output(item, cmdOpts);
+        });
+    });
     domain
         .command('status')
-        .argument('<box>', 'box id, name, or hostname')
-        .argument('<domain-id>', 'domain id from `box domain list`')
+        .argument('<sandbox>', REFERENCE_HELP)
+        .argument('<domain-id>', 'domain id from `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);
-    }));
+        .action((reference, domainId, cmdOpts) => {
+        domainNote('status');
+        return 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`), cmdOpts);
+        });
+    });
     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}`);
-    }));
+        .argument('<sandbox>', REFERENCE_HELP)
+        .argument('<domain-id>', 'domain id from `domain list`')
+        .action((reference, domainId) => {
+        domainNote('rm');
+        return 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

@@ -3,7 +3,7 @@ import crypto from 'node:crypto';
 import { hostname } from 'node:os';
 import { spawn } from 'node:child_process';
 import { ApiClient, ApiError } from '../api.js';
-import { clearCredentials, credentialsDisplayPath, normalizeApiUrl, saveCredentials } from '../config.js';
+import { clearCredentials, credentialsDisplayPath, loadCredentials, normalizeApiUrl, saveCredentials, } from '../config.js';
 import { acquirePromptIO, ask, PromptAbortedError, select, } from '../prompt.js';
 import { AuthError, createApiKey, fetchProviders, isValidEmail, isValidOtp, normalizeOtp, sendEmailCode, verifyEmailCode, } from '../runCloudAuth.js';
 const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
@@ -114,7 +114,7 @@ export async function startCallbackServer(state, appOrigin, timeoutMs) {
         },
     };
 }
-function openBrowser(url) {
+export function openBrowser(url) {
     const [cmd, args] = process.platform === 'darwin'
         ? ['open', [url]]
         : process.platform === 'win32'
@@ -201,6 +201,20 @@ export async function verifyRunCloudCredential(apiUrl, token) {
             `(${e instanceof Error ? e.message : String(e)}). Saving it anyway.`);
     }
 }
+export async function revokeRunCloudCredential(apiUrl, token) {
+    try {
+        await new ApiClient(normalizeApiUrl(apiUrl), token).delete('/run-cloud/api-keys/self');
+        return 'Credential revoked.';
+    }
+    catch (e) {
+        if (e instanceof ApiError && (e.status === 401 || e.status === 403)) {
+            return 'Credential was already invalid.';
+        }
+        return (`Warning: could not reach ${apiUrl} to revoke this credential ` +
+            `(${e instanceof Error ? e.message : String(e)}). It may still be valid — ` +
+            'revoke it from the run.cloud dashboard.');
+    }
+}
 export function registerLogin(program) {
     const isRunCloud = program.name() === 'runcloud';
     const defaultAppUrl = isRunCloud
@@ -212,7 +226,7 @@ export function registerLogin(program) {
         ? 'Log in with your run.cloud account: email, Google, or GitHub'
         : 'Log in with your 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('--manual', 'newly skin only: 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)')
         .option('--token <token>', 'explicit credential token (skips browser; use with --api-url)')
         .option('--expires-in <seconds>', 'session lifetime when using --token (default 7 days)', (v) => Number(v), 604800)
@@ -251,19 +265,12 @@ export function registerLogin(program) {
                 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);
-                }
+            if (opts.manual && !isRunCloud) {
                 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,
@@ -295,6 +302,7 @@ export function registerLogin(program) {
                             apiUrl: authApiUrl,
                             appUrl: opts.appUrl,
                             expiresAt: Number.MAX_SAFE_INTEGER,
+                            revocable: true,
                         });
                         console.log(`\n  Signed in as ${email}`);
                         console.log(`  Credential saved to ${credentialsDisplayPath()}\n`);
@@ -310,6 +318,29 @@ export function registerLogin(program) {
                 if (method === 'google' || method === 'github')
                     socialProvider = method;
             }
+            if (isRunCloud) {
+                if (opts.manual) {
+                    console.log('Note: --manual is no longer needed for run.cloud — `runcloud login` works over SSH and headless via device flow.');
+                }
+                const apiUrl = opts.apiUrl ?? process.env.RUN_CLOUD_API_URL ?? DEFAULT_RUN_CLOUD_API_URL;
+                const { runDeviceLogin } = await import('../deviceLogin.js');
+                const payload = await runDeviceLogin({
+                    apiUrl,
+                    appUrl: opts.appUrl,
+                    provider: socialProvider,
+                    openBrowser,
+                });
+                await verifyRunCloudCredential(payload.apiUrl, payload.token);
+                saveCredentials({
+                    token: payload.token,
+                    apiUrl: payload.apiUrl,
+                    appUrl: opts.appUrl,
+                    expiresAt: Math.floor(Date.now() / 1000) + payload.expiresIn,
+                    revocable: true,
+                });
+                console.log(`Logged in. Credentials saved to ${credentialsDisplayPath()}`);
+                return;
+            }
             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);
@@ -345,8 +376,14 @@ export function registerLogin(program) {
     });
     program
         .command('logout')
-        .description('Delete the stored CLI credential')
-        .action(() => {
+        .description(isRunCloud
+        ? 'Revoke this machine’s credential and delete it locally'
+        : 'Delete the stored CLI credential')
+        .action(async () => {
+        const creds = loadCredentials();
+        if (isRunCloud && creds?.revocable) {
+            console.log(await revokeRunCloudCredential(creds.apiUrl, creds.token));
+        }
         clearCredentials();
         console.log('Logged out.');
     });

package/dist/commands/sandbox.js

@@ -2,10 +2,10 @@ 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 { ApiClient, ApiError, friendlyApiError } from '../api.js';
 import { requireCredentials } from '../config.js';
 import { runSandboxShell } from '../shellSession.js';
-import { registerBoxAccessCommands } from './boxAccess.js';
+import { noteDeprecated, registerAccessCommands } from './boxAccess.js';
 const MAX_SANDBOX_DISK_GIB = 2048;
 const DEFAULT_BOX_CPU_CORES = 2;
 const DEFAULT_BOX_MEMORY_MIB = 24 * 1024;
@@ -98,40 +98,126 @@ export function openBrowserUrl(url, platform = process.platform) {
     }
     execFileSync('xdg-open', [url], { stdio: 'ignore' });
 }
+async function findBoxForSandbox(api, sandboxId) {
+    const data = await api.get('/run-cloud/boxes');
+    return (data?.items ?? []).find((box) => box.sandboxId === sandboxId);
+}
+function attachHostname(api, sandboxId, name, port) {
+    return api.post('/run-cloud/boxes', { sandboxId, name, port });
+}
 export function registerSandbox(program) {
     const sandbox = program.command('sandbox').description('Spawn and control microVM sandboxes');
     withOutput(sandbox
         .command('create')
         .description('Spawn a microVM sandbox')
-        .option('--image <ref>', 'base image', 'runcloud/agent-base')
+        .option('--image <ref>', 'base image (default runcloud/agent-base, or runcloud/box with --expose)')
         .option('--region <region>', 'placement region')
-        .option('--name <name>', 'human-readable name')
+        .option('--name <name>', 'human-readable name; with --expose, the hostname prefix <name>-box.run.cloud')
         .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 };
+        .option('--idle-pause <seconds>', 'pause after inactivity; 0 keeps it running', parseIdlePauseSeconds)
+        .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)).action((opts) => run(async () => {
+        const exposed = opts.expose !== undefined;
+        if (exposed && !opts.name) {
+            throw new Error('--expose needs --name <name>, the hostname prefix for <name>-box.run.cloud');
+        }
+        if ((exposed || opts.persistent) && opts.idlePause !== undefined && opts.idlePause !== 0) {
+            throw new Error('--persistent and --expose keep the sandbox running; drop the non-zero --idle-pause');
+        }
+        const body = {
+            image: opts.image ?? (exposed ? 'runcloud/box' : 'runcloud/agent-base'),
+        };
         if (opts.name)
             body.name = opts.name;
         if (opts.region)
             body.region = opts.region;
         if (opts.org)
             body.orgId = opts.org;
-        if (opts.cpu !== undefined)
-            body.cpu = opts.cpu;
-        if (opts.memory !== undefined)
-            body.memory = opts.memory;
+        const cpu = opts.cpu ?? (exposed ? DEFAULT_BOX_CPU_CORES : undefined);
+        const memory = opts.memory ?? (exposed ? DEFAULT_BOX_MEMORY_MIB : undefined);
+        if (cpu !== undefined)
+            body.cpu = cpu;
+        if (memory !== undefined)
+            body.memory = memory;
         if (opts.disk !== undefined)
             body.disk = opts.disk;
-        if (opts.idlePause !== undefined)
+        if (exposed || opts.persistent)
+            body.idlePauseSeconds = 0;
+        else if (opts.idlePause !== undefined)
             body.idlePauseSeconds = opts.idlePause;
-        print(await runCloudApi().post('/run-cloud/sandboxes', body), opts);
+        const api = runCloudApi();
+        const created = await api.post('/run-cloud/sandboxes', body);
+        if (!exposed) {
+            print(created, opts);
+            return;
+        }
+        if (typeof created?.id !== 'string')
+            throw new Error('sandbox create response did not include an id');
+        const box = await attachHostname(api, created.id, opts.name, opts.expose);
+        print({ ...created, box }, opts);
     }));
     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 runCloudApi().get(`/run-cloud/sandboxes${qs}`);
-        print(data?.items ?? [], opts);
+        const api = runCloudApi();
+        const [data, boxes] = await Promise.all([
+            api.get(`/run-cloud/sandboxes${qs}`),
+            api.get('/run-cloud/boxes'),
+        ]);
+        const bySandbox = new Map((boxes?.items ?? []).map((box) => [box.sandboxId, box]));
+        const items = (data?.items ?? []).map((item) => {
+            const box = bySandbox.get(item.id);
+            return box ? { ...item, hostname: box.hostname, exposedPort: box.port } : item;
+        });
+        print(items, opts);
+    }));
+    withOutput(sandbox
+        .command('get')
+        .description('Inspect a sandbox, including its public hostname when exposed')
+        .argument('<id>', 'sandbox id')).action((id, opts) => run(async () => {
+        const api = runCloudApi();
+        const [record, box] = await Promise.all([
+            api.get(`/run-cloud/sandboxes/${encodeURIComponent(id)}`),
+            findBoxForSandbox(api, id),
+        ]);
+        print(box ? { ...record, box } : record, opts);
+    }));
+    withOutput(sandbox
+        .command('expose')
+        .description('Publish a sandbox guest port at a stable hostname, or change the published port')
+        .argument('<id>', 'sandbox id')
+        .option('--port <port>', 'guest port to publish (default 3000)', parsePort)
+        .option('--name <name>', 'hostname prefix for a first exposure: <name>-box.run.cloud (defaults to the sandbox name)')
+        .option('--reconcile', 'retry or reconcile hostname routing', false)).action((id, opts) => run(async () => {
+        const api = runCloudApi();
+        const existing = await findBoxForSandbox(api, id);
+        if (!existing) {
+            if (opts.reconcile)
+                throw new Error(`sandbox ${id} has no hostname to reconcile`);
+            let name = opts.name;
+            if (!name) {
+                const record = await api.get(`/run-cloud/sandboxes/${encodeURIComponent(id)}`);
+                name = typeof record?.name === 'string' && record.name ? record.name : undefined;
+            }
+            if (!name)
+                throw new Error('this sandbox has no name; pass --name <name> to mint <name>-box.run.cloud');
+            print(await attachHostname(api, id, name, opts.port ?? 3000), opts);
+            return;
+        }
+        if (opts.name && opts.name !== existing.name) {
+            throw new Error(`hostname is fixed at ${existing.hostname}; run 'sandbox rm ${id}' and expose again to rename`);
+        }
+        if (opts.reconcile) {
+            print(await api.post(`/run-cloud/boxes/${encodeURIComponent(existing.id)}/route`), opts);
+            return;
+        }
+        if (opts.port !== undefined) {
+            print(await api.patch(`/run-cloud/boxes/${encodeURIComponent(existing.id)}`, { port: opts.port }), opts);
+            return;
+        }
+        print(existing, opts);
     }));
     withOutput(sandbox
         .command('exec')
@@ -249,8 +335,22 @@ export function registerSandbox(program) {
         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)}`);
+    withOutput(sandbox
+        .command('rm')
+        .description('Destroy a sandbox, along with its public hostname when exposed')
+        .argument('<id>', 'sandbox id')).action((id, opts) => run(async () => {
+        const api = runCloudApi();
+        try {
+            await api.delete(`/run-cloud/sandboxes/${encodeURIComponent(id)}`);
+        }
+        catch (err) {
+            if (!(err instanceof ApiError) || err.status !== 409)
+                throw err;
+            const box = await findBoxForSandbox(api, id);
+            if (!box)
+                throw err;
+            await api.delete(`/run-cloud/boxes/${encodeURIComponent(box.id)}`);
+        }
         if (!opts.json)
             console.log(`destroyed ${id}`);
     }));
@@ -294,10 +394,13 @@ export function registerSandbox(program) {
             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');
+    registerAccessCommands(sandbox);
+    const box = program
+        .command('box')
+        .description('Deprecated: a box is a sandbox with --persistent and --expose — use `runcloud sandbox`');
     withOutput(box
         .command('create')
-        .description('Create a persistent box or attach a hostname to an existing sandbox')
+        .description('Deprecated: use `sandbox create --expose <port> --name <name>`')
         .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)
@@ -306,61 +409,77 @@ export function registerSandbox(program) {
         .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);
-    }));
+        .option('--disk <gb>', 'root disk capacity in GiB', parseDiskGb)).action((name, opts) => {
+        noteDeprecated('box create', opts.sandbox
+            ? `sandbox expose ${opts.sandbox} --name ${name}`
+            : `sandbox create --expose ${opts.port} --name ${name}`);
+        return 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 attachHostname(api, sandboxId, name, opts.port), opts);
+        });
+    });
+    withOutput(box.command('list').description('Deprecated: use `sandbox list`')).action((opts) => {
+        noteDeprecated('box list', 'sandbox list');
+        return run(async () => {
+            const data = await runCloudApi().get('/run-cloud/boxes');
+            print(data?.items ?? [], opts);
+        });
+    });
+    withOutput(box.command('get').description('Deprecated: use `sandbox get <sandbox-id>`').argument('<id>', 'box id')).action((id, opts) => {
+        noteDeprecated('box get', 'sandbox get <sandbox-id>');
+        return 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')
+        .description('Deprecated: use `sandbox expose <sandbox-id> --port <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);
-    }));
+        .argument('<port>', 'guest port', parsePort)).action((id, port, opts) => {
+        noteDeprecated('box port', `sandbox expose <sandbox-id> --port ${port}`);
+        return 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);
-    }));
+        .description('Deprecated: use `sandbox expose <sandbox-id> --reconcile`')
+        .argument('<id>', 'box id')).action((id, opts) => {
+        noteDeprecated('box route', 'sandbox expose <sandbox-id> --reconcile');
+        return 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);
+        .description('Deprecated: use `sandbox rm <sandbox-id>`')
+        .argument('<id>', 'box id')).action((id, opts) => {
+        noteDeprecated('box rm', 'sandbox rm <sandbox-id>');
+        return run(async () => {
+            await runCloudApi().delete(`/run-cloud/boxes/${encodeURIComponent(id)}`);
+            if (!opts.json)
+                console.log(`destroyed box ${id}`);
+        });
+    });
+    registerAccessCommands(box, { deprecated: true });
 }

package/dist/deviceLogin.js

@@ -0,0 +1,48 @@
+import { normalizeApiUrl } from "./config.js";
+export async function runDeviceLogin(deps) {
+    const fetchFn = deps.fetchFn ?? fetch;
+    const log = deps.log ?? ((m) => console.log(m));
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = deps.now ?? (() => Date.now());
+    const base = normalizeApiUrl(deps.apiUrl);
+    const startRes = await fetchFn(`${base}/run-cloud/cli-auth/device`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+    });
+    if (!startRes.ok)
+        throw new Error(`Could not start login (${startRes.status}).`);
+    const start = (await startRes.json());
+    log(`\nTo authorize this terminal, confirm the code below in your browser:\n\n    ${start.user_code}\n`);
+    log(`Opening ${start.verification_uri} … (if it doesn't open, go there and enter the code)\n`);
+    const approvalUrl = new URL(start.verification_uri_complete);
+    if (deps.provider)
+        approvalUrl.searchParams.set("provider", deps.provider);
+    deps.openBrowser?.(approvalUrl.toString());
+    let intervalMs = Math.max(0, start.interval) * 1000;
+    const deadline = now() + start.expires_in * 1000;
+    for (;;) {
+        if (now() >= deadline)
+            throw new Error("Login timed out. Run `runcloud login` again.");
+        await sleep(intervalMs);
+        const res = await fetchFn(`${base}/run-cloud/cli-auth/token`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ device_code: start.device_code }),
+        });
+        if (res.ok) {
+            const body = (await res.json());
+            return { token: body.token, apiUrl: body.apiUrl, expiresIn: body.expiresIn };
+        }
+        const { error } = (await res.json().catch(() => ({ error: "unknown" })));
+        if (error === "authorization_pending")
+            continue;
+        if (error === "slow_down") {
+            intervalMs += 5000;
+            continue;
+        }
+        if (error === "access_denied")
+            throw new Error("Authorization was denied. Run `runcloud login` again.");
+        throw new Error("The login code expired. Run `runcloud login` again.");
+    }
+}

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = '0.1.9';
+export const CLI_VERSION = '0.1.11';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcloud",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Create and control run.cloud remote mobile simulators and cloud sandboxes",
   "license": "UNLICENSED",
   "type": "module",