instabox 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# instabox (npm)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+```
+npx instabox@latest
+```
+
+Signs you in to instabox in your browser (first run only; Google by default, `--github` for GitHub), 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 (macOS/Linux; skip with `--no-cli`), installs the agent skills from [`../skills`](../skills) into `~/.claude/skills` and `~/.agents/skills` (skip with `--no-skills`), and drops you into the box over SSH. `npx instabox@latest sh` does the same.
+
+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.
+- The bin is also called `instabox`, so `lib/cli.mjs` finds the real CLI the way the insta CLI does: PATH without `node_modules` dirs and without links back to this script, then the installer's own targets.
+- `prepack` copies `../skills` into the package; every skill there ships on the next publish.
+
+## Develop
+
+```sh
+npm ci
+npm test
+npm run format:check
+npm pack            # copies ../skills, then builds instabox-<version>.tgz
+npx --package=./instabox-0.4.0.tgz instabox --help
+```
+
+`INSTABOX_API_URL` points it at another instabox server.
+
+## Release
+
+Bump `version` in `package.json`, merge, then push a tag `npm-v<version>` (for example `git tag npm-v0.4.1 && git push origin npm-v0.4.1`). [`npm-release.yml`](../.github/workflows/npm-release.yml) checks the tag against `package.json`, runs the tests and publishes through npm trusted publishing, so there is no npm token anywhere. A version with a `-` (`0.5.0-rc.1`) goes to the `next` dist-tag, never to `latest`.
+
+The trusted publisher is set on npmjs.com, package `instabox` → Settings → Trusted Publisher: GitHub Actions, `InsForge` / `instabox` / `npm-release.yml`. The very first publish, before the package existed, was by hand with `npm publish --access public` from this directory.

package/bin/instabox.mjs

@@ -0,0 +1,405 @@
+#!/usr/bin/env node
+// npx instabox@latest: box + CLI + skills + SSH in; any other command goes to the instabox CLI.
+import { spawn, spawnSync } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdtempSync, readFileSync, writeFileSync, rmSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+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, findCli, installCli, isOnboarding, runCli } from '../lib/cli.mjs';
+import { callbackHandler } from '../lib/login.mjs';
+import { loadCredentials, saveCredentials } from '../lib/credentials.mjs';
+
+// Same variables, same order as the instabox CLI, so both talk to one server.
+const API = (
+  process.env.INSTABOX_SERVER ||
+  process.env.INSTABOX_API_URL ||
+  process.env.INSTABOX_API ||
+  'https://api.instabox.sh'
+).replace(/\/$/, '');
+const IMAGE = process.env.INSTABOX_IMAGE || 'universal';
+// SSH certificate lifetime for a box with no timeout of its own.
+const CERT_MIN = 120;
+const PROVIDER = process.argv.includes('--github') ? 'github' : 'google';
+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);
+const enc = encodeURIComponent;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function die(msg) {
+  console.error(`\n  ${msg}\n`);
+  process.exit(1);
+}
+
+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
+      --github                      sign in with GitHub instead of Google
+      --no-cli                      do not install 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)
+`);
+}
+
+// ---- instabox API ------------------------------------------------------------------------------
+const client = createClient(API);
+
+function openBrowser(url) {
+  const cmd =
+    process.platform === 'darwin'
+      ? ['open', [url]]
+      : process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '', url]]
+        : ['xdg-open', [url]];
+  try {
+    spawn(cmd[0], cmd[1], { stdio: 'ignore', detached: true })
+      .on('error', () => {})
+      .unref();
+  } 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.
+async function browserLogin() {
+  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) => 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;
+  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();
+  if (result.err) die(`sign-in failed: ${result.err}`);
+  return result.tok;
+}
+
+// The CLI's saved token, a refreshed one, or a browser 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;
+  if (c?.refreshToken && new Date(c.refreshExpiresAt) > Date.now()) {
+    try {
+      const t = await client.anon('POST', '/v1/auth/refresh', { refreshToken: c.refreshToken });
+      saveCredentials(API, t);
+      return t;
+    } catch {}
+  }
+  const t = await browserLogin();
+  saveCredentials(API, t);
+  return t;
+}
+
+async function waitOp(op) {
+  let delay = 250;
+  const deadline = Date.now() + 120_000;
+  while (op.state !== 'succeeded' && op.state !== 'failed') {
+    if (Date.now() > deadline) throw new Error('timed out waiting for the box');
+    await sleep(delay);
+    delay = Math.min(delay * 1.5, 1000);
+    op = await client.call('GET', '/v1/operations/' + enc(op.id));
+  }
+  if (op.state === 'failed') throw new Error(op.error?.message || 'box creation failed');
+  return op;
+}
+
+const LISTED = Symbol('listed');
+
+// The box to enter, null for a new one, or LISTED when there is no terminal to ask which one.
+async function chooseBox() {
+  const { machines = [] } = await client
+    .call('GET', '/v1/machines?limit=100')
+    .catch((e) => die(`could not list your boxes: ${e.message}`));
+  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;
+  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 };
+  }
+  if (m.state !== 'running') throw new Error(`box ${m.name} is ${m.state}`);
+  return { id: m.id, reused: true };
+}
+
+async function newBox() {
+  const { images } = await client.call('GET', '/v1/images');
+  const named = images.filter((i) => i.name === IMAGE || i.id === IMAGE);
+  const img = named.find((i) => i.official) || named[0];
+  const body = {
+    name: `demo-${randomBytes(3).toString('hex')}`,
+    desiredState: 'running',
+  };
+  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 };
+}
+
+// Runs while the box starts; never fatal. Returns a line to print, or null.
+async function ensureCli() {
+  if (process.argv.includes('--no-cli')) return null;
+  if (findCli()) return `instabox CLI already installed ${dim('· try')} instabox ls`;
+  if (process.platform === 'win32') return null;
+  const r = await installCli(API);
+  if (r.error) return `instabox CLI not installed ${dim(`(${r.error})`)}`;
+  return (
+    `instabox CLI installed${r.path ? ` at ${r.path}` : ''} ${dim('· try')} instabox ls` +
+    (r.pathHint ? `\n    ${dim('add it to your PATH:')} ${r.pathHint}` : '')
+  );
+}
+
+// Agent skills shipped in this package (skills/<name>/SKILL.md) into the folders coding agents
+// read. Overwrites only copies we installed earlier (marked `installed-by: instabox-demo`).
+function installSkills() {
+  if (process.argv.includes('--no-skills')) return null;
+  const src = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills');
+  let names;
+  try {
+    names = readdirSync(src).filter((n) => existsSync(join(src, n, 'SKILL.md')));
+  } catch {
+    return null;
+  }
+  const roots = [join(homedir(), '.claude', 'skills'), join(homedir(), '.agents', 'skills')];
+  const done = new Set();
+  for (const root of roots) {
+    for (const n of names) {
+      const dest = join(root, n, 'SKILL.md');
+      try {
+        if (existsSync(dest) && !readFileSync(dest, 'utf8').includes('installed-by: instabox-demo')) continue;
+        mkdirSync(join(root, n), { recursive: true });
+        writeFileSync(dest, readFileSync(join(src, n, 'SKILL.md')));
+        done.add(n);
+      } catch {}
+    }
+  }
+  return done.size
+    ? `agent skills installed: ${[...done].join(', ')} ${dim('(~/.claude/skills, ~/.agents/skills)')}`
+    : null;
+}
+
+// Waits for the CLI install started earlier, installs the skills, and prints a line for each.
+async function reportInstalls(cli) {
+  const cliLine = await cli;
+  if (cliLine) console.log(`  ${green('✓')} ${cliLine}`);
+  const skillsLine = installSkills();
+  if (skillsLine) console.log(`  ${green('✓')} ${skillsLine}`);
+}
+
+async function sh() {
+  console.log(`\n  ${bold('instabox')} ${dim('· a cloud box in seconds')}\n`);
+
+  client.use(await signedIn());
+  const me = await client.call('GET', '/v1/me').catch((e) => die(`instabox did not accept the sign-in: ${e.message}`));
+  console.log(
+    `  ${dim('signed in as')} ${bold(me.name || me.login)}${me.login && me.name ? dim(` (${me.login})`) : ''} ${dim('· not you?')} npx instabox@latest logout`,
+  );
+
+  const cli = ensureCli();
+  const picked = await chooseBox();
+  if (picked === LISTED) {
+    await reportInstalls(cli);
+    console.log(
+      `\n  Which box? ${bold('npx instabox@latest --box NAME')} enters one, ${bold('instabox create --name NAME')} starts a new one.\n`,
+    );
+    return;
+  }
+  // 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.`);
+  }
+  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}`),
+  );
+
+  // A throwaway key for this session; only its public half leaves this machine.
+  const dir = mkdtempSync(join(tmpdir(), 'instabox-'));
+  process.on('exit', () => {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {}
+  });
+  const key = join(dir, 'id_ed25519');
+  const kg = spawnSync('ssh-keygen', ['-q', '-t', 'ed25519', '-N', '', '-C', 'instabox', '-f', key], {
+    stdio: 'ignore',
+  });
+  if (kg.status !== 0 || !existsSync(key + '.pub')) die('could not create an SSH key (ssh-keygen failed)');
+  const m = await client.call('GET', '/v1/machines/' + enc(box.id));
+  const ttlSeconds = Math.max(
+    60,
+    Math.floor((new Date(m.timeoutAt || Date.now() + CERT_MIN * 60_000) - Date.now()) / 1000),
+  );
+  const c = await client.call('POST', `/v1/machines/${enc(box.id)}/connections`, {
+    publicKey: readFileSync(key + '.pub', 'utf8').trim(),
+    ttlSeconds,
+  });
+  writeFileSync(key + '-cert.pub', c.certificate.trim() + '\n');
+  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`);
+  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.
+  if (process.stdout.isTTY && process.stdout.columns > 0 && process.stdout.columns < 60)
+    console.log(dim(`  your terminal is ${process.stdout.columns} columns wide; widen it for a readable prompt`));
+  console.log();
+
+  const args = [
+    '-i',
+    key,
+    '-o',
+    `CertificateFile=${key}-cert.pub`,
+    '-o',
+    `UserKnownHostsFile=${join(dir, 'known_hosts')}`,
+    '-o',
+    'IdentitiesOnly=yes',
+    '-o',
+    'StrictHostKeyChecking=yes',
+    '-o',
+    'LogLevel=ERROR',
+    '-p',
+    String(c.port),
+    '-t',
+    `${c.username}@${c.host}`,
+  ];
+  const 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`);
+    process.exit(code ?? 0);
+  });
+}
+
+// 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 {
+  let path = findCli();
+  if (!path) {
+    if (process.platform === 'win32') die('the instabox CLI runs on macOS and Linux only');
+    console.error(dim('  installing the instabox CLI…'));
+    const r = await installCli(API);
+    if (r.error) die(`could not install the instabox CLI: ${r.error}`);
+    if (!r.path) die('the installer finished but the instabox CLI was not found');
+    path = r.path;
+  }
+  runCli(path, args);
+}

package/lib/api.mjs

@@ -0,0 +1,65 @@
+// instabox API calls; a 401 renews the session once and replays the call, as the insta CLI does.
+import { randomUUID } from 'node:crypto';
+import { loadCredentials, saveCredentials } from './credentials.mjs';
+
+export class ApiError extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+  }
+}
+
+export function createClient(
+  server,
+  { fetch = globalThis.fetch, load = () => loadCredentials(server), save = (t) => saveCredentials(server, t) } = {},
+) {
+  let session = null;
+
+  const send = (token, method, path, body, key) => {
+    const headers = { Accept: 'application/json' };
+    if (token) headers.Authorization = `Bearer ${token}`;
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
+    if (key) headers['Idempotency-Key'] = key;
+    return fetch(server + path, { method, headers, body: body === undefined ? undefined : JSON.stringify(body) });
+  };
+
+  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}`);
+    return data;
+  };
+
+  const anon = async (method, path, body) =>
+    parse(await send(null, method, path, body, method === 'GET' ? null : randomUUID()));
+
+  // The CLI's newer token if it already refreshed (a reused refresh token ends the session), else one rotation.
+  async function renew() {
+    const c = load();
+    if (c?.accessToken && c.accessToken !== session.accessToken && new Date(c.accessExpiresAt) - Date.now() > 60_000) {
+      session = c;
+      return true;
+    }
+    try {
+      session = await anon('POST', '/v1/auth/refresh', { refreshToken: c?.refreshToken || session.refreshToken });
+      save(session);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async function call(method, path, body) {
+    const key = method === 'GET' ? null : randomUUID();
+    let res = await send(session.accessToken, method, path, body, key);
+    if (res.status === 401 && (await renew())) res = await send(session.accessToken, method, path, body, key);
+    return parse(res);
+  }
+
+  return {
+    anon,
+    call,
+    use(tokens) {
+      session = tokens;
+    },
+  };
+}

package/lib/boxes.mjs

@@ -0,0 +1,15 @@
+// Which of your boxes to offer, in order: 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

@@ -0,0 +1,98 @@
+// The Go instabox CLI: find it, install it, hand it the command line.
+import { spawn, spawnSync } from 'node:child_process';
+import { realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, join, sep } from 'node:path';
+
+const OUR_FLAGS = new Set(['--github', '--no-cli', '--no-skills']);
+
+// Bare `instabox` (or the old `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;
+}
+
+const real = (p) => {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+};
+
+function runnable(p) {
+  try {
+    const s = statSync(p);
+    return s.isFile() && (s.mode & 0o111) !== 0;
+  } catch {
+    return false;
+  }
+}
+
+// Skips node_modules dirs and links back to us, like insta's findDurableOnPath.
+export function findCli({ env = process.env, self = process.argv[1] } = {}) {
+  const me = real(self);
+  const home = env.HOME || homedir();
+  const dirs = [
+    ...(env.PATH || '').split(delimiter),
+    env.INSTABOX_INSTALL_DIR,
+    '/usr/local/bin',
+    join(home, '.local', 'bin'),
+  ];
+  for (const dir of dirs) {
+    if (!dir || dir.toLowerCase().includes('node_modules')) continue;
+    const p = join(dir, 'instabox');
+    if (!runnable(p)) continue;
+    const r = real(p);
+    if (r === me || r.includes(`${sep}node_modules${sep}`)) continue;
+    return p;
+  }
+  return null;
+}
+
+// The URL is "$1", never script text; a failed download stops before sh runs anything.
+const INSTALL = 's=$(curl -fsSL "$1/install.sh") && printf \'%s\\n\' "$s" | sh';
+
+// path is null, never a bare `instabox` that could resolve back to this script.
+export function installCli(api) {
+  return new Promise((resolve) => {
+    let out = '';
+    const p = spawn('sh', ['-c', INSTALL, 'sh', api], { stdio: ['ignore', 'pipe', 'pipe'] });
+    p.stdout.on('data', (d) => {
+      out += d;
+    });
+    p.stderr.on('data', (d) => {
+      out += d;
+    });
+    p.on('error', (e) => resolve({ error: e.message }));
+    p.on('close', (code) => {
+      if (code !== 0) return resolve({ error: out.trim().split('\n').pop() || 'installer failed' });
+      resolve({
+        path: (out.match(/^Installed (.+) \([^()]*, sha256 [0-9a-f]+\)$/m) || [])[1] || findCli(),
+        pathHint: (out.match(/export PATH="[^"]+"/) || [])[0] || null,
+      });
+    });
+  });
+}
+
+// Hand the command line to the Go CLI and exit with its status.
+export function runCli(path, args) {
+  const r = spawnSync(path, args, { stdio: 'inherit' });
+  if (r.error) {
+    console.error(`instabox: could not run ${path}: ${r.error.message}`);
+    process.exit(1);
+  }
+  process.exit(r.status ?? 1);
+}

package/lib/credentials.mjs

@@ -0,0 +1,34 @@
+// The instabox CLI's credentials.json (cmd/instabox/creds.go), so one sign-in serves both.
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const trim = (s) => String(s ?? '').replace(/\/+$/, '');
+
+export function configDir(env = process.env) {
+  if (env.XDG_CONFIG_HOME) return join(env.XDG_CONFIG_HOME, 'instabox');
+  return join(env.HOME || homedir(), '.config', 'instabox');
+}
+
+// Tokens stored for `server`, else null.
+export function loadCredentials(server, env = process.env) {
+  try {
+    const c = JSON.parse(readFileSync(join(configDir(env), 'credentials.json'), 'utf8'));
+    return trim(c.server) === trim(server) ? c : null;
+  } catch {
+    return null;
+  }
+}
+
+// Written to a temp file and renamed over, so the CLI never reads half a file.
+export function saveCredentials(server, tokens, env = process.env) {
+  const dir = configDir(env);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  const { accessToken, accessExpiresAt, refreshToken, refreshExpiresAt } = tokens;
+  const body = JSON.stringify({ server, accessToken, accessExpiresAt, refreshToken, refreshExpiresAt }, null, 2) + '\n';
+  const tmp = join(dir, `.credentials.${randomBytes(6).toString('hex')}.tmp`);
+  writeFileSync(tmp, body, { mode: 0o600 });
+  renameSync(tmp, join(dir, 'credentials.json'));
+}

package/lib/login.mjs

@@ -0,0 +1,35 @@
+// 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();
+    }
+    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') };
+    } 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));
+    finish(result);
+  };
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "instabox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.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": {
+    "instabox": "bin/instabox.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/"
+  ],
+  "scripts": {
+    "prepack": "rm -rf skills && cp -R ../skills skills",
+    "test": "node --test test/*.test.mjs",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "license": "Apache-2.0",
+  "homepage": "https://instabox.sh",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/InsForge/instabox.git",
+    "directory": "npm"
+  },
+  "devDependencies": {
+    "prettier": "3.9.9"
+  }
+}

package/skills/instabox/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: instabox
+description: Use when the user wants a cloud Linux box (instabox sandbox) from the terminal with the `instabox` CLI — create one, SSH in, run a command in it, read its files, set its timeout, or delete it. For saving or restoring a box's disks, see instabox-snapshots.
+metadata:
+  installed-by: instabox-demo
+---
+
+# instabox CLI
+
+An instabox sandbox is a Linux VM (Debian, user `dev`, sudo). It has a root disk and a persistent `/data` disk; HOME is `/data/home`. Boxes are private to the signed-in account.
+
+## Sign in
+
+```sh
+instabox whoami              # who is signed in (fails if nobody)
+instabox login               # browser sign-in (GitHub); --provider google for Google
+```
+
+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.
+
+## Everyday commands
+
+```sh
+instabox templates                              # base systems to start from
+instabox create --name work --timeout 2h        # 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 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
+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 N`, `--disk-gib N`, `--meta K=V`, `--no-wait`.
+- `exec` returns the command's exit code; add `--timeout S` for long jobs and `--stdin` to pipe input.
+- Prefer `exec` over `ssh` when you (an agent) need output; use `ssh` only for interactive work the user will drive.
+- A public URL for a dev server in the box: `instabox preview expose work --port 3000`.
+
+## Habits
+
+- Give boxes a `--timeout` so forgotten ones pause or delete themselves.
+- Check `instabox ls` before creating, and reuse a running box with the same purpose.
+- `instabox usage` shows storage use and limits. A quota error means delete or stop something; do not retry the same create in a loop.

package/skills/instabox-migrate/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: instabox-migrate
+description: Use when the user wants to move their local project or setup onto instabox — "move my setup to instabox", "migrate this repo to a box", "continue this work in the cloud". Copies the current git repo (uncommitted and untracked work included, .gitignored files left out) and its Claude Code / Codex conversation history into a new box, then installs dependencies there until it builds.
+metadata:
+  installed-by: instabox-demo
+---
+
+# Move a local project to instabox
+
+Moves the git repo of the current directory into one new box (see the `instabox` skill for the CLI). What goes over:
+
+- The whole `.git` directory (branches, stashes, the index, so staged changes stay staged) and every working-tree file that is tracked or untracked but **not ignored by git**. Files git ignores (usually `node_modules`, build output, `.env`) stay behind: dependencies are reinstalled on the box. Untracked `.env` and `.env.*` files are also left out even when `.gitignore` does not list them. A `.env` that is committed or staged (`git add`ed) is in `.git` and goes with it.
+- Claude Code and Codex conversations about this project, copied unchanged.
+
+Not moved: credentials (git, gh, cloud, API keys), other local tools and config, other repos.
+
+Before starting, tell the user plainly:
+
+- **git push/pull from the box will not work until they set up credentials there** (for example `instabox ssh <box>` then `gh auth login`).
+- **The copied conversation history may contain secrets they pasted earlier** (tokens, keys, passwords). Offer to skip the history.
+
+## 1. Check and create the box
+
+```bash
+instabox whoami                                  # signed in? otherwise: instabox login
+git rev-parse --show-toplevel                    # must be inside a git repo
+du -sh "$(git rev-parse --show-toplevel)/.git"   # large repos: add --disk-gib to create
+instabox ls                                      # pick a box name that is not taken
+```
+
+If `.git` is a file (a git worktree or submodule checkout), move the main checkout instead. Submodules: their history comes along inside `.git/modules`; run `git submodule update --init` on the box. Uncommitted changes inside a submodule are not copied.
+
+```bash
+instabox create --name <box> --vcpus 4 --mem-mib 8192
+```
+
+Box names are lowercase letters, digits and `-`. The default template (`universal`) has git, node/npm, python3/uv, go, cargo and docker. Do not add a kill timeout: this box is meant to stay (offer `instabox timeout <box> 8h --on-timeout pause` if the user wants it to pause itself).
+
+## 2. Copy the repo and history
+
+Run this with **bash** from inside the repo; set `BOX` first. The repo lands in `/data/workspace/<repo-name>` (`/data` is the box's persistent disk; HOME is `/data/home`).
+
+```bash
+BOX=<box>
+export COPYFILE_DISABLE=1          # macOS tar: no ._ AppleDouble files
+SRC=$(git rev-parse --show-toplevel)
+NAME=$(basename "$SRC" | LC_ALL=C tr -c 'A-Za-z0-9._\n-' '-')   # safe inside the quoted remote commands
+DEST=/data/workspace/$NAME
+OLD_ENC=$(printf %s "$SRC" | sed 's/[^A-Za-z0-9]/-/g')    # Claude Code's project dir name
+NEW_ENC=$(printf %s "$DEST" | sed 's/[^A-Za-z0-9]/-/g')
+X='tar -xzf - --warning=no-unknown-keyword'                # the box runs GNU tar
+cd "$SRC"
+
+# Repo: all of .git, plus tracked files and untracked files that are not ignored, if they still exist.
+# Untracked .env / .env.* files are skipped even if .gitignore misses them.
+{ find .git -print0
+  { git ls-files -z --cached
+    git ls-files -z --others --exclude-standard -- . ':(exclude,glob)**/.env' ':(exclude,glob)**/.env.*'
+  } | while IFS= read -r -d '' f; do { [ -e "$f" ] || [ -L "$f" ]; } && printf '%s\0' "$f"; done
+} | tar --null --no-recursion -T - -czf - |
+  instabox ssh "$BOX" -- "mkdir -p '$DEST' && $X -C '$DEST'"
+
+# Claude Code history: ~/.claude/projects/<encoded path>/ (the name starts with '-': keep the ./)
+[ -d ~/.claude/projects/"$OLD_ENC" ] &&
+  tar -C ~/.claude/projects -czf - "./$OLD_ENC" |
+  instabox ssh "$BOX" -- "mkdir -p ~/.claude/projects && $X -C ~/.claude/projects"
+
+# Codex history: rollout files that recorded this cwd.
+LIST=$(mktemp)
+[ -d ~/.codex/sessions ] && (cd ~/.codex && grep -rlF --include='rollout-*.jsonl' "\"cwd\":\"$SRC\"" sessions) > "$LIST"
+[ -s "$LIST" ] && tar -C ~/.codex -czf - -T "$LIST" |
+  instabox ssh "$BOX" -- "mkdir -p ~/.codex && $X -C ~/.codex"
+
+# Session ids for step 5, read from the local copy that was sent: a count and the 5 most recent.
+n=$(ls ~/.claude/projects/"$OLD_ENC"/*.jsonl 2>/dev/null | wc -l)
+[ "$n" -gt 0 ] && { echo "Claude: $n sessions, most recent:"
+  ls -t ~/.claude/projects/"$OLD_ENC"/*.jsonl | head -n 5 | sed -nE 's;.*/(.*)\.jsonl$;\1;p'; }
+n=$(wc -l < "$LIST")
+[ "$n" -gt 0 ] && { echo "Codex: $n sessions, most recent:"   # file names start with the date
+  sed -E 's;.*/;;' "$LIST" | sort -r | head -n 5 | sed -nE 's/.*-([0-9a-f-]{36})\.jsonl$/\1/p'; }
+rm -f "$LIST"
+```
+
+Check that the box has the same state. The only allowed difference is `??` lines for the skipped `.env` files, including a whole `?? dir/` line when that directory held only `.env` files:
+
+```bash
+git status --porcelain; git rev-parse HEAD
+instabox exec "$BOX" --cwd "$DEST" -- 'git status --porcelain; git rev-parse HEAD'
+```
+
+## 3. Make the history resumable
+
+Link Claude Code's project directory for the new path to the copied one, so `claude --resume` (picker) and `claude --continue` in `$DEST` show the old conversations. Do it before anyone runs `claude` in `$DEST` on the box (it creates the directory otherwise). Nothing is rewritten.
+
+```bash
+[ "$OLD_ENC" = "$NEW_ENC" ] || instabox ssh "$BOX" -- "cd ~/.claude/projects &&
+  if [ ! -d './$OLD_ENC' ]; then echo 'no Claude Code history copied; nothing to link'
+  elif [ -e './$NEW_ENC' ] || [ -L './$NEW_ENC' ]; then ls -ld './$NEW_ENC'; echo 'already exists: link NOT created'
+  else ln -s -- '$OLD_ENC' '$NEW_ENC' && echo linked; fi"
+```
+
+If it prints `already exists: link NOT created` and `$NEW_ENC` is a real directory (someone already ran `claude` in `$DEST`), the old conversations will not show in the picker or `--continue`. Tell the user. `claude --resume <session-id>` still works.
+
+Do not write any notes about the move into `CLAUDE.md`, `AGENTS.md` or settings files on the box, global or in the repo.
+
+## 4. Install dependencies until it builds
+
+There is no fixed recipe. Inspect the project on the box, install, then build and test, and repeat until it builds:
+
+1. Look at what the project declares: lockfiles and manifests (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`, `requirements*.txt`, `pyproject.toml`/`uv.lock`, `go.mod`, `Cargo.toml`, `Gemfile`, `pom.xml`, ...), toolchain pins (`.nvmrc`, `.node-version`, `.python-version`, `.tool-versions`, `rust-toolchain*`, `go` line in `go.mod`), `Dockerfile`/`docker-compose.yml`, the README and CI config (`.github/workflows`), which often lists the exact setup steps.
+2. Install the matching toolchain versions and the dependencies with the project's own package manager (`sudo apt-get install -y ...` for system libraries).
+3. Run the build and the tests the project defines. Read each failure, install what is missing (a package, a system library, a different toolchain version), and run again.
+
+Run short steps (looking at files, checking versions) with `instabox exec "$BOX" --cwd "$DEST" -- '<cmd>'`. It runs `bash -lc` as user `dev`, with sudo. `--timeout` defaults to 60 seconds and cannot go above 600. Installs, builds and test runs can take longer, so run those over `instabox ssh`, which has no time limit and passes the exit status back. Use a login shell so the PATH matches `exec` (`~/go/bin`, `~/.cargo/bin`):
+
+```bash
+instabox ssh "$BOX" -- "cd '$DEST' && bash -l" <<'EOF'
+npm ci && npm run build      # the step's commands
+EOF
+```
+
+The script arrives on stdin, so a command that reads stdin would eat the rest of it. Pass `-y` or `</dev/null` to anything that might prompt. Stop and ask the user when something needs a secret (`.env` values, private registry tokens) or a choice only they can make.
+
+## 5. Tell the user
+
+- The box name and where the repo is: `instabox ssh <box>`, then `cd /data/workspace/<name>`.
+- What was installed, whether build and tests pass, and anything left to do.
+- Again: git push/pull needs credentials set up on the box. Ignored files and untracked `.env` files were not copied. Secrets in committed or staged files, or in the copied history, did go over.
+- How to pick up old conversations, kept short, with the session ids printed in step 2:
+  - Claude Code, in the repo directory on the box: `claude --continue` (latest) or `claude --resume` (picker, or `claude --resume <id>`).
+  - Codex keys its picker on the old path: `codex resume <id>` (or pick from `codex resume --all`) and choose "Use current directory"; after that it shows up in plain `codex resume` there too.
+- The local copy is untouched; nothing keeps the two in sync after this.

package/skills/instabox-snapshots/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: instabox-snapshots
+description: Use when the user wants to save an instabox box's state and load it later — "save a snapshot", "checkpoint this box", "restore/load from a snapshot", "start a new box from my setup", "clone this box". Covers instabox snapshot save/ls/files/rm, create --snapshot and fork.
+metadata:
+  installed-by: instabox-demo
+---
+
+# instabox snapshots: save and load
+
+A snapshot is a saved copy of a box's disks (root disk and `/data`), private to the account. Load it by creating a new box from it. Snapshots hold disks only: running processes and memory are not saved (use `instabox suspend` for that).
+
+## Save
+
+```sh
+instabox snapshot save work --name work-ready --description "deps installed, repo cloned"
+```
+
+- A running box is saved live, without stopping it: the snapshot is `pending` in `instabox snapshot ls` until its disks finish uploading (`--no-wait` returns at once).
+- Do not stop the box first: `stop` ends every process in it. A live snapshot is like a clean power cut: what is on disk is kept, what programs hold only in memory is not. Only if the server answers that this box must be stopped, or if a program must write its data to disk first (a database mid-write), run `instabox stop work`, save, then `instabox start work`.
+- `--root-only` saves just the root disk (smaller; `/data` is not included).
+- A snapshot includes credentials stored under HOME (gh, Claude, Codex, git, SSH keys). Sign out of tools or remove secrets first if the snapshot will be shared or kept long.
+- Pick names that say what is inside (`node20-playwright`, `api-db-seeded`); names must be unique among your snapshots.
+
+## Load
+
+```sh
+instabox snapshot ls                                    # your snapshots: id, name, root/data size, source
+instabox create --name work2 --snapshot work-ready --timeout 2h
+instabox exec work2 -- ls /data/home                    # same root disk and /data as when saved
+```
+
+`--snapshot` takes a snapshot name or its `sn_...` id.
+
+## Look inside without starting anything
+
+```sh
+instabox snapshot files work-ready /etc                 # list a directory of the root disk
+instabox snapshot files work-ready /etc/os-release      # print a text file
+```
+
+This reads the snapshot's root disk only; `/data` (and HOME) are not browsable here. To check files under `/data`, load the snapshot into a box and use `instabox exec`.
+
+## Copy a box directly
+
+```sh
+instabox fork work work-copy            # copies a stopped box's root and /data; no snapshot kept
+```
+
+Use `fork` for a one-off copy and `snapshot save` when you will start from the same state again.
+
+## Clean up
+
+```sh
+instabox snapshot rm work-ready
+```
+
+Snapshots count toward the account's snapshot and storage limits (`instabox usage`). Delete ones you no longer need.
+
+## Typical agent loop
+
+1. `instabox create --name job --snapshot <base> --timeout 2h`
+2. Work with `instabox exec job -- ...`
+3. When the setup is worth keeping: `instabox snapshot save job --name <base>-v2` (no need to stop it)
+4. `instabox rm job` when done.