runcloud 0.1.2 → 0.1.3

package/dist/commands/run-cloud.js

@@ -1,25 +1,81 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { basename, join, resolve } from 'node:path';
+import { Option } from 'commander';
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { ApiClient, friendlyApiError } from '../api.js';
 import { requireCredentials } from '../config.js';
-const RUN_CLOUD_SKILL = `---
+export const RUN_CLOUD_SKILL = `---
 name: run-cloud-ios-simulator
-description: Build, install, and inspect iOS apps with run.cloud remote simulator sessions.
-version: 0.1.0
+description: Configure and use run.cloud for agent sandboxes, provider-compatible migrations, and mobile simulator sessions.
+version: 0.4.0
 ---
 
-# run.cloud iOS Simulator
+# run.cloud Agent Runtime
 
-Use this skill when a user asks an agent to run, inspect, smoke test, or debug an iOS app in a remote simulator through run.cloud.
+Use this skill when a user asks an agent to adopt run.cloud, migrate an existing sandbox integration, or run, inspect, smoke test, or debug an iOS or Android app through run.cloud.
 
 ## Requirements
 
-- The user must be authenticated with \`runcloud login\`.
+- Read the API credential from \`RUN_CLOUD_API_KEY\`. Never print it, commit it, or write it into a skill file.
+- Use \`RUN_CLOUD_API_URL\` when set; otherwise use \`https://api.newly.app\`.
+- CLI simulator commands can use \`runcloud login\`; SDK and API usage should use \`RUN_CLOUD_API_KEY\`.
 - The account must have run.cloud access and a positive run.cloud balance.
-- App artifacts should be simulator-compatible builds. Device App Store IPAs may fail to install on iOS Simulator.
+- App artifacts must match the target platform. iOS sessions need simulator-compatible builds; Android sessions need Android-compatible artifacts such as APKs.
 
-## Workflow
+## Detect the Existing Sandbox Provider
+
+Before changing dependencies or imports, inspect package manifests, lockfiles, source imports, and provider-specific environment variable names. Check for these signals:
+
+| Provider | Common package/import signal | run.cloud compatibility entry point |
+| --- | --- | --- |
+| Modal | \`modal\` | \`run_cloud.compat.modal\` |
+| E2B | \`e2b\`, \`@e2b/code-interpreter\` | \`run_cloud.compat.e2b\` |
+| Blaxel | \`blaxel\` | \`run_cloud.compat.blaxel\` |
+| CodeSandbox | \`@codesandbox/sdk\` | \`@run-cloud/sdk/compat/codesandbox\` |
+| Vercel Sandbox | \`@vercel/sandbox\` | \`@run-cloud/sdk/compat/vercel\` |
+| Cloudflare Sandbox | \`@cloudflare/sandbox\` | \`@run-cloud/sdk/compat/cloudflare\` |
+| Fly Machines | \`@flydotio/machines\` | \`@run-cloud/sdk/compat/fly\` |
+| Daytona | \`daytona\` | \`run_cloud.compat.daytona\` |
+
+When a provider is detected:
+
+1. Preserve the existing provider-shaped API and change only the integration boundary.
+2. Use the matching compatibility entry point only after confirming its package resolves through the project's package manager or configured registry.
+3. Run the existing provider integration tests after the import change. Provider-specific images, networking, regions, and lifecycle options still require explicit validation.
+4. If more than one provider is present, map each call site independently and report the result. Do not choose one globally.
+
+When no provider is detected, prefer native \`runcloud\` CLI commands for supported operations. For TypeScript, \`@run-cloud/sdk\` is the native API-key SDK.
+
+## TypeScript SDK
+
+Install the SDK only when the project can resolve npm packages:
+
+\`\`\`bash
+npm install @run-cloud/sdk
+\`\`\`
+
+Use \`RUN_CLOUD_API_KEY\` for authentication:
+
+\`\`\`ts
+import { Client } from "@run-cloud/sdk";
+
+const cloud = new Client();
+const session = await cloud.simulators.create({
+  platform: "android",
+  displayName: "Agent smoke",
+  inactivityTimeout: "60s",
+});
+
+await cloud.simulators.openUrl(session.id, "myapp://settings", {
+  platform: session.platform,
+});
+await cloud.simulators.delete(session.id, {
+  platform: session.platform,
+});
+\`\`\`
+
+## iOS Simulator Workflow
 
 1. Check access with \`runcloud account --json\`.
 2. Create a simulator with \`runcloud ios create --install ./build/MyApp.tar.gz --json\`.
@@ -27,20 +83,41 @@ Use this skill when a user asks an agent to run, inspect, smoke test, or debug a
 4. Use \`runcloud ios open-url <url> --id <session-id>\` when a URL or deep link must be opened.
 5. Release the session with \`runcloud ios delete <session-id>\`.
 
+Use \`runcloud ios create --codec webrtc --json\` when the viewer must open directly on the WebRTC stream path. The response includes \`platform\`, \`codec\`, and \`stream\` fields. WebRTC is experimental; only use it when the environment enables experimental WebRTC.
+
+## Android Emulator Workflow
+
+1. Check access with \`runcloud account --json\`.
+2. Create an emulator with \`runcloud android create --install ./build/app-debug.apk --json\`.
+3. Save the returned session id and URL.
+4. Use \`runcloud android open-url <url> --id <session-id>\` when a URL or deep link must be opened.
+5. Release the session with \`runcloud android delete <session-id>\`.
+
+## Simulator Demos
+
+- Run \`runcloud demo run parallel-simulators --open\` to create three independent sessions.
+- Run \`runcloud demo run eight-device-mosaic --open\` to coordinate eight sessions in one 4x2 animated display.
+- Run \`runcloud demo run live-camera-relay --open\` to connect a webcam to one simulator camera and relay its WebRTC video to two receiver simulators.
+
+All demos release every session automatically. Their source is public at \`https://github.com/newly-app/run-cloud-examples\`. They require the existing \`runcloud login\` simulator credential in addition to the API key.
+
 ## Embedded Iframes
 
 - Use \`runcloud ios create --inactivity-timeout 60s --json\` when the embed should auto-close after user inactivity.
+- Use \`runcloud android create --inactivity-timeout 60s --json\` for Android emulator embeds with the same inactivity policy.
 - Omit \`--inactivity-timeout\` or pass \`none\` when the user needs a metered session without idle auto-close.
-- Iframes post \`ios-simulator:status\`, \`ios-simulator:auth-error\`, \`ios-simulator:session-ended\`, and \`ios-simulator:session-restart-requested\` to the parent window. Verify \`event.source\` before acting.
-- If \`ios-simulator:session-restart-requested\` arrives, create a fresh run.cloud session; do not reuse the ended iframe URL.
+- Iframes post simulator status, auth error, session ended, and restart request messages to the parent window. Verify \`event.source\` before acting.
+- If a session restart request arrives, create a fresh run.cloud session; do not reuse the ended iframe URL.
 
 ## Rules
 
 - Prefer \`--json\` for parsed output.
+- Detect existing provider usage before proposing SDK changes.
+- Do not install an adapter until its package is resolvable.
 - Always release sessions you create unless the user asks to keep them open.
-- If installation fails, verify that the artifact is a simulator build before attempting code changes.
+- If installation fails, verify that the artifact matches the target platform before attempting code changes.
 - Do not assume a local tunnel is installed on the user's machine.
-- Do not expose iOS simulator tokens in logs or screenshots.
+- Do not expose simulator tokens in logs or screenshots.
 `;
 function client() {
     const creds = requireCredentials();
@@ -123,6 +200,61 @@ function installSkill(opts) {
     }
     return results;
 }
+const RUN_CLOUD_DEMOS = [
+    'parallel-simulators',
+    'eight-device-mosaic',
+    'live-camera-relay',
+];
+function experimentalWebRtcEnabled() {
+    return ['1', 'true', 'yes', 'on'].includes((process.env.RUN_CLOUD_EXPERIMENTAL_WEBRTC ?? '').trim().toLowerCase());
+}
+function assertDevHostAllowed(devHost) {
+    if (devHost && process.env.RUN_CLOUD_DEV_FEATURES !== '1') {
+        throw new Error('--dev-host is dev-only; set RUN_CLOUD_DEV_FEATURES=1 to use it');
+    }
+}
+function requestedCodec(codec) {
+    const value = codec?.trim().toLowerCase() || 'auto';
+    if (value === 'webrtc' && !experimentalWebRtcEnabled()) {
+        throw new Error('--codec webrtc is experimental; set RUN_CLOUD_EXPERIMENTAL_WEBRTC=1 to use it');
+    }
+    return value;
+}
+function demoDirectory(name) {
+    if (!RUN_CLOUD_DEMOS.some((demoName) => demoName === name)) {
+        throw new Error(`Unknown demo: ${name}. Available demos: ${RUN_CLOUD_DEMOS.join(', ')}`);
+    }
+    const source = resolve(dirname(fileURLToPath(import.meta.url)), '../../examples', name);
+    if (!existsSync(source))
+        throw new Error(`The ${name} demo is missing from this runcloud package.`);
+    return source;
+}
+export function initRunCloudDemo(name = 'parallel-simulators', directory, opts = {}) {
+    const source = demoDirectory(name);
+    const target = resolve(directory ?? `run-cloud-${name}`);
+    if (existsSync(target)) {
+        if (!opts.force)
+            throw new Error(`${target} already exists. Pass --force to overwrite it.`);
+        rmSync(target, { recursive: true, force: true });
+    }
+    cpSync(source, target, { recursive: true });
+    return { example: name, path: target, status: 'created' };
+}
+export async function runCloudDemo(name = 'parallel-simulators', opts = {}, loadDemo = async (url) => (await import(url))) {
+    if (name === 'eight-device-mosaic' && opts.duration) {
+        throw new Error('The eight-device mosaic uses a fixed 10-minute lease and does not accept --duration.');
+    }
+    const args = [];
+    if (opts.count)
+        args.push('--count', opts.count);
+    if (opts.duration)
+        args.push('--duration', opts.duration);
+    if (opts.open)
+        args.push('--open');
+    const source = join(demoDirectory(name), 'demo.mjs');
+    const demo = await loadDemo(pathToFileURL(source).href);
+    await demo.runDemo(args);
+}
 async function pushAsset(path, opts = {}) {
     const { blob, name } = fileBlob(path);
     const form = new FormData();
@@ -131,92 +263,162 @@ async function pushAsset(path, opts = {}) {
         form.set('name', opts.name);
     return (await client().uploadForm('/run-cloud/assets', form));
 }
-async function action(fn) {
-    try {
-        await fn();
-    }
-    catch (err) {
-        console.error(friendlyApiError(err));
-        process.exitCode = 1;
-    }
+async function createSimulatorSession(platform, opts) {
+    assertDevHostAllowed(opts.devHost);
+    const uploadedAssets = [];
+    for (const file of opts.install ?? [])
+        uploadedAssets.push(await pushAsset(file));
+    const installAssets = [
+        ...(opts.installAsset ?? []),
+        ...uploadedAssets
+            .map((asset) => asset.id)
+            .filter((id) => typeof id === 'string' && id.length > 0),
+    ];
+    return await client().post(`/run-cloud/${platform}`, {
+        model: opts.model,
+        region: opts.region,
+        displayName: opts.displayName,
+        labels: parseLabels(opts.label),
+        installAssets,
+        inactivityTimeout: opts.inactivityTimeout,
+        hardTimeout: opts.hardTimeout,
+        autoDelete: opts.rm,
+        codec: requestedCodec(opts.codec),
+        ...(opts.devHost ? { devHost: opts.devHost } : {}),
+    });
 }
-export function registerRunCloud(program) {
-    program
-        .command('account')
-        .description('Show run.cloud entitlement and metered balance')
-        .option('--json', 'output JSON', false)
-        .action((opts) => action(async () => {
-        print(await client().get('/run-cloud/account'), opts);
-    }));
-    const ios = program.command('ios').description('Create, list, inspect, and delete iOS simulator sessions');
-    ios
+function registerSimulatorCommands(program, platform) {
+    const label = platform === 'android' ? 'Android emulator' : 'iOS simulator';
+    const article = platform === 'android' ? 'an' : 'an';
+    const simulator = program.command(platform).description(`Create, list, inspect, and delete ${label} sessions`);
+    simulator
         .command('create')
-        .description('Create a remote iOS simulator session')
-        .option('--model <iphone|ipad>', 'simulator model', 'iphone')
+        .description(`Create a remote ${label} session`)
+        .option('--model <model>', platform === 'ios' ? 'simulator model' : 'emulator model', platform === 'ios' ? 'iphone' : 'pixel')
         .option('--region <region>', 'fleet region')
         .option('--display-name <name>', 'human-readable name')
         .option('--label <key=value>', 'label to attach to the session', (v, p) => [...p, v], [])
-        .option('--install <file>', 'local .ipa, .zip, .tar.gz, or simulator .app archive to upload and install', (v, p) => [...p, v], [])
+        .option('--install <file>', 'local app artifact to upload and install', (v, p) => [...p, v], [])
         .option('--install-asset <name-or-id>', 'previously uploaded asset to install', (v, p) => [...p, v], [])
         .option('--inactivity-timeout <duration>', 'auto-close idle timeout, e.g. 60s, 3m, or none')
         .option('--hard-timeout <duration>', 'maximum lifetime, e.g. 10m or 1h')
+        .option('--codec <auto|mjpeg|webrtc>', 'force the simulator viewer stream codec', 'auto')
         .option('--rm', 'release the session when this command exits', false)
         .option('--json', 'output JSON', false)
+        .addOption(new Option('--dev-host <host>', 'dev-only: target a specific serve-sim fleet host').hideHelp())
         .action((opts) => action(async () => {
-        const uploadedAssets = [];
-        for (const file of opts.install ?? [])
-            uploadedAssets.push(await pushAsset(file));
-        const installAssets = [
-            ...(opts.installAsset ?? []),
-            ...uploadedAssets
-                .map((asset) => asset.id)
-                .filter((id) => typeof id === 'string' && id.length > 0),
-        ];
-        const session = await client().post('/run-cloud/ios', {
-            model: opts.model,
-            region: opts.region,
-            displayName: opts.displayName,
-            labels: parseLabels(opts.label),
-            installAssets,
-            inactivityTimeout: opts.inactivityTimeout,
-            hardTimeout: opts.hardTimeout,
-            autoDelete: opts.rm,
-        });
-        print(session, opts);
+        print(await createSimulatorSession(platform, opts), opts);
     }));
-    ios
+    simulator
         .command('list')
-        .description('List active iOS simulator sessions')
+        .description(`List active ${label} sessions`)
         .option('--all', 'include released sessions', false)
         .option('--json', 'output JSON', false)
         .action((opts) => action(async () => {
         const qs = opts.all ? '?all=1' : '';
-        print(await client().get(`/run-cloud/ios${qs}`), opts);
+        print(await client().get(`/run-cloud/${platform}${qs}`), opts);
     }));
-    ios
+    simulator
         .command('get')
-        .description('Show an iOS simulator session')
+        .description(`Show ${article} ${label} session`)
         .argument('<id>')
         .option('--json', 'output JSON', false)
         .action((id, opts) => action(async () => {
-        print(await client().get(`/run-cloud/ios/${encodeURIComponent(id)}`), opts);
+        print(await client().get(`/run-cloud/${platform}/${encodeURIComponent(id)}`), opts);
     }));
-    ios
+    simulator
         .command('delete')
-        .description('Release an iOS simulator session')
+        .description(`Release ${article} ${label} session`)
         .argument('<id>')
         .option('--json', 'output JSON', false)
         .action((id, opts) => action(async () => {
-        print(await client().delete(`/run-cloud/ios/${encodeURIComponent(id)}`), opts);
+        print(await client().delete(`/run-cloud/${platform}/${encodeURIComponent(id)}`), opts);
     }));
-    ios
+    simulator
         .command('open-url')
-        .description('Open a URL or deep link in an iOS simulator session')
+        .description(`Open a URL or deep link in ${article} ${label} session`)
         .argument('<url>')
         .requiredOption('--id <id>', 'session id')
         .option('--json', 'output JSON', false)
         .action((url, opts) => action(async () => {
-        print(await client().post(`/run-cloud/ios/${encodeURIComponent(opts.id)}/open-url`, { url }), opts);
+        print(await client().post(`/run-cloud/${platform}/${encodeURIComponent(opts.id)}/open-url`, { url }), opts);
+    }));
+    return simulator;
+}
+async function action(fn) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        console.error(friendlyApiError(err));
+        process.exitCode = 1;
+    }
+}
+export function registerRunCloud(program) {
+    const demo = program.command('demo').description('Create and run run.cloud demo projects');
+    demo
+        .command('init')
+        .description('Scaffold a standalone demo project')
+        .argument('[name]', 'demo to create', 'parallel-simulators')
+        .argument('[directory]', 'output directory')
+        .option('--force', 'overwrite an existing output directory', false)
+        .option('--json', 'output JSON', false)
+        .action((name, directory, opts) => action(async () => {
+        print(initRunCloudDemo(name, directory, opts), opts);
+    }));
+    demo
+        .command('run')
+        .description('Run a bundled demo without scaffolding a project')
+        .argument('[name]', 'demo to run', 'parallel-simulators')
+        .option('--count <2|3>', 'number of sessions (parallel-simulators only)')
+        .option('--duration <seconds>', 'duration for parallel-simulators and live-camera-relay')
+        .option('--open', 'open the demo viewer or live sessions in the browser', false)
+        .action((name, opts) => action(async () => {
+        await runCloudDemo(name, opts);
+    }));
+    program
+        .command('account')
+        .description('Show run.cloud entitlement and metered balance')
+        .option('--json', 'output JSON', false)
+        .action((opts) => action(async () => {
+        print(await client().get('/run-cloud/account'), opts);
+    }));
+    const ios = registerSimulatorCommands(program, 'ios');
+    registerSimulatorCommands(program, 'android');
+    ios
+        .command('tunnel')
+        .description('Connect a local service to a remote iOS simulator session')
+        .argument('<id>')
+        .requiredOption('--local-port <port>', 'local service port, for example Metro on 8081')
+        .option('--service <name>', 'service name shown in status', 'metro')
+        .option('--local-host <host>', 'loopback service host', '127.0.0.1')
+        .option('--sidecar-url <url>', 'Newly sidecar URL', 'http://127.0.0.1:4500')
+        .option('--json', 'output JSON', false)
+        .action((id, opts) => action(async () => {
+        const localPort = Number(opts.localPort);
+        if (!Number.isInteger(localPort) || localPort < 1 || localPort > 65535)
+            throw new Error('--local-port must be a valid TCP port');
+        const allocation = await client().post(`/sessions/${encodeURIComponent(id)}/tunnel`, {
+            localService: opts.service, localHost: opts.localHost, localPort,
+        });
+        if (!allocation.tunnel)
+            throw new Error('Control plane did not return tunnel credentials');
+        const sidecarResponse = await fetch(`${opts.sidecarUrl.replace(/\/$/, '')}/run-cloud/tunnel`, {
+            method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(allocation.tunnel),
+        });
+        const status = await sidecarResponse.json();
+        if (!sidecarResponse.ok)
+            throw new Error(`Local tunnel failed: ${status.error ?? sidecarResponse.statusText}`);
+        print(status, opts);
+    }));
+    ios
+        .command('tunnel-status')
+        .description('Show the local tunnel sidecar status')
+        .option('--sidecar-url <url>', 'Newly sidecar URL', 'http://127.0.0.1:4500')
+        .option('--json', 'output JSON', false)
+        .action((opts) => action(async () => {
+        const response = await fetch(`${opts.sidecarUrl.replace(/\/$/, '')}/run-cloud/tunnel`);
+        print(await response.json(), opts);
     }));
     const asset = program
         .command('asset')
@@ -260,7 +462,7 @@ export function registerRunCloud(program) {
     const skills = program.command('skills').description('Install run.cloud skills for AI coding agents');
     skills
         .command('install')
-        .description('Install the run.cloud iOS simulator skill')
+        .description('Install the run.cloud agent runtime skill')
         .option('--agents <agent>', 'agent to install for: claude, codex, cursor', (v, p) => [...p, v], [])
         .option('--scope <project|global>', 'install scope', 'project')
         .option('--force', 'overwrite existing skill', false)

package/dist/commands/sandbox.js

@@ -0,0 +1,136 @@
+import { friendlyApiError } from '../api.js';
+class CpClient {
+    baseUrl;
+    token;
+    constructor(baseUrl, token) {
+        this.baseUrl = baseUrl;
+        this.token = token;
+    }
+    async request(method, path, body) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: { Authorization: `Bearer ${this.token}`, 'Content-Type': 'application/json' },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            let msg = text;
+            try {
+                msg = JSON.parse(text).error ?? text;
+            }
+            catch {
+            }
+            throw new Error(`control plane ${res.status}: ${msg}`);
+        }
+        return text ? JSON.parse(text) : null;
+    }
+}
+function cp(opts) {
+    const baseUrl = (opts.cpUrl || process.env.SBX_API_URL || 'http://127.0.0.1:8080').replace(/\/+$/, '');
+    const token = opts.cpToken || process.env.SBX_TOKEN;
+    if (!token) {
+        throw new Error('No control-plane token: set SBX_TOKEN or pass --cp-token.');
+    }
+    return new CpClient(baseUrl, token);
+}
+function print(value, opts) {
+    if (opts.json) {
+        console.log(JSON.stringify(value, null, 2));
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            console.log(formatRecord(item));
+        return;
+    }
+    console.log(formatRecord(value));
+}
+function formatRecord(value) {
+    if (!value || typeof value !== 'object')
+        return String(value);
+    return Object.entries(value)
+        .filter(([, v]) => v !== undefined && v !== null)
+        .map(([k, v]) => `${k}: ${typeof v === 'object' ? JSON.stringify(v) : String(v)}`)
+        .join('\n');
+}
+async function run(fn) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        console.error(friendlyApiError(err));
+        process.exitCode = 1;
+    }
+}
+function withCp(cmd) {
+    return cmd
+        .option('--cp-url <url>', 'control-plane base URL (default $SBX_API_URL or http://127.0.0.1:8080)')
+        .option('--cp-token <token>', 'control-plane org token (or $SBX_TOKEN; required)')
+        .option('--json', 'output JSON', false);
+}
+export function registerSandbox(program) {
+    const sandbox = program.command('sandbox').description('Spawn and control microVM sandboxes');
+    withCp(sandbox
+        .command('create')
+        .description('Spawn a microVM sandbox')
+        .option('--image <ref>', 'base image', 'newly/agent-base')
+        .option('--size <class>', 'size preset', 's-2')
+        .option('--region <region>', 'placement region')
+        .option('--name <name>', 'human-readable name')).action((opts) => run(async () => {
+        const body = { size_class: opts.size, image: opts.image };
+        if (opts.name)
+            body.name = opts.name;
+        if (opts.region)
+            body.region = opts.region;
+        print(await cp(opts).request('POST', '/v1/sandboxes', body), opts);
+    }));
+    withCp(sandbox.command('list').description('List sandboxes').option('--state <state>', 'filter by state')).action((opts) => run(async () => {
+        const qs = opts.state ? `?state=${encodeURIComponent(opts.state)}` : '';
+        const data = await cp(opts).request('GET', `/v1/sandboxes${qs}`);
+        print(data?.items ?? [], opts);
+    }));
+    withCp(sandbox
+        .command('exec')
+        .description('Run a command in a sandbox (via /bin/sh -c)')
+        .argument('<id>', 'sandbox id')
+        .argument('<cmd...>', 'command to run, e.g. npm run build')).action((id, cmdParts, opts) => run(async () => {
+        const r = await cp(opts).request('POST', `/v1/sandboxes/${encodeURIComponent(id)}/exec`, {
+            cmd: ['/bin/sh', '-c', cmdParts.join(' ')],
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(r, null, 2));
+        }
+        else {
+            if (r.stdout)
+                process.stdout.write(r.stdout);
+            if (r.stderr)
+                process.stderr.write(r.stderr);
+        }
+        process.exitCode = r.exit_code ?? 0;
+    }));
+    withCp(sandbox
+        .command('logs')
+        .description('Show recent sandbox logs (one-shot journalctl tail; streaming is a follow-up)')
+        .argument('<id>', 'sandbox id')
+        .option('--lines <n>', 'number of lines to tail', '200')).action((id, opts) => run(async () => {
+        const n = Number(opts.lines) || 200;
+        const r = await cp(opts).request('POST', `/v1/sandboxes/${encodeURIComponent(id)}/exec`, {
+            cmd: [
+                '/bin/sh',
+                '-c',
+                `j="$(journalctl -n ${n} --no-pager 2>/dev/null)"; if [ -n "$j" ]; then printf "%s\\n" "$j"; else tail -n ${n} /root/.natively/expo_server.log 2>&1 || echo '(no logs available)'; fi`,
+            ],
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(r, null, 2));
+            return;
+        }
+        process.stdout.write(r.stdout ?? '');
+        process.stderr.write(r.stderr ?? '');
+    }));
+    withCp(sandbox.command('rm').description('Destroy a sandbox').argument('<id>', 'sandbox id')).action((id, opts) => run(async () => {
+        await cp(opts).request('DELETE', `/v1/sandboxes/${encodeURIComponent(id)}`);
+        if (!opts.json)
+            console.log(`destroyed ${id}`);
+    }));
+}

package/dist/config.js

@@ -1,13 +1,16 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, join } from 'node:path';
+function isRunCloud() {
+    const invoked = basename(process.argv[1] ?? '');
+    return invoked === 'runcloud' || invoked === 'run-cloud.js';
+}
 function credentialsHome() {
     if (process.env.RUN_CLOUD_HOME)
         return process.env.RUN_CLOUD_HOME;
     if (process.env.NEWLY_HOME)
         return process.env.NEWLY_HOME;
-    const invoked = basename(process.argv[1] ?? '');
-    if (invoked === 'runcloud' || invoked === 'run-cloud.js')
+    if (isRunCloud())
         return join(homedir(), '.run-cloud');
     return process.env.NEWLY_HOME ?? join(homedir(), '.newly');
 }
@@ -20,12 +23,10 @@ export function credentialsDisplayPath() {
     return path.startsWith(home) ? `~${path.slice(home.length)}` : path;
 }
 function loginCommandName() {
-    const invoked = basename(process.argv[1] ?? '');
-    return invoked === 'runcloud' || invoked === 'run-cloud.js' ? 'runcloud login' : 'newly login';
+    return isRunCloud() ? 'runcloud login' : 'newly login';
 }
 export function normalizeApiUrl(url) {
-    const trimmed = url.replace(/\/+$/, '');
-    return trimmed.endsWith('/api') ? trimmed : `${trimmed}/api`;
+    return url.replace(/\/+$/, '');
 }
 export function saveCredentials(creds) {
     mkdirSync(credentialsHome(), { recursive: true, mode: 0o700 });
@@ -34,13 +35,19 @@ export function saveCredentials(creds) {
     chmodSync(credentialsPath(), 0o600);
 }
 export function loadCredentials() {
-    const envToken = process.env.NEWLY_API_TOKEN ?? process.env.NEWLY_CLI_TOKEN;
-    const envApiUrl = process.env.NEWLY_API_URL ?? process.env.NEWLY_API_HOST ?? process.env.NEXT_PUBLIC_API_HOST;
+    const envToken = isRunCloud()
+        ? process.env.RUN_CLOUD_API_TOKEN ?? process.env.RUN_CLOUD_API_KEY
+        : process.env.NEWLY_API_TOKEN ?? process.env.NEWLY_CLI_TOKEN;
+    const envApiUrl = isRunCloud()
+        ? process.env.RUN_CLOUD_API_URL
+        : process.env.NEWLY_API_URL;
     if (envToken?.trim() && envApiUrl?.trim()) {
         return {
             token: envToken.trim(),
             apiUrl: normalizeApiUrl(envApiUrl.trim()),
-            appUrl: process.env.NEWLY_APP_URL ?? 'https://newly.dev',
+            appUrl: isRunCloud()
+                ? process.env.RUN_CLOUD_APP_URL ?? 'https://run.cloud'
+                : process.env.NEWLY_APP_URL ?? 'https://newly.app',
             expiresAt: Number.MAX_SAFE_INTEGER,
         };
     }
@@ -56,6 +63,40 @@ export function loadCredentials() {
         return null;
     }
 }
+function environmentSelectionPath(dir) {
+    return join(dir, '.newly', 'environment.json');
+}
+export function writeEnvironmentSelection(dir, selection) {
+    const selectionDir = join(dir, '.newly');
+    mkdirSync(selectionDir, { recursive: true });
+    const gitignorePath = join(selectionDir, '.gitignore');
+    if (!existsSync(gitignorePath))
+        writeFileSync(gitignorePath, '*\n');
+    writeFileSync(environmentSelectionPath(dir), JSON.stringify(selection, null, 2) + '\n');
+}
+export function readEnvironmentSelection(dir) {
+    try {
+        const parsed = JSON.parse(readFileSync(environmentSelectionPath(dir), 'utf8'));
+        if (!parsed.id || !parsed.name || !parsed.projectId)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function clearEnvironmentSelection(dir) {
+    rmSync(environmentSelectionPath(dir), { force: true });
+}
+export function requireEnvironmentSelection(dir, projectId) {
+    const selection = readEnvironmentSelection(dir);
+    if (!selection)
+        throw new Error('No environment selected. Run `newly env use <name>` first.');
+    if (selection.projectId !== projectId) {
+        throw new Error('The selected environment belongs to a different linked project. Run `newly env clear`.');
+    }
+    return selection;
+}
 export function clearCredentials() {
     rmSync(credentialsPath(), { force: true });
 }