instabox 0.6.3 → 0.7.0

package/README.md

@@ -5,17 +5,17 @@ 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 (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 with a device code (first run only: open the page it prints on any device and enter the code; it opens the page for you where there is a browser, never with `--no-browser`), 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>`).
 
-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`.
+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 sign-in page offer both. `--google` asks for Google directly, as does `instabox login --provider google`.
 
 Any other command line is the instabox CLI's ([`cmd/instabox`](../cmd/instabox)): `npx instabox@latest ls` runs `instabox ls`, installing the CLI first if it is missing.
 
 ## 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.
+- `bin/instabox.mjs` runs instabox's device-code sign-in (RFC 8628, `POST /v1/auth/device`, then polls `/v1/auth/device/token`), as `instabox login` does, 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.
 - `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.

package/bin/instabox.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // 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 { randomBytes } from 'node:crypto';
 import {
   accessSync,
   constants as fsConstants,
@@ -13,7 +13,6 @@ import {
   mkdirSync,
   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';
@@ -22,7 +21,7 @@ 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 { browserCommand, callbackHandler } from '../lib/login.mjs';
+import { browserCommand, canOpenBrowser, deviceLogin } from '../lib/login.mjs';
 import { makeDirPrivate, sessionArgs } from '../lib/ssh.mjs';
 import { loadCredentials, saveCredentials } from '../lib/credentials.mjs';
 import { agentName, track } from '../lib/telemetry.mjs';
@@ -38,9 +37,10 @@ const API = (
 const IMAGE = process.env.INSTABOX_IMAGE || 'agent-browser';
 // SSH certificate lifetime for a box with no timeout of its own.
 const CERT_MIN = 120;
-// With no provider selected, the browser confirms its existing Instabox account
-// or offers sign-in. Explicit flags still start the chosen provider directly.
+// With no provider selected, the sign-in page offers GitHub or Google; --google asks for Google's.
 const PROVIDER = process.argv.includes('--google') ? 'google' : process.argv.includes('--github') ? 'github' : '';
+// The code is always printed; --no-browser only stops opening the sign-in page.
+const NO_BROWSER = process.argv.includes('--no-browser');
 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);
@@ -56,10 +56,11 @@ function usage() {
   console.log(`
   ${bold('instabox')}: a cloud box in seconds
 
-  npx instabox@latest               sign in (first time), install the instabox CLI and agent skills
+  npx instabox@latest               sign in with a device code (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
+      --github, --google            sign in with that provider
+      --no-browser                  only print the sign-in page and code; do not open a browser
       --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)
@@ -89,54 +90,6 @@ function openBrowser(url) {
   } catch {}
 }
 
-// The page the browser lands on after sign-in (served from the loopback listener).
-function signInPage(ok, title, text, who) {
-  const esc = (s) =>
-    String(s ?? '').replace(
-      /[&<>"']/g,
-      (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c],
-    );
-  const accent = ok ? '#6ee7b7' : '#f87171';
-  const icon = ok ? '<path d="M7 12.5l3.2 3.2L17 9" />' : '<path d="M8 8l8 8M16 8l-8 8" />';
-  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
-<title>${esc(title)} · instabox</title>
-<style>
-  :root { --bg:#0b0b0c; --panel:#141416; --line:#26262a; --fg:#ededed; --dim:#8b8b92; --accent:${accent}; }
-  * { box-sizing:border-box; }
-  html, body { height:100%; margin:0; }
-  body { background:radial-gradient(1200px 600px at 50% -10%, color-mix(in srgb, var(--accent) 10%, transparent), transparent 60%), var(--bg);
-    color:var(--fg); font:15px/1.5 ui-sans-serif,system-ui,-apple-system,sans-serif; display:grid; place-items:center; padding:24px 16px; }
-  .card { width:100%; max-width:420px; background:var(--panel); border:1px solid var(--line); border-radius:16px; padding:36px 28px 28px; text-align:center;
-    box-shadow:0 30px 80px rgba(0,0,0,.45); animation:rise .5s cubic-bezier(.2,.9,.3,1.1) both; }
-  .brand { font:600 13px ui-monospace,SFMono-Regular,Menlo,monospace; letter-spacing:.08em; color:var(--dim); margin-bottom:28px; }
-  .badge { width:64px; height:64px; margin:0 auto 20px; border-radius:50%; display:grid; place-items:center;
-    background:color-mix(in srgb, var(--accent) 14%, transparent); border:1px solid color-mix(in srgb, var(--accent) 55%, transparent);
-    box-shadow:0 0 36px color-mix(in srgb, var(--accent) 35%, transparent); animation:pop .6s .15s cubic-bezier(.2,.9,.3,1.4) both; }
-  .badge svg { width:30px; height:30px; stroke:var(--accent); stroke-width:2.4; fill:none; stroke-linecap:round; stroke-linejoin:round;
-    stroke-dasharray:30; stroke-dashoffset:30; animation:draw .45s .45s ease-out forwards; }
-  h1 { font-size:22px; margin:0 0 6px; }
-  .who { color:var(--accent); font-weight:600; margin:0 0 10px; }
-  p { color:var(--dim); margin:0; }
-  .hint { margin-top:24px; padding-top:18px; border-top:1px solid var(--line); font-size:13px; color:var(--dim); }
-  kbd { white-space:nowrap; font:12px ui-monospace,SFMono-Regular,Menlo,monospace; background:var(--bg); border:1px solid var(--line); border-radius:6px; padding:2px 6px; color:var(--fg); }
-  @keyframes rise { from { opacity:0; transform:translateY(12px); } }
-  @keyframes pop { from { opacity:0; transform:scale(.4); } }
-  @keyframes draw { to { stroke-dashoffset:0; } }
-  @media (prefers-reduced-motion: reduce) { .card, .badge, .badge svg { animation:none; stroke-dashoffset:0; } }
-</style></head><body>
-<main class="card">
-  <div class="brand">INSTABOX</div>
-  <div class="badge"><svg viewBox="0 0 24 24" aria-hidden="true">${icon}</svg></div>
-  <h1>${esc(title)}</h1>
-  ${who ? `<p class="who">Signed in as ${esc(who)}</p>` : ''}
-  <p>${esc(text)}</p>
-  ${ok ? '<div class="hint">You can close this tab. Next time, <kbd>npx instabox@latest</kbd> skips this step.</div>' : ''}
-</main>
-</body></html>`;
-}
-
-// 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.
 // 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 '';
@@ -151,11 +104,22 @@ async function askInvite(again) {
   }
 }
 
-// signInWithInvite is browserLogin, asking for an invite code when the account is on the waitlist.
+// signInWithInvite is a device-code sign-in, asking for an invite code when the account is on the waitlist.
 async function signInWithInvite() {
   let invite = '';
   for (;;) {
-    const r = await browserLogin(invite);
+    const r = await deviceLogin({
+      anon: client.anon,
+      invite,
+      provider: PROVIDER,
+      show: (ds) => {
+        console.log(`  ${bold('Sign in to instabox')}: open ${ds.verificationUri}`);
+        console.log(`  and enter the code ${bold(ds.userCode)}\n`);
+        console.log(`  ${dim('Waiting for you to sign in…')}`);
+      },
+      open: NO_BROWSER || !canOpenBrowser() ? null : openBrowser,
+      sleep,
+    });
     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');
@@ -168,50 +132,7 @@ async function signInWithInvite() {
   }
 }
 
-async function browserLogin(invite) {
-  const verifier = randomBytes(32).toString('base64url');
-  const state = randomBytes(24).toString('base64url');
-  const challenge = createHash('sha256').update(verifier).digest('base64url');
-  let finish;
-  const done = new Promise((r) => {
-    finish = r;
-  });
-  const exchange = async (code) => {
-    const tok = await client.anon('POST', '/v1/auth/cli/token', {
-      code,
-      codeVerifier: verifier,
-      redirectUri: redirect,
-    });
-    client.use(tok);
-    return { tok, me: await client.call('GET', '/v1/me').catch(() => null) };
-  };
-  const page = {
-    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, 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`);
-  openBrowser(start);
-  const timer = setTimeout(() => finish({ err: 'timed out waiting for the browser sign-in' }), 5 * 60_000);
-  const result = await done;
-  clearTimeout(timer);
-  server.close();
-  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.
+// The CLI's saved token, a refreshed one, or a device-code sign-in; saved where the CLI reads it.
 async function signedIn() {
   const c = loadCredentials(API);
   if (c?.accessToken && new Date(c.accessExpiresAt) - Date.now() > 60_000) return c;

package/lib/cli.mjs

@@ -5,7 +5,7 @@ import { createReadStream, mkdirSync, realpathSync, renameSync, rmSync, statSync
 import { homedir } from 'node:os';
 import { join, sep } from 'node:path';
 
-const OUR_FLAGS = new Set(['--github', '--google', '--no-cli', '--no-skills']);
+const OUR_FLAGS = new Set(['--github', '--google', '--no-browser', '--no-cli', '--no-skills']);
 
 // Bare `instabox` or `sh`, with only our flags; anything else is a CLI command.
 export function isOnboarding(args) {

package/lib/login.mjs

@@ -1,40 +1,41 @@
-// The loopback sign-in callback (RFC 8252); one code exchange per sign-in, however often it is hit.
-export function callbackHandler({ state, exchange, finish, page }) {
-  let taken = false;
-  return async (req, res) => {
-    const u = new URL(req.url, 'http://127.0.0.1');
-    const html = { 'Content-Type': 'text/html; charset=utf-8' };
-    if (u.pathname !== '/callback') {
-      res.writeHead(404);
-      return res.end();
+// Device-code sign-in (RFC 8628), as `instabox login` does it: POST /v1/auth/device for a code,
+// show it, then poll /v1/auth/device/token until the user approves, denies, or the code expires.
+export async function deviceLogin({ anon, invite = '', provider = '', show, open, sleep, now = Date.now }) {
+  const body = {};
+  if (invite) body.invite = invite;
+  // GitHub is the server's default device sign-in; only WorkOS's offers Google.
+  if (provider === 'google' || provider === 'workos') body.provider = provider;
+  let ds;
+  try {
+    ds = await anon('POST', '/v1/auth/device', body);
+  } catch (e) {
+    return { err: e.message, code: e.code };
+  }
+  if (body.provider && ds.provider !== 'workos')
+    return { err: "this server's device sign-in supports GitHub only: use --github" };
+  show(ds);
+  if (open) open(ds.verificationUriComplete || ds.verificationUri);
+  let interval = (Number.isFinite(ds.interval) && ds.interval >= 0 ? ds.interval : 5) * 1000;
+  const deadline = now() + (ds.expiresIn > 0 ? ds.expiresIn : 900) * 1000;
+  for (;;) {
+    await sleep(interval);
+    try {
+      return { tok: await anon('POST', '/v1/auth/device/token', { deviceCode: ds.deviceCode }) };
+    } catch (e) {
+      if (e.code === 'slow_down') interval += 5000;
+      else if (e.code === 'expired_token') return { err: 'the code expired; run the command again', code: e.code };
+      else if (e.code === 'access_denied') return { err: 'sign-in was denied', code: e.code };
+      else if (e.code !== 'authorization_pending') return { err: e.message, code: e.code };
     }
-    if (u.searchParams.get('state') !== state) {
-      res.writeHead(400, html);
-      return res.end(page.stale());
-    }
-    // A reload or a double navigation: the server revokes the whole session when a code comes back.
-    if (taken) {
-      res.writeHead(200, html);
-      return res.end(page.again());
-    }
-    taken = true;
-    let result;
-    if (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'));
-      } catch (e) {
-        result = { err: e.message };
-      }
-    }
-    res.writeHead(200, html);
-    res.end(result.tok ? page.ok(result) : page.failed(result.err, result.code));
-    finish(result);
-  };
+    if (now() > deadline) return { err: 'the code expired; run the command again', code: 'expired_token' };
+  }
+}
+
+// Whether a local browser can show the sign-in page; the code is printed either way.
+export function canOpenBrowser(env = process.env, platform = process.platform) {
+  const display = Boolean(env.DISPLAY || env.WAYLAND_DISPLAY);
+  if (env.SSH_CONNECTION && !display) return false;
+  return display || platform === 'darwin' || platform === 'win32';
 }
 
 // The command that opens url in the browser. On Windows never `cmd /c start`: cmd ends the URL at its first &.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instabox",
-  "version": "0.6.3",
+  "version": "0.7.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,12 +13,12 @@ An instabox sandbox is a Linux VM (Debian, one user with passwordless sudo: name
 
 ```sh
 instabox whoami              # who is signed in (fails if nobody)
-instabox login               # confirm the browser's account, or choose GitHub / Google
+instabox login               # device code: open the printed page, enter the code
 ```
 
-A GitHub sign-in and a Google sign-in with the same verified email share one account; with different emails they 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.
+A GitHub sign-in and a Google sign-in with the same verified email share one account; with different emails they are separate accounts with separate boxes. Both `instabox login` and `npx instabox@latest` sign in with a device code: they print a page and a code (and open the page when there is a browser); the user opens it on any device, enters the code and chooses GitHub or Google there. It works the same over SSH or on a machine without a browser. Relay the page and the code to the user and wait; the command finishes on its own. For Google directly, use `instabox login --provider google`, or `npx instabox@latest --google`. The CLI shares the sign-in `npx` made.
 
-For CI or an agent without a browser, use an API key instead: `export INSTABOX_API_KEY=ibk_...` (the user creates it on the dashboard's API Keys page). Never print, commit or log a key.
+For CI or an agent without a browser, use an API key instead: `export INSTABOX_API_KEY=ibk_...` (the user creates it in the dashboard: API keys in the sidebar). Never print, commit or log a key.
 
 ## Templates
 
@@ -27,6 +27,7 @@ For CI or an agent without a browser, use an API key instead: `export INSTABOX_A
 - `universal`: the same tools without the desktop, which installs itself the first time it is used (about half a minute); a smaller root disk. The dashboard shows it as **basic**.
 - `herdr`: for the herdr client.
 - `orca`: for Orca desktop and mobile.
+- `t3`: for the T3 Code desktop and mobile clients.
 
 `instabox templates` lists the ones this server offers. The free plan creates boxes from `agent-browser` only: another template is refused with `403 template_not_allowed` and needs a paid plan (the user upgrades on the dashboard). A box from a snapshot (`--snapshot`) works on every plan, whatever template the snapshot came from. Do not retry another template on the free plan; use `agent-browser`.
 
@@ -52,7 +53,9 @@ instabox ssh work                               # interactive shell (leave with:
 instabox exec work -- uname -a                  # one command, no SSH client needed
 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                  # idle time before it pauses (fixed at 30m unless an admin gave the account manual lifecycle)
+instabox auto-suspend work 10m                  # idle time before a paid box pauses
+instabox max-run work 120                      # pause a paid box after two running hours
+instabox max-run work -1                       # remove the runtime cap; idle policy still applies
 instabox stop work && instabox start work       # stop ends processes, keeps disks
 instabox suspend work && instabox resume work   # pause/resume keeps running processes
 instabox rename work api                        # rename in place, any state; ID and port URLs stay
@@ -60,41 +63,44 @@ instabox rm work                                # delete the box
 ```
 
 - Names or IDs (`m_...`) both work wherever `<id-or-name>` is accepted.
-- `create` options: `--template T` or `--snapshot S`, `--vcpus N --mem-mib M` (a size of the plan, see Sizes), `--auto-suspend D|0`, `--meta K=V`, `--org O`, `--secrets all|NAME,NAME|none`, `--env-secrets NAME,NAME|none`, `--no-wait`.
-- A 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. The 30 minutes are fixed for every account unless an admin gave it manual lifecycle: only then do `--auto-suspend 0` (always on) and `--auto-suspend 2h` apply, and the CLI prints a note when the server kept 30m. Boxes have no other timeout. Do not try to keep a box on by other means; a paused box resumes on the next command.
+- `create` options: `--template T` or `--snapshot S`, `--vcpus N --mem-mib M` (a size of the plan, see Sizes), `--auto-suspend D|0`, `--max-run-minutes N`, `--meta K=V`, `--org O`, `--secrets all|NAME,NAME|none`, `--no-wait`.
+- Idle auto-pause defaults to 30 minutes. Paid boxes allow 5, 10, 15, 20, 25 or 30 minutes, or `0` to turn it off. Free boxes keep 30 minutes unless an admin grants an idle override. Idle means no agent working, no terminal use and little CPU.
+- Max run minutes is independent of idle activity: `-1` is unlimited, `0` pauses immediately, and a positive integer forces a pause after that many running minutes. Free boxes have a fixed 480-minute cap that only an admin session can change; paid boxes default to `-1` and can change it. An idle override does not permit changes to a free box's runtime cap. The first limit reached pauses the box; both timers restart after sleep and wake.
+- A runtime pause blocks every wake path during a server-configured cooldown, 10 minutes by default. Wait until the `cooldownUntil` deadline shown by `instabox get`; edits cannot clear it. Afterward, an automatically paused box wakes on `exec`, `ssh`, `files`, a public port request or `instabox wake <box>`. A zero runtime cap must be changed before waking. A normal pause preserves memory and processes.
 - 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'`.
+- `exec` with one argument after `--` runs it as a shell string (`instabox exec work -- 'ls | wc -l'`); several arguments run as that exact argv, each quoted for you (`instabox exec work -- bash -c 'echo a b > /tmp/x'`).
+- `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 longer commands (installs, builds, test suites) over SSH, which also returns the exit code: `instabox ssh work -- 'cd /data/workspace/app && npm ci'`. The box's runtime cap still applies during SSH or exec.
 - The box's HOME has `MACHINE.md` (which box it is, its size, what survives a stop, the installed tools) and `AGENTS.md`. Both are worth reading before working in the box; they appear a moment after it starts.
 - A public URL for a web server in the box: `instabox port publish work 3000` prints it (`instabox port ls`, `instabox port unpublish work 3000`). The URL works while the box runs.
 
 ## Organization Secrets
 
-Secrets are encrypted key=value entries owned by an org. Each entry has one delivery mode:
+Secrets are encrypted API credentials owned by an org, each limited to the HTTPS hosts it may be sent to. A box that selects a Secret gets a placeholder in its environment, never the credential itself. When a request from the box goes to one of the Secret's allowed hosts over HTTPS, the outbound proxy swaps the placeholder in the request headers for the credential. Code in the box can call the API but cannot read or copy the credential. No header-name configuration is needed.
 
-- `proxy`: the box receives a placeholder. The outbound proxy replaces it in ordinary HTTPS header values only when the destination matches the Secret's allowed hosts. Code in the box can use this credential but does not receive its real value through Secret delivery. No header-name configuration is needed.
-- `env`: the box receives the real value. Use this explicitly for native database credentials, local signing, and clients that cannot use header substitution. Code running in the box can read and copy the value.
+Secrets suit HTTP API keys and tokens that a client sends in a request header: model providers, GitHub's API, deploy and SaaS APIs. They do not cover database URLs or passwords, signing keys, or anything a client hashes, encodes or sends outside an HTTPS header; those need their own setup on the box.
 
-A new box without Secret selection flags keeps the existing Vault behavior. Opt into Secrets with `--secrets` or `--env-secrets`, or use `secrets select` later. At creation, `--env-secrets` alone also selects all org proxy Secrets. Select env names explicitly; there is no env `all` mode. Metadata labels do not select Secrets, and Secrets do not deliver files.
+Secrets replace the Vault, which is legacy and will be retired: save every new API credential as a Secret, never in the Vault, and do not suggest `vault set`, `set-file` or `import` to users. A new box without `--secrets` still gets an existing user's Vault items (see the last point below). Opt into Secrets with `create --secrets`, or use `secrets select` later. Metadata labels do not select Secrets, and Secrets do not deliver files.
 
 ```sh
 instabox secrets ls --org team                 # metadata only
-instabox secrets show work                    # selection and independent proxy/guest status
-instabox secrets set SERVICE_API_KEY --org team --delivery proxy --host api.example.com
-instabox secrets set DATABASE_URL --org team --delivery env
-instabox create --name app --org team --secrets SERVICE_API_KEY --env-secrets DATABASE_URL
-instabox secrets select work --env-secrets DATABASE_URL
-instabox secrets push work                    # refresh managed env/trust on a running box
-instabox create --name tenant --no-vault --secrets none --env-secrets none
+instabox secrets show work                     # selection and proxy status
+instabox secrets set SERVICE_API_KEY --org team --host api.example.com
+instabox secrets import .env --org team --host api.example.com   # every value gets these hosts
+instabox create --name app --org team --secrets SERVICE_API_KEY
+instabox secrets select work --secrets SERVICE_API_KEY,OTHER_API_KEY
+instabox secrets push work                     # refresh the selection on a running box
+instabox create --name tenant --no-vault --secrets none
 ```
 
-- Values for `set` come from stdin or a hidden prompt. Never print a credential or put its value into agent output, chat, command arguments, or logs. Before asking for a credential, check metadata with `secrets ls --org <org>` and `secrets show <box>`. A silent check such as `test "${NAME+x}" = x` tests variable presence without revealing it; it does not prove successful proxy authorization.
-- Org commands default to the signed-in user's personal org. Use `--org` for a team, and select only Secrets from the box's org. Value, host, delivery-mode and deletion changes require an org owner/admin sign-in. API keys with the appropriate machine scopes can inspect metadata and manage sandbox selections, but cannot retrieve or change Secret values.
-- Selection updates replace each supplied list; omitted lists remain unchanged. Preserve existing names when adding to a selection. Proxy selection accepts `all`; both selections accept `none` or `[]`. JSON arrays allow a Secret literally named `all` or `none`.
-- Proxy delivery requires allowed hosts and works with literal placeholders in HTTPS headers on port 443. Do not hash, encode, or sign with a placeholder. Native database TLS is not HTTPS. Unsupported traffic never falls back to real-value env delivery.
-- Rotating an existing proxy value preserves its placeholder. Env refresh and newly added variables affect new shells that load the managed environment; restart or reconfigure existing applications and connection pools. Removing a selection cannot recover env values already copied into processes, files, or snapshots. Revoke or rotate those credentials at the upstream service when necessary.
-- For a box intended for another person or tenant, disable personal Vault injection with `--no-vault` and explicitly select only the org Secrets they may use. For a fresh box with neither system's credentials, use `--no-vault --secrets none --env-secrets none`. Empty Secret selections alone still permit Vault injection. These flags do not remove credentials already copied into a source snapshot.
-- For an existing box, disable Vault with `start BOX --no-vault` or `resume BOX --no-vault` and explicitly clear both Secret selections with `secrets select BOX --secrets none --env-secrets none`. Refresh a running guest with both `vault push BOX` and `secrets push BOX`. Existing processes and copied files can retain values; disabling either system does not recover those copies.
-- Vault remains available through `vault set`, `set-file`, `import`, `ls`, `rm`, `show`, and `push`. The CLI warns about future retirement. A box may use Vault and Secrets together; Secrets wins same-named environment variables. Neither store automatically copies or deletes the other. Move values deliberately when the user is ready.
+- Values for `set` come from stdin or a hidden prompt. Never print a credential or put its value into agent output, chat, command arguments, or logs. Before asking for a credential, check metadata with `secrets ls --org <org>` and `secrets show <box>`. A silent check such as `test "${NAME+x}" = x` tests that the placeholder is present without revealing it; it does not prove the upstream accepts the credential.
+- `--host` is optional and repeatable. Give each exact hostname the credential may be sent to; without `--host` (or with `--host '*'`) every public HTTPS destination is allowed. Schemes, ports, paths, IP addresses, and partial wildcards such as `*.example.com` are rejected. Use the service's API host, such as `api.openai.com`, never a guess from the credential's value.
+- Org commands default to the signed-in user's personal org. Use `--org` for a team, and select only Secrets from the box's org. Value, host and deletion changes require an org owner/admin sign-in. API keys with the appropriate machine scopes can inspect metadata and manage sandbox selections, but cannot retrieve or change Secret values.
+- `secrets select BOX --secrets` replaces the box's selection: `all`, `none`, comma-separated names, or a JSON array (which allows a Secret literally named `all` or `none`). Keep existing names when adding one.
+- Placeholders work only in HTTPS request headers on port 443 to the allowed hosts. Do not hash, encode, or sign with a placeholder; other traffic carries the placeholder unchanged.
+- Rotating a value keeps its placeholder, so running clients need no change. Newly selected names appear in new shells that load the managed environment; restart existing applications to pick them up.
+- For a box intended for another person or tenant, disable personal Vault injection with `--no-vault` and select only the org Secrets they may use. For a fresh box with neither system's credentials, use `--no-vault --secrets none`. An empty Secret selection alone still permits Vault injection. These flags do not remove credentials already copied into a source snapshot.
+- For an existing box, disable Vault with `start BOX --no-vault` or `resume BOX --no-vault` and clear the Secret selection with `secrets select BOX --secrets none`. Refresh a running guest with both `vault push BOX` and `secrets push BOX`. Vault values already copied into processes or files remain there; disabling Vault does not recover them.
+- The Vault is legacy and will be retired; every `vault` command prints a warning. Its commands remain only for items a user already saved: `vault ls`, `show`, `push` and `rm`, and `vault export` to recover a retained item. A box may use Vault and Secrets together; Secrets wins same-named environment variables. Neither store copies or deletes the other. To move a Vault env item that is an HTTP API credential, the user enters its value again as a Secret with its hosts (`secrets set NAME --host HOST` reads it from a hidden prompt), you select it on the box, then `vault rm` it with the user's go-ahead. Never read a Vault value to copy it. Database credentials and other non-HTTP secrets are not supported by Secrets and need their own setup on the box; Vault file items likewise.
 
 ## Moving work onto a box
 
@@ -115,7 +121,7 @@ instabox feedback --json --type bug --component cli --area exec \
 
 - `--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.
+- Emails, keys, tokens, home paths and public IPv4 addresses are redacted before sending, but do not paste secrets into it. Signed in, the report opens a support ticket on the account, and the team's replies show in the dashboard at the link it prints (`ticket` in `--json`); signed out or waitlisted, it reaches the team without one.
 - A failed or unconfirmed submission prints a warning and exits 0: do not retry. File one report per problem, not one per attempt.
 
 ## Habits

package/skills/instabox-basic-setup/SKILL.md

@@ -1,19 +1,21 @@
 ---
 name: instabox-basic-setup
-description: Use when the user wants their instabox setup to use local tokens, git config or editor config — "put my tokens / dotfiles / git config into instabox", "set up my box like my laptop", "move my setup to instabox". Produces a names-only scan and a reviewable plan, saves selected credentials as org key=value Secrets with explicit proxy/env modes, grants them only through sandbox selections, and copies approved ordinary config files directly to named running sandboxes. It does not put files in the Secret store or automatically give real credentials to future boxes. Moves no code; for a repo, use instabox-move-repo.
+description: Use when the user wants their instabox setup to use local tokens, git config or editor config — "put my tokens / dotfiles / git config into instabox", "set up my box like my laptop", "move my setup to instabox". Produces a names-only scan and a reviewable plan, saves known API tokens as org Secrets for their service's HTTPS API hosts, selects them on named sandboxes, and copies approved ordinary config files directly to named running sandboxes. It does not put files in the Secret store. Moves no code; for a repo, use instabox-move-repo.
 metadata:
   installed-by: instabox
 ---
 
 # Basic setup with org Secrets and sandbox config copies
 
-Use the user's chosen org and sandbox IDs. Secrets are shared within an org, but real-value `env` delivery requires explicit sandbox selection. A `proxy` Secret supplies a placeholder for HTTPS header substitution at its allowed hosts. Other org sandboxes selecting all proxy Secrets, including future sandboxes, can also use a newly saved proxy credential. Updating an existing Secret affects every sandbox already authorized to use it.
+Use the user's chosen org and sandbox IDs. Secrets are shared within an org. A sandbox that selects a Secret gets a placeholder in its environment; the outbound proxy puts the token into HTTPS request headers sent to the Secret's allowed hosts, and nowhere else. Other org sandboxes whose selection is `all`, including future sandboxes, can also use a newly saved Secret. Updating an existing Secret affects every sandbox already selecting it.
+
+Only tokens in the built-in registry (`TOKEN_HOSTS` in `scripts/lib.mjs`) are saved, each for its service's API hosts: for example `ANTHROPIC_API_KEY` for `api.anthropic.com`, `OPENAI_API_KEY` for `api.openai.com`, `GH_TOKEN` and `GITHUB_TOKEN` for `api.github.com`. Every other credential-looking export becomes a manual step. Secrets work only for clients that send the token in an HTTPS header; database URLs, signing keys and git's own credential exchange need their own setup on the box.
 
 Git and editor configuration is copied separately, once, to the named running sandboxes. It is not stored as Secrets, does not consume Secret quota, and is not reapplied on start or resume. This skill moves no repository or agent history. Use `instabox-move-repo` for code and conversation history.
 
 | Group | Destination | Sources |
 | --- | --- | --- |
-| Tokens | Encrypted org key=value Secrets; explicit per-token `proxy` or `env` mode | GitHub token through `gh auth token`; known service credentials in the environment or shell startup files; other credential-like exports listed unchecked |
+| Tokens | Encrypted org Secrets, each limited to its registry hosts | GitHub token through `gh auth token`; registry tokens in the environment or shell startup files; other credential-like exports listed as manual steps |
 | Git | Files under the selected sandbox's home | `.gitconfig`, `.config/git/config`, global gitignore |
 | Editor and terminal | Files under the selected sandbox's home | `.vimrc`, nvim config without plugin checkouts, `.tmux.conf` |
 
@@ -23,11 +25,11 @@ The scripts beside this file require Node 18+ locally and Python 3 in sandboxes
 | --- | --- |
 | `scan.mjs` | Read-only inventory of names, source locations, sizes and manual setup requirements; no credential values in output |
 | `plan.mjs` | Write and strictly parse the editable plan, binding it to an org and Secret metadata |
-| `push.mjs` | Read approved values into memory, validate all inputs and quotas, save Secrets through CLI stdin, merge explicit sandbox selections, and copy config |
+| `push.mjs` | Read approved values into memory, validate all inputs and quotas, save Secrets with their registry hosts through CLI stdin, merge sandbox selections, and copy config |
 | `content.mjs` | Rewrite HOME paths, remove recognized credential lines, and adapt git/editor configuration for Linux |
 | `install-files.py` | Install ordinary config files privately, refusing symlinks and unsafe paths; no Secret-store or legacy Vault access |
 
-Never print credential values, shell startup files, credential-bearing config, or `gh auth token` output. Do not run these scripts against the user's machine unless their request authorizes this setup. Scripts may read credentials internally; their output is limited to names, sizes and outcomes. If a value cannot be obtained, let the user supply it through a hidden CLI prompt with the appropriate org and delivery mode.
+Never print credential values, shell startup files, credential-bearing config, or `gh auth token` output. Do not run these scripts against the user's machine unless their request authorizes this setup. Scripts may read credentials internally; their output is limited to names, sizes and outcomes. If a value cannot be obtained, let the user supply it through the hidden prompt of `instabox secrets set NAME --org ORG --host HOST`.
 
 ## 1. Scan and choose the org
 
@@ -53,20 +55,11 @@ node "$S/plan.mjs" write --scan "$W/scan.json" --secrets "$W/secrets.json" \
   --org "$ORG_ID" --sandbox <sandbox-id> > "$W/plan.md"
 ```
 
-Repeat `--sandbox` for additional targets, or omit it to save Secrets without adding env grants or copying files. The plan lists `Org`, `Sandboxes`, checkboxes and one `Delivery` line per token. The org is bound to the metadata used to generate the plan; regenerate for another org. Sandbox IDs and delivery policies can be edited in the plan.
-
-A token policy looks like either of these:
-
-```text
-Delivery `env:SERVICE_API_KEY`: `proxy` hosts `api.example.com`
-Delivery `env:DATABASE_URL`: `env` hosts `-`
-```
-
-The `env:` prefix is the scanner's variable ID, not its delivery mode. New token rows start with explicit `env` mode for client compatibility; this gives the named sandboxes the real value. Choose `proxy` and exact approved hosts when the client sends the value literally in an HTTPS header on port 443. Do not infer hosts from a token's value or silently switch modes when a client fails. Native database protocols, local signing and git's encoded credential exchange need the real value or a separate protocol-aware broker. Proxy placeholders cannot be used as real signing or encoding inputs.
+Repeat `--sandbox` for additional targets, or omit it to save Secrets without changing any selection or copying files. The plan lists `Org`, `Sandboxes` and checkboxes; each token row names the hosts its Secret is limited to. The org is bound to the metadata used to generate the plan; regenerate for another org. Sandbox IDs and checkboxes can be edited in the plan; hosts come from the registry and cannot.
 
-Well-known token rows are checked by default; unknown and keychain-backed sources are unchecked. Existing Secrets changed outside the last successful run are unchecked, and checking them authorizes replacement in the org. A previous proxy mode is preserved as the starting policy on a repeat run. Files are unchecked when no sandbox is selected. Checking a config file authorizes replacement of that path on each named sandbox.
+The `env:` prefix in a row ID is the scanner's variable ID. Registry token rows are checked by default; keychain-backed sources are unchecked. Existing Secrets changed outside the last successful run are unchecked, and checking them authorizes replacement in the org. Files are unchecked when no sandbox is selected. Checking a config file authorizes replacement of that path on each named sandbox.
 
-Show the concrete names, modes, allowed hosts, org and target sandboxes. Obtain any choices or authorization the original request did not already provide before reading values or writing. Do not ask again for an action already explicitly authorized. Explain that env values are readable by sandbox code and may persist in processes, files or snapshots; removing a selection cannot recover them.
+Show the concrete names, allowed hosts, org and target sandboxes. Obtain any choices or authorization the original request did not already provide before reading values or writing. Do not ask again for an action already explicitly authorized.
 
 Parse the approved plan:
 
@@ -75,7 +68,7 @@ node "$S/plan.mjs" parse --scan "$W/scan.json" --secrets "$W/secrets.json" \
   --org "$ORG_ID" --limits "$W/limits.json" "$W/plan.md" > "$W/selection.json"
 ```
 
-Exit 1 identifies malformed or missing rows, invalid policies, a changed org/catalog, unsafe config, or a file selection without targets. Fix choices without changing item IDs or deleting rows. Exit 3 identifies quota or copy-size limits. Config files have their own copy limits and do not count as Secret entries. Values are measured before push; plan generation never reads token values. Legacy selector-based plans and manifests grant no authority in the new model and must be regenerated.
+Exit 1 identifies malformed or missing rows, a changed org/catalog, a scan with a token outside the registry, unsafe config, or a file selection without targets. Fix choices without changing item IDs or deleting rows. Exit 3 identifies quota or copy-size limits. Config files have their own copy limits and do not count as Secret entries. Values are measured before push; plan generation never reads token values. Legacy selector-based plans and manifests grant no authority in the new model and must be regenerated.
 
 ## 3. Dry-run, then apply the approved selection
 
@@ -88,11 +81,11 @@ The dry-run reads the approved credential sources and prepares filtered config,
 
 The pusher verifies org ownership, target orgs, Secret IDs and versions, input limits and total Secret quota before mutations. If a selected Secret changed since planning, regenerate the plan. These are preflight checks, not a transaction across all CLI operations: concurrent org edits can still occur during application. A failed run reports partial outcomes; successfully saved Secrets remain in the org. Do not assume rollback or automatic removal of previously copied files.
 
-Only selected token names are added to each target's grants; existing selections are preserved, including proxy `all`. Env selection never becomes `all`. Running targets receive an immediate managed-environment refresh; stopped targets can receive selections for their next start, but config copying requires them to be running. A failed or pending guest refresh does not install config that may depend on those credentials. Existing processes need to reload their environment or restart.
+Only selected token names are added to each target's selection; existing names are preserved, and a target selecting `all` stays `all`. Running targets receive an immediate refresh; stopped targets receive the selection at their next start, but config copying requires them to be running. A failed or pending refresh does not install config that may depend on those credentials. Existing processes need to reload their environment or restart to see new placeholders.
 
-Files are transformed before direct copying: this machine's HOME becomes `/data/home`, recognized credential lines are removed, macOS-only lines and unsupported signing/SSH rewrites are commented out. Structured config suspected of containing credentials is rejected rather than copied verbatim. This filtering is best effort, not a guarantee that arbitrary configuration is credential-free. The gh git helper is added only when this plan explicitly selects `GH_TOKEN` with env delivery. An existing org Secret by itself is not a sandbox grant; reuse it through an explicitly reviewed `instabox secrets select` update if needed, preserving other selected names.
+Files are transformed before direct copying: this machine's HOME becomes `/data/home`, recognized credential lines are removed, macOS-only lines and unsupported signing/SSH rewrites are commented out. Structured config suspected of containing credentials is rejected rather than copied verbatim. This filtering is best effort, not a guarantee that arbitrary configuration is credential-free. No git credential helper is added: git over HTTPS sends credentials in a form the proxy cannot fill in, so the box needs its own git sign-in (for example `gh auth login` there). An existing org Secret by itself is not a sandbox selection; add it through an explicitly reviewed `instabox secrets select BOX --secrets ...` that keeps the other selected names.
 
-The local manifest at `~/.config/instabox-basic-setup/pushed.json` stores org IDs, Secret IDs/versions/modes and copied sandbox paths, never values. It does not grant reuse across orgs or across deletion and recreation of a Secret. It records completed work for a repeat plan; it does not sync changes automatically.
+The local manifest at `~/.config/instabox-basic-setup/pushed.json` stores org IDs, Secret IDs, versions and hosts, and copied sandbox paths, never values. It does not grant reuse across orgs or across deletion and recreation of a Secret. It records completed work for a repeat plan; it does not sync changes automatically.
 
 ## 4. Verify and report
 
@@ -101,8 +94,8 @@ instabox secrets show <box>
 instabox exec <box> -- 'test "${GH_TOKEN+x}" = x && test -f "$HOME/.gitconfig"'
 ```
 
-Use silent presence checks and metadata; never print variables to verify them. A placeholder's presence does not prove proxy authorization or upstream success. Confirm client behavior without logging credentials, and explain application restarts when env values changed.
+Use silent presence checks and metadata; never print variables to verify them. A placeholder's presence does not prove the upstream accepts the token. Confirm client behavior without logging credentials, and explain application restarts.
 
-Report the org Secret names and modes saved, sandbox IDs whose selections changed, config paths copied, failures and manual setup steps. Saving env Secrets without targets adds no grants; replacing a value still affects sandboxes already authorized to use it. Future boxes without Secret selection flags keep their existing Vault behavior. At creation, selecting env Secrets alone also selects all org proxy Secrets; add an explicit proxy selection to narrow that access. Previously saved credentials or config not selected this time remain; deletion or cleanup needs its own intended scope. Rotate or revoke upstream when a previously delivered env value must stop working.
+Report the org Secret names and hosts saved, sandbox IDs whose selections changed, config paths copied, failures and manual setup steps. Saving Secrets without targets changes no selection; replacing a value still affects sandboxes already selecting it. Say that git over HTTPS needs its own sign-in on the box, and that credentials outside the registry (database URLs, cloud keys, other tokens) were not moved and need their own setup there; an HTTP API key can be added with `instabox secrets set NAME --org ORG --host HOST`. Future boxes created without `--secrets` keep their existing Vault behavior. Previously saved credentials or config not selected this time remain; deletion or cleanup needs its own intended scope.
 
 Config edits in a sandbox are not overwritten at every resume. Shell aliases, SSH keys, cloud credential files, agent sign-in databases and repositories are outside this inventory. Complete the selected manual sign-in steps only within existing authorization. Remove `$W` when no longer needed; it contains metadata and choices, not credential values.