runcloud 0.1.106 → 0.1.108

package/dist/commands/run-cloud.js

@@ -99,7 +99,7 @@ export function consumeSimulatorLogSse(raw) {
 function writeSimulatorLogEntry(entry, json) {
     console.log(json ? JSON.stringify(entry) : entry.message);
 }
-function parseLabels(labels) {
+function parseTags(labels) {
     const out = {};
     for (const raw of labels ?? []) {
         const idx = raw.indexOf('=');
@@ -307,7 +307,7 @@ async function createSimulatorSession(platform, opts) {
         model: opts.model,
         region: opts.region,
         displayName: opts.displayName,
-        labels: parseLabels(opts.label),
+        tags: parseTags(opts.label),
         installAssets,
         inactivityTimeout: opts.inactivityTimeout,
         hardTimeout: opts.hardTimeout,

package/dist/commands/sandbox.js

@@ -263,6 +263,33 @@ function secretSelector(opts) {
 function collectRepeatable(value, previous) {
     return [...previous, value];
 }
+export function parseTagPairs(values) {
+    return values.map((raw) => {
+        const at = raw.indexOf('=');
+        if (at <= 0) {
+            throw new Error(`--tag must be key=value (got ${JSON.stringify(raw)})`);
+        }
+        return [raw.slice(0, at), raw.slice(at + 1)];
+    });
+}
+export async function resolveSandboxByTag(api, tags) {
+    if (tags.length === 0) {
+        throw new Error('Provide a sandbox id, or --tag key=value to find one.');
+    }
+    const query = new URLSearchParams();
+    for (const [key, value] of parseTagPairs(tags))
+        query.append('tag', `${key}:${value}`);
+    const data = await api.get(`/run-cloud/sandboxes?${query}`);
+    const items = data?.items ?? [];
+    if (items.length === 0) {
+        throw new Error(`No sandbox matches ${tags.join(' ')}.`);
+    }
+    if (items.length > 1) {
+        const listed = items.map((s) => `  ${s.id}${s.name ? `  ${s.name}` : ''}`).join('\n');
+        throw new Error(`${items.length} sandboxes match ${tags.join(' ')} — narrow it, or pass an id:\n${listed}`);
+    }
+    return items[0].id;
+}
 export function registerSandbox(program) {
     const sandbox = program.command('sandbox').description('Spawn and control microVM sandboxes');
     const defaultHelp = new Help();
@@ -362,12 +389,16 @@ export function registerSandbox(program) {
         .command('list')
         .description('List sandboxes')
         .option('--state <state>', 'filter by state')
-        .option('--name <name>', 'filter by name (exact)')).action((opts) => run(async () => {
+        .option('--name <name>', 'filter by name (exact)')
+        .option('--tag <key=value>', 'filter by tag; repeatable, and a sandbox must carry every one', collectRepeatable, [])).action((opts) => run(async () => {
         const query = new URLSearchParams();
         if (opts.state)
             query.set('state', opts.state);
         if (opts.name)
             query.set('name', opts.name);
+        for (const [key, value] of parseTagPairs(opts.tag ?? [])) {
+            query.append('tag', `${key}:${value}`);
+        }
         const qs = query.size ? `?${query}` : '';
         const api = runCloudApi();
         const [data, boxes] = await Promise.all([
@@ -384,6 +415,23 @@ export function registerSandbox(program) {
         else
             console.log(renderSandboxList(items));
     }));
+    withOutput(sandbox
+        .command('tag')
+        .description('Set or remove tags on a sandbox')
+        .argument('<id>', 'sandbox id')
+        .argument('<pairs...>', 'key=value to set, or key= to remove')).action((id, pairs, opts) => run(async () => {
+        const tags = Object.fromEntries(parseTagPairs(pairs).map(([key, value]) => [key, value === '' ? null : value]));
+        const updated = await runCloudApi().patch(`/run-cloud/sandboxes/${encodeURIComponent(id)}/tags`, { tags });
+        if (opts.json)
+            printJson(updated);
+        else {
+            const applied = (updated?.tags ?? {});
+            const entries = Object.entries(applied);
+            console.log(entries.length === 0
+                ? `${id} now has no tags`
+                : `${id}\n${entries.map(([k, v]) => `  ${k}=${v}`).join('\n')}`);
+        }
+    }));
     withOutput(sandbox
         .command('get')
         .description('Inspect a sandbox, including its public hostname when exposed')
@@ -497,15 +545,17 @@ export function registerSandbox(program) {
     sandbox
         .command('shell')
         .description('Open an interactive shell (resumes paused sandboxes)')
-        .argument('<id>', 'sandbox id')
-        .action((id) => run(async () => {
+        .argument('[id]', 'sandbox id; omit when using --tag')
+        .option('--tag <key=value>', 'find the sandbox by tag instead of id; repeatable, must match exactly one', collectRepeatable, [])
+        .action((id, opts) => run(async () => {
         const credentials = requireCredentials();
         const api = new ApiClient(credentials.apiUrl, credentials.token);
-        await prepareSandboxShell(api, id);
+        const sandboxId = id ?? (await resolveSandboxByTag(api, opts.tag ?? []));
+        await prepareSandboxShell(api, sandboxId);
         process.exitCode = await runSandboxShell({
             apiUrl: credentials.apiUrl,
             token: credentials.token,
-            sandboxId: id,
+            sandboxId,
         });
     }));
     for (const lifecycle of [

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = '0.1.106';
+export const CLI_VERSION = '0.1.108';

package/examples/eight-device-mosaic/demo.mjs

@@ -71,9 +71,14 @@ function escapeHtml(value) {
     .replaceAll('>', '>');
 }
 
+function scriptData(value) {
+  return JSON.stringify(value).replaceAll('<', '\\u003c');
+}
+
 function embedUrl(value) {
   const url = new URL(value);
   url.searchParams.set('embed', '1');
+  url.searchParams.set('loadingGuard', '1');
   return url.toString();
 }
 
@@ -130,6 +135,7 @@ export function mosaicViewerHtml(sessions, deadline = Date.now() + DEMO_LEASE_MS
       const deadline = ${deadline};
       const tiles = [...document.querySelectorAll('.tile')];
       const frames = [...document.querySelectorAll('iframe')];
+      const frameOrigins = ${scriptData(sessions.map((session) => new URL(session.url).origin))};
       const ready = new Set();
       const count = document.querySelector('#ready-count');
       const timer = document.querySelector('#timer');
@@ -141,7 +147,12 @@ export function mosaicViewerHtml(sessions, deadline = Date.now() + DEMO_LEASE_MS
       setInterval(tick, 250);
       window.addEventListener('message', (event) => {
         const index = frames.findIndex((frame) => frame.contentWindow === event.source);
-        if (index < 0 || !event.data || typeof event.data !== 'object') return;
+        if (
+          index < 0
+          || event.origin !== frameOrigins[index]
+          || !event.data
+          || typeof event.data !== 'object'
+        ) return;
         if (event.data.type === 'ios-simulator:status' && event.data.streaming === true) {
           ready.add(index);
           tiles[index].dataset.ready = 'true';

package/examples/eight-device-mosaic/verify.mjs

@@ -35,8 +35,11 @@ test('renders eight signed embeds without printing them into the viewer URL', as
   }));
   const html = mosaicViewerHtml(sessions, 601_000);
   assert.equal((html.match(/<iframe /g) || []).length, 8);
-  assert.match(html, /embed=1/);
-  assert.doesNotMatch(html, /loadingGuard=1/);
+  assert.equal((html.match(/embed=1/g) || []).length, 8);
+  assert.equal((html.match(/loadingGuard=1/g) || []).length, 8);
+  assert.match(html, /const frameOrigins = \["https:\/\/sim\.example"/);
+  assert.match(html, /frame\.contentWindow === event\.source/);
+  assert.match(html, /event\.origin !== frameOrigins\[index\]/);
   assert.match(html, /const deadline = 601000/);
 
   const viewer = await startMosaicViewer(sessions, 601_000);

package/examples/live-camera-relay/demo.mjs

@@ -87,6 +87,7 @@ function scriptData(value) {
 function embedUrl(value) {
   const url = new URL(value);
   url.searchParams.set('embed', '1');
+  url.searchParams.set('loadingGuard', '1');
   return url.toString();
 }
 
@@ -193,6 +194,7 @@ export function cameraViewerHtml(sessions, duration, roomId, now = Date.now()) {
       const deadline = ${deadline};
       const devices = [...document.querySelectorAll('.device')];
       const frames = [...document.querySelectorAll('iframe')];
+      const frameOrigins = ${scriptData(sessions.map((session) => new URL(session.url).origin))};
       const ready = new Set();
       const count = document.querySelector('#ready-count');
       const timer = document.querySelector('#timer');
@@ -287,7 +289,12 @@ export function cameraViewerHtml(sessions, duration, roomId, now = Date.now()) {
       setInterval(tick, 250);
       window.addEventListener('message', (event) => {
         const index = frames.findIndex((frame) => frame.contentWindow === event.source);
-        if (index < 0 || !event.data || typeof event.data !== 'object') return;
+        if (
+          index < 0
+          || event.origin !== frameOrigins[index]
+          || !event.data
+          || typeof event.data !== 'object'
+        ) return;
         if (event.data.type === 'ios-simulator:status' && event.data.streaming === true) {
           ready.add(index);
           devices[index].dataset.ready = 'true';

package/examples/live-camera-relay/verify.mjs

@@ -67,8 +67,11 @@ test('renders three signed embeds while keeping credentials out of the local URL
   const demoSessions = sessions();
   const html = cameraViewerHtml(demoSessions, 60, 'room-12345678', 1_000);
   assert.equal((html.match(/<iframe /g) || []).length, 3);
-  assert.match(html, /embed=1/);
-  assert.doesNotMatch(html, /loadingGuard=1/);
+  assert.equal((html.match(/embed=1/g) || []).length, 3);
+  assert.equal((html.match(/loadingGuard=1/g) || []).length, 3);
+  assert.match(html, /const frameOrigins = \["https:\/\/sim\.example"/);
+  assert.match(html, /frame\.contentWindow === event\.source/);
+  assert.match(html, /event\.origin !== frameOrigins\[index\]/);
   assert.match(html, /Connect webcam/);
   assert.match(html, /com\.apple\.mobilesafari/);
   assert.match(html, /audio: false/);

package/package.json

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

package/skills/run-cloud-ios-simulator/SKILL.md

@@ -134,7 +134,7 @@ import { Client } from "@run-cloud/sdk";
 const cloud = new Client();
 const session = await cloud.ios.create({
   displayName: "Agent smoke",
-  labels: { owner: "agent" },
+  tags: { owner: "agent" },
   inactivityTimeout: "60s",
   hardTimeout: "10m",
   codec: "auto",
@@ -159,7 +159,7 @@ The mobile SDK surface is:
   `delete`
 - `cloud.assets`: `upload`, `list`, `delete`
 
-Create options include `model`, `region`, `displayName`, `labels`,
+Create options include `model`, `region`, `displayName`, `tags`,
 `installAssets`, `inactivityTimeout`, `hardTimeout`, and `codec`.
 
 Do not invent SDK methods for scripted taps, typing, recording, app lifecycle,
@@ -180,10 +180,13 @@ Delete uploaded assets when they are no longer needed.
 
 ## Embed a Session
 
+- In React, use `RemoteControl` from `@runcloud/ui` with the signed session URL.
 - Add `embed=1` to the signed session URL for the clean iframe UI.
 - Add `loadingGuard=1` when the iframe should block interaction until streaming
   and app launch are ready.
-- Verify `event.source` is the expected iframe before processing messages.
+- For raw iframes, verify both `event.source` and the exact signed-URL origin
+  before processing messages, and use that exact origin as the command
+  `postMessage` target.
 - Handle `ios-simulator:status`, `ios-simulator:auth-error`,
   `ios-simulator:session-ended`, and
   `ios-simulator:session-restart-requested`.

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

@@ -204,6 +204,76 @@ 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.
 
+## Tag Sandboxes, and Find Them Again
+
+Tags are arbitrary `key=value` metadata on a lease. They are how an operator
+gets from a symptom back to the machine that caused it, and they **outlive the
+sandbox** — so "which sandbox ran this?" is still answerable after the VM is
+gone, which is usually when you are asking.
+
+Tag on create, or on an existing sandbox:
+
+```bash
+runcloud sandbox create --image runcloud/agent-base   # then:
+runcloud sandbox tag sbx_123 newly.run=run-42 owner=qasim
+runcloud sandbox tag sbx_123 owner=          # empty value removes the key
+```
+
+Find by tag — repeatable, and a sandbox must carry every one:
+
+```bash
+runcloud sandbox list --tag newly.run=run-42 --json
+runcloud sandbox shell --tag newly.run=run-42   # resolves, then opens a shell
+```
+
+`shell --tag` refuses to guess: no match and several matches are both errors,
+and the ambiguous case lists what it found. Opening a shell on the wrong
+machine is worse than being told to be precise.
+
+Reserved keys the platform sets itself — do not overwrite them:
+
+| key | meaning |
+| --- | --- |
+| `newly.kind` | what created it (`ci`, …) |
+| `newly.run` | the CI run id |
+| `newly.environment` | the CI environment id |
+| `newly.session` / `newly.role` | Newly session association, for simulators |
+
+### Debugging when you have only a log line
+
+The control plane logs a sandbox's tags on **create** and **destroy**, so the
+first step needs no API token and no database access:
+
+```bash
+gcloud logging read \
+  'resource.labels.service_name="cp-api-dev" AND jsonPayload.message="run.cloud sandbox created"' \
+  --limit 20 --freshness=6h --format=json
+```
+
+Then either query as a normal user (`runcloud sandbox list --tag …`), or use the
+ops endpoint, which is org-agnostic and audited — the right tool when you do not
+know whose org it was:
+
+```
+GET /diagnose/sandbox?tag=newly.run:run-42
+```
+
+It is gated by an ops OIDC token, not a user credential: mint one by
+impersonating the `cp-diagnose-ops-<env>` service account, which every engineer
+can do. Destroyed sandboxes are included on purpose.
+
+**Credentials.** The CLI defaults to **prod**. For dev, set both:
+
+```bash
+export RUN_CLOUD_API_URL=https://cp-api-dev-97683904813.us-east4.run.app
+export RUN_CLOUD_API_TOKEN=...   # RUN_CLOUD_DEV_API_TOKEN in secrets/dev.yaml
+```
+
+Key names do not match the env vars, and `sops` needs
+`gcloud auth application-default login` rather than plain `gcloud auth login` —
+see the Secrets section of the root `CLAUDE.md`/`AGENTS.md` before concluding
+you lack access.
+
 ## Guardrails
 
 - Destroy every sandbox created during a task unless the user explicitly asks
@@ -215,3 +285,5 @@ desktop URLs private and inspect each subcommand's help before automation.
   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.
+- Do not overwrite a `newly.*` tag; the platform sets those and support reads
+  them. Add your own key instead.