instabox 0.4.3 → 0.5.1

package/README.md

@@ -1,19 +1,22 @@
 # instabox (npm)
 
 ```
-npx instabox@latest
+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
 ```
 
-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.
+`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.
 
-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`.
+`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>`).
+
+A GitHub and a Google sign-in are separate instabox accounts, each with its own boxes. Both this entry point and `instabox login` let the browser confirm the account. Explicit `--github` or `--google` starts that provider directly, as does `instabox login --provider github|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.
 
 ## How it works
 
 - `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.
+- `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.
 - 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.

package/bin/instabox.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// npx instabox@latest: box + CLI + skills + SSH in; any other command goes to the instabox CLI.
+// npx instabox@latest: sign in + CLI + skills; `sh` also starts a new box and SSHes in. Anything else goes to the CLI.
 import { spawn, spawnSync } from 'node:child_process';
 import { createHash, randomBytes } from 'node:crypto';
 import {
@@ -14,13 +14,13 @@ 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 { 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, checkCli, findCli, installCli, installCommand, isOnboarding, real, runCli } from '../lib/cli.mjs';
+import { orderBoxes } from '../lib/boxes.mjs';
+import { checkCli, findCli, installCli, installCommand, isOnboarding, real, runCli } from '../lib/cli.mjs';
 import { callbackHandler } from '../lib/login.mjs';
 import { loadCredentials, saveCredentials } from '../lib/credentials.mjs';
 
@@ -34,10 +34,9 @@ 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;
-// 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';
+// With no provider selected, the browser confirms its existing Instabox account
+// or offers sign-in. Explicit flags still start the chosen provider directly.
+const PROVIDER = process.argv.includes('--google') ? 'google' : process.argv.includes('--github') ? '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);
@@ -53,12 +52,10 @@ function usage() {
   console.log(`
   ${bold('instabox')}: a cloud box in seconds
 
-  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
-      --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)
+  npx instabox@latest               sign in (first time), install the instabox CLI and agent skills
+  npx instabox@latest sh            the same, then start a new box and SSH into it
+      --github, --google            sign in directly with that provider instead of confirming
+                                    the browser's current Instabox account
       --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)
@@ -130,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');
@@ -151,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`);
@@ -166,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.
@@ -181,7 +212,7 @@ async function signedIn() {
       return t;
     } catch {}
   }
-  const t = await browserLogin();
+  const t = await signInWithInvite();
   saveCredentials(API, t);
   return t;
 }
@@ -199,51 +230,17 @@ async function waitOp(op) {
   return op;
 }
 
-// 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')
-    .catch((e) => die(`could not list your boxes: ${e.message}`));
+// At the box limit: say so, and show the boxes there are to remove or open instead.
+async function quotaFull(err) {
+  const { machines = [] } = await client.call('GET', '/v1/machines?limit=100').catch(() => ({}));
   const boxes = orderBoxes(machines);
-  const wanted = boxFlag(process.argv.slice(2));
-  if (wanted) return boxes.find((b) => b.name === wanted || b.id === wanted) || die(`you have no box named ${wanted}`);
-  if (!boxes.length) return null;
-  const ask = process.stdin.isTTY && process.stdout.isTTY;
-  const w = Math.max(...boxes.map((b) => b.name.length));
-  console.log(`\n  ${bold('Your boxes')}`);
-  boxes.forEach((b, i) =>
-    console.log(
-      `    ${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: true };
-  console.log(`    ${boxes.length + 1}) ${green('+ new box')}`);
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    for (;;) {
-      const i = parseChoice(await rl.question('  Enter a box [1]: '), boxes.length);
-      if (i !== null) return i === boxes.length ? null : boxes[i];
-    }
-  } finally {
-    rl.close();
-  }
-}
-
-// Wakes a suspended or stopped box and leaves its settings (timeout, auto-suspend) alone.
-async function enterBox(id) {
-  const path = '/v1/machines/' + enc(id);
-  let m = await client.call('GET', path);
-  if (m.operationId) {
-    await waitOp(await client.call('GET', '/v1/operations/' + enc(m.operationId)));
-    m = await client.call('GET', path);
-  }
-  if (m.state === 'suspended' || m.state === 'stopped') {
-    await waitOp(await client.call('POST', `${path}/${m.state === 'suspended' ? 'resume' : 'start'}`));
-    return { id: m.id, resumed: true };
+  console.log(`\n  ${bold('Box limit reached')} ${dim(`(${err.message})`)}`);
+  if (boxes.length) {
+    const w = Math.max(...boxes.map((b) => b.name.length));
+    for (const b of boxes) console.log(`    ${b.name.padEnd(w)}  ${b.state}`);
   }
-  if (m.state !== 'running') throw new Error(`box ${m.name} is ${m.state}`);
-  return { id: m.id, reused: true };
+  console.log(`\n  Remove one with ${bold('instabox rm <box>')}, or open one with ${bold('instabox ssh <box>')}.\n`);
+  process.exit(1);
 }
 
 async function newBox() {
@@ -257,7 +254,7 @@ async function newBox() {
   if (img) body.imageId = img.id;
   else body.templateId = IMAGE;
   const op = await waitOp(await client.call('POST', '/v1/machines', body));
-  return { id: op.machineId, reused: false };
+  return { id: op.machineId, name: body.name };
 }
 
 // Runs while the box starts; never fatal. Returns a line to print, or null.
@@ -307,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`).
@@ -356,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;
 }
 
@@ -367,7 +386,16 @@ async function reportInstalls(cli) {
   if (skillsLine) console.log(`  ${green('✓')} ${skillsLine}`);
 }
 
-async function sh() {
+// The commands to run next, one per line, descriptions lined up.
+function nextSteps(rows) {
+  const w = Math.max(...rows.map(([cmd]) => cmd.length));
+  console.log(`\n  ${bold('Next steps')}`);
+  for (const [cmd, what] of rows) console.log(`    ${cmd.padEnd(w)}  ${dim(what)}`);
+  console.log();
+}
+
+// Sign-in, the CLI and the skills; with `sh` (wantBox) also a new box and an SSH session in it.
+async function onboard(wantBox) {
   console.log(`\n  ${bold('instabox')} ${dim('· a cloud box in seconds')}\n`);
 
   client.use(await signedIn());
@@ -377,22 +405,40 @@ async function sh() {
   );
 
   const cli = ensureCli();
-  const picked = await chooseBox();
-  if (picked?.listed) {
+  if (!wantBox) {
     await reportInstalls(cli);
-    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;
+    return nextSteps([
+      ['npx instabox@latest sh', 'start a new box and SSH into it'],
+      ['instabox ls', 'list your boxes'],
+      ['instabox ssh <box>', 'open a shell in one; add -- <command> to run just that'],
+    ]);
   }
-  // Only entering a box needs OpenSSH; the list-and-stop path above runs without it.
-  for (const bin of ['ssh', 'ssh-keygen']) {
-    if (spawnSync(bin, ['-V'], { stdio: 'ignore' }).error) die(`${bin} was not found. Install OpenSSH and try again.`);
+  // An agent (no terminal) cannot use an interactive shell, so it gets the commands instead.
+  const tty = process.stdin.isTTY && process.stdout.isTTY;
+  if (tty) {
+    for (const bin of ['ssh', 'ssh-keygen']) {
+      if (spawnSync(bin, ['-V'], { stdio: 'ignore' }).error)
+        die(`${bin} was not found. Install OpenSSH and try again.`);
+    }
   }
   const t0 = Date.now();
-  process.stdout.write(`\n  ${dim(picked ? `opening ${picked.name}…` : 'starting a new box…')}`);
-  const box = await (picked ? enterBox(picked.id) : newBox()).catch((e) =>
-    die(`could not start your box: ${e.message}`),
-  );
+  process.stdout.write(`\n  ${dim('starting a new box…')}`);
+  const box = await newBox().catch(async (e) => {
+    if (e.code !== 'quota_exceeded') die(`could not start your box: ${e.message}`);
+    // The way out of the limit is `instabox rm`, so the CLI and the skills land before the exit.
+    console.log();
+    await reportInstalls(cli);
+    return quotaFull(e);
+  });
+  const ready = `ready in ${((Date.now() - t0) / 1000).toFixed(1)}s`;
+  if (!tty) {
+    console.log(`\n  ${green('✓')} box ${bold(box.name)} ${ready}`);
+    await reportInstalls(cli);
+    return nextSteps([
+      [`instabox ssh ${box.name} -- <command>`, 'run a command in it'],
+      [`instabox ssh ${box.name}`, 'open a shell in it, from a terminal'],
+    ]);
+  }
 
   // A throwaway key for this session; only its public half leaves this machine.
   const dir = mkdtempSync(join(tmpdir(), 'instabox-'));
@@ -419,12 +465,7 @@ async function sh() {
   writeFileSync(join(dir, 'known_hosts'), `@cert-authority [${c.host}]:${c.port} ${c.hostTrust.publicKey}\n`);
 
   const pauses = m.timeoutAt ? dim(` · pauses itself in ${Math.max(1, Math.round(ttlSeconds / 60))} min`) : '';
-  const took = box.resumed
-    ? `resumed in ${((Date.now() - t0) / 1000).toFixed(1)}s`
-    : box.reused
-      ? 'back in'
-      : `ready in ${((Date.now() - t0) / 1000).toFixed(1)}s`;
-  process.stdout.write(`${process.stdout.isTTY ? '\r' : '\n'}  ${green('✓')} box ${bold(m.name)} ${took}${pauses}\n`);
+  process.stdout.write(`\r  ${green('✓')} box ${bold(m.name)} ${ready}${pauses}\n`);
   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.
@@ -452,7 +493,7 @@ async function sh() {
   ];
   const child = spawn('ssh', args, { stdio: 'inherit' });
   child.on('exit', (code) => {
-    console.log(`\n  ${dim(`left ${m.name}. Run`)} npx instabox@latest ${dim('again to get back in.')}\n`);
+    console.log(`\n  ${dim(`left ${m.name}. Back in:`)} instabox ssh ${m.name}\n`);
     process.exit(code ?? 0);
   });
 }
@@ -460,7 +501,7 @@ async function sh() {
 // Any other command line is the CLI's, so `npm i -g instabox` still gives a working `instabox`.
 const args = process.argv.slice(2);
 if (args.length === 1 && (args[0] === '-h' || args[0] === '--help')) usage();
-else if (isOnboarding(args)) await sh();
+else if (isOnboarding(args)) await onboard(args.includes('sh'));
 else {
   let path = findCli();
   if (!path) {

package/lib/api.mjs

@@ -3,9 +3,10 @@ import { randomUUID } from 'node:crypto';
 import { loadCredentials, saveCredentials } from './credentials.mjs';
 
 export class ApiError extends Error {
-  constructor(status, message) {
+  constructor(status, message, code) {
     super(message);
     this.status = status;
+    this.code = code;
   }
 }
 
@@ -25,7 +26,8 @@ export function createClient(
 
   const parse = async (res) => {
     const data = res.status === 204 ? null : await res.json().catch(() => null);
-    if (!res.ok) throw new ApiError(res.status, data?.error?.message || `instabox HTTP ${res.status}`);
+    if (!res.ok)
+      throw new ApiError(res.status, data?.error?.message || `instabox HTTP ${res.status}`, data?.error?.code);
     return data;
   };
 

package/lib/boxes.mjs

@@ -1,15 +1,6 @@
-// Which of your boxes to offer, in order: live ones only, running first, then newest.
+// Your boxes in the order to show them: live ones only, running first, then newest.
 export function orderBoxes(machines) {
   return machines
     .filter((m) => !['deleting', 'deleted', 'error'].includes(m.state))
     .sort((a, b) => (b.state === 'running') - (a.state === 'running') || new Date(b.createdAt) - new Date(a.createdAt));
 }
-
-// The 0-based pick from a typed answer: Enter is the first box, count itself is "new box", else null.
-export function parseChoice(answer, count) {
-  const s = answer.trim();
-  if (s === '') return 0;
-  if (!/^\d+$/.test(s)) return null;
-  const n = Number(s);
-  return n >= 1 && n <= count + 1 ? n - 1 : null;
-}

package/lib/cli.mjs

@@ -7,22 +7,9 @@ import { delimiter, join, sep } from 'node:path';
 
 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.
+// Bare `instabox` or `sh`, with only our flags; anything else is a CLI command.
 export function isOnboarding(args) {
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (a === '--box' && i + 1 < args.length) i++;
-    else if (a !== 'sh' && !OUR_FLAGS.has(a) && !a.startsWith('--box=')) return false;
-  }
-  return true;
-}
-
-// The box named by --box NAME or --box=NAME, else null.
-export function boxFlag(args) {
-  const i = args.indexOf('--box');
-  if (i !== -1) return args[i + 1] ?? null;
-  const eq = args.find((a) => a.startsWith('--box='));
-  return eq ? eq.slice('--box='.length) : null;
+  return args.every((a) => a === 'sh' || OUR_FLAGS.has(a));
 }
 
 export const real = (p) => {

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.4.3",
+  "version": "0.5.1",
   "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,10 +13,10 @@ 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 with GitHub; --provider google for Google
+instabox login               # confirm the browser's account, or choose GitHub / 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.
+A GitHub sign-in and a Google sign-in are separate accounts with separate boxes. Both `instabox login` and `npx instabox@latest` open account confirmation in the browser: use its current Instabox account or choose another. To go directly to a provider, use `instabox login --provider github|google`, or `npx instabox@latest --github|--google`. The CLI shares the sign-in `npx` made. Device-code sign-in (`--device`) uses GitHub.
 
 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.
 
@@ -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,12 @@ 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.
+
 ## 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.