runcloud 0.1.120 → 0.1.122

package/dist/commands/run-cloud.js

@@ -1305,13 +1305,15 @@ async function action(fn, opts = {}) {
 }
 function configureMachineReadableParseErrors(program) {
     const output = program.configureOutput();
+    const writeErrorLine = output.outputError ??
+        ((value, destination) => destination(value));
     program.configureOutput({
         ...output,
         outputError: (message, write) => {
             const rawArgs = program.rawArgs ?? [];
             const argumentsSeen = [...process.argv, ...rawArgs, ...program.args];
             if (!argumentsSeen.includes('--json')) {
-                (output.outputError ?? ((value, destination) => destination(value)))(message, write);
+                writeErrorLine(message, write);
                 return;
             }
             write(`${JSON.stringify({

package/dist/commands/sandbox.js

@@ -8,7 +8,7 @@ import { runSandboxCommand, shellCommand } from '../sandboxExec.js';
 import { runSandboxShell } from '../shellSession.js';
 import { printJson, StatusLine, style } from '../terminal.js';
 import { noteDeprecated, registerAccessCommands } from './boxAccess.js';
-import { renderSandbox, renderSandboxList, } from './sandboxOutput.js';
+import { renderHeldSecrets, renderSandbox, renderSandboxList, } from './sandboxOutput.js';
 const MAX_SANDBOX_DISK_GIB = 2048;
 const DEFAULT_SANDBOX_TIMEOUT_SECONDS = 300;
 const DEFAULT_BOX_CPU_CORES = 2;
@@ -260,6 +260,15 @@ function secretSelector(opts) {
         out.env = env;
     return out;
 }
+async function replaceSandboxSecrets(id, opts) {
+    const body = secretSelector(opts);
+    await runCloudApi().put(`/run-cloud/sandboxes/${encodeURIComponent(id)}/secrets`, body);
+    if (opts.json) {
+        printJson({ id, revoked: opts.noSecrets === true, ...body });
+        return;
+    }
+    console.log(opts.noSecrets ? `${id}: all secrets revoked` : `${id}: secrets replaced`);
+}
 function collectRepeatable(value, previous) {
     return [...previous, value];
 }
@@ -472,17 +481,38 @@ export function registerSandbox(program) {
             await new Promise((resolveDelay) => setTimeout(resolveDelay, opts.interval * 1_000));
         }
     }));
-    withOutput(sandbox
+    const secrets = withOutput(sandbox
         .command('secrets')
-        .description('Replace the secrets a running sandbox holds (a full replacement, not a merge)')
+        .description('Show what secrets a sandbox holds (names and origins, never values)')
+        .argument('[id]', 'sandbox id'))
+        .showHelpAfterError("hint: `runcloud sandbox secrets set <id> …` changes what a sandbox holds; the bare form only reads it");
+    const wantsJson = (opts) => Boolean(secrets.opts().json) || Boolean(opts.json);
+    secrets.action((id, opts) => run(async () => {
+        if (!id)
+            throw new Error('which sandbox? usage: runcloud sandbox secrets <id>');
+        const { held } = (await runCloudApi().get(`/run-cloud/sandboxes/${encodeURIComponent(id)}/secrets`));
+        if (opts.json) {
+            printJson({ held });
+            return;
+        }
+        console.log(renderHeldSecrets(id, held));
+    }));
+    withOutput(secrets
+        .command('set')
+        .description('Replace what a sandbox holds (a full replacement, not a merge)')
         .argument('<id>', 'sandbox id')
         .option('--secret-group <group>', 'attach a secret group; repeatable and ORDER MATTERS (a later group wins on a name collision)', collectRepeatable, [])
         .option('--secret <group/name>', 'attach one secret out of a group; repeatable, same ordering', collectRepeatable, [])
         .option('--env <NAME=VALUE>', 'literal value; applied last, so it wins; repeatable', collectRepeatable, [])).action((id, opts) => run(async () => {
-        const body = secretSelector(opts);
-        await runCloudApi().put(`/run-cloud/sandboxes/${encodeURIComponent(id)}/secrets`, body);
-        console.log(`${id}: secrets replaced`);
+        if (!opts.secretGroup.length && !opts.secret.length && !opts.env.length) {
+            throw new Error('name what the sandbox should hold with --secret-group/--secret/--env, or run `runcloud sandbox secrets revoke <id>` to take everything back');
+        }
+        await replaceSandboxSecrets(id, { ...opts, json: wantsJson(opts) });
     }));
+    withOutput(secrets
+        .command('revoke')
+        .description('Take every secret back from a sandbox')
+        .argument('<id>', 'sandbox id')).action((id, opts) => run(() => replaceSandboxSecrets(id, { noSecrets: true, json: wantsJson(opts) })));
     withOutput(sandbox
         .command('expose')
         .description('Publish a sandbox guest port at a stable hostname, or change the published port')

package/dist/commands/sandboxOutput.js

@@ -1,4 +1,24 @@
 import { formatAge, formatCpu, formatMib, formatSeconds, formatState, renderDetails, renderTable, shortDigest, style, } from '../terminal.js';
+export function renderHeldSecrets(id, held) {
+    const heading = `Secrets held by ${id}`;
+    if (held === null) {
+        return `${style.bold(heading)}\n\nUnknown — nothing was recorded for this sandbox, so what it\nholds cannot be answered from here.\n\n${style.dim('Check the environment inside it, or run `runcloud sandbox secrets set`,')}\n${style.dim('which records what it pushes.')}`;
+    }
+    if (held.length === 0) {
+        return `${style.bold(heading)}\n\nNothing. This sandbox holds no secrets.\n\n${style.dim('Attach some:')}  runcloud sandbox secrets set ${id} --secret-group <group>`;
+    }
+    return renderTable(`${heading} (${held.length})`, [
+        { key: 'name', label: 'NAME', maxWidth: 32 },
+        { key: 'kind', label: 'KIND' },
+        { key: 'source', label: 'FROM', maxWidth: 28 },
+        { key: 'digest', label: 'DIGEST' },
+    ], held.map((secret) => ({
+        name: secret.name,
+        kind: secret.kind,
+        source: secret.source,
+        digest: secret.digest,
+    })));
+}
 function resources(record) {
     const memory = formatMib(record.mem_mb);
     const disk = formatMib(record.disk_mb);

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = '0.1.120';
+export const CLI_VERSION = '0.1.122';

package/package.json

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

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

@@ -190,9 +190,20 @@ immediately.
 - 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.
+- Three verbs, because two of them change things:
+  - `runcloud sandbox secrets <id>` reads. Names, where each one resolved from,
+    and a digest of its value.
+  - `runcloud sandbox secrets set <id> ...` replaces. It is a
+    full replacement, not a merge: the sandbox ends up holding exactly what
+    that one command names.
+  - `runcloud sandbox secrets revoke <id>` takes everything back.
+- A listing of `Unknown` is not `Nothing`. The inventory is recorded when a
+  delivery is accepted, so a sandbox created before inventories existed has no
+  record — its secrets still work. Only `Nothing` means the sandbox is empty.
+- Values never come back, from any command. The digest exists so you can tell
+  whether the value in a sandbox is still the one its group holds; it is not
+  reversible and there is no masked form.
+- Snapshots do not contain secrets, so a restored sandbox starts with none.
 
 Inspect `runcloud secret-group --help` and `runcloud secrets --help` for the
 current non-plaintext input forms.
@@ -295,14 +306,42 @@ Three limits that change what you can conclude from it:
   early output is gone, not merely paged out. An empty-looking start is a trim,
   not proof the process printed nothing.
 - `systemd-run` output goes to the journal, not the console, so those units never
-  appear here at all. Read `journalctl -u <unit>` inside the sandbox instead.
+  appear here at all. `journalctl -u <unit>` reaches it, but only from inside a
+  running sandbox, so that output is unrecoverable once the sandbox is destroyed
+  and needs a resume on a paused one. A workload whose output has to survive a
+  post-mortem should write to stdout rather than a unit.
+
+Two details about reading the file: the `created` marker is appended to a shell
+prompt line rather than starting one, so match `--- sandbox` anywhere in the line
+rather than anchoring to the start, and boot output dwarfs everything else, so
+reach for the tail before the head.
+
+### What the metrics actually settle
+
+`runcloud sandbox metrics <id> --json` carries typed counters, and they are how
+you refute a theory instead of arguing about it. The natural wrong answer on a
+128 MiB sandbox is always "it OOMed":
+
+| field | what a zero proves |
+| --- | --- |
+| `memory_oom_kills`, `memory_oom_events` | nothing was OOM-killed, so a dead process exited on its own |
+| `cpu_throttled_periods`, `cpu_throttled_millicores` | the CPU reservation was not starving it |
+| lifetime `network` totals | at ~0 bytes in, no request ever arrived, so the fault is upstream of the guest |
+
+Each has a `*_valid` companion; when that is false the counter is unavailable
+rather than zero, and a zero you cannot trust proves nothing.
+
+`memory_bytes` is the exception and it misleads. It is measured host-side and
+includes page cache, so it routinely reads several times the sandbox's `mem_mb`
+reservation. That is not a leak and not an impending OOM. Believe
+`memory_oom_kills` over it, every time.
 
 ### Lifecycle markers
 
 The host writes a marker into the console on every transition:
 
 ```
---- sandbox destroyed: timeout-sweep at 2026-08-05T11:02:11Z ---
+--- sandbox paused: timeout-sweep at 2026-08-05T11:02:11Z ---
 ```
 
 The events are `created`, `paused`, `resumed`, `stopped`, and `destroyed`. The
@@ -310,22 +349,53 @@ token after the colon is the control plane's actor, written verbatim so it can b
 matched rather than parsed; the sentence around it is not a contract. Only stops
 carry a reason, so `created` and `resumed` appear without one.
 
-| actor | what it means |
-| --- | --- |
-| `timeout-sweep` | hit its `--timeout` lifetime cap. Not a crash |
-| `idle-sweep` | idle-paused after `--idle-pause` seconds. Resumable, and not a failure |
-| `retention-sweep` | destroyed after its 48h parked window expired |
-| `pause` `resume` `stop` `archive` `restore` | a caller requested exactly this |
-| `api` `api-force` | a caller destroyed it. `api-force` bypassed a wedged guest |
-| `health-sweep` `host-reconcile` `reap-sweep` | the platform reclaimed it |
-| `boot-failure` `placement-timeout` `request-timeout` `scheduler` | it never started. Capacity or image, not the workload |
-| `image-built` `image-build-failure` | an async image build finished or failed |
-| `startup-recover` `volume-lease-invalid` `replica-fork-resume-failure` | platform recovery paths |
+Read the **event** before the actor. A paused sandbox still exists and its disk is
+intact; a destroyed one is gone. Telling someone their work is lost when it is
+warm-parked and resumable is the most expensive mistake available here.
+
+| actor | ends up | what it means |
+| --- | --- | --- |
+| `timeout-sweep` | paused | hit its `--timeout` lifetime cap. Not a crash, and the work is still there |
+| `idle-sweep` | paused | idle-paused after `--idle-pause` seconds. Not a failure at all |
+| `retention-sweep` | destroyed | the 48h parked window expired and it was reaped for real |
+| `pause` `resume` `stop` `archive` `restore` | as asked | a caller requested exactly this |
+| `api` `api-force` | destroyed | a caller destroyed it. `api-force` bypassed a wedged guest |
+| `health-sweep` | interrupted | the platform judged it unhealthy |
+| `host-state-reconcile` | paused | the host had already parked it and the control plane caught up. The pause happened earlier than this event says |
+| `host-reconcile` `reap-sweep` | destroyed | the platform reclaimed it |
+| `boot-failure` `placement-timeout` `request-timeout` `scheduler` | never ran | capacity or image, not the workload |
+| `image-built` `image-build-failure` | varies | an async image build finished or failed |
+| `startup-recover` `volume-lease-invalid` `replica-fork-resume-failure` | varies | platform recovery paths |
+
+**Getting a parked sandbox back.** `timeout-sweep` and `idle-sweep` leave a full
+snapshot, so `runcloud sandbox resume <id>` restores it warm. You have 48h before
+`retention-sweep` destroys it for real. Resuming restarts the lifetime window from
+now rather than clearing it, so a sandbox parked by `timeout-sweep` will park again
+after the same interval; raise the cap first with the SDK's
+`cloud.sandboxes.setTimeout(id, seconds)`, which has no CLI equivalent.
+
+**The `--timeout` trap.** `--timeout` is a wall-clock lifetime cap, wholly separate
+from `--idle-pause`. It fires on a fully busy sandbox, and `--persistent` /
+`--idle-pause 0` do **not** hold it off, despite `--persistent` reading as "never
+pause when idle". Default is 300s, ceiling 24h.
 
 A sandbox that failed before it ever reached a host has no console, because the
 file is created at boot. Those carry a `Last error` row on
 `runcloud sandbox get` instead, which is then the only record of the cause.
 
+### "Not reachable" is usually not a network problem
+
+Exposure is a separate record, not a field on the sandbox, so `sandbox get` omits
+it entirely when none exists rather than showing it as empty. Absence of a
+`Hostname` row therefore means **no public route exists**, not that the CLI
+declined to print one. `runcloud sandbox domain list <id>` states it outright and
+names the fix. A sandbox created without `--expose` is unreachable from outside
+however healthy the workload is.
+
+When a route does exist and the port still refuses, the guest is usually bound to
+`127.0.0.1` rather than `0.0.0.0`, which is invisible from outside and looks
+identical to a dead app.
+
 ## Guardrails
 
 - Destroy every sandbox created during a task unless the user explicitly asks