instabox 0.4.1 → 0.4.3

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; GitHub by default, `--google` for Google), 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.
+
+A GitHub and a Google sign-in are separate instabox accounts, each with its own boxes, so this and the CLI's own `instabox login` default to the same provider, GitHub. With `--google`, the account is the Google one, and the CLI reaches it with `instabox login --provider 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.3.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';
 
@@ -24,7 +34,10 @@ const API = (
 const IMAGE = process.env.INSTABOX_IMAGE || 'universal';
 // SSH certificate lifetime for a box with no timeout of its own.
 const CERT_MIN = 120;
-const PROVIDER = process.argv.includes('--github') ? 'github' : 'google';
+// GitHub, the provider the instabox CLI itself signs in with: a GitHub and a
+// Google sign-in are separate accounts, and the two entry points disagreeing
+// put one person in both. --google is still here for a Google account.
+const PROVIDER = process.argv.includes('--google') ? 'google' : 'github';
 const bold = (s) => (process.stdout.isTTY ? `\x1b[1m${s}\x1b[0m` : s);
 const dim = (s) => (process.stdout.isTTY ? `\x1b[2m${s}\x1b[0m` : s);
 const green = (s) => (process.stdout.isTTY ? `\x1b[32m${s}\x1b[0m` : s);
@@ -43,8 +56,10 @@ 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
+      --google                      sign in with Google instead of GitHub (a separate account
+                                    with its own boxes; instabox login --provider google
+                                    signs the CLI in to the same one)
+      --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 +199,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 +217,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 +263,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})`)}`;
@@ -258,8 +297,19 @@ async function ensureCli() {
   );
 }
 
-// Agent skills shipped in this package (skills/<name>/SKILL.md) into the folders coding agents
-// read. Overwrites only copies we installed earlier (marked `installed-by: instabox`).
+// A skill directory's files, relative to it, sorted.
+function skillFiles(dir, rel = '') {
+  return readdirSync(join(dir, rel), { withFileTypes: true })
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .flatMap((e) => {
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      return e.isDirectory() ? skillFiles(dir, r) : e.isFile() ? [r] : [];
+    });
+}
+
+// Agent skills shipped in this package (skills/<name>/SKILL.md, with any scripts beside it) into
+// the folders coding agents read. Overwrites only copies we installed earlier (marked
+// `installed-by: instabox`).
 function installSkills() {
   if (process.argv.includes('--no-skills')) return null;
   const src = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills');
@@ -270,21 +320,43 @@ 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);
+        let what = 'installed';
+        if (existsSync(dest)) {
+          const old = readFileSync(dest, 'utf8');
+          if (!old.includes('installed-by: instabox')) {
+            kept.add(n);
+            continue;
+          }
+          what = 'unchanged';
+        }
+        // SKILL.md and whatever else the skill ships (scripts/...).
+        for (const f of skillFiles(join(src, n))) {
+          const body = readFileSync(join(src, n, f));
+          const to = join(root, n, f);
+          if (existsSync(to) && readFileSync(to).equals(body)) continue;
+          if (what === 'unchanged') what = 'updated';
+          mkdirSync(dirname(to), { recursive: true });
+          writeFileSync(to, 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 +380,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,10 +1,11 @@
 // 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';
 
-const OUR_FLAGS = new Set(['--github', '--no-cli', '--no-skills']);
+const OUR_FLAGS = new Set(['--github', '--google', '--no-cli', '--no-skills']);
 
 // Bare `instabox` (or the old `sh`) with only our flags; anything else is a CLI command.
 export function isOnboarding(args) {
@@ -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.3",
   "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. Both `instabox login` and `npx instabox@latest` sign in with GitHub unless given `--provider google` or `--google`, and the CLI shares the sign-in `npx` made.
+
 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-move-all/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: instabox-move-all
+description: Use when the user wants to move their whole local setup onto instabox, not just one repo — "move everything to instabox", "move my whole setup", "all my projects to a box", "set up a box like my laptop". Scans this machine (repos with unsaved work, agent history, credentials, dotfiles, agent config, global tools), lets the user pick from a checkbox plan, then moves the picks onto one new box. The bulk version of instabox-migrate.
+metadata:
+  installed-by: instabox
+---
+
+# Move a whole local setup to instabox
+
+The bulk version of the `instabox-migrate` skill: instead of the current repo, it moves everything the user picks onto **one new box**. Each repo goes over exactly as `instabox-migrate` moves one; this skill adds the scan, the plan, credentials and the environment around it. See the `instabox` skill for the CLI.
+
+Four scripts in `scripts/` next to this file do the parts that must be exact (Node 18+, nothing to install):
+
+| Script | Does |
+| --- | --- |
+| `scan.mjs` | Read-only inventory, as JSON. Credentials by name and place only, never values. |
+| `plan.mjs` | `write`: the checkbox plan from the scan. `parse`: reads the edited plan back, strictly, as JSON. |
+| `stage-env.mjs` | Copies the picked dotfiles and agent config into a local directory, credentials and macOS-only lines removed, plus a setup script for the box. |
+| `push-creds.mjs` | Puts the picked credentials into the Vault for this box only, piping each value from its source into `instabox vault set`. |
+
+**Never read, print or paste a credential value yourself**: not `gh auth token`, not `cat ~/.aws/credentials`, not `echo $OPENAI_API_KEY`, not a `.env`. `push-creds.mjs` is the only thing that touches values. If a credential needs something the script cannot do, tell the user the command to run themselves.
+
+Before starting, tell the user plainly:
+
+- What happens: a scan of this machine (nothing changes here), a plan file they edit, then one new box with what they checked. Their local copies stay as they are, and nothing keeps the two in sync afterwards.
+- **Agent conversation history can contain secrets they pasted into a chat.** It is a separate checkbox per repo.
+- Some sign-ins cannot move (below); the final report says what to run on the box for each.
+
+## 1. Scan
+
+```bash
+instabox whoami                                   # signed in? otherwise: instabox login
+S=~/.claude/skills/instabox-move-all/scripts      # or ~/.agents/skills/instabox-move-all/scripts: wherever this file is
+W=~/instabox-move && mkdir -p -m 700 "$W"
+node "$S/scan.mjs" > "$W/scan.json"
+```
+
+It looks for git repos under `~/Work ~/work ~/code ~/src ~/projects ~/dev ~/Developer ~/repos ~/git ~/github` (three levels down), the current directory's repo, and any repo the user's Claude Code or Codex history points at. If the user keeps code elsewhere, add `--root DIR` (repeatable); `--depth N` to look deeper; `--no-tools` to skip asking brew/npm/uv/cargo.
+
+What it finds, in four lists:
+
+- `work`: each repo with its branch, changed / untracked / stashed / unpushed counts, whether it has a remote, and its size the way `instabox-migrate` copies it (`.git` plus files git does not ignore). Its box directory is `/data/workspace/<name>`, `-2`, `-3`... when two repos share a name.
+- `history`: Claude Code (`~/.claude/projects`) and Codex (`~/.codex/sessions`) sessions, per repo.
+- `credentials`: each with where it comes from and what it becomes: a Vault `env` item, a Vault `file` item, or `manual` (cannot move, with the reason and the command to run on the box).
+- `environment`: dotfiles, Claude Code and Codex config, skills, local MCP servers, and global tools (`brew leaves`, `npm -g`, `uv tool`, `cargo install`, `~/go/bin`).
+
+## 2. Write the plan and let the user choose
+
+Pick a box name `instabox ls` does not show (lowercase letters, digits, `-`), then:
+
+```bash
+BOX=<box>
+node "$S/plan.mjs" write --scan "$W/scan.json" --box "$BOX" > "$W/migrate-plan.md"
+```
+
+`migrate-plan.md` has three sections, Work, Credentials and Environment, one `- [x]` / `- [ ]` line per item with its size and where it goes. Defaults:
+
+- Repos with work that exists only here (uncommitted, untracked, stashed, unpushed, or no remote) are checked, with their history. Clean, pushed repos are unchecked: they can be cloned again.
+- Credentials that work as a token or a file are checked. SSH private keys are unchecked (prefer `GH_TOKEN` over HTTPS, or a new key made on the box). Sign-ins that cannot move are unchecked and marked "can't move".
+- Dotfiles, agent config and tools are checked.
+
+Show the user a short summary (how many repos and how big, which credentials, what cannot move) and the path of the file, and ask them to edit the checkboxes and the `Box:` line, then tell you to go on. In Claude Code you may first ask a few coarse questions with AskUserQuestion (multiSelect), such as "Move: repos with unsaved work / every repo / credentials / dotfiles and agent config / tools", and apply the answers to the plan by changing only `[x]` and `[ ]`; the user still gets the file for the details.
+
+When they are done, read it back:
+
+```bash
+GIB=$(instabox usage --json | jq -r '.limits.machineSpec.persistentDiskGiB // 20')
+node "$S/plan.mjs" parse --scan "$W/scan.json" --disk-gib "$GIB" "$W/migrate-plan.md" > "$W/selection.json"
+```
+
+- Exit 1: the plan has problems (a malformed checkbox, a line deleted or duplicated, an unknown id, a "can't move" item checked, history checked without its repo, a bad box name, a plan from an older scan). All are listed; show them to the user, fix or let them fix, and parse again. Never fix a plan by editing ids or deleting lines.
+- Exit 2: a usage error, e.g. `--disk-gib` is empty because `instabox usage` failed. Fix that (`instabox login`) and parse again; never drop `--disk-gib`.
+- Exit 3: too big. Every box has the same `/data` disk, and half of it stays free for dependencies and builds. Ask the user what to uncheck (the message gives the sizes), then parse again.
+- Warnings about the Vault's limits (100 items, 256 KiB in all): ask the user to uncheck some credential files.
+
+From here on, `selection.json` is the plan: `.box`, `.work`, `.history`, `.credentials`, `.environment`, `.tools`, `.manual` (what the user must do by hand) and `.bytes`.
+
+## 3. Create the box
+
+```bash
+BOX=$(jq -r .box "$W/selection.json")
+instabox create --name "$BOX" --meta migrated="$BOX"
+instabox ls --meta migrated="$BOX"                     # exactly this box
+instabox exec "$BOX" -- df -h /data                    # room for what is coming
+```
+
+The `migrated=<box>` label is what the credentials select on (next step), so they reach this box and no other. No `--timeout`: this box is meant to stay (offer `instabox timeout "$BOX" 8h --on-timeout pause` if the user wants it to pause itself).
+
+## 4. Credentials into the Vault
+
+```bash
+node "$S/push-creds.mjs" --selection "$W/selection.json" --dry-run   # names and sizes only
+node "$S/push-creds.mjs" --selection "$W/selection.json"
+instabox vault push "$BOX"
+instabox vault show "$BOX"
+```
+
+Every item gets the selector `migrated=<box>`. Values go from their source (a variable sourced from the user's shell file, `gh auth token`, a key in `~/.codex/auth.json`, a file) straight into the CLI's stdin; the output is names, sizes and outcomes. An item already in the Vault under the same name or path is left alone (it would change what other boxes get), unless it is from an earlier run of this move; the output says which. `.env` files of repos go in as Vault files under `~/.config/instabox-move/env/<repo>/` and are linked into the repo in step 5. If an item fails, tell the user what failed and the command to set it themselves, for example `instabox vault set NAME --selector migrated=<box>` (it prompts without echo).
+
+## 5. Environment
+
+```bash
+node "$S/stage-env.mjs" --selection "$W/selection.json" --out "$W/stage"
+COPYFILE_DISABLE=1 tar -C "$W/stage" -czf - . |
+  instabox ssh "$BOX" -- 'tar -xzf - --skip-old-files --no-overwrite-dir --warning=no-unknown-keyword -C ~'
+instabox ssh "$BOX" -- 'bash -l ~/.config/instabox-move/setup.sh'
+rm -rf "$W/stage"
+```
+
+What the staged copy and `setup.sh` do on the box:
+
+- Lines that look like credentials are replaced by a comment; macOS-only lines (Homebrew paths, `osxkeychain`, `UseKeychain`, `pbcopy`, ...) are commented out; this machine's HOME becomes `/data/home`. The JSON summary printed by `stage-env.mjs` counts the lines changed per file.
+- The box keeps its own startup files: `~/.bashrc` sources the user's bash files, `~/.gitconfig` includes theirs, Claude Code `settings.json` is merged (theirs wins), `CLAUDE.md` / `AGENTS.md` are appended. Files the box already has are not overwritten (`--skip-old-files`). zsh is installed when there is a `.zshrc`; bash stays the login shell.
+- Skills, commands and agents go to `~/.claude/...` and `~/.agents/skills`; local MCP servers are added with `claude mcp add-json` (their secrets come from the Vault as environment variables).
+- Tools are installed fresh: Homebrew formulae through a table of Debian packages (or `uv tool` / `npm -g`), npm globals, `uv tool`, `cargo install`, `go install`. No macOS binary is copied. Formulae without a mapping are listed in `.manual`.
+
+`setup.sh` is safe to run again. Run it over `ssh` (installs can take minutes). It carries on past a failed step, then lists every failed step and exits 1: report those to the user, fix what you can on the box and run it again. Then check the shells still parse: `instabox exec "$BOX" -- 'bash -n ~/.bashrc; [ -f ~/.zshrc ] && zsh -n ~/.zshrc'`. Fix a broken line in the staged copy under `~/.config/instabox-move/shell/` on the box.
+
+## 6. Work: each repo
+
+For each repo in `selection.json`:
+
+```bash
+jq -r '.work[] | [.path, .name] | @tsv' "$W/selection.json"
+jq -r '.history[].repo' "$W/selection.json"        # repos whose history goes too ("repo:<path>")
+```
+
+follow **steps 2, 3 and 4 of the `instabox-migrate` skill** for that repo, with two changes:
+
+- `cd` into the repo's path first, and set `NAME` to the repo's `name` from `selection.json` instead of the `basename` line, so two repos with the same name do not land in one directory.
+- Copy the Claude Code and Codex history (the second and third parts of its step 2, and its step 3) only if the repo is in `.history`.
+
+Its checks apply: the box must show the same `git status` and `HEAD`. Do the dependency installs and builds of its step 4 per repo; the tools and `.env` links from step 5 are already there.
+
+## 7. Verify and report
+
+```bash
+instabox exec "$BOX" -- 'gh auth status; git config user.name; claude --version; codex --version'
+instabox exec "$BOX" -- 'test "${GH_TOKEN+x}" = x && echo GH_TOKEN set'   # presence only; same for other names
+instabox vault show "$BOX"
+```
+
+Tell the user, in short sections:
+
+- **Moved**: the box name (`instabox ssh <box>`), each repo with its directory and whether it builds and its tests pass, the credentials now in the Vault for this box, the environment and tools installed.
+- **Skipped**: what they unchecked, and anything that failed (with the reason).
+- **To do by hand**: every entry of `.manual`, with its exact command (for example `codex login --device-auth`, `claude` then `/login`, `gcloud auth login --no-launch-browser`, `docker login ghcr.io`, `aws sso login --use-device-code`), and how to pick up old conversations (`claude --continue` in a repo; `codex resume <id>`).
+- The credentials reach only boxes with the label `migrated=<box>`; a box created later with `--meta migrated=<box>` gets them too. Remove one with `instabox vault rm NAME`.
+- Ignored files stayed behind (except the `.env` files that went to the Vault), and secrets in committed files or in the copied history went over.
+
+Delete `$W` when the user is done with it (it holds the scan and plan, no values).
+
+## What cannot move, and why
+
+- **Rotating OAuth sign-ins**: Claude Code's login, Codex's ChatGPT login (`~/.codex/auth.json` tokens), gcloud user credentials, remote MCP servers signed in with OAuth. Their refresh token changes on use, so a copy would sign one side out. Sign in again on the box.
+- **macOS keychain-bound**: Docker's `credsStore`, Claude Code on macOS, AWS `credential_process` helpers. The keychain does not exist on the box. (`gh`'s keychain token can move: it is read with `gh auth token`.)
+- **Short-lived**: AWS SSO sessions and `aws_session_token`. Sign in on the box.
+- **Too big**: a credential file over 64 KiB; the plan says how to copy it.