runcloud 0.1.24 → 0.1.26

package/README.md

@@ -34,7 +34,7 @@ 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.
+pick with `--email`, `--google`, `--github`, or `--browser` to skip the prompt.
 
 The token expires — re-run `runcloud login` when a command reports you're logged out.
 
@@ -84,6 +84,8 @@ runcloud sandbox create --disk 80                # request an 80 GiB root filesy
 runcloud sandbox exec <id> npm run build         # run a command inside it
 runcloud sandbox shell <id>                      # interactive shell, streamed over the API
 runcloud sandbox logs <id> --lines 200           # tail its logs
+runcloud sandbox metrics <id> --range 24h        # CPU, memory, network, and disk usage
+runcloud sandbox pause <id>                      # park it; `resume` brings it back warm
 runcloud sandbox list
 runcloud sandbox rm <id>                          # destroy it
 ```
@@ -112,13 +114,21 @@ 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
+### Lifetime, pausing, and a public hostname
 
-A sandbox pauses when idle by default. Tune that with `--idle-pause <seconds>`,
-turn it off with `--persistent`, and publish a guest port at a stable
-`<name>-box.run.cloud` hostname with `--expose`:
+Two clocks stop a sandbox, and the first one bites after five minutes:
+
+- `--timeout <seconds>` — maximum lifetime, wall-clock from boot or the last
+  resume, busy or not. **Defaults to 300**; `0` removes the limit.
+- `--idle-pause <seconds>` — pause after that much inactivity.
+
+Both *pause* rather than destroy. `runcloud sandbox resume <id>` brings a
+sandbox back warm with its filesystem intact, and a paused sandbox is destroyed
+after 48 hours. `--persistent` stops both clocks; `--expose` implies it and
+publishes a guest port at a stable `<name>-box.run.cloud` hostname.
 
 ```bash
+runcloud sandbox create --timeout 3600                      # an hour of wall clock, then pause
 runcloud sandbox create --idle-pause 600                    # pause after 10 idle minutes
 runcloud sandbox create --name my-project --persistent      # never pauses
 runcloud sandbox create --name my-project --expose 3000     # persistent + https://my-project-box.run.cloud
@@ -126,6 +136,10 @@ runcloud sandbox expose <id> --port 8080                    # expose later, or m
 runcloud sandbox get <id>                                   # inspect, including the hostname
 ```
 
+The CLI only sets the timer at create time. To extend it on a running sandbox —
+what a long job or a live agent session needs — call
+`sandbox.setTimeout(id, seconds)` from [`@run-cloud/sdk`](https://www.npmjs.com/package/@run-cloud/sdk).
+
 `--expose` needs `--name` — that name is the hostname prefix, and it is fixed
 once minted.
 
@@ -152,6 +166,48 @@ runcloud sandbox restore <snapshot-id> --name fork   # fork a NEW sandbox from t
 runcloud sandbox snapshot rm <snapshot-id>
 ```
 
+### Secrets
+
+Store secrets in a named group, then attach the group when you create a sandbox:
+
+```bash
+runcloud secret-group create aws --key AWS_ACCESS_KEY_ID --key AWS_SECRET_ACCESS_KEY
+runcloud secret-group create prod --from-dotenv ./.env.production
+runcloud secret-group list
+runcloud secret-group show aws                              # names only, never values
+runcloud secrets set DATABASE_URL --group prod              # hidden prompt, or --stdin
+runcloud secrets set-file sa.json --group prod --path .config/gcloud/sa.json --from-file ./sa.json
+
+runcloud sandbox create --secret-group prod --env LOG_LEVEL=debug
+runcloud sandbox create --secret prod/DATABASE_URL          # one secret out of a group
+runcloud sandbox create --no-secrets                        # state explicitly that it holds none
+```
+
+`--secret-group`, `--secret`, and `--env` are repeatable and **order matters** —
+a later one wins a name collision, and `--env` is applied last.
+
+`runcloud sandbox secrets <id>` re-attaches on a running sandbox. It *replaces*
+the whole set rather than merging, which is how a credential gets revoked:
+passing no flags at all takes them all back.
+
+A value can never be passed as a command argument — it would land in your shell
+history, in `ps` output, and in CI logs. Use a hidden prompt, a file, or stdin.
+
+## Custom images
+
+A sandbox boots an OCI image. Register your own once, then create sandboxes from
+it:
+
+```bash
+runcloud image create --ref python:3.12-slim   # registers, and waits for the build
+runcloud image list
+runcloud image refresh python:3.12-slim        # re-pin the tag to its current upstream digest
+runcloud sandbox create --image python:3.12-slim
+```
+
+Built in: `runcloud/agent-base` (the default), `runcloud/desktop`, and
+`runcloud/box` (the default with `--expose`).
+
 ## Demos
 
 ```bash

package/dist/commands/build.js

@@ -194,6 +194,23 @@ async function waitForBuild(client, buildId, log) {
                 status = event.status;
         }
     }
+    if (status !== 'completed' && status !== 'failed' && status !== 'cancelled') {
+        const deadline = Date.now() + 60 * 60 * 1000;
+        let lastLoggedStatus = status;
+        while (Date.now() < deadline) {
+            const build = (await client.get(`/builds/${buildId}`));
+            const current = typeof build.status === 'string' ? build.status : status;
+            if (current !== lastLoggedStatus) {
+                log(`Build ${buildId} ${current}`);
+                lastLoggedStatus = current;
+            }
+            status = current;
+            if (status === 'completed' || status === 'failed' || status === 'cancelled')
+                return status;
+            await new Promise((resolve) => setTimeout(resolve, 5_000));
+        }
+        throw new Error(`iOS simulator build ${buildId} timed out`);
+    }
     return status;
 }
 async function waitForAndroidApkBuild(client, buildId, log) {

package/dist/commands/desktop.js

@@ -11,11 +11,11 @@ export function desktopRunUrl(project, mode, start = true, platform = 'ios') {
     url.searchParams.set('request', randomUUID());
     return url.toString();
 }
-export async function startDesktopRun(project, mode, platform = 'ios', fetchImpl = fetch) {
+export async function startDesktopRun(project, mode, platform = 'ios', key = 'default', sessionId, fetchImpl = fetch) {
     const response = await fetchImpl(DESKTOP_RUN_START_URL, {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ cwd: resolve(project), key: 'default', mode, platform }),
+        body: JSON.stringify({ cwd: resolve(project), key, mode, platform, ...(sessionId ? { sessionId } : {}) }),
     });
     if (response.ok)
         return;
@@ -38,14 +38,18 @@ export function registerDesktop(program) {
         .requiredOption('--project <path>', 'local Expo project directory')
         .option('--mode <mode>', 'simulator mode: local or remote', 'local')
         .option('--platform <platform>', 'simulator platform: ios or android', 'ios')
+        .option('--key <key>', 'run lane key in the desktop sidecar', 'default')
+        .option('--session-id <id>', 'control-plane session id for session-scoped remote simulator builds')
+        .option('--no-open', 'skip the newly:// opener and call the running sidecar directly')
         .action(async (opts) => {
         if (opts.mode !== 'local' && opts.mode !== 'remote')
             throw new Error('--mode must be local or remote');
         if (opts.platform !== 'ios' && opts.platform !== 'android')
             throw new Error('--platform must be ios or android');
         const url = desktopRunUrl(opts.project, opts.mode, false, opts.platform);
-        openDesktopUrl(url);
-        await startDesktopRun(opts.project, opts.mode, opts.platform);
-        console.log(`Opened Newly and started the ${opts.mode} ${opts.platform} simulator run for ${resolve(opts.project)}`);
+        if (opts.open)
+            openDesktopUrl(url);
+        await startDesktopRun(opts.project, opts.mode, opts.platform, opts.key, opts.sessionId);
+        console.log(`${opts.open ? 'Opened Newly and started' : 'Started'} the ${opts.mode} ${opts.platform} simulator run for ${resolve(opts.project)}`);
     });
 }

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = '0.1.24';
+export const CLI_VERSION = '0.1.26';

package/package.json

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