instabox 0.5.0 → 0.5.2

package/bin/instabox.mjs

@@ -14,6 +14,7 @@ import {
   readdirSync,
 } from 'node:fs';
 import http from 'node:http';
+import { createInterface } from 'node:readline/promises';
 import { tmpdir, homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -126,7 +127,38 @@ function signInPage(ok, title, text, who) {
 
 // Browser sign-in, the same loopback flow as instabox's own CLI (RFC 8252 + PKCE): listen on
 // 127.0.0.1, open /auth/cli/start, receive the code at /callback, exchange it with the verifier.
-async function browserLogin() {
+// askInvite asks for an invite code on the terminal; '' without one (a pipe, CI) or when left empty.
+async function askInvite(again) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return '';
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const q = again
+      ? `  That code is invalid or used up. ${bold('Invite code')} ${dim('(Enter to stop)')}: `
+      : `  You're on the waitlist; an invite code lets you in now.\n  ${bold('Invite code')} ${dim('(Enter to stop)')}: `;
+    return (await rl.question(q)).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+// signInWithInvite is browserLogin, asking for an invite code when the account is on the waitlist.
+async function signInWithInvite() {
+  let invite = '';
+  for (;;) {
+    const r = await browserLogin(invite);
+    if (r.tok) return r.tok;
+    const waitlisted = r.code === 'invite_required' || r.code === 'invite_invalid';
+    if (waitlisted) invite = await askInvite(r.code === 'invite_invalid');
+    if (waitlisted && invite) continue;
+    if (waitlisted)
+      die(
+        "this account is on the waitlist; we'll email you an invite code.\n  Have one? Run: npx instabox@latest login --invite-code <code>",
+      );
+    die(`sign-in failed: ${r.err}`);
+  }
+}
+
+async function browserLogin(invite) {
   const verifier = randomBytes(32).toString('base64url');
   const state = randomBytes(24).toString('base64url');
   const challenge = createHash('sha256').update(verifier).digest('base64url');
@@ -147,13 +179,17 @@ async function browserLogin() {
     stale: () => signInPage(false, 'This sign-in link is stale', 'Run the command in your terminal again.'),
     again: () => signInPage(true, 'Already signing you in', 'Head back to your terminal.'),
     ok: (r) => signInPage(true, "You're in", 'Head back to your terminal.', r.me && (r.me.name || r.me.login)),
-    failed: (err) => signInPage(false, 'Sign-in failed', `${err}. Return to your terminal and run the command again.`),
+    failed: (err, code) =>
+      code === 'invite_required' || code === 'invite_invalid'
+        ? signInPage(false, "You're on the waitlist", 'Return to your terminal to enter an invite code.')
+        : signInPage(false, 'Sign-in failed', `${err}. Return to your terminal and run the command again.`),
   };
   const server = http.createServer(callbackHandler({ state, exchange, finish, page }));
   await new Promise((r) => server.listen(0, '127.0.0.1', r));
   const redirect = `http://127.0.0.1:${server.address().port}/callback`;
   const q = { redirect_uri: redirect, state, code_challenge: challenge, code_challenge_method: 'S256' };
   if (PROVIDER) q.provider = PROVIDER;
+  if (invite) q.invite = invite;
   const start = `${API}/auth/cli/start?` + new URLSearchParams(q);
   console.log(`  ${bold('Sign in to instabox')} in your browser ${dim('(opening it now)')}`);
   console.log(`  ${dim('If it did not open:')} ${start}\n`);
@@ -162,8 +198,7 @@ async function browserLogin() {
   const result = await done;
   clearTimeout(timer);
   server.close();
-  if (result.err) die(`sign-in failed: ${result.err}`);
-  return result.tok;
+  return result.err ? { err: result.err, code: result.code } : { tok: result.tok };
 }
 
 // The CLI's saved token, a refreshed one, or a browser sign-in; saved where the CLI reads it.
@@ -177,7 +212,7 @@ async function signedIn() {
       return t;
     } catch {}
   }
-  const t = await browserLogin();
+  const t = await signInWithInvite();
   saveCredentials(API, t);
   return t;
 }
@@ -269,6 +304,26 @@ function skillFiles(dir, rel = '') {
     });
 }
 
+// Skills this package used to ship under another name. A copy we installed (marked
+// `installed-by: instabox`) is removed, so the agent does not see both; the user's own is kept.
+const RETIRED_SKILLS = [
+  'instabox-migrate', // now instabox-move-repo
+  'instabox-move-all', // now instabox-basic-setup
+];
+
+function removeRetiredSkills(roots) {
+  const removed = new Set();
+  for (const root of roots)
+    for (const n of RETIRED_SKILLS) {
+      try {
+        if (!readFileSync(join(root, n, 'SKILL.md'), 'utf8').includes('installed-by: instabox')) continue;
+        rmSync(join(root, n), { recursive: true, force: true });
+        removed.add(n);
+      } catch {}
+    }
+  return [...removed];
+}
+
 // 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`).
@@ -318,6 +373,8 @@ function installSkills() {
   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(', ')}`);
+  const retired = removeRetiredSkills(roots);
+  if (retired.length) parts.push(`removed the old ${retired.join(', ')}`);
   return parts.length ? `agent skills: ${parts.join('; ')} ${dim('(~/.claude/skills, ~/.agents/skills)')}` : null;
 }
 

package/lib/login.mjs

@@ -20,7 +20,10 @@ export function callbackHandler({ state, exchange, finish, page }) {
     taken = true;
     let result;
     if (u.searchParams.get('error')) {
-      result = { err: u.searchParams.get('error_description') || u.searchParams.get('error') };
+      result = {
+        err: u.searchParams.get('error_description') || u.searchParams.get('error'),
+        code: u.searchParams.get('error'),
+      };
     } else {
       try {
         result = await exchange(u.searchParams.get('code'));
@@ -29,7 +32,7 @@ export function callbackHandler({ state, exchange, finish, page }) {
       }
     }
     res.writeHead(200, html);
-    res.end(result.tok ? page.ok(result) : page.failed(result.err));
+    res.end(result.tok ? page.ok(result) : page.failed(result.err, result.code));
     finish(result);
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instabox",
-  "version": "0.5.0",
+  "version": "0.5.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

@@ -1,6 +1,6 @@
 ---
 name: instabox
-description: Use when the user wants a cloud Linux box (instabox sandbox) from the terminal with the `instabox` CLI — create one, SSH in, run a command in it, read its files, set its timeout, or delete it. For saving or restoring a box's disks, see instabox-snapshots.
+description: Use when the user wants a cloud Linux box (instabox sandbox) from the terminal with the `instabox` CLI — create one, SSH in, run a command in it, read its files, set its timeout, or delete it, or to report a problem with instabox itself (`instabox feedback`). For saving or restoring a box's disks, see instabox-snapshots.
 metadata:
   installed-by: instabox
 ---
@@ -34,12 +34,13 @@ For CI or an agent without a browser, use an API key instead: `export INSTABOX_A
 
 ```sh
 instabox templates                              # base systems to start from
-instabox create --name work --timeout 2h        # new box; waits until it is running
+instabox create --name work                     # new box; waits until it is running
 instabox ls                                     # your boxes and their states
 instabox ssh work                               # interactive shell (leave with: exit)
 instabox exec work -- uname -a                  # one command, no SSH client needed
 instabox exec work --cwd /data/home -- ls -la   # exec runs `bash -lc` as dev
 instabox files work /data/home                  # list a directory (or print a text file)
+instabox auto-suspend work 10m                  # pause after 10 idle minutes (default 30m; 0: never)
 instabox timeout work 2h --on-timeout pause     # pause (keeps memory) or kill at the deadline
 instabox stop work && instabox start work       # stop ends processes, keeps disks
 instabox suspend work && instabox resume work   # pause/resume keeps running processes
@@ -47,7 +48,8 @@ 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`, `--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.
+- `create` options: `--template T` or `--snapshot S`, `--auto-suspend D|0`, `--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.
+- A new box pauses itself after 30 idle minutes (no agent working, no terminal use, little CPU) and wakes on the next `exec`, `ssh` or `files`; a paused box keeps its memory and processes. `--auto-suspend 0` keeps a box always on (a server that must keep answering); `--auto-suspend 2h` changes the idle time.
 - 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.
@@ -72,8 +74,30 @@ instabox create --name tenant --no-vault # a box for someone else: never gets th
 - 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.
 
+## Moving work onto a box
+
+To move the repo the user is working in (with its worktrees, uncommitted work and agent conversations) onto a new box and install its dependencies there, follow the `instabox-move-repo` skill.
+
+## When instabox itself gets in your way (feedback)
+
+If instabox is at fault — a command breaks the contract its help or this skill states, the skill does not match what really happens, a capability is missing, or the CLI is confusing — report it, then carry on with the user's task using a workaround. Never block on the report, and never report problems in the code the user is building.
+
+```sh
+instabox feedback --json --type bug --component cli --area exec \
+  --title "exec --timeout 600 stops the command at 60s" \
+  --detail "instabox exec work --timeout 600 -- make test was killed after 60 seconds" \
+  --command "instabox exec work --timeout 600 -- make test" \
+  --expected "the skill says exec accepts up to 600 seconds" --doc "skills/instabox/SKILL.md" \
+  --workaround "ran it over instabox ssh instead"
+```
+
+- `--type`: `bug` when something does not work as its help or the docs say (when instructions did not match reality, also give `--doc`, `--expected` and `--workaround`), `feature-request` when what you need is not supported, `friction` when it works but is confusing or awkward, `other` otherwise.
+- `--component`: `cli`, `api`, `sandbox` (the box itself, its templates or tools), `dashboard`, `skills`, `docs` or `other`. `--severity blocker|major|minor` (default `minor`); `--sandbox NAME` names the box involved.
+- Emails, keys, tokens, home paths and public IPv4 addresses are redacted before sending, but do not paste secrets into it. The report carries the signed-in account (its user ID, and its login unless that is an email address), so the team can follow up.
+- A failed or unconfirmed submission prints a warning and exits 0: do not retry. File one report per problem, not one per attempt.
+
 ## Habits
 
-- Give boxes a `--timeout` so forgotten ones pause or delete themselves.
+- Forgotten boxes pause themselves. Give a box a `--timeout` when it must stop at a deadline, or `--timeout D --on-timeout kill` when it should be deleted then.
 - 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-basic-setup/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: instabox-basic-setup
+description: Use when the user wants their instabox boxes set up like their laptop — "put my tokens / dotfiles / git config into instabox", "set up my boxes like my laptop", "give every box my GitHub and Claude tokens", "move my setup to instabox", "move everything to instabox". Scans this machine, lets the user pick from a checkbox plan, then puts the picks into their instabox Vault, so every box (and every box created later) gets them: tokens (GH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN, model and service API keys) as environment variables, and git and editor config (~/.gitconfig, global gitignore, ~/.vimrc, nvim, ~/.tmux.conf) as files. Moves no code: for a repo, use instabox-move-repo.
+metadata:
+  installed-by: instabox
+---
+
+# Put a basic setup into the instabox Vault
+
+This skill puts the user's personal setup into their instabox **Vault** (`instabox vault`: per-user secrets and files, written into their boxes), so every box of theirs starts with it: the ones running now (at their next start or resume, or at once with `instabox vault push <box>`) and every box created later. It copies no repository, no agent history, installs nothing and touches no box directly. To move a repository, use the `instabox-move-repo` skill. See the `instabox` skill for the CLI.
+
+What it moves, and nothing else:
+
+| Group | Becomes | From |
+| --- | --- | --- |
+| Tokens | Vault `env` items: on tmpfs in the box, set in every login shell; gone at a stop, back at the next start; never in a snapshot | `GH_TOKEN` from `gh auth token`; well-known model and service tokens exported in the shell files (`ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`, `HF_TOKEN`, `NPM_TOKEN`, `VERCEL_TOKEN`, `CLOUDFLARE_API_TOKEN`, `SUPABASE_ACCESS_TOKEN`, `FLY_API_TOKEN`, `SENTRY_AUTH_TOKEN`, `LINEAR_API_KEY`, ...) or in this shell's environment. Other credential-looking exports are listed unchecked. |
+| Git | Vault `file` items in the box's home | `~/.gitconfig` (and `~/.config/git/config`), the global gitignore |
+| Editor and terminal | Vault `file` items | `~/.vimrc`, nvim's `init.lua` / `init.vim` and the `.lua` / `.vim` files around it (no plugin checkouts), `~/.tmux.conf` |
+
+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: tokens by name and place (never values), the files, and what cannot move. |
+| `plan.mjs` | `write`: the checkbox plan. `parse`: reads the edited plan back, strictly, as JSON. |
+| `push.mjs` | Puts the picks into the Vault, piping each value from its source into `instabox vault set` / `set-file`. `--dry-run` first. |
+| `content.mjs` | What a file becomes in the Vault (used by the other two). |
+
+**Never read, print or paste a credential value yourself**: not `gh auth token`, not `echo $OPENAI_API_KEY`, not `cat` of a shell file or of `~/.gitconfig`, never the macOS keychain. `push.mjs` is the only thing that touches values. If something needs a value the scripts cannot get, tell the user the command to run themselves (`instabox vault set NAME` prompts without echo).
+
+Before starting, tell the user plainly: a scan of this machine (nothing changes here), a plan file they edit, then their Vault gets what they checked. By default every box they have and will create gets it; they can scope it with a selector. Nothing is copied from a box back here, and nothing keeps the two in sync: to change something later, change it here and run this again.
+
+## 1. Scan
+
+```bash
+instabox whoami                                    # signed in? otherwise: instabox login
+S=~/.claude/skills/instabox-basic-setup/scripts    # or ~/.agents/skills/instabox-basic-setup/scripts: wherever this file is
+W=~/instabox-basic-setup && mkdir -p -m 700 "$W"
+node "$S/scan.mjs" > "$W/scan.json"
+instabox vault ls --json > "$W/vault.json"         # what is in the Vault already (names, no values)
+instabox usage --json | jq '.limits.vault // {}' > "$W/limits.json"
+```
+
+`instabox vault ls` fails with `API keys cannot manage the vault` when `INSTABOX_API_KEY` is set: ask the user to unset it and `instabox login`. A `404` means the server has no Vault: stop and say so.
+
+## 2. Write the plan and let the user choose
+
+```bash
+node "$S/plan.mjs" write --scan "$W/scan.json" --vault "$W/vault.json" > "$W/plan.md"
+```
+
+Add `--selector key=value` (comma-separated for more) only if the user wants the setup on some boxes, not all; the plan's `Selector:` line can be edited too (`*` is every box). A box gets the items when its metadata has every label (`instabox create --meta key=value`).
+
+`plan.md` has a `- [x]` / `- [ ]` line per item, in three sections (Tokens, Git, Editor and terminal), then a "Can't move" list with no checkboxes. Defaults:
+
+- Well-known tokens and every file are checked. Other credential-looking exports, and tokens the shell reads from the macOS keychain, are unchecked (checking the latter runs that keychain lookup once, at push time).
+- Something already in the Vault, set there some other way than this skill, is unchecked and says so: checking it **replaces** it (for every box its selector reached). Items this skill set on an earlier run are replaced without asking (the manifest, step 3).
+
+Show the user a short summary (which tokens, which files, what cannot move) and the path of the file, and ask them to edit the checkboxes and the selector, then tell you to go on. In Claude Code you may ask a coarse question first with AskUserQuestion (multiSelect: "Tokens / Git / Editor and terminal") and apply the answer by changing only `[x]` and `[ ]`; the user still gets the file for details.
+
+When they are done, read it back:
+
+```bash
+node "$S/plan.mjs" parse --scan "$W/scan.json" --vault "$W/vault.json" --limits "$W/limits.json" "$W/plan.md" > "$W/selection.json"
+```
+
+- Exit 1: the plan has problems (a malformed checkbox, a line deleted or duplicated, an unknown id, a bad selector, a plan from another scan or Vault state, a file that became empty or over 64 KiB). All are listed; show them, fix or let the user fix, parse again. Never fix a plan by editing ids or deleting lines. If the scan or Vault changed, run step 1 and 2 again.
+- Exit 3: over the Vault's limits (100 items, 256 KiB in all, items already there included; 64 KiB per item). The message gives the totals and the biggest lines: ask the user what to uncheck (nvim's files are one item each), or which old Vault items to remove (`instabox vault rm NAME`), then parse again.
+
+## 3. Push into the Vault
+
+```bash
+node "$S/push.mjs" --selection "$W/selection.json" --dry-run   # names, sizes, totals; writes nothing
+node "$S/push.mjs" --selection "$W/selection.json"
+```
+
+Show the user the dry run's lines before the real run. Values go from their source (`gh auth token`, a variable after sourcing the user's shell file, this environment) straight into the CLI's stdin. A shell file that only exports when interactive (the usual `case $- in *i*)` guard) is sourced a second time in an interactive shell, which may run its prompt setup; a token it still does not yield comes from this environment, or fails with the reason; the output is names, sizes and outcomes. Every value is read and the totals checked before anything is written: over the limits, nothing is written (exit 3). An item that appeared in the Vault after the plan was written is left alone (`kept`). A `failed` line names the item and why; give the user the command to set it themselves (`instabox vault set NAME`, which prompts without echo). Re-running is safe: the same items are set again.
+
+The run records what it set in `~/.config/instabox-basic-setup/pushed.json` (names, kinds, paths; no values), so the next run knows those are its own.
+
+What a file becomes (counted per file in the plan's sizes):
+
+- This machine's HOME is rewritten to the box's (`/data/home`); lines that look like a credential are replaced by a comment; macOS-only lines (`osxkeychain`, Homebrew paths, `pbcopy`, `reattach-to-user-namespace`, ...) are commented out.
+- `~/.gitconfig` also: commit and tag signing is turned off (`gpgsign`: the signing key is not on the box), `url."git@...".insteadOf` rewrites are commented out (the box has no SSH key), and when `GH_TOKEN` is in the Vault, gh's credential helper for github.com is added (what `gh auth setup-git` writes), so `git clone https://github.com/...` and `git push` use the token.
+
+## 4. Verify on a box (optional)
+
+If the user names a running box (`instabox ls`), or wants one to try, write the Vault into it now and look:
+
+```bash
+BOX=<box>
+instabox vault push "$BOX"            # writes now; lists variables and files written, and any "kept" path
+instabox vault show "$BOX"            # what it gets with its metadata
+instabox exec "$BOX" -- 'gh auth status; git config --get user.name; test -n "${CLAUDE_CODE_OAUTH_TOKEN-}${ANTHROPIC_API_KEY-}" && echo claude token set'
+```
+
+A `kept: ~/path (not written: ... symlink ...)` line means the box has a symlink in that path; tell the user. Check presence of a token, never print one. A box created with `--no-vault` gets nothing, ever; one whose metadata does not match the selector gets nothing either. Do not create a box for this unless the user asks.
+
+## 5. Report
+
+Tell the user, in short sections:
+
+- **In your Vault**: each token by name, each file by path, and which boxes get them (every box, or the selector). Running boxes get them at their next start or resume, or now with `instabox vault push <box>`; new boxes at once.
+- **Left alone**: what they unchecked, items kept because they were set some other way, failures with the reason. Items from an earlier run they unchecked this time are still in the Vault (the push prints them): `instabox vault rm NAME` removes one, and boxes lose it at their next write.
+- **Do these yourself**: every entry of `.manual` in `selection.json`, with its command, for example: Claude Code's sign-in — run `claude setup-token` here yourself, then `instabox vault set CLAUDE_CODE_OAUTH_TOKEN` and paste it (or `claude`, then `/login`, on each box); Codex — `codex login --device-auth` on the box, or `instabox vault set OPENAI_API_KEY`; `gh auth login` here if gh is not signed in.
+- **Good to know**: Vault files are written again at every start and resume, so an edit made to them on a box is replaced; change them here and run this skill again (or `instabox vault rm` the item to keep a box's own copy). Tokens are environment variables of login shells (SSH, `instabox exec`, the terminal), not of systemd services. Shell aliases, SSH keys, cloud credential files and agent config are not part of this setup.
+
+Delete `$W` when the user is done with it (it holds the scan, the plan and the Vault's item names, no values).

package/skills/instabox-basic-setup/scripts/content.mjs

@@ -0,0 +1,98 @@
+// What a file item's content becomes in the Vault: the local file with this
+// machine's HOME rewritten to the box's, lines that look like credentials
+// removed and macOS-only lines commented out. ~/.gitconfig also gets a few
+// changes so git works on a box that has GH_TOKEN and no SSH key.
+//
+// Used by plan.mjs (for sizes) and push.mjs (for the upload). Nothing here
+// prints a file's content.
+import { readFileSync } from 'node:fs';
+import { basename, extname } from 'node:path';
+import { BOX_HOME, MACOS_ONLY, SECRET_KEY_LINE, SECRET_VALUE } from './lib.mjs';
+
+const TAG = '[instabox-basic-setup]';
+
+function commentStyle(path) {
+  const b = basename(path);
+  const e = extname(path);
+  if (e === '.lua') return '--';
+  if (e === '.vim' || b === '.vimrc' || b === '.gvimrc') return '"';
+  return '#';
+}
+
+const isComment = (line) => /^\s*(?:#|;|--|")/.test(line);
+
+// Filters one text file. Returns the new text and how many lines were changed.
+export function scrubText(text, { path, home }) {
+  const c = commentStyle(path);
+  let secrets = 0;
+  let macos = 0;
+  const out = text.split('\n').map((line) => {
+    if (SECRET_VALUE.test(line) || (SECRET_KEY_LINE.test(line) && !isComment(line))) {
+      secrets++;
+      return `${c} ${TAG} removed a line that looked like a credential`;
+    }
+    if (MACOS_ONLY.test(line) && !isComment(line)) {
+      macos++;
+      return `${c} ${TAG} macOS only: ${line.trim()}`;
+    }
+    return home ? line.split(home).join(BOX_HOME) : line;
+  });
+  return { text: out.join('\n'), secrets, macos };
+}
+
+// The credential helper `gh auth setup-git` writes: git over HTTPS uses GH_TOKEN through gh.
+export const GH_HELPER = [
+  '',
+  `# ${TAG}: git over HTTPS to GitHub uses GH_TOKEN (from the Vault) through gh`,
+  '[credential "https://github.com"]',
+  '\thelper =',
+  '\thelper = !gh auth git-credential',
+  '[credential "https://gist.github.com"]',
+  '\thelper =',
+  '\thelper = !gh auth git-credential',
+  '',
+].join('\n');
+
+// ~/.gitconfig for the box. ghToken: GH_TOKEN goes to the Vault too, so the gh helper is added.
+// Changes, besides scrubText's:
+//  - commit/tag signing is turned off: the signing key (GPG, SSH, 1Password) is not on the box;
+//  - url.<ssh>.insteadOf rewrites are commented out: the box has no SSH key, and they would
+//    send HTTPS remotes over SSH.
+export function gitconfigText(text, { home, ghToken }) {
+  const r = scrubText(text, { path: '.gitconfig', home });
+  let section = '';
+  let signing = 0;
+  let insteadOf = 0;
+  const lines = r.text.split('\n').map((line) => {
+    const h = line.match(/^\s*\[([^\]]*)\]/);
+    if (h) section = h[1].trim();
+    if (isComment(line)) return line;
+    if (/^\s*gpgsign\s*=\s*(?:true|yes|on|1)\s*$/i.test(line)) {
+      signing++;
+      return `# ${TAG} signing off (no signing key on the box): ${line.trim()}`;
+    }
+    if (/^\s*(?:push)?insteadof\s*=/i.test(line) && /^url\s+"(?:git@|ssh:\/\/)/i.test(section)) {
+      insteadOf++;
+      return `# ${TAG} no SSH key on the box: ${line.trim()}`;
+    }
+    return line;
+  });
+  let out = lines.join('\n');
+  if (ghToken) out = out.replace(/\n*$/, '\n') + GH_HELPER;
+  return { text: out, secrets: r.secrets, macos: r.macos, signing, insteadOf };
+}
+
+// The content of one file of a file item, or {error}. f: {path, src, transform}.
+export function fileContent(f, { home, ghToken = false } = {}) {
+  let buf;
+  try {
+    buf = readFileSync(f.src);
+  } catch (e) {
+    return { error: `${f.src}: ${e.code || 'unreadable'}` };
+  }
+  if (buf.includes(0)) return { error: `${f.src}: a binary file (the Vault holds text only)` };
+  const text = buf.toString('utf8');
+  if (f.transform === 'gitconfig') return gitconfigText(text, { home, ghToken });
+  if (f.transform === 'raw') return { text, secrets: 0, macos: 0 };
+  return scrubText(text, { path: f.path, home });
+}

package/skills/instabox-basic-setup/scripts/lib.mjs

@@ -0,0 +1,233 @@
+// Shared by the instabox-basic-setup scripts. Node >= 18, no dependencies.
+//
+// The one rule every function here keeps: a credential's value is never
+// returned to the agent, stored in a file or printed. Code that looks at a
+// secret returns names, places and sizes only.
+import { spawnSync } from 'node:child_process';
+import { lstatSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+
+// Environment variable names that hold a credential, also with a rotation or environment
+// qualifier after it (OPENAI_API_KEY_2, GITHUB_TOKEN_OLD). The qualifier needs its own `_`,
+// so PATH is not PAT plus H.
+export const SECRET_NAME =
+  /(?:^|_)(?:API_?KEY|APIKEY|KEY_?SECRET|TOKEN|ACCESS_?TOKEN|AUTH_?TOKEN|REFRESH_?TOKEN|SECRET|SECRET_?KEY|CLIENT_?SECRET|ACCESS_?KEY|ACCESS_?KEY_?ID|PASSWORD|PASSWD|PASS|PAT|PRIVATE_?KEY|CREDENTIALS?)(?:_(?:\d+|V\d+|OLD|NEW|PREV|PREVIOUS|BAK|BACKUP|ALT|PROD|PRODUCTION|DEV|STAGING|STAGE|TEST|LOCAL|CI))?$/i;
+
+// Values that are credentials whatever they are called: token prefixes of the common
+// services, private keys, and URLs with a password in them.
+export const SECRET_VALUE = new RegExp(
+  [
+    String.raw`\bgh[pousr]_[A-Za-z0-9]{20,}`,
+    String.raw`\bgithub_pat_[A-Za-z0-9_]{20,}`,
+    String.raw`\bsk-[A-Za-z0-9_-]{20,}`,
+    String.raw`\bAKIA[0-9A-Z]{16}\b`,
+    String.raw`\bASIA[0-9A-Z]{16}\b`,
+    String.raw`\bxox[abposr]-[A-Za-z0-9-]{10,}`,
+    String.raw`\bglpat-[A-Za-z0-9_-]{20,}`,
+    String.raw`\bnpm_[A-Za-z0-9]{30,}`,
+    String.raw`\bAIza[0-9A-Za-z_-]{35}`,
+    String.raw`-----BEGIN [A-Z ]*PRIVATE KEY-----`,
+    String.raw`[a-z][a-z0-9+.-]*://[^/\s:@'"]+:[^@\s'"/]+@`,
+  ].join('|'),
+);
+
+// key = value / key: value pairs whose key says it is a secret (config files); numbers and
+// booleans are not secrets (max_tokens = 100).
+export const SECRET_KEY_LINE =
+  /(?:^|[\s{,;:])["']?[\w.-]*(?:token|password|passwd|secret|api[_-]?key|apikey|_auth|authorization|extraheader|private[_-]?key)[\w.-]*["']?\s*[=:]\s*["']?(?![0-9.]+\b|true\b|false\b)[^\s"',}]/i;
+
+// Model-provider and developer-service tokens: moved by default when found. Any other
+// credential-looking variable exported in a shell file is listed unchecked.
+export const WELL_KNOWN = new Set([
+  'GH_TOKEN',
+  'GITHUB_TOKEN',
+  'CLAUDE_CODE_OAUTH_TOKEN',
+  'ANTHROPIC_API_KEY',
+  'OPENAI_API_KEY',
+  'GEMINI_API_KEY',
+  'GOOGLE_API_KEY',
+  'GOOGLE_GENERATIVE_AI_API_KEY',
+  'OPENROUTER_API_KEY',
+  'GROQ_API_KEY',
+  'MISTRAL_API_KEY',
+  'DEEPSEEK_API_KEY',
+  'XAI_API_KEY',
+  'TOGETHER_API_KEY',
+  'FIREWORKS_API_KEY',
+  'PERPLEXITY_API_KEY',
+  'COHERE_API_KEY',
+  'VOYAGE_API_KEY',
+  'REPLICATE_API_TOKEN',
+  'ELEVENLABS_API_KEY',
+  'TAVILY_API_KEY',
+  'EXA_API_KEY',
+  'FIRECRAWL_API_KEY',
+  'BRAVE_API_KEY',
+  'PINECONE_API_KEY',
+  'HF_TOKEN',
+  'HUGGING_FACE_HUB_TOKEN',
+  'NPM_TOKEN',
+  'VERCEL_TOKEN',
+  'NETLIFY_AUTH_TOKEN',
+  'CLOUDFLARE_API_TOKEN',
+  'SUPABASE_ACCESS_TOKEN',
+  'FLY_API_TOKEN',
+  'RAILWAY_TOKEN',
+  'RENDER_API_KEY',
+  'NEON_API_KEY',
+  'SENTRY_AUTH_TOKEN',
+  'LINEAR_API_KEY',
+  'GITLAB_TOKEN',
+  'DIGITALOCEAN_ACCESS_TOKEN',
+]);
+
+// Names the Vault refuses for env items (docs/vault.md).
+const RESERVED = new Set(['HOME', 'PATH', 'USER', 'LOGNAME', 'SHELL', 'TERM', 'XDG_RUNTIME_DIR', 'DBUS_SESSION_BUS_ADDRESS']);
+export function vaultEnvNameOK(name) {
+  return (
+    /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) &&
+    name.length <= 128 &&
+    !RESERVED.has(name) &&
+    !name.startsWith('INSTABOX_') &&
+    !name.startsWith('SSH_')
+  );
+}
+
+export const isSecretName = (name) => SECRET_NAME.test(name);
+
+// Lines in macOS configs that mean nothing on the Linux box.
+export const MACOS_ONLY =
+  /\/opt\/homebrew|\/usr\/local\/Cellar|\/usr\/local\/Homebrew|\/Applications\/|\/Library\/|\bosxkeychain\b|\bUseKeychain\b|\bpbcopy\b|\bpbpaste\b|\bosascript\b|\breattach-to-user-namespace\b|\bterminal-notifier\b|\bafplay\b|\/System\/|\.orbstack\/|1password.*agent\.sock|\bsecurity (?:find|add)-[a-z-]*password\b/i;
+
+// The Vault's limits (docs/vault.md, pkg/instaboxapi MaxVaultValueBytes); the server's own
+// come from `instabox usage --json` (.limits.vault) when it answers.
+export const VAULT_MAX_VALUE = 64 * 1024;
+export const VAULT_MAX_TOTAL = 256 * 1024;
+export const VAULT_MAX_ITEMS = 100;
+
+export const BOX_HOME = '/data/home';
+
+// Runs a command without a shell; never throws. stdout is returned to the caller only:
+// callers that run credential tools (gh auth token) must not keep or print it.
+export function run(argv, { cwd, env, input, timeout = 30_000 } = {}) {
+  const r = spawnSync(argv[0], argv.slice(1), {
+    cwd,
+    env,
+    input,
+    timeout,
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
+  });
+  return { ok: r.status === 0 && !r.error, status: r.status, stdout: r.stdout || '', stderr: r.stderr || '' };
+}
+
+export function hasCommand(name, env) {
+  for (const dir of (env?.PATH || '').split(':')) {
+    if (!dir) continue;
+    try {
+      const st = lstatSync(join(dir, name));
+      if (st.isFile() || st.isSymbolicLink()) return true;
+    } catch {}
+  }
+  return false;
+}
+
+// stat, following symlinks (dotfiles are often links into a dotfiles repo), or null.
+export function statOrNull(p) {
+  try {
+    return statSync(p);
+  } catch {
+    return null;
+  }
+}
+
+// Every regular file under dir (symlinks followed), as paths relative to it, sorted.
+export function listFiles(dir, skip = () => false, rel = '', depth = 0) {
+  const out = [];
+  if (depth > 8) return out;
+  let names = [];
+  try {
+    names = readdirSync(join(dir, rel)).sort();
+  } catch {
+    return out;
+  }
+  for (const n of names) {
+    if (skip(n)) continue;
+    const r = rel ? `${rel}/${n}` : n;
+    const st = statOrNull(join(dir, r));
+    if (!st) continue;
+    if (st.isDirectory()) out.push(...listFiles(dir, skip, r, depth + 1));
+    else if (st.isFile()) out.push(r);
+  }
+  return out;
+}
+
+export function readText(p) {
+  try {
+    return readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+export function human(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  const u = ['KB', 'MB', 'GB'];
+  let v = bytes / 1024;
+  let i = 0;
+  while (v >= 1024 && i < u.length - 1) {
+    v /= 1024;
+    i++;
+  }
+  return `${v >= 10 ? Math.round(v) : v.toFixed(1)} ${u[i]}`;
+}
+
+// The Vault item name for a file item: its path with / as -, as `instabox vault set-file` does.
+export function vaultFileName(path) {
+  return path
+    .replace(/^\./, '')
+    .replaceAll('/', '-')
+    .replace(/[^A-Za-z0-9._-]/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 128);
+}
+
+// A Vault file path must be relative, clean, without .. components (docs/vault.md).
+export function vaultPathOK(p) {
+  if (!p || p.startsWith('/') || p.length > 255 || /[\0\\\n]/.test(p)) return false;
+  return p.split('/').every((c) => c !== '' && c !== '.' && !c.startsWith('..'));
+}
+
+// A selector as the plan writes it: `*` (every box) or `key=value,key=value`.
+export function parseSelector(s) {
+  s = s.trim();
+  if (s === '*' || s === '') return {};
+  const out = {};
+  for (const part of s.split(',')) {
+    const m = part.trim().match(/^([A-Za-z0-9_.-]{1,63})=([^,]{0,512})$/);
+    if (!m) throw new Error(`selector ${JSON.stringify(s)}: write * or key=value,key=value`);
+    out[m[1]] = m[2];
+  }
+  if (Object.keys(out).length > 32) throw new Error('selector: 32 labels at most');
+  return out;
+}
+
+export function selectorString(sel) {
+  const e = Object.entries(sel || {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return e.length ? e.map(([k, v]) => `${k}=${v}`).join(',') : '*';
+}
+
+export function sameSelector(a, b) {
+  return selectorString(a) === selectorString(b);
+}
+
+// True when the module is the script node was started with (not imported by a test).
+export function isMain(meta) {
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(meta.url));
+  } catch {
+    return false;
+  }
+}