@pirol/nido 0.3.0 → 0.5.0

package/README.md

@@ -76,6 +76,7 @@ Instead of an agent, run any command. It needs no key:
 | `secrets` | Names of stored secrets, never values |
 | `network` | Hosts the sandbox may reach on port 443; everything else is blocked |
 | `storage` | Storage volumes, mounted at `/data/<name>` |
+| `from` | Template a new sandbox starts from (`nido save`) |
 | `output` | Folder that comes back after the run; default `output/` |
 
 ## Storage
@@ -83,7 +84,7 @@ Instead of an agent, run any command. It needs no key:
 Keep large data in storage, independently of sandboxes:
 
 ```bash
-nido storage put ./data my-data   # upload straight to Cloud Storage in Frankfurt
+nido storage put ./data my-data   # upload straight to storage in Frankfurt
 nido storage ls                   # volumes with file count and size
 nido storage ls my-data           # files in one volume
 nido storage rm my-data           # only once no sandbox uses it
@@ -93,6 +94,27 @@ Add `"storage": ["my-data"]` to `nido.json` (or `nido create shop --storage my-d
 sandbox reads and writes the data at `/data/my-data`, without copying. Volumes are attached when a
 sandbox is created; after changing `storage`, run `nido run --fresh`.
 
+## Backups and templates
+
+Storage is safe: it lives in Frankfurt, independently of any sandbox. A sandbox's own folder
+`/sandbox` is fast but local, and can be lost, for example when the machine it runs on is
+replaced. nido backs it up to your storage whenever the sandbox stops.
+
+```bash
+nido stop shop                  # backs up /sandbox, then stops (--no-backup to skip)
+nido restore shop               # last backup back into a running sandbox
+nido save shop base             # save the work as template "base"
+nido create other --from base   # or "from": "base" in nido.json
+nido fork shop experiment       # new sandbox with the work of a running one
+nido save ls
+nido save rm base
+```
+
+A backup holds only what changed since the sandbox was created. If the folder was lost, `nido start`
+restores the last backup by itself. Backups count as storage.
+
+`nido rm` keeps the backup, and `nido ls` lists it. `nido rm <name> --backup` deletes it too.
+
 ## Secrets
 
 ```bash
@@ -129,7 +151,7 @@ Paths inside a sandbox must be below `/sandbox`.
 - No interactive shell yet; use `nido exec`.
 - The agent runs in the foreground. If the connection drops, `nido pull` fetches what is already
   in `output/`.
-- No backups or templates of a sandbox yet. Keep anything important in `output/` or in storage.
+- A backup holds at most 5 GB, and an account keeps up to 20 templates. Keep larger data in storage.
 
 ## Development
 

package/dist/api.js

@@ -69,11 +69,33 @@ export class Api {
     create(spec) {
         return this.json("POST", "/v1/sandboxes", spec);
     }
-    remove(name) {
-        return this.json("DELETE", `/v1/sandboxes/${encodeURIComponent(name)}`);
+    /** The backup stays in storage and comes back, unless deleteBackup is set. */
+    async remove(name, opts = {}) {
+        const query = opts.deleteBackup ? "?backup=delete" : "";
+        const res = await this.json("DELETE", `/v1/sandboxes/${encodeURIComponent(name)}${query}`);
+        return res?.backup ?? null;
     }
-    stop(name) {
-        return this.json("POST", `/v1/sandboxes/${encodeURIComponent(name)}/stop`);
+    /** All backups, those of removed sandboxes included. */
+    async backups() {
+        return (await this.json("GET", "/v1/backups")).backups;
+    }
+    /** Backs /sandbox up into storage first, unless backup is false. */
+    async stop(name, opts = {}) {
+        const query = opts.backup === false ? "?backup=false" : "";
+        const res = await this.json("POST", `/v1/sandboxes/${encodeURIComponent(name)}/stop${query}`);
+        return res?.backup ?? null;
+    }
+    async restore(name) {
+        return (await this.json("POST", `/v1/sandboxes/${encodeURIComponent(name)}/restore`)).restored;
+    }
+    async templates() {
+        return (await this.json("GET", "/v1/templates")).templates;
+    }
+    saveTemplate(name, sandbox) {
+        return this.json("PUT", `/v1/templates/${encodeURIComponent(name)}`, { sandbox });
+    }
+    removeTemplate(name) {
+        return this.json("DELETE", `/v1/templates/${encodeURIComponent(name)}`);
     }
     start(name) {
         return this.json("POST", `/v1/sandboxes/${encodeURIComponent(name)}/start`);
@@ -171,7 +193,7 @@ export class Api {
         return this.json("DELETE", `/v1/storage/${encodeURIComponent(name)}`);
     }
 }
-/** Sends a local file to an upload URL from storageUploads (straight to Cloud Storage). */
+/** Sends a local file to an upload URL from storageUploads (straight to the storage). */
 export function putFile(url, file, size) {
     return new Promise((resolve, reject) => {
         const req = request(url, { method: "PUT", headers: { "content-length": size } }, (res) => {

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { readFileSync, realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { copy, createSandbox, exec, init, list, login, logout, pull, runFolder, secretList, secretRemove, secretSet, simple, whoami, } from "./commands.js";
+import { copy, createSandbox, exec, fork, init, list, login, logout, pull, remove, restore, runFolder, save, secretList, secretRemove, secretSet, simple, whoami, } from "./commands.js";
 import { storageLs, storagePut, storageRm } from "./storage.js";
 const HELP = `nido — run agents in isolated sandboxes (closed beta)
 
@@ -15,15 +15,23 @@ Folder workflow
   nido pull                    bring output/ back again
 
 Sandboxes
-  nido create <name> [--image <ref>] [--secret <name>]… [--network <host>]… [--storage <name>]…
+  nido create <name> [--image <ref>] [--secret <name>]… [--network <host>]… [--storage <name>]… [--gpu l4|h100] [--from <template>]
   nido ls                      list your sandboxes
   nido exec <name> -- <cmd>…   run a command
   nido cp <src> <dst>          copy files; write the sandbox side as <name>:<path>
   nido logs <name>             sandbox logs
-  nido stop|start|rm <name>
+  nido stop <name> [--no-backup]  stop; backs /sandbox up to your storage first
+  nido start <name>
+  nido rm <name> [--backup]    remove; the backup stays unless --backup
+  nido restore <name>          put the last backup back into a running sandbox
+  nido fork <from> <new>       new sandbox with the work of a running one
+
+Templates (a sandbox's work, saved in your storage)
+  nido save <sandbox> <template>
+  nido save ls | nido save rm <template>
 
 Storage (lives on without sandboxes, mounted at /data/<name>)
-  nido storage put <folder|file> <name>   upload, straight to Cloud Storage
+  nido storage put <folder|file> <name>   upload, straight to storage
   nido storage ls [name]
   nido storage rm <name>
 
@@ -76,6 +84,8 @@ async function main(argv) {
                 secrets: flags.get("secret") ?? [],
                 network: flags.get("network") ?? [],
                 storage: flags.get("storage") ?? [],
+                gpu: flags.get("gpu")?.[0]?.toLowerCase(),
+                from: flags.get("from")?.[0],
             });
             return 0;
         case "ls":
@@ -87,12 +97,27 @@ async function main(argv) {
             return exec(one("name"), passthrough);
         case "shell":
             throw new Error(`nido shell is not in the beta yet. Use: nido exec ${args[0] ?? "<name>"} -- <command>`);
-        case "logs":
         case "stop":
+            await simple("stop", one("name"), { backup: !flags.has("no-backup") });
+            return 0;
+        case "logs":
         case "start":
-        case "rm":
             await simple(cmd, one("name"));
             return 0;
+        case "rm":
+            await remove(one("name"), { backup: flags.has("backup") });
+            return 0;
+        case "restore":
+            await restore(one("name"));
+            return 0;
+        case "fork":
+            if (args.length !== 2)
+                throw new Error("Usage: nido fork <from> <new>");
+            await fork(args[0], args[1]);
+            return 0;
+        case "save":
+            await save(args);
+            return 0;
         case "cp":
             if (args.length !== 2)
                 throw new Error("Usage: nido cp <src> <dst>  (sandbox side as <name>:<path>)");
@@ -130,7 +155,7 @@ async function storage(args) {
         throw new Error("Usage: nido storage put <folder|file> <name> | nido storage ls [name] | nido storage rm <name>");
     return 0;
 }
-const VALUE_FLAGS = new Set(["image", "secret", "network", "storage"]);
+const VALUE_FLAGS = new Set(["image", "secret", "network", "storage", "gpu", "from"]);
 export function parse(argv) {
     const flags = new Map();
     const args = [];

package/dist/commands.js

@@ -51,18 +51,106 @@ export function init(dir, kind) {
 // ---------------------------------------------------------------- sandboxes
 export async function createSandbox(name, spec) {
     const api = Api.fromConfig();
-    say(`Creating sandbox ${name}…`);
+    const origin = spec.from ? ` from template ${spec.from}` : spec.fork ? ` as a copy of ${spec.fork}` : "";
+    say(`Creating sandbox ${name}${spec.gpu ? ` with a GPU (${spec.gpu})` : ""}${origin}…`);
+    const started = Date.now();
     const info = await api.create({ name, ...spec });
-    say(`Sandbox ${name} ready in ${(info.ready_ms / 1000).toFixed(1)} s`);
+    if (info.phase !== "Ready")
+        await waitForGpu(api, name, info.gpu);
+    say(`Sandbox ${name} ready in ${((Date.now() - started) / 1000).toFixed(1)} s`);
+    if (info.backup) {
+        say(`A removed sandbox ${name} left a backup from ${when(info.backup.at)} (${size(info.backup.bytes)}).`);
+        say(`Put it in with: nido restore ${name}. The next nido stop replaces it.`);
+    }
+}
+/** nido fork: a new sandbox with the changes of a running one. */
+export async function fork(from, to) {
+    await createSandbox(to, { secrets: [], network: [], storage: [], fork: from });
+}
+/** How long nido waits for a GPU node before it gives up (the sandbox stays queued). */
+export const GPU_WAIT_MS = 30 * 60_000;
+/**
+ * Waits until a sandbox is ready. GPU sandboxes need a node of their own,
+ * which takes minutes; an H100 may wait for free capacity. The API answers
+ * at once, so nido asks every few seconds and shows the time.
+ */
+export async function waitUntilReady(get, opts) {
+    const now = opts.now ?? Date.now;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const start = now();
+    for (;;) {
+        const info = await get();
+        if (!info)
+            throw new Error("The sandbox is gone");
+        if (info.phase === "Ready")
+            return info;
+        if (info.phase === "Error" || info.phase === "Failed")
+            throw new Error(`Sandbox ${info.name} failed to start`);
+        const elapsed = now() - start;
+        if (elapsed >= opts.timeoutMs)
+            throw new TimeoutError(info);
+        opts.onTick?.(elapsed);
+        await sleep(opts.intervalMs ?? 3000);
+    }
+}
+class TimeoutError extends Error {
+    info;
+    constructor(info) {
+        super(`Sandbox ${info.name} is still ${info.phase}`);
+        this.info = info;
+    }
+}
+async function waitForGpu(api, name, gpu = "GPU") {
+    const tty = process.stderr.isTTY;
+    try {
+        await waitUntilReady(() => api.get(name), {
+            timeoutMs: GPU_WAIT_MS,
+            onTick: (ms) => {
+                const line = `Waiting for a free ${gpu.toUpperCase()} node… ${clock(ms)}`;
+                if (tty)
+                    process.stderr.write(`\r${line}`);
+                else if (ms % 60_000 < 3000)
+                    say(line);
+            },
+        });
+    }
+    catch (err) {
+        if (err instanceof TimeoutError) {
+            throw new Error(`No ${gpu.toUpperCase()} free after ${GPU_WAIT_MS / 60_000} minutes. ${name} stays queued and starts when one is free. ` +
+                `Check with: nido ls. Remove it with: nido rm ${name}`);
+        }
+        throw err;
+    }
+    finally {
+        if (tty)
+            process.stderr.write("\r\x1b[K");
+    }
+}
+function clock(ms) {
+    const s = Math.floor(ms / 1000);
+    return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}`;
 }
 export async function list() {
-    const sandboxes = await Api.fromConfig().list();
+    const api = Api.fromConfig();
+    const [sandboxes, backups] = await Promise.all([api.list(), api.backups()]);
+    // Backups stay after nido rm. They cost storage, so they show up here.
+    const left = backups.filter((b) => !sandboxes.some((s) => s.name === b.name));
     if (!sandboxes.length)
-        return say("No sandboxes. Create one with: nido run or nido create <name>");
-    const width = Math.max(4, ...sandboxes.map((s) => s.name.length));
-    process.stdout.write(`${"NAME".padEnd(width)}  ${"CREATED".padEnd(19)}  PHASE\n`);
-    for (const s of sandboxes)
-        process.stdout.write(`${s.name.padEnd(width)}  ${s.created.padEnd(19)}  ${s.phase}\n`);
+        say("No sandboxes. Create one with: nido run or nido create <name>");
+    else {
+        const width = Math.max(4, ...sandboxes.map((s) => s.name.length));
+        process.stdout.write(`${"NAME".padEnd(width)}  ${"GPU".padEnd(4)}  ${"CREATED".padEnd(19)}  ${"PHASE".padEnd(9)}  LAST BACKUP\n`);
+        for (const s of sandboxes) {
+            const backup = s.backup ? `${when(s.backup.at)}, ${size(s.backup.bytes)}` : "-";
+            process.stdout.write(`${s.name.padEnd(width)}  ${(s.gpu ?? "-").padEnd(4)}  ${s.created.padEnd(19)}  ${s.phase.padEnd(9)}  ${backup}\n`);
+        }
+    }
+    if (!left.length)
+        return;
+    process.stdout.write(`\nBackups of removed sandboxes (delete with: nido rm <name> --backup)\n`);
+    const width = Math.max(4, ...left.map((b) => b.name.length));
+    for (const b of left)
+        process.stdout.write(`${b.name.padEnd(width)}  ${when(b.at)}, ${size(b.bytes)}\n`);
 }
 export async function exec(name, command) {
     return Api.fromConfig().exec(name, command, {
@@ -70,17 +158,90 @@ export async function exec(name, command) {
         onErr: (text) => process.stderr.write(text),
     });
 }
-export async function simple(action, name) {
+export async function simple(action, name, opts = {}) {
     const api = Api.fromConfig();
-    if (action === "rm")
-        await api.remove(name);
-    if (action === "stop")
-        await api.stop(name);
-    if (action === "start")
-        await api.start(name);
+    if (action === "stop") {
+        if (opts.backup !== false)
+            say(`Backing up ${name}…`);
+        const backup = await api.stop(name, opts);
+        return say(stopMessage(name, backup, opts.backup !== false));
+    }
+    if (action === "start") {
+        const info = await api.start(name);
+        if (info.phase !== "Ready")
+            await waitForGpu(api, name, info.gpu);
+        if (info.restored) {
+            say(`The workspace of ${name} was lost: the machine it ran on was replaced.`);
+            say(`Restored the backup from ${when(info.restored.at)} (${size(info.restored.bytes)}).`);
+        }
+    }
     if (action === "logs")
         return void process.stdout.write(await api.logs(name));
-    say(`${action === "rm" ? "Removed" : action === "stop" ? "Stopped" : "Started"} ${name}`);
+    say(`Started ${name}`);
+}
+/** nido rm: the backup stays in storage, unless --backup. */
+export async function remove(name, opts) {
+    const kept = await Api.fromConfig().remove(name, { deleteBackup: opts.backup });
+    say(removeMessage(name, kept, opts.backup));
+}
+export function removeMessage(name, kept, deleteBackup) {
+    if (deleteBackup)
+        return `Removed ${name} and its backup`;
+    if (!kept)
+        return `Removed ${name}`;
+    return `Removed ${name}. Its backup from ${when(kept.at)} (${size(kept.bytes)}) stays in your storage. Delete it with: nido rm ${name} --backup`;
+}
+export function stopMessage(name, backup, wanted) {
+    if (!wanted)
+        return `Stopped ${name}, without a backup`;
+    if (!backup)
+        return `Stopped ${name}. Nothing changed since the last backup.`;
+    return `Stopped ${name}. Backed up ${size(backup.bytes)} to your storage.`;
+}
+/** nido restore: the last backup back into a running sandbox. */
+export async function restore(name) {
+    const backup = await Api.fromConfig().restore(name);
+    say(`Restored the backup of ${name} from ${when(backup.at)} (${size(backup.bytes)})`);
+}
+/** nido save: templates. */
+export async function save(args) {
+    const api = Api.fromConfig();
+    const [a, b] = args;
+    if (a === "ls" && !b) {
+        const templates = await api.templates();
+        if (!templates.length)
+            return say("No templates. Save one with: nido save <sandbox> <template>");
+        const width = Math.max(8, ...templates.map((t) => t.name.length));
+        process.stdout.write(`${"TEMPLATE".padEnd(width)}  ${"SAVED".padEnd(16)}  SIZE\n`);
+        for (const t of templates)
+            process.stdout.write(`${t.name.padEnd(width)}  ${when(t.at).padEnd(16)}  ${size(t.bytes)}\n`);
+        return;
+    }
+    if (a === "rm" && b) {
+        await api.removeTemplate(b);
+        return say(`Removed template ${b}`);
+    }
+    if (a && b && a !== "ls" && a !== "rm") {
+        say(`Saving ${a} as template ${b}…`);
+        const t = await api.saveTemplate(b, a);
+        return say(`Saved template ${b} (${size(t.bytes)}). Start from it with: nido create <name> --from ${b}`);
+    }
+    throw new Error("Usage: nido save <sandbox> <template> | nido save ls | nido save rm <template>");
+}
+/** "2026-11-06T14:05:12Z" as "2026-11-06 14:05" in local time. */
+export function when(iso) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return iso;
+    const p = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+export function size(bytes) {
+    if (bytes < 1024 ** 2)
+        return `${Math.max(bytes / 1024, bytes ? 0.1 : 0).toFixed(1)} KB`;
+    if (bytes < 1024 ** 3)
+        return `${(bytes / 1024 ** 2).toFixed(1)} MB`;
+    return `${(bytes / 1024 ** 3).toFixed(2)} GB`;
 }
 /** nido cp: "shop:/sandbox/x" is in the sandbox, anything else is local. */
 export async function copy(src, dst) {
@@ -163,19 +324,18 @@ async function ensureSandbox(api, m, fresh) {
         info = undefined;
     }
     if (!info) {
-        say(`Creating sandbox ${m.name}…`);
-        const created = await api.create({
-            name: m.name,
+        await createSandbox(m.name, {
             image: m.imageSet ? m.image : undefined,
             secrets: m.secrets,
             network: m.network,
             storage: m.storage,
+            gpu: m.gpu,
+            from: m.from,
         });
-        say(`Sandbox ${m.name} ready in ${(created.ready_ms / 1000).toFixed(1)} s`);
         return true;
     }
     if (info.phase !== "Ready")
-        await api.start(m.name);
+        await simple("start", m.name);
     return false;
 }
 async function upload(api, dir, m, uploaded) {

package/dist/manifest.js

@@ -25,7 +25,7 @@ export function parseManifest(raw, folderName) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw))
         throw new Error(`${MANIFEST} must be an object`);
     const m = raw;
-    const known = ["name", "agent", "task", "command", "image", "files", "secrets", "network", "storage", "output"];
+    const known = ["name", "agent", "task", "command", "image", "files", "secrets", "network", "storage", "gpu", "from", "output"];
     const unknown = Object.keys(m).filter((key) => !known.includes(key) && !key.startsWith("$"));
     if (unknown.length)
         throw new Error(`${MANIFEST}: unknown field ${unknown.map((k) => `"${k}"`).join(", ")}`);
@@ -70,6 +70,8 @@ export function parseManifest(raw, folderName) {
                 throw new Error(`${MANIFEST}: "${name}" in "storage" is not a valid name`);
             return name;
         }),
+        gpu: optionalString(m, "gpu")?.toLowerCase(),
+        from: checkFrom(optionalString(m, "from")),
         output,
     };
 }
@@ -83,6 +85,11 @@ export function sandboxName(input) {
         .replace(/-+$/, "");
     return name || "nest";
 }
+function checkFrom(name) {
+    if (name !== undefined && !isVolumeName(name))
+        throw new Error(`${MANIFEST}: "${name}" in "from" is not a valid template name`);
+    return name;
+}
 /** Storage names, like sandbox names: lowercase letters, digits and dashes, at most 40. */
 export function isVolumeName(name) {
     return /^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$/.test(name);

package/dist/storage.js

@@ -1,5 +1,5 @@
-// nido storage: volumes in Cloud Storage that live independently of
-// sandboxes. Files go straight to Cloud Storage; the API only hands out an
+// nido storage: volumes in object storage that live independently of
+// sandboxes. Files go straight to the storage; the API only hands out an
 // upload URL per file.
 import { existsSync, statSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pirol/nido",
-  "version": "0.3.0",
-  "description": "Run agents in isolated sandboxes. Give it a folder, get results back.",
+  "version": "0.5.0",
+  "description": "Run coding agents and commands in isolated sandboxes in Frankfurt, with the nido CLI.",
   "type": "module",
   "bin": {
     "nido": "dist/cli.js"