instabox 0.4.1 → 0.4.2

package/README.md

@@ -4,7 +4,9 @@
 npx instabox@latest
 ```
 
-Signs you in to instabox in your browser (first run only; Google by default, `--github` for GitHub), lets you pick one of your boxes or start a new one (no boxes yet: a new one, no question; `--box NAME` skips the question), installs the `instabox` CLI already signed in (macOS/Linux; skip with `--no-cli`), installs the agent skills from [`../skills`](../skills) into `~/.claude/skills` and `~/.agents/skills` (skip with `--no-skills`), and drops you into the box over SSH. `npx instabox@latest sh` does the same.
+Signs you in to instabox in your browser (first run only; Google by default, `--github` for GitHub), lets you pick one of your boxes or start a new one (no boxes yet: a new one, no question; `--box NAME` skips the question), installs the `instabox` CLI already signed in or updates an out-of-date one (macOS/Linux; skip with `--no-cli`), installs or updates the agent skills from [`../skills`](../skills) in `~/.claude/skills` and `~/.agents/skills` (skip with `--no-skills`), and drops you into the box over SSH. `npx instabox@latest sh` does the same.
+
+Google and GitHub sign-ins are separate instabox accounts, each with its own boxes. The CLI's own `instabox login` signs in with GitHub by default (`--provider google` for Google), so when the CLI needs a new sign-in, `instabox login --provider google` keeps you in the account you used here with Google.
 
 Any other command line is the instabox CLI's ([`cmd/instabox`](../cmd/instabox)): `npx instabox@latest ls` runs `instabox ls`, installing the CLI first if it is missing.
 
@@ -12,6 +14,8 @@ Any other command line is the instabox CLI's ([`cmd/instabox`](../cmd/instabox))
 
 - `bin/instabox.mjs` runs instabox's loopback sign-in (RFC 8252 + PKCE) and saves the tokens where the CLI keeps its own, `~/.config/instabox/credentials.json`, so both are signed in at once. There is one copy on purpose: the server rotates refresh tokens and ends the session when a rotated one comes back.
 - The box list is `instabox ls`: running boxes first, then newest. A suspended or stopped box is resumed or started; its settings (timeout, auto-suspend) are left alone. Without a terminal to ask (an agent running it), it lists the boxes, installs the CLI and skills, and stops; `--box NAME` or `instabox create` takes it from there.
+- An installed CLI is checked against what the server's `/install.sh` would install: the binary's sha256 against the server's `/dl/SHA256SUMS` (release builds are named after a commit, so their versions do not sort). One the server no longer serves is replaced in place through the same installer; a development build (`instabox dev`, or `-dirty`) is left alone with a one-line notice of the install command.
+- Skills are written only over copies marked `installed-by: instabox`; the output says which were installed, updated, already up to date, or kept because they are the user's own.
 - The bin is also called `instabox`, so `lib/cli.mjs` finds the real CLI the way the insta CLI does: PATH without `node_modules` dirs and without links back to this script, then the installer's own targets.
 - `prepack` copies `../skills` into the package; every skill there ships on the next publish.
 
@@ -22,7 +26,7 @@ npm ci
 npm test
 npm run format:check
 npm pack            # copies ../skills, then builds instabox-<version>.tgz
-npx --package=./instabox-0.4.0.tgz instabox --help
+npx --package=./instabox-0.4.2.tgz instabox --help
 ```
 
 `INSTABOX_API_URL` points it at another instabox server.

package/bin/instabox.mjs

@@ -2,7 +2,17 @@
 // npx instabox@latest: box + CLI + skills + SSH in; any other command goes to the instabox CLI.
 import { spawn, spawnSync } from 'node:child_process';
 import { createHash, randomBytes } from 'node:crypto';
-import { mkdtempSync, readFileSync, writeFileSync, rmSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import {
+  accessSync,
+  constants as fsConstants,
+  mkdtempSync,
+  readFileSync,
+  writeFileSync,
+  rmSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+} from 'node:fs';
 import http from 'node:http';
 import { tmpdir, homedir } from 'node:os';
 import { join, dirname } from 'node:path';
@@ -10,7 +20,7 @@ import { createInterface } from 'node:readline/promises';
 import { fileURLToPath } from 'node:url';
 import { createClient } from '../lib/api.mjs';
 import { orderBoxes, parseChoice } from '../lib/boxes.mjs';
-import { boxFlag, findCli, installCli, isOnboarding, runCli } from '../lib/cli.mjs';
+import { boxFlag, checkCli, findCli, installCli, installCommand, isOnboarding, real, runCli } from '../lib/cli.mjs';
 import { callbackHandler } from '../lib/login.mjs';
 import { loadCredentials, saveCredentials } from '../lib/credentials.mjs';
 
@@ -43,8 +53,9 @@ function usage() {
   npx instabox@latest               sign in (first time), pick one of your boxes or start a new
                                     one, SSH into it, and install the instabox CLI and agent skills
       --box NAME                    go straight to that box instead of asking
-      --github                      sign in with GitHub instead of Google
-      --no-cli                      do not install the instabox CLI
+      --github                      sign in with GitHub instead of Google (a separate account;
+                                    instabox login uses GitHub, --provider google for Google)
+      --no-cli                      do not install or update the instabox CLI
       --no-skills                   do not install the instabox agent skills
   npx instabox@latest <command>     run an instabox CLI command (instabox help lists them)
 `);
@@ -184,8 +195,8 @@ async function waitOp(op) {
   return op;
 }
 
-// The box to enter, null for a new one, or { listed: <name> } when there is no terminal to ask
-// which one; the name is the box the list puts first, so the hint below is ready to paste.
+// The box to enter, null for a new one, or { listed: true } when there is no terminal to ask
+// which one (an agent running it): the boxes are listed and nothing is picked for it.
 async function chooseBox() {
   const { machines = [] } = await client
     .call('GET', '/v1/machines?limit=100')
@@ -202,7 +213,7 @@ async function chooseBox() {
       `    ${ask ? `${i + 1}) ` : ''}${b.name.padEnd(w)}  ${b.state.padEnd(9)} ${dim(`${b.template?.id || ''}  created ${new Date(b.createdAt).toLocaleString()}`)}`,
     ),
   );
-  if (!ask) return { listed: boxes[0].name };
+  if (!ask) return { listed: true };
   console.log(`    ${boxes.length + 1}) ${green('+ new box')}`);
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
@@ -248,7 +259,31 @@ async function newBox() {
 // Runs while the box starts; never fatal. Returns a line to print, or null.
 async function ensureCli() {
   if (process.argv.includes('--no-cli')) return null;
-  if (findCli()) return `instabox CLI already installed ${dim('· try')} instabox ls`;
+  const found = findCli();
+  // The installer is a sh script: on Windows an existing CLI is only reported, never checked.
+  if (found && process.platform === 'win32') return `instabox CLI already installed ${dim('· try')} instabox ls`;
+  if (found) {
+    const { state, version } = await checkCli(found, API);
+    const v = version ? ` ${version}` : '';
+    if (state === 'current') return `instabox CLI${v} is up to date ${dim('· try')} instabox ls`;
+    if (state === 'dev')
+      return `instabox CLI at ${found} is a development build (${version}), left as is ${dim('· for the release:')} ${installCommand(API)}`;
+    if (state === 'unknown')
+      return `instabox CLI${v} already installed, could not check for an update ${dim('· to update:')} ${installCommand(API)}`;
+    // stale: replace it where it is, the way a first install does. Through a symlink, replace
+    // the file it points to, so the link (and whatever manages it) stays as it was.
+    const dir = dirname(real(found));
+    try {
+      accessSync(dir, fsConstants.W_OK);
+    } catch {
+      // Installing anywhere else would leave the old copy first on PATH.
+      return `instabox CLI${v} at ${found} is out of date and ${dir} is not writable ${dim('· to update it there:')} ${installCommand(API, dir)}`;
+    }
+    const r = await installCli(API, { dir });
+    if (r.error)
+      return `instabox CLI${v} is out of date and could not be updated ${dim(`(${r.error}) · to update:`)} ${installCommand(API)}`;
+    return `instabox CLI updated${v ? ` from${v}` : ''}${r.version ? ` to ${r.version}` : ''} at ${found} ${dim('· try')} instabox ls`;
+  }
   if (process.platform === 'win32') return null;
   const r = await installCli(API);
   if (r.error) return `instabox CLI not installed ${dim(`(${r.error})`)}`;
@@ -270,21 +305,39 @@ function installSkills() {
     return null;
   }
   const roots = [join(homedir(), '.claude', 'skills'), join(homedir(), '.agents', 'skills')];
-  const done = new Set();
+  // A skill counts as updated if any of its copies changed, else installed if one was new.
+  const outcome = new Map();
+  const rank = { unchanged: 0, installed: 1, updated: 2 };
+  const kept = new Set();
   for (const root of roots) {
     for (const n of names) {
       const dest = join(root, n, 'SKILL.md');
       try {
-        if (existsSync(dest) && !readFileSync(dest, 'utf8').includes('installed-by: instabox')) continue;
-        mkdirSync(join(root, n), { recursive: true });
-        writeFileSync(dest, readFileSync(join(src, n, 'SKILL.md')));
-        done.add(n);
+        const body = readFileSync(join(src, n, 'SKILL.md'), 'utf8');
+        let what = 'installed';
+        if (existsSync(dest)) {
+          const old = readFileSync(dest, 'utf8');
+          if (!old.includes('installed-by: instabox')) {
+            kept.add(n);
+            continue;
+          }
+          what = old === body ? 'unchanged' : 'updated';
+        }
+        if (what !== 'unchanged') {
+          mkdirSync(join(root, n), { recursive: true });
+          writeFileSync(dest, body);
+        }
+        if (rank[what] > (rank[outcome.get(n)] ?? -1)) outcome.set(n, what);
       } catch {}
     }
   }
-  return done.size
-    ? `agent skills installed: ${[...done].join(', ')} ${dim('(~/.claude/skills, ~/.agents/skills)')}`
-    : null;
+  const of = (what) => names.filter((n) => outcome.get(n) === what);
+  const parts = [];
+  if (of('updated').length) parts.push(`updated ${of('updated').join(', ')}`);
+  if (of('installed').length) parts.push(`installed ${of('installed').join(', ')}`);
+  if (of('unchanged').length) parts.push(`${of('unchanged').join(', ')} already up to date`);
+  if (kept.size) parts.push(`kept your own ${[...kept].join(', ')}`);
+  return parts.length ? `agent skills: ${parts.join('; ')} ${dim('(~/.claude/skills, ~/.agents/skills)')}` : null;
 }
 
 // Waits for the CLI install started earlier, installs the skills, and prints a line for each.
@@ -308,9 +361,8 @@ async function sh() {
   const picked = await chooseBox();
   if (picked?.listed) {
     await reportInstalls(cli);
-    console.log(
-      `\n  Which box? ${bold(`npx instabox@latest --box ${picked.listed}`)} enters it, ${bold('instabox create --name NAME')} starts a new one.\n`,
-    );
+    console.log(`\n  New box: ${bold('instabox create --name NAME')}`);
+    console.log(`  Or enter one listed above: ${bold('npx instabox@latest --box NAME')}\n`);
     return;
   }
   // Only entering a box needs OpenSSH; the list-and-stop path above runs without it.

package/lib/cli.mjs

@@ -1,6 +1,7 @@
 // The Go instabox CLI: find it, install it, hand it the command line.
-import { spawn, spawnSync } from 'node:child_process';
-import { realpathSync, statSync } from 'node:fs';
+import { execFile, spawn, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createReadStream, realpathSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { delimiter, join, sep } from 'node:path';
 
@@ -24,7 +25,7 @@ export function boxFlag(args) {
   return eq ? eq.slice('--box='.length) : null;
 }
 
-const real = (p) => {
+export const real = (p) => {
   try {
     return realpathSync(p);
   } catch {
@@ -65,11 +66,73 @@ export function findCli({ env = process.env, self = process.argv[1] } = {}) {
 // The URL is "$1", never script text; a failed download stops before sh runs anything.
 const INSTALL = 's=$(curl -fsSL "$1/install.sh") && printf \'%s\\n\' "$s" | sh';
 
-// path is null, never a bare `instabox` that could resolve back to this script.
-export function installCli(api) {
+// The command a person runs to install or update the CLI themselves; with dir, one that puts it
+// in that directory (for a directory they cannot write to without sudo).
+export const installCommand = (api, dir) =>
+  dir ? `curl -fsSL ${api}/install.sh | sudo env INSTABOX_INSTALL_DIR=${dir} sh` : `curl -fsSL ${api}/install.sh | sh`;
+
+// What `instabox --version` prints after "instabox ", or null when it does not run. Async, so a
+// slow or hung binary does not hold up the rest of onboarding.
+export function cliVersion(path) {
+  return new Promise((resolve) => {
+    execFile(path, ['--version'], { encoding: 'utf8', timeout: 10_000 }, (err, stdout) => {
+      if (err) return resolve(null);
+      const m = String(stdout)
+        .trim()
+        .match(/^instabox (\S+)$/);
+      resolve(m ? m[1] : null);
+    });
+  });
+}
+
+// The file's sha256, streamed: the CLI is tens of MB and this runs while the box starts.
+function sha256File(path) {
+  return new Promise((resolve, reject) => {
+    const h = createHash('sha256');
+    createReadStream(path)
+      .on('error', reject)
+      .on('data', (d) => h.update(d))
+      .on('end', () => resolve(h.digest('hex')));
+  });
+}
+
+// Whether the CLI at path is the build the server's /install.sh would install. Release builds
+// are named after a commit (scripts/build-release.sh), which says nothing about which is newer,
+// so the check is by content: the binary's sha256 against the server's SHA256SUMS.
+//   current: one of the server's builds
+//   dev:     a local build (`go build` leaves "dev"; build-cli.sh marks a dirty tree "-dirty"),
+//            which is not ours to replace
+//   stale:   a release build the server no longer serves
+//   unknown: the CLI does not run, or SHA256SUMS could not be read
+export async function checkCli(path, api, { fetch = globalThis.fetch } = {}) {
+  const version = await cliVersion(path);
+  if (!version) return { state: 'unknown', version };
+  if (version === 'dev' || version.endsWith('-dirty')) return { state: 'dev', version };
+  let sums;
+  try {
+    const res = await fetch(`${api}/dl/SHA256SUMS`, { signal: AbortSignal.timeout(10_000) });
+    if (!res.ok) return { state: 'unknown', version };
+    sums = new Set((await res.text()).match(/\b[0-9a-f]{64}\b/g) || []);
+  } catch {
+    return { state: 'unknown', version };
+  }
+  if (!sums.size) return { state: 'unknown', version };
+  let mine;
+  try {
+    mine = await sha256File(path);
+  } catch {
+    return { state: 'unknown', version };
+  }
+  return { state: sums.has(mine) ? 'current' : 'stale', version };
+}
+
+// path is null, never a bare `instabox` that could resolve back to this script. dir replaces the
+// CLI in that directory (INSTABOX_INSTALL_DIR), so an update lands where the old one is found.
+export function installCli(api, { dir } = {}) {
   return new Promise((resolve) => {
     let out = '';
-    const p = spawn('sh', ['-c', INSTALL, 'sh', api], { stdio: ['ignore', 'pipe', 'pipe'] });
+    const env = dir ? { ...process.env, INSTABOX_INSTALL_DIR: dir } : process.env;
+    const p = spawn('sh', ['-c', INSTALL, 'sh', api], { stdio: ['ignore', 'pipe', 'pipe'], env });
     p.stdout.on('data', (d) => {
       out += d;
     });
@@ -79,8 +142,10 @@ export function installCli(api) {
     p.on('error', (e) => resolve({ error: e.message }));
     p.on('close', (code) => {
       if (code !== 0) return resolve({ error: out.trim().split('\n').pop() || 'installer failed' });
+      const installed = out.match(/^Installed (.+) \(([^()]*), sha256 [0-9a-f]+\)$/m) || [];
       resolve({
-        path: (out.match(/^Installed (.+) \([^()]*, sha256 [0-9a-f]+\)$/m) || [])[1] || findCli(),
+        path: installed[1] || findCli(),
+        version: installed[2]?.replace(/^instabox /, '') || null,
         pathHint: (out.match(/export PATH="[^"]+"/) || [])[0] || null,
       });
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instabox",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "A cloud box for your coding agent, the instabox CLI and its agent skills in one command: npx instabox@latest",
   "type": "module",
   "bin": {

package/skills/instabox/SKILL.md

@@ -13,11 +13,23 @@ An instabox sandbox is a Linux VM (Debian, user `dev`, sudo). It has a root disk
 
 ```sh
 instabox whoami              # who is signed in (fails if nobody)
-instabox login               # browser sign-in (GitHub); --provider google for Google
+instabox login               # browser sign-in with GitHub; --provider google for Google
 ```
 
+A GitHub sign-in and a Google sign-in are separate accounts with separate boxes, so sign in the way the user did. `npx instabox@latest` signs in with Google unless given `--github`, and the CLI shares its sign-in.
+
 For CI or an agent without a browser, use an API key instead: `export INSTABOX_API_KEY=ibk_...` (the user creates it on the dashboard's API Keys page). Never print, commit or log a key.
 
+## Templates
+
+`universal` is the default, so `create` needs no `--template` for ordinary work. It is Debian with git, gh, Node.js 22, Python (uv), Go, Rust, a C toolchain, Docker, Claude Code and Codex; a desktop (VNC, Chromium) installs itself the first time it is used. Pick another template only for its one purpose:
+
+- `agent-browser`: universal with the desktop already installed, for browsing or driving a GUI from the start.
+- `herdr`: for the herdr client.
+- `orca`: for Orca desktop and mobile.
+
+`instabox templates` lists the ones this server offers.
+
 ## Everyday commands
 
 ```sh
@@ -35,13 +47,33 @@ instabox rm work                                # delete the box
 ```
 
 - Names or IDs (`m_...`) both work wherever `<id-or-name>` is accepted.
-- `create` options: `--template T` or `--snapshot S`, `--vcpus N`, `--mem-mib N`, `--disk-gib N`, `--meta K=V`, `--no-wait`.
-- `exec` returns the command's exit code; add `--timeout S` for long jobs and `--stdin` to pipe input.
-- Prefer `exec` over `ssh` when you (an agent) need output; use `ssh` only for interactive work the user will drive.
-- A public URL for a dev server in the box: `instabox preview expose work --port 3000`.
+- `create` options: `--template T` or `--snapshot S`, `--timeout D [--on-timeout pause|kill]`, `--meta K=V`, `--no-vault`, `--no-wait`. Every box is the same size (`instabox usage` shows it); there are no size flags.
+- Use `exec` to run a command and read its output, and `ssh` for an interactive shell.
+- `exec` returns the command's exit code and takes `--stdin` to pipe input. It stops the command after `--timeout` seconds: 60 by default, 600 at most. Run anything longer (installs, builds, test suites) over SSH, which has no time limit and also returns the exit code: `instabox ssh work -- 'cd /data/workspace/app && npm ci'`.
+- The box's HOME has `MACHINE.md` (which box it is, its size, what survives a stop, the installed tools) and `AGENTS.md`. Both are worth reading before working in the box; they appear a moment after it starts.
+- A public URL for a web server in the box: `instabox port publish work 3000` prints it (`instabox port ls`, `instabox port unpublish work 3000`). The URL works while the box runs.
+
+## Vault: the user's secrets in every box
+
+The user's Vault holds their secrets (API keys for model providers, a `.env`, a service-account file) on the server and writes them into every box of theirs when it boots or resumes: `env` items as environment variables of every login shell (so of `instabox exec` too), `file` items as files under HOME.
+
+```sh
+instabox vault show work                 # what the box gets (names, never values) and the last write
+instabox vault push work                 # write the current items into a running box now
+instabox vault set ANTHROPIC_API_KEY     # value from stdin, or prompted without echo (sign-in only)
+instabox vault set-file .config/svc.json --from ./svc.json
+instabox vault ls; instabox vault rm NAME
+instabox create --name tenant --no-vault # a box for someone else: never gets the user's items
+```
+
+- Before asking the user for a credential, check names with `instabox vault show <box>`. Inside the box, use silent presence checks: `test "${NAME+x}" = x` for an environment variable (replace `NAME` with its name), or `test -f "$HOME/.config/svc.json"` for a credential file. Exit status 0 means present, 1 means absent. Never print credential values or read credential-file contents into agent output, chat or logs.
+- A changed item reaches the box at its next boot or resume, or at once with `vault push` (a changed `env` item reaches new shells only).
+- A box made for another person or tenant must be created with `--no-vault` (`vault: false` in the API): anything running in it can read what the Vault writes. This is for good; `instabox start|resume <box> --no-vault` does the same to an existing box.
+- An item's selector (`--selector K=V`) limits it to boxes whose metadata has those labels: create the box with the `--meta` the user's items expect.
+- Managing items needs a sign-in; an API key cannot read, create or change them. Never ask for a secret's value to put it somewhere else.
 
 ## Habits
 
 - Give boxes a `--timeout` so forgotten ones pause or delete themselves.
-- Check `instabox ls` before creating, and reuse a running box with the same purpose.
+- When the user asks for a new box, create one, with a name `instabox ls` does not already show. Offer an existing box only when they want to continue earlier work in it.
 - `instabox usage` shows storage use and limits. A quota error means delete or stop something; do not retry the same create in a loop.

package/skills/instabox-migrate/SKILL.md

@@ -24,17 +24,17 @@ Before starting, tell the user plainly:
 ```bash
 instabox whoami                                  # signed in? otherwise: instabox login
 git rev-parse --show-toplevel                    # must be inside a git repo
-du -sh "$(git rev-parse --show-toplevel)/.git"   # large repos: add --disk-gib to create
+du -sh "$(git rev-parse --show-toplevel)/.git"   # must fit on /data (instabox usage shows the size)
 instabox ls                                      # pick a box name that is not taken
 ```
 
 If `.git` is a file (a git worktree or submodule checkout), move the main checkout instead. Submodules: their history comes along inside `.git/modules`; run `git submodule update --init` on the box. Uncommitted changes inside a submodule are not copied.
 
 ```bash
-instabox create --name <box> --vcpus 4 --mem-mib 8192
+instabox create --name <box>
 ```
 
-Box names are lowercase letters, digits and `-`. The default template (`universal`) has git, node/npm, python3/uv, go, cargo and docker. Do not add a kill timeout: this box is meant to stay (offer `instabox timeout <box> 8h --on-timeout pause` if the user wants it to pause itself).
+Box names are lowercase letters, digits and `-`. Every box is the same size. The default template (`universal`) has git, node/npm, python3/uv, go, cargo and docker. Do not add a kill timeout: this box is meant to stay (offer `instabox timeout <box> 8h --on-timeout pause` if the user wants it to pause itself).
 
 ## 2. Copy the repo and history
 

package/skills/instabox-snapshots/SKILL.md

@@ -18,7 +18,7 @@ instabox snapshot save work --name work-ready --description "deps installed, rep
 - A running box is saved live, without stopping it: the snapshot is `pending` in `instabox snapshot ls` until its disks finish uploading (`--no-wait` returns at once).
 - Do not stop the box first: `stop` ends every process in it. A live snapshot is like a clean power cut: what is on disk is kept, what programs hold only in memory is not. Only if the server answers that this box must be stopped, or if a program must write its data to disk first (a database mid-write), run `instabox stop work`, save, then `instabox start work`.
 - `--root-only` saves just the root disk (smaller; `/data` is not included).
-- A snapshot includes credentials stored under HOME (gh, Claude, Codex, git, SSH keys). Sign out of tools or remove secrets first if the snapshot will be shared or kept long.
+- A snapshot includes credentials stored under HOME (gh, Claude, Codex, git, SSH keys), and the Vault's `file` items (its `env` items live on tmpfs and are not saved). Sign out of tools or remove secrets first if the snapshot will be shared or kept long.
 - Pick names that say what is inside (`node20-playwright`, `api-db-seeded`); names must be unique among your snapshots.
 
 ## Load