runcloud 0.1.25 → 0.1.27

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/login.js

@@ -215,6 +215,31 @@ export async function revokeRunCloudCredential(apiUrl, token) {
             'revoke it from the run.cloud dashboard.');
     }
 }
+export function existingLoginSummary(creds) {
+    const who = creds.account ? ` as ${creds.account}` : '';
+    const expiry = creds.expiresAt < Number.MAX_SAFE_INTEGER
+        ? `, valid until ${new Date(creds.expiresAt * 1000).toLocaleString()}`
+        : '';
+    return `You are already logged in${who} (${creds.apiUrl}${expiry}).`;
+}
+export async function confirmReplaceExistingLogin(creds) {
+    if (!creds)
+        return true;
+    const terminal = acquirePromptIO();
+    if (!terminal)
+        return true;
+    try {
+        console.log(`\n  ${existingLoginSummary(creds)}`);
+        const choice = await select('  Do you want to continue?', [
+            { value: 'keep', label: 'Keep this session', hint: 'nothing to do' },
+            { value: 'again', label: 'Log in again', hint: 'replaces the saved credential' },
+        ], terminal.io);
+        return choice === 'again';
+    }
+    finally {
+        terminal.close();
+    }
+}
 export function registerLogin(program) {
     const isRunCloud = program.name() === 'runcloud';
     const defaultAppUrl = isRunCloud
@@ -265,6 +290,10 @@ export function registerLogin(program) {
                 console.log(`Logged in headlessly. Credentials written for API ${apiUrl}.`);
                 return;
             }
+            if (!(await confirmReplaceExistingLogin(loadCredentials()))) {
+                console.log(`  Keeping the credential at ${credentialsDisplayPath()}\n`);
+                return;
+            }
             if (opts.manual && !isRunCloud) {
                 const { createInterface } = await import('node:readline/promises');
                 const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -303,6 +332,7 @@ export function registerLogin(program) {
                             appUrl: opts.appUrl,
                             expiresAt: Number.MAX_SAFE_INTEGER,
                             revocable: true,
+                            account: email,
                         });
                         console.log(`\n  Signed in as ${email}`);
                         console.log(`  Credential saved to ${credentialsDisplayPath()}\n`);

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = '0.1.25';
+export const CLI_VERSION = '0.1.27';

package/package.json

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