instabox 0.5.2 → 0.5.3

package/README.md

@@ -5,7 +5,7 @@ npx instabox@latest      # sign in, install the CLI and the agent skills
 npx instabox@latest sh   # the same, then start a new box and SSH into it
 ```
 
-`npx instabox@latest` signs you in to instabox in your browser (first run only; confirm its current Instabox account or choose another), 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 prints the next steps. It does not touch your boxes.
+`npx instabox@latest` signs you in to instabox in your browser (first run only; confirm its current Instabox account or choose another), installs the `instabox` CLI already signed in or updates an out-of-date one (skip with `--no-cli`), installs or updates the agent skills from [`../skills`](../skills) in `~/.claude/skills` and `~/.agents/skills` (skip with `--no-skills`), and prints the next steps. It does not touch your boxes.
 
 `npx instabox@latest sh` does all that, then starts a new box (`box-<hex>`) and drops you into it over SSH, no questions. Run by an agent (no terminal), it starts the box and prints `instabox ssh <box> -- <command>` instead of opening a shell. At the box limit it starts nothing and lists your boxes, to remove one (`instabox rm <box>`) or open one (`instabox ssh <box>`).
 
@@ -19,6 +19,7 @@ Any other command line is the instabox CLI's ([`cmd/instabox`](../cmd/instabox))
 - `sh` always starts a new box, with no timeout and no idle auto-suspend of its own. An existing box is entered with the CLI: `instabox ssh <box>`.
 - 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.
+- On Windows, where `/install.sh` does not run, the CLI is installed by `lib/cli.mjs` itself: `/dl/instabox-windows-<arch>.exe`, checked against `SHA256SUMS` and `--version`, renamed to `%LOCALAPPDATA%\Programs\instabox\instabox.exe`. The output gives the PowerShell line that puts that folder on the user's PATH; `npx instabox@latest <command>` finds it without that.
 - 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.
 

package/bin/instabox.mjs

@@ -20,8 +20,10 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createClient } from '../lib/api.mjs';
 import { orderBoxes } from '../lib/boxes.mjs';
+import { guestUserNote, localGuestUser } from '../lib/guestuser.mjs';
 import { checkCli, findCli, installCli, installCommand, isOnboarding, real, runCli } from '../lib/cli.mjs';
-import { callbackHandler } from '../lib/login.mjs';
+import { browserCommand, callbackHandler } from '../lib/login.mjs';
+import { sessionArgs } from '../lib/ssh.mjs';
 import { loadCredentials, saveCredentials } from '../lib/credentials.mjs';
 
 // Same variables, same order as the instabox CLI, so both talk to one server.
@@ -66,12 +68,7 @@ function usage() {
 const client = createClient(API);
 
 function openBrowser(url) {
-  const cmd =
-    process.platform === 'darwin'
-      ? ['open', [url]]
-      : process.platform === 'win32'
-        ? ['cmd', ['/c', 'start', '', url]]
-        : ['xdg-open', [url]];
+  const cmd = browserCommand(url);
   try {
     spawn(cmd[0], cmd[1], { stdio: 'ignore', detached: true })
       .on('error', () => {})
@@ -253,16 +250,18 @@ async function newBox() {
   };
   if (img) body.imageId = img.id;
   else body.templateId = IMAGE;
+  // The box's Linux user is named after yours, so `ssh <box>` over your own network works. A
+  // box from one of your own snapshots keeps the snapshot's user.
+  const user = localGuestUser();
+  if (user.name && (!img || img.official)) body.guestUser = user.name;
   const op = await waitOp(await client.call('POST', '/v1/machines', body));
-  return { id: op.machineId, name: body.name };
+  return { id: op.machineId, name: body.name, user };
 }
 
 // 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;
   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}` : '';
@@ -285,7 +284,6 @@ async function ensureCli() {
       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})`)}`;
   return (
@@ -433,6 +431,9 @@ async function onboard(wantBox) {
   const ready = `ready in ${((Date.now() - t0) / 1000).toFixed(1)}s`;
   if (!tty) {
     console.log(`\n  ${green('✓')} box ${bold(box.name)} ${ready}`);
+    const got = await client.call('GET', '/v1/machines/' + enc(box.id)).catch(() => null);
+    const note = guestUserNote(box.user, box.name, got?.guestUser);
+    if (note) console.log(dim(`  ${note}`));
     await reportInstalls(cli);
     return nextSteps([
       [`instabox ssh ${box.name} -- <command>`, 'run a command in it'],
@@ -466,6 +467,8 @@ async function onboard(wantBox) {
 
   const pauses = m.timeoutAt ? dim(` · pauses itself in ${Math.max(1, Math.round(ttlSeconds / 60))} min`) : '';
   process.stdout.write(`\r  ${green('✓')} box ${bold(m.name)} ${ready}${pauses}\n`);
+  const note = guestUserNote(box.user, m.name, m.guestUser);
+  if (note) console.log(dim(`  ${note}`));
   await reportInstalls(cli);
   console.log(dim(`  type ${'exit'} to leave · stuck? press Enter, then ~.`));
   // The box's prompt is ~37 columns; narrower terminals make bash scroll the input line sideways.
@@ -473,24 +476,7 @@ async function onboard(wantBox) {
     console.log(dim(`  your terminal is ${process.stdout.columns} columns wide; widen it for a readable prompt`));
   console.log();
 
-  const args = [
-    '-i',
-    key,
-    '-o',
-    `CertificateFile=${key}-cert.pub`,
-    '-o',
-    `UserKnownHostsFile=${join(dir, 'known_hosts')}`,
-    '-o',
-    'IdentitiesOnly=yes',
-    '-o',
-    'StrictHostKeyChecking=yes',
-    '-o',
-    'LogLevel=ERROR',
-    '-p',
-    String(c.port),
-    '-t',
-    `${c.username}@${c.host}`,
-  ];
+  const args = sessionArgs({ dir, key, port: c.port, username: c.username, host: c.host });
   const child = spawn('ssh', args, { stdio: 'inherit' });
   child.on('exit', (code) => {
     console.log(`\n  ${dim(`left ${m.name}. Back in:`)} instabox ssh ${m.name}\n`);
@@ -505,7 +491,6 @@ else if (isOnboarding(args)) await onboard(args.includes('sh'));
 else {
   let path = findCli();
   if (!path) {
-    if (process.platform === 'win32') die('the instabox CLI runs on macOS and Linux only');
     console.error(dim('  installing the instabox CLI…'));
     const r = await installCli(API);
     if (r.error) die(`could not install the instabox CLI: ${r.error}`);

package/lib/cli.mjs

@@ -1,9 +1,9 @@
 // The Go instabox CLI: find it, install it, hand it the command line.
 import { execFile, spawn, spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { createReadStream, realpathSync, statSync } from 'node:fs';
+import { createReadStream, mkdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { delimiter, join, sep } from 'node:path';
+import { join, sep } from 'node:path';
 
 const OUR_FLAGS = new Set(['--github', '--google', '--no-cli', '--no-skills']);
 
@@ -20,29 +20,36 @@ export const real = (p) => {
   }
 };
 
-function runnable(p) {
+// Windows has no execute bit: any instabox.exe file runs.
+function runnable(p, platform) {
   try {
     const s = statSync(p);
-    return s.isFile() && (s.mode & 0o111) !== 0;
+    return s.isFile() && (platform === 'win32' || (s.mode & 0o111) !== 0);
   } catch {
     return false;
   }
 }
 
+// Where installCli puts the CLI on Windows, which has no /install.sh.
+export function windowsInstallDir(env = process.env) {
+  const local = env.LOCALAPPDATA || join(env.USERPROFILE || homedir(), 'AppData', 'Local');
+  return join(local, 'Programs', 'instabox');
+}
+
 // Skips node_modules dirs and links back to us, like insta's findDurableOnPath.
-export function findCli({ env = process.env, self = process.argv[1] } = {}) {
+export function findCli({ env = process.env, self = process.argv[1], platform = process.platform } = {}) {
   const me = real(self);
+  const win = platform === 'win32';
   const home = env.HOME || homedir();
   const dirs = [
-    ...(env.PATH || '').split(delimiter),
+    ...(env.PATH || '').split(win ? ';' : ':'),
     env.INSTABOX_INSTALL_DIR,
-    '/usr/local/bin',
-    join(home, '.local', 'bin'),
+    ...(win ? [windowsInstallDir(env)] : ['/usr/local/bin', join(home, '.local', 'bin')]),
   ];
   for (const dir of dirs) {
     if (!dir || dir.toLowerCase().includes('node_modules')) continue;
-    const p = join(dir, 'instabox');
-    if (!runnable(p)) continue;
+    const p = join(dir, win ? 'instabox.exe' : 'instabox');
+    if (!runnable(p, platform)) continue;
     const r = real(p);
     if (r === me || r.includes(`${sep}node_modules${sep}`)) continue;
     return p;
@@ -55,8 +62,12 @@ const INSTALL = 's=$(curl -fsSL "$1/install.sh") && printf \'%s\\n\' "$s" | sh';
 
 // 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`;
+export const installCommand = (api, dir, platform = process.platform) =>
+  platform === 'win32'
+    ? 'npx instabox@latest'
+    : 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.
@@ -115,7 +126,8 @@ export async function checkCli(path, api, { fetch = globalThis.fetch } = {}) {
 
 // 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 } = {}) {
+export function installCli(api, { dir, platform = process.platform, ...win } = {}) {
+  if (platform === 'win32') return installWindows(api, { dir, ...win });
   return new Promise((resolve) => {
     let out = '';
     const env = dir ? { ...process.env, INSTABOX_INSTALL_DIR: dir } : process.env;
@@ -148,3 +160,51 @@ export function runCli(path, args) {
   }
   process.exit(r.status ?? 1);
 }
+
+const WINDOWS_ARCH = { x64: 'amd64', arm64: 'arm64' };
+
+// Keep its checks in step with /install.sh's, which Windows cannot run.
+async function installWindows(
+  api,
+  { dir, env = process.env, arch = process.arch, fetch = globalThis.fetch, version = cliVersion } = {},
+) {
+  if (!WINDOWS_ARCH[arch]) return { error: `no instabox CLI for Windows on ${arch} (x64 and arm64 only)` };
+  const name = `instabox-windows-${WINDOWS_ARCH[arch]}.exe`;
+  const to = dir || env.INSTABOX_INSTALL_DIR || windowsInstallDir(env);
+  const tmp = join(to, `.instabox.install.${process.pid}.exe`);
+  try {
+    const get = async (file) => {
+      const res = await fetch(`${api}/dl/${file}`, { signal: AbortSignal.timeout(300_000) });
+      if (!res.ok) throw new Error(`download ${file}: HTTP ${res.status}`);
+      return Buffer.from(await res.arrayBuffer());
+    };
+    const [body, sums] = await Promise.all([get(name), get('SHA256SUMS')]);
+    const want = String(sums)
+      .split('\n')
+      .map((l) => l.trim().split(/\s+/))
+      .find(([, n]) => n === name || n === `*${name}`)?.[0];
+    if (!/^[0-9a-f]{64}$/.test(want || '')) return { error: `no valid checksum for ${name} in SHA256SUMS` };
+    const got = createHash('sha256').update(body).digest('hex');
+    if (got !== want) return { error: `checksum mismatch for ${name}; run it again if a deploy was in progress` };
+    mkdirSync(to, { recursive: true });
+    writeFileSync(tmp, body, { mode: 0o755 });
+    const v = await version(tmp);
+    if (!v) {
+      rmSync(tmp, { force: true });
+      return { error: 'the downloaded instabox does not run (instabox --version failed)' };
+    }
+    const path = join(to, 'instabox.exe');
+    renameSync(tmp, path);
+    const onPath = (env.PATH || '').split(';').some((d) => d.replace(/[\\/]+$/, '').toLowerCase() === to.toLowerCase());
+    return {
+      path,
+      version: v,
+      pathHint: onPath
+        ? null
+        : `[Environment]::SetEnvironmentVariable('Path', [Environment]::GetEnvironmentVariable('Path', 'User') + ';${to.replaceAll("'", "''")}', 'User')`,
+    };
+  } catch (e) {
+    rmSync(tmp, { force: true });
+    return { error: e.message };
+  }
+}

package/lib/guestuser.mjs

@@ -0,0 +1,59 @@
+// The box's Linux user (docs/guest-user-plan.md): the person's local username, normalized the
+// way the server and the instabox CLI do (pkg/instaboxapi/guestuser.go; the shared test vectors
+// keep them equal). A name that is not valid after normalization is not sent: the box gets `user`.
+import { userInfo } from 'node:os';
+
+export const DEFAULT_GUEST_USER = 'user';
+
+const PATTERN = /^[a-z_][a-z0-9_-]{0,31}$/;
+
+// root, instabox and the users and groups of the Debian base rootfs; names starting with
+// `systemd-` too. Nothing else (pkg/instaboxapi/guestuser.go): `ubuntu`, `admin`, `docker`, … are
+// allowed, and the guest falls back to `user` when its rootfs already has the name.
+const RESERVED = new Set(
+  `root daemon bin sys sync games man lp mail news uucp proxy www-data backup list irc
+   _gnats gnats nobody nogroup _apt messagebus sshd polkitd tss
+   sudo adm staff users tty disk shadow utmp operator dialout audio video plugdev netdev
+   input render kvm instabox`.split(/\s+/),
+);
+
+export function validGuestUser(name) {
+  return PATTERN.test(name) && !RESERVED.has(name) && !name.startsWith('systemd-');
+}
+
+// The guest user for a local username: trimmed, without a `DOMAIN\` prefix or an `@domain`
+// suffix, lowercased, spaces made `_`. null when that is not a valid guest user.
+export function normalizeGuestUser(local) {
+  let s = String(local ?? '').trim();
+  const b = s.lastIndexOf('\\');
+  if (b >= 0) s = s.slice(b + 1);
+  const a = s.lastIndexOf('@');
+  if (a >= 0) s = s.slice(0, a);
+  s = s.trim().toLowerCase().replaceAll(' ', '_');
+  return validGuestUser(s) ? s : null;
+}
+
+// This computer's username and its guest user: { local, name } (name null when it cannot be
+// one); local is '' when the OS does not say.
+export function localGuestUser() {
+  let local = '';
+  try {
+    local = userInfo().username || '';
+  } catch {}
+  if (!local) local = process.env.USER || process.env.USERNAME || '';
+  return { local, name: local ? normalizeGuestUser(local) : null };
+}
+
+// The user of boxes from templates that predate per-box users; nothing to say about it.
+export const LEGACY_GUEST_USER = 'dev';
+
+// The one line to print about the box's user after a create, or null when there is nothing to
+// say: plain `ssh <box>` over your own network sends the local name, which matches only when
+// normalization left it as it was. actual is the box's guestUser as the server reports it.
+export function guestUserNote({ local, name }, box, actual) {
+  if (!local || actual === LEGACY_GUEST_USER) return null;
+  const user = actual || name || DEFAULT_GUEST_USER;
+  if (!name) return `your username ${local} cannot be a Linux user name; the box's user is ${user}`;
+  if (name === local && (!actual || actual === name)) return null;
+  return `user ${user} (ssh ${user}@${box} over your own network; instabox ssh ${box} as usual)`;
+}

package/lib/login.mjs

@@ -36,3 +36,10 @@ export function callbackHandler({ state, exchange, finish, page }) {
     finish(result);
   };
 }
+
+// The command that opens url in the browser. On Windows never `cmd /c start`: cmd ends the URL at its first &.
+export function browserCommand(url, platform = process.platform) {
+  if (platform === 'darwin') return ['open', [url]];
+  if (platform === 'win32') return ['rundll32', ['url.dll,FileProtocolHandler', url]];
+  return ['xdg-open', [url]];
+}

package/lib/ssh.mjs

@@ -0,0 +1,26 @@
+// ssh's argv for a session with this run's throwaway key, certificate and known_hosts.
+import { join } from 'node:path';
+
+// ssh splits an -o value at whitespace and reads ' as an open quote; Windows profile paths often have either.
+export const sshConfigArg = (path) => (/[ \t']/.test(path) ? `"${path}"` : path);
+
+export function sessionArgs({ dir, key, port, username, host }) {
+  return [
+    '-i',
+    key,
+    '-o',
+    `CertificateFile=${sshConfigArg(`${key}-cert.pub`)}`,
+    '-o',
+    `UserKnownHostsFile=${sshConfigArg(join(dir, 'known_hosts'))}`,
+    '-o',
+    'IdentitiesOnly=yes',
+    '-o',
+    'StrictHostKeyChecking=yes',
+    '-o',
+    'LogLevel=ERROR',
+    '-p',
+    String(port),
+    '-t',
+    `${username}@${host}`,
+  ];
+}

package/package.json

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

@@ -7,7 +7,7 @@ metadata:
 
 # instabox CLI
 
-An instabox sandbox is a Linux VM (Debian, user `dev`, sudo). It has a root disk and a persistent `/data` disk; HOME is `/data/home`. Boxes are private to the signed-in account.
+An instabox sandbox is a Linux VM (Debian, one user with passwordless sudo: named after your local username when created with `instabox create`, `user` from the dashboard, `dev` on older boxes; `instabox get <box>` shows it). It has a root disk and a persistent `/data` disk; HOME is `/data/home`. Boxes are private to the signed-in account.
 
 ## Sign in
 
@@ -38,7 +38,7 @@ instabox create --name work                     # new box; waits until it is run
 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 exec work --cwd /data/home -- ls -la   # exec runs `bash -lc` as the box's user
 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
@@ -49,7 +49,7 @@ 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`, `--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.
+- A new box pauses itself after 30 idle minutes (no agent working, no terminal use, little CPU) and wakes on the next `exec`, `ssh`, `files`, public port request or `instabox wake <box>`; 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.

package/skills/instabox-snapshots/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: instabox-snapshots
-description: Use when the user wants to save an instabox box's state and load it later — "save a snapshot", "checkpoint this box", "restore/load from a snapshot", "start a new box from my setup", "clone this box". Covers instabox snapshot save/ls/files/rm, create --snapshot and fork.
+description: Use when the user wants to save an instabox box's state and load it later — "save a snapshot", "checkpoint this box", "restore/load from a snapshot", "start a new box from my setup", "clone this box". Covers instabox snapshot save/ls/files/rm and create --snapshot.
 metadata:
   installed-by: instabox
 ---
@@ -40,13 +40,17 @@ instabox snapshot files work-ready /etc/os-release      # print a text file
 
 This reads the snapshot's root disk only; `/data` (and HOME) are not browsable here. To check files under `/data`, load the snapshot into a box and use `instabox exec`.
 
-## Copy a box directly
+## Copy a box
+
+There is no direct copy: save a snapshot of it, create the new box from that, and delete the snapshot if you will not use it again.
 
 ```sh
-instabox fork work work-copy            # copies a stopped box's root and /data; no snapshot kept
+instabox snapshot save work --name work-copy
+instabox create --name work2 --snapshot work-copy
+instabox snapshot rm work-copy                          # optional; work2 is not affected
 ```
 
-Use `fork` for a one-off copy and `snapshot save` when you will start from the same state again.
+The copy does not inherit `--no-vault`. If the box was created with `--no-vault`, pass it again: `instabox create --name work2 --snapshot work-copy --no-vault`.
 
 ## Clean up