instabox 0.4.3 → 0.5.0

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 {
@@ -16,11 +16,10 @@ import {
 import http from 'node:http';
 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 +33,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 +51,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)
@@ -199,51 +195,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();
+  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}`);
   }
-}
-
-// 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 };
-  }
-  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 +219,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.
@@ -367,7 +329,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 +348,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 +408,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 +436,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 +444,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/package.json

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