runcloud 0.1.17 → 0.1.19

package/dist/commands/boxAccess.js

@@ -32,7 +32,7 @@ async function resolveSandboxId(client, reference) {
         return sandbox.id;
     return (await resolveBox(client, reference)).sandboxId ?? reference;
 }
-async function writeSandboxFile(client, sandboxId, path, content) {
+export async function writeSandboxFile(client, sandboxId, path, content) {
     const chunkSize = 512 * 1024;
     const count = Math.max(1, Math.ceil(content.byteLength / chunkSize));
     for (let index = 0; index < count; index += 1) {
@@ -47,6 +47,12 @@ async function writeSandboxFile(client, sandboxId, path, content) {
         });
         if (response?.error)
             throw new Error(String(response.error));
+        const expectedNextOffset = offset + chunk.byteLength;
+        if (chunk.byteLength > 0
+            && (!Number.isSafeInteger(response?.next_offset)
+                || response.next_offset !== expectedNextOffset)) {
+            throw new Error('file write chunk was not acknowledged; the file may be incomplete');
+        }
     }
 }
 async function readSandboxFile(client, sandboxId, path) {

package/dist/commands/run-cloud.js

@@ -6,20 +6,40 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createHash } from 'node:crypto';
 import { ApiClient, friendlyApiError } from '../api.js';
 import { requireCredentials } from '../config.js';
-const RUN_CLOUD_SKILL_FILENAME = 'run-cloud-ios-simulator/SKILL.md';
-function loadRunCloudSkill() {
+export const RUN_CLOUD_SKILL_NAMES = [
+    'run-cloud',
+    'run-cloud-ios-simulator',
+    'run-cloud-sandboxes',
+];
+const RUN_CLOUD_SKILL_FILE_NAMES = ['SKILL.md', 'agents/openai.yaml'];
+function loadRunCloudSkillFiles(skillName) {
+    const embedded = globalThis.__RUN_CLOUD_EMBEDDED_SKILLS__?.[skillName];
+    if (embedded)
+        return embedded;
     const commandDirectory = dirname(fileURLToPath(import.meta.url));
     const candidates = [
-        resolve(commandDirectory, '../../skills', RUN_CLOUD_SKILL_FILENAME),
-        resolve(commandDirectory, '../../../.claude/skills', RUN_CLOUD_SKILL_FILENAME),
+        resolve(commandDirectory, '../../skills', skillName),
+        resolve(commandDirectory, '../../../.claude/skills', skillName),
     ];
     for (const candidate of candidates) {
-        if (existsSync(candidate))
-            return readFileSync(candidate, 'utf8');
+        if (RUN_CLOUD_SKILL_FILE_NAMES.every((filename) => existsSync(join(candidate, filename)))) {
+            return Object.fromEntries(RUN_CLOUD_SKILL_FILE_NAMES.map((filename) => [
+                filename,
+                readFileSync(join(candidate, filename), 'utf8'),
+            ]));
+        }
     }
-    throw new Error('run.cloud agent skill is missing from the package; reinstall runcloud or use npx skills add newly-app/run-cloud-examples --skill run-cloud-ios-simulator');
+    throw new Error(`run.cloud agent skill ${skillName} is missing from the package; reinstall runcloud or use npx skills add newly-app/run-cloud-examples`);
 }
-export const RUN_CLOUD_SKILL = loadRunCloudSkill();
+const RUN_CLOUD_SKILL_FILES = Object.fromEntries(RUN_CLOUD_SKILL_NAMES.map((skillName) => [
+    skillName,
+    loadRunCloudSkillFiles(skillName),
+]));
+export const RUN_CLOUD_SKILLS = Object.fromEntries(RUN_CLOUD_SKILL_NAMES.map((skillName) => [
+    skillName,
+    RUN_CLOUD_SKILL_FILES[skillName]['SKILL.md'],
+]));
+export const RUN_CLOUD_SKILL = RUN_CLOUD_SKILLS['run-cloud-ios-simulator'];
 function client() {
     const creds = requireCredentials();
     return new ApiClient(creds.apiUrl, creds.token);
@@ -84,20 +104,30 @@ function skillBase(agent, scope) {
         return join(homedir(), '.agents', 'skills');
     throw new Error(`Unsupported agent: ${agent}`);
 }
-function installSkill(opts) {
+function installSkills(opts) {
     const agents = opts.agents?.length ? opts.agents : ['claude', 'codex', 'cursor'];
     const scope = opts.scope ?? 'project';
+    const targets = agents.flatMap((agent) => RUN_CLOUD_SKILL_NAMES.map((skill) => ({
+        agent,
+        skill,
+        path: join(skillBase(agent, scope), skill),
+    })));
+    if (!opts.force) {
+        const existing = targets.find((target) => existsSync(target.path));
+        if (existing) {
+            throw new Error(`${existing.path} already exists. Pass --force to overwrite.`);
+        }
+    }
     const results = [];
-    for (const agent of agents) {
-        const target = join(skillBase(agent, scope), 'run-cloud-ios-simulator');
-        if (existsSync(target)) {
-            if (!opts.force)
-                throw new Error(`${target} already exists. Pass --force to overwrite.`);
+    for (const { agent, skill, path: target } of targets) {
+        if (existsSync(target))
             rmSync(target, { recursive: true, force: true });
+        for (const filename of RUN_CLOUD_SKILL_FILE_NAMES) {
+            const destination = join(target, filename);
+            mkdirSync(dirname(destination), { recursive: true });
+            writeFileSync(destination, RUN_CLOUD_SKILL_FILES[skill][filename]);
         }
-        mkdirSync(target, { recursive: true });
-        writeFileSync(join(target, 'SKILL.md'), RUN_CLOUD_SKILL);
-        results.push({ agent, path: target, status: 'installed' });
+        results.push({ agent, skill, path: target, status: 'installed' });
     }
     return results;
 }
@@ -440,13 +470,13 @@ 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 agent runtime skill')
+        .description('Install the run.cloud router, mobile-session, and sandbox skills')
         .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)
         .option('--json', 'output JSON', false)
         .action((opts) => action(async () => {
         const scope = opts.scope === 'global' ? 'global' : 'project';
-        print(installSkill({ ...opts, scope }), opts);
+        print(installSkills({ ...opts, scope }), opts);
     }));
 }

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = '0.1.17';
+export const CLI_VERSION = '0.1.19';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcloud",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Create and control run.cloud remote mobile simulators and cloud sandboxes",
   "license": "Apache-2.0",
   "keywords": [

package/skills/run-cloud/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: run-cloud
+description: Route run.cloud work to the focused mobile-session or sandbox skill. Use when a request mentions run.cloud generally, spans both products, or does not yet distinguish remote iOS and Android sessions from microVM sandboxes.
+---
+
+# Route run.cloud Work
+
+Keep this skill as a router. Do not duplicate operational instructions here.
+
+- Use `$run-cloud-ios-simulator` for remote iOS simulators, Android emulators,
+  app installation, mobile smoke tests, simulator screenshots, media injection,
+  iframe embeds, Metro tunnels, mobile assets, and mobile session cleanup.
+- Use `$run-cloud-sandboxes` for microVM sandboxes, command execution, files,
+  snapshots, images, SSH, secrets, public ports, desktop automation, resource
+  sizing, and sandbox cleanup.
+- Use both focused skills when a workflow genuinely combines mobile sessions
+  and sandboxes. Follow each skill's authentication, security, metering, and
+  cleanup guardrails.
+
+If the request is ambiguous, infer the product from the resource noun and
+desired outcome. Ask only when choosing the wrong product would materially
+change the work.

package/skills/run-cloud/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Run Cloud"
+  short_description: "Route run.cloud work to focused agent skills"
+  default_prompt: "Use $run-cloud to select the focused run.cloud skill for this task."

package/skills/run-cloud-sandboxes/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: run-cloud-sandboxes
+description: Operate run.cloud microVM sandboxes with the CLI or TypeScript SDK. Use for creating isolated compute, running commands, moving files, managing snapshots or images, exposing ports, using SSH or desktop automation, attaching secrets, sizing resources, or cleaning up sandboxes.
+---
+
+# Operate run.cloud Sandboxes
+
+Use the `runcloud` CLI for terminal and interactive workflows. Use
+`@run-cloud/sdk` for TypeScript applications, CI, and agent code.
+
+## Authenticate
+
+- Install the CLI with `npm install -g runcloud`.
+- Use `runcloud login` for an interactive browser handoff. Use
+  `runcloud login --manual` when a local callback cannot open.
+- In CI, set `RUN_CLOUD_API_KEY`. `RUN_CLOUD_API_TOKEN` is an equivalent alias.
+- Set `RUN_CLOUD_API_URL` only to override the production default
+  `https://api.run.cloud`.
+- Never print, commit, or place credentials in a skill file.
+- Treat signed desktop and tunnel URLs as bearer secrets.
+- Require Node.js 20 or newer for the CLI and TypeScript SDK.
+
+Inspect account and organization usage before starting metered work:
+
+```bash
+runcloud account --json
+```
+
+## Choose the Interface
+
+- Prefer CLI commands with `--json` for shell automation.
+- Prefer the TypeScript SDK when code needs streaming command output, binary
+  file transfer, retry-safe creation, or short-lived public tunnels.
+- Inspect `runcloud sandbox --help`, a subcommand's `--help`, or installed SDK
+  types before using a method not documented here.
+- Use the `sandbox` noun. The older `box` commands are deprecated aliases.
+
+## Run a CLI Lifecycle
+
+Create a sandbox, capture its ID, run a command, and destroy it:
+
+```bash
+SANDBOX_ID=$(runcloud sandbox create \
+  --image runcloud/agent-base \
+  --timeout 900 \
+  --json | jq -r '.id')
+
+trap 'runcloud sandbox rm "$SANDBOX_ID" >/dev/null 2>&1 || true' EXIT
+
+runcloud sandbox get "$SANDBOX_ID" --json
+runcloud sandbox exec "$SANDBOX_ID" "npm install && npm test"
+```
+
+The main lifecycle commands are:
+
+- `runcloud sandbox create`
+- `runcloud sandbox list [--state <state>]`
+- `runcloud sandbox get <id>`
+- `runcloud sandbox exec <id> <cmd...>`
+- `runcloud sandbox shell <id>`
+- `runcloud sandbox pause|resume <id>`
+- `runcloud sandbox logs <id> [--lines <n>]`
+- `runcloud sandbox metrics <id> [--range <range>] [--watch]`
+- `runcloud sandbox rm <id>`
+
+Create accepts `--image`, `--region`, `--name`, `--org`, `--cpu`, `--memory`,
+`--disk`, `--idle-pause`, `--timeout`, `--persistent`, `--expose`, secret
+selectors, `--no-wait`, and `--json`.
+
+The default reservation is 0.125 vCPU and 128 MiB when CPU and memory are
+omitted. Set finite timeouts for unattended work. Use `--timeout 0` only when a
+persistent workload is intentional.
+
+CLI `exec` runs through `/bin/sh -c` and returns the guest command's exit code.
+A paused sandbox must be resumed before `exec`; `shell` resumes it
+automatically.
+
+## Use the TypeScript SDK
+
+Install the SDK:
+
+```bash
+npm install @run-cloud/sdk
+```
+
+Use an idempotency key when a job runner may retry creation, check non-zero
+exit codes explicitly, and always destroy metered resources:
+
+```ts
+import { Client } from "@run-cloud/sdk";
+
+const cloud = new Client();
+const sandbox = await cloud.sandboxes.create({
+  image: "runcloud/agent-base",
+  cpu: 1,
+  memory: 1024,
+  timeoutSeconds: 900,
+  idempotencyKey: process.env.CI_JOB_ID,
+});
+
+try {
+  const result = await cloud.sandboxes.exec(
+    sandbox.id,
+    ["npm", "test"],
+    {
+      onStdout: (chunk) => process.stdout.write(chunk),
+      onStderr: (chunk) => process.stderr.write(chunk),
+    },
+  );
+  if (result.exitCode !== 0) {
+    throw new Error(`tests failed with exit code ${result.exitCode}`);
+  }
+} finally {
+  await cloud.sandboxes.destroy(sandbox.id);
+}
+```
+
+The TypeScript sandbox surface is:
+
+- `cloud.sandboxes`: `create`, `list`, `get`, `exec`, `readFile`,
+  `writeFile`, `openTunnel`, `closeTunnel`, `setTimeout`, `snapshot`,
+  `destroy`, and the `delete` alias
+- `cloud.snapshots`: `list`, `restore`, `delete`
+- `cloud.account()` and `cloud.usage({ orgId? })`
+
+A string passed to SDK `exec` runs through `/bin/sh -c`; an argv array executes
+directly. A non-zero guest exit code is returned rather than thrown. Use
+`cwd`, `env`, `timeoutSeconds`, `onStdout`, `onStderr`, and `signal` as needed.
+
+Use `readFile` and `writeFile` for binary-safe SDK file transfer. For
+interactive terminal workflows, configure SSH with `runcloud sandbox setup-ssh`
+and inspect `runcloud sandbox ssh`, `cp`, and `code` help before use.
+
+## Snapshot and Restore
+
+Snapshot a prepared filesystem and restore it into fresh sandboxes:
+
+```bash
+runcloud sandbox snapshot create "$SANDBOX_ID" --label deps-installed --json
+runcloud sandbox snapshot list --json
+runcloud sandbox restore <snapshot-id> --json
+runcloud sandbox snapshot rm <snapshot-id>
+```
+
+The SDK equivalents are `cloud.sandboxes.snapshot`,
+`cloud.snapshots.restore`, `cloud.snapshots.list`, and
+`cloud.snapshots.delete`.
+
+A restore creates a new billed sandbox with a new ID. One snapshot can fan out
+to parallel workers, but every restored sandbox counts toward concurrency and
+must be destroyed. A restored sandbox inherits no secrets; attach only the
+secrets it needs.
+
+## Use Images
+
+Use reusable images when every sandbox needs the same base tools:
+
+```bash
+runcloud image create my-agent --dockerfile ./Dockerfile
+runcloud image list --json
+runcloud sandbox create --image my-agent --json
+runcloud image refresh my-agent
+```
+
+Inspect `runcloud image --help` for current build-source options. Do not invent
+image methods on the TypeScript SDK.
+
+## Expose a Service
+
+Choose one exposure model deliberately:
+
+- For a stable hostname, create with
+  `runcloud sandbox create --name <name> --expose <port> --persistent`, or use
+  `runcloud sandbox expose <id> --port <port>`.
+- For a short-lived random URL in TypeScript, call
+  `cloud.sandboxes.openTunnel(id, port, { ttlSeconds })`, then
+  `closeTunnel(id, tunnel.id)`.
+
+An SDK tunnel does not make the sandbox persistent or disable idle pause. Do
+not log its URL. Revocation can take effect shortly after `closeTunnel`
+returns; stop the guest service or destroy the sandbox when access must end
+immediately.
+
+## Handle Secrets Safely
+
+- Create secret groups from `--from-dotenv`, `--from-json`, `--stdin`, a file,
+  or a hidden prompt. Never pass a secret value as a command argument.
+- Attach only the required groups or names with repeatable `--secret-group` and
+  `--secret`. Later selectors win on name collisions; `--env` is applied last.
+- Use `--no-secrets` to state explicitly that a new sandbox needs none.
+- Treat `runcloud sandbox secrets <id> ...` as full replacement, not a merge.
+- Remember that values cannot be read back and snapshots do not contain
+  secrets.
+
+Inspect `runcloud secret-group --help` and `runcloud secrets --help` for the
+current non-plaintext input forms.
+
+## Operate Desktop Sandboxes
+
+For a compatible desktop image, use `runcloud sandbox desktop <id>` to open its
+signed browser desktop. The CLI also provides `screenshot`, `click`, `type`,
+and `key` subcommands for explicit pixel-coordinate automation. Keep signed
+desktop URLs private and inspect each subcommand's help before automation.
+
+## Guardrails
+
+- Destroy every sandbox created during a task unless the user explicitly asks
+  to keep it. Also remove unused snapshots, tunnels, and public hostnames.
+- Use `try/finally` or a shell trap around every metered lifecycle.
+- Check `exitCode`; do not treat a completed SDK `exec` call as success by
+  itself.
+- Do not expose API credentials, secret values, signed desktop URLs, or tunnel
+  URLs in logs, screenshots, PR comments, or chat output.
+- Do not claim that CLI-only lifecycle, image, secret-group, desktop, or stable
+  hostname commands are TypeScript SDK methods.

package/skills/run-cloud-sandboxes/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Run Cloud Sandboxes"
+  short_description: "Operate secure remote microVM sandboxes"
+  default_prompt: "Use $run-cloud-sandboxes to create, operate, and clean up run.cloud sandboxes."