instabox 0.6.0 → 0.6.1

package/skills/instabox-basic-setup/scripts/scan.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Read-only inventory of the basic setup that can go into the instabox Vault:
+// Read-only inventory of the basic setup for org Secrets and explicit sandbox config copies:
 // tokens (by name and place, never values), git config, editor and terminal
 // config. Prints JSON.
 //
@@ -12,7 +12,7 @@ import { join, relative, resolve } from 'node:path';
 import {
   MACOS_ONLY,
   SECRET_VALUE,
-  VAULT_MAX_VALUE,
+  FILE_MAX_VALUE,
   WELL_KNOWN,
   hasCommand,
   isMain,
@@ -21,16 +21,37 @@ import {
   readText,
   run,
   statOrNull,
-  vaultEnvNameOK,
-  vaultFileName,
-  vaultPathOK,
+  secretNameOK,
+  configPathOK,
 } from './lib.mjs';
 
 // Shell startup files: read for exported tokens only. They do not move.
-export const SHELL_RC = ['.zshenv', '.zprofile', '.zshrc', '.bash_profile', '.bash_login', '.profile', '.bashrc', '.bash_aliases'];
+export const SHELL_RC = [
+  '.zshenv',
+  '.zprofile',
+  '.zshrc',
+  '.bash_profile',
+  '.bash_login',
+  '.profile',
+  '.bashrc',
+  '.bash_aliases',
+];
 
 // nvim: config files only. Plugin managers' checkouts and editor state stay behind.
-const NVIM_SKIP = new Set(['.git', 'node_modules', 'pack', 'plugged', 'bundle', 'site', 'undo', 'backup', 'swap', 'sessions', 'spell', '.repro']);
+const NVIM_SKIP = new Set([
+  '.git',
+  'node_modules',
+  'pack',
+  'plugged',
+  'bundle',
+  'site',
+  'undo',
+  'backup',
+  'swap',
+  'sessions',
+  'spell',
+  '.repro',
+]);
 const NVIM_MAX_FILES = 40;
 const NVIM_MAX_BYTES = 128 * 1024;
 
@@ -50,12 +71,12 @@ function scanTokens({ home, env, procEnv }) {
   const manual = [];
   const byName = new Map();
   const add = (name, source, from, extra = {}) => {
-    if (byName.has(name)) return; // the first place a name is found wins: the Vault holds one value per name
+    if (byName.has(name)) return; // the first place a name is found wins: an org holds one value per Secret name
     const item = { id: `env:${name}`, section: 'tokens', kind: 'env', name, source, from, checked: true, ...extra };
     byName.set(name, item);
     items.push(item);
   };
-  const unvaultable = new Set();
+  const reserved = new Set();
 
   // gh: the token gh keeps (keychain or hosts.yml), read with `gh auth token` at push time.
   if (hasCommand('gh', env)) {
@@ -74,12 +95,12 @@ function scanTokens({ home, env, procEnv }) {
     if (text === null) continue;
     for (const a of shellAssignments(text)) {
       if (!WELL_KNOWN.has(a.name) && !isSecretName(a.name) && !a.secretValue) continue;
-      if (!vaultEnvNameOK(a.name)) {
-        if (!unvaultable.has(a.name)) {
-          unvaultable.add(a.name);
+      if (!secretNameOK(a.name)) {
+        if (!reserved.has(a.name)) {
+          reserved.add(a.name);
           manual.push({
             what: `${a.name} (~/${f}:${a.line})`,
-            why: 'the Vault does not take env items with this name (INSTABOX_*, SSH_* and a few system names)',
+            why: 'Secrets reserve this variable name for sandbox or trust configuration',
             todo: `if a box needs it, set it there by hand`,
           });
         }
@@ -91,7 +112,7 @@ function scanTokens({ home, env, procEnv }) {
         extra.reason = 'your shell reads it from the macOS keychain: checking it runs that lookup once, at push time';
       } else if (!WELL_KNOWN.has(a.name)) {
         extra.checked = false;
-        extra.reason = 'not a well-known model or service token: check it if every box should have it';
+        extra.reason = 'not a well-known model or service token: check it only for the org and sandboxes in the plan';
       }
       add(a.name, { type: 'rc', file: join(home, f), name: a.name }, `~/${f}:${a.line}`, extra);
     }
@@ -106,40 +127,51 @@ function scanTokens({ home, env, procEnv }) {
     manual.push({
       what: 'GitHub token (GH_TOKEN)',
       why: hasCommand('gh', env) ? 'gh is not signed in on this machine' : 'gh is not installed on this machine',
-      todo: 'sign in here with `gh auth login` and run this again; or put a token in yourself: `instabox vault set GH_TOKEN` (it prompts without echo)',
+      todo: 'sign in here with `gh auth login` and run this again; or put a token in yourself: `instabox secrets set GH_TOKEN --org <org> --delivery env` (it prompts without echo)',
     });
   if (!byName.has('CLAUDE_CODE_OAUTH_TOKEN'))
     manual.push({
       what: 'Claude Code sign-in (CLAUDE_CODE_OAUTH_TOKEN)',
       why: 'not found in your shell files; the sign-in on this machine is in the macOS keychain, and is never read',
       todo:
-        'run `claude setup-token` yourself (it prints a token that lasts a year), then `instabox vault set CLAUDE_CODE_OAUTH_TOKEN` and paste it at the prompt' +
-        (byName.has('ANTHROPIC_API_KEY') ? ' (or skip it: ANTHROPIC_API_KEY is in the plan, and Claude Code uses that)' : '; or `claude`, then /login, on each box'),
+        'run `claude setup-token` yourself, then `instabox secrets set CLAUDE_CODE_OAUTH_TOKEN --org <org> --delivery env` and paste it at the prompt' +
+        (byName.has('ANTHROPIC_API_KEY')
+          ? ' (or skip it: ANTHROPIC_API_KEY is in the plan, and Claude Code uses that)'
+          : '; or `claude`, then /login, on each box'),
     });
   if (!byName.has('OPENAI_API_KEY') && (hasCommand('codex', env) || statOrNull(join(home, '.codex'))))
     manual.push({
       what: 'Codex sign-in',
       why: 'no OPENAI_API_KEY in your shell files; a ChatGPT sign-in cannot be copied (its refresh token rotates)',
-      todo: 'on each box: `codex login --device-auth`; or `instabox vault set OPENAI_API_KEY` once for every box',
+      todo: 'on each box: `codex login --device-auth`; or `instabox secrets set OPENAI_API_KEY --org <org> --delivery env`, then select it explicitly for each intended sandbox',
     });
   return { items, manual };
 }
 
-// A home-relative path for a file, or null when it is outside HOME or not one the Vault takes.
+// A home-relative path for a config copy, or null for an unsafe target.
 function homePath(home, p) {
   const rel = relative(home, p);
-  return rel && !rel.startsWith('..') && vaultPathOK(rel) ? rel : null;
+  return rel && !rel.startsWith('..') && configPathOK(rel) ? rel : null;
 }
 
 function fileEntry(home, section, rel, transform, extra = {}) {
   const src = join(home, rel);
   const st = statOrNull(src);
   if (!st?.isFile()) return null;
-  const file = { path: rel, name: vaultFileName(rel), src, transform, bytes: st.size };
-  const e = { id: `file:${rel}`, section, kind: 'file', path: rel, files: [file], bytes: st.size, checked: true, ...extra };
-  if (st.size > VAULT_MAX_VALUE) {
+  const file = { path: rel, src, transform, bytes: st.size };
+  const e = {
+    id: `file:${rel}`,
+    section,
+    kind: 'file',
+    path: rel,
+    files: [file],
+    bytes: st.size,
+    checked: true,
+    ...extra,
+  };
+  if (st.size > FILE_MAX_VALUE) {
     e.checked = false;
-    e.reason = `${st.size} bytes: over the Vault's 64 KiB per item`;
+    e.reason = `${st.size} bytes: over the config-copy limit of 64 KiB per file`;
   }
   return e;
 }
@@ -150,7 +182,9 @@ function scanGit({ home, env }) {
     note: 'osxkeychain and other macOS-only lines, credentials and commit signing left out',
   });
   if (gc) out.push(gc);
-  const xdg = fileEntry(home, 'git', '.config/git/config', 'gitconfig', { note: 'macOS-only lines and credentials left out' });
+  const xdg = fileEntry(home, 'git', '.config/git/config', 'gitconfig', {
+    note: 'macOS-only lines and credentials left out',
+  });
   if (xdg) out.push(xdg);
   // The global gitignore: core.excludesfile, else git's default.
   let ignore = null;
@@ -189,22 +223,30 @@ function scanEditor({ home }) {
       if (!keep) continue;
       const rel = `.config/nvim/${f}`;
       const st = statOrNull(join(real, f));
-      if (!vaultPathOK(rel) || !st) continue;
-      if (st.size > VAULT_MAX_VALUE) {
+      if (!configPathOK(rel) || !st) continue;
+      if (st.size > FILE_MAX_VALUE) {
         left.push(`${f} (${st.size} bytes)`);
         continue;
       }
-      files.push({ path: rel, name: vaultFileName(rel), src: join(real, f), transform: f.endsWith('.json') ? 'raw' : 'text', bytes: st.size });
+      files.push({ path: rel, src: join(real, f), transform: f.endsWith('.json') ? 'raw' : 'text', bytes: st.size });
     }
     if (files.some((f) => /^\.config\/nvim\/init\.(?:lua|vim)$/.test(f.path))) {
       const bytes = files.reduce((s, f) => s + f.bytes, 0);
-      const e = { id: 'files:.config/nvim', section: 'editor', kind: 'file', path: '.config/nvim', files, bytes, checked: true };
+      const e = {
+        id: 'files:.config/nvim',
+        section: 'editor',
+        kind: 'file',
+        path: '.config/nvim',
+        files,
+        bytes,
+        checked: true,
+      };
       const notes = ['plugins are not copied: your plugin manager installs them on the box'];
       if (left.length) notes.push(`left out, over 64 KiB: ${left.join(', ')}`);
       e.note = notes.join('; ');
       if (files.length > NVIM_MAX_FILES || bytes > NVIM_MAX_BYTES) {
         e.checked = false;
-        e.reason = `${files.length} files: a big share of the Vault's 100 items and 256 KiB`;
+        e.reason = `${files.length} files: over the suggested config-copy size; review before selecting`;
       }
       out.push(e);
     }
@@ -212,27 +254,12 @@ function scanEditor({ home }) {
   return out;
 }
 
-// Two paths can map to one item name (a-b.lua and a/b.lua): the second gets -2, -3...
-function uniqueNames(entries) {
-  const used = new Set();
-  for (const e of entries) {
-    if (e.kind === 'env') used.add(e.name);
-    for (const f of e.files || []) {
-      let n = f.name;
-      for (let i = 2; used.has(n); i++) n = `${f.name}-${i}`;
-      f.name = n;
-      used.add(n);
-    }
-  }
-}
-
 export function scan(opts = {}) {
   const env = opts.env || process.env;
   const home = resolve(opts.home || env.HOME);
   const tokens = scanTokens({ home, env, procEnv: opts.procEnv || env });
   const items = [...tokens.items, ...scanGit({ home, env }), ...scanEditor({ home })];
-  uniqueNames(items);
-  return { version: 2, home, platform: opts.platform || process.platform, items, manual: tokens.manual };
+  return { version: 3, home, platform: opts.platform || process.platform, items, manual: tokens.manual };
 }
 
 function main() {

package/skills/instabox-move-repo/SKILL.md

@@ -20,16 +20,16 @@ Three scripts in `scripts/` next to this file do the parts that must be exact (N
 What goes over:
 
 - All of the main checkout's `.git` (branches, tags, stashes, unpushed commits, the index so staged changes stay staged, each worktree's own HEAD and index), every tracked file, and every untracked file git does not ignore, in the main checkout and in each linked worktree.
-- **Never build output or dependencies**, even when the repo forgot to ignore them: `node_modules`, `target`, `dist`, `build`, `out`, `.next`, `.nuxt`, `.svelte-kit`, `.turbo`, `.cache`, `coverage`, `__pycache__`, `.venv`, `venv`, `.tox`, `.mypy_cache`, `.pytest_cache`, `.gradle`, `bazel-*`, `*.egg-info`, `*.o`, `*.so`, `*.pyc`, `*.class`, ... (the full list is `EXCLUDED_DIRS` and `EXCLUDED_FILES` in `repo-files.mjs`). Files git ignores stay too. A **tracked** file always goes, even under such a name, so `git status` matches. `--keep NAME` copies an excluded name anyway, for a repo whose source really lives in, say, `build/` (pass it to every `repo-files.mjs` run, step 1 and step 3, through `KEEP`). It does not bring back an untracked `.env`: those only go through the Vault (step 7).
+- **Never build output or dependencies**, even when the repo forgot to ignore them: `node_modules`, `target`, `dist`, `build`, `out`, `.next`, `.nuxt`, `.svelte-kit`, `.turbo`, `.cache`, `coverage`, `__pycache__`, `.venv`, `venv`, `.tox`, `.mypy_cache`, `.pytest_cache`, `.gradle`, `bazel-*`, `*.egg-info`, `*.o`, `*.so`, `*.pyc`, `*.class`, ... (the full list is `EXCLUDED_DIRS` and `EXCLUDED_FILES` in `repo-files.mjs`). Files git ignores stay too. A **tracked** file always goes, even under such a name, so `git status` matches. `--keep NAME` copies an excluded name anyway, for a repo whose source really lives in, say, `build/` (pass it to every `repo-files.mjs` run, step 1 and step 3, through `KEEP`). It does not bring back an untracked `.env`: their values need explicit Secret import and selection (step 7).
 - Claude Code and Codex conversations for the repo and its worktrees (on by default, the user can opt out).
 
-Not moved: `.env` files that are not committed (they go through the Vault, step 7), credentials stored outside the repo (git credential helpers, gh, cloud, API keys in your environment), other local tools and config, other repos. A `.env` that is committed or staged is in `.git` and goes with it. Everything inside `.git` goes, including `.git/config` and so a remote URL with a token embedded in it (`https://x-access-token:TOKEN@...`); and only `.env`-named untracked files are held back, so an untracked `.npmrc` with a token, a `*.pem` or a `secrets.yaml` that git does not ignore goes too.
+Not moved: `.env` files that are not committed (their values can be imported as Secrets in step 7), credentials stored outside the repo (git credential helpers, gh, cloud, API keys in your environment), other local tools and config, other repos. A `.env` that is committed or staged is in `.git` and goes with it. Everything inside `.git` goes, including `.git/config` and so a remote URL with a token embedded in it (`https://x-access-token:TOKEN@...`); and only `.env`-named untracked files are held back, so an untracked `.npmrc` with a token, a `*.pem` or a `secrets.yaml` that git does not ignore goes too.
 
 **Never read, print or paste a credential value yourself**: not a `.env`, not `gh auth token`, not `echo $SOME_KEY`.
 
 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 `instabox-basic-setup` skill, where installed, puts tokens and git config into the Vault).
+- **git push/pull from the box will not work until they set up credentials there** (for example `instabox ssh <box>` then `gh auth login`; org Secrets support key=value credentials, while git configuration must be set up separately).
 - **The copied conversation history may contain secrets they pasted earlier** (tokens, keys, passwords). It goes by default; ask whether to skip it (or only Codex / only Claude Code).
 - Their local copy stays as it is, and nothing keeps the two in sync afterwards.
 
@@ -72,7 +72,7 @@ BOX=<box>
 instabox create --name "$BOX" --meta repo="$(basename "$DEST")"
 ```
 
-Box names are lowercase letters, digits and `-`. Every box is the same size. The default template (`universal`) has git, Node.js 22, Python (uv), Go, Rust, a C toolchain 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). The `repo=` label lets Vault items (step 7) reach this box only.
+Box names are lowercase letters, digits and `-`. Every box is the same size. The default template (`agent-browser`, shown as standard in the dashboard) has git, Node.js 22, Python (uv), Go, Rust, a C toolchain, Docker and a desktop with Chromium. 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). The `repo=` label can match existing Vault selectors; it does not select org Secrets. Without Secret selection flags the box keeps the existing Vault behavior. Opt into org Secrets explicitly with `--secrets` or `--env-secrets`; at creation, `--env-secrets` alone also selects all org proxy Secrets. Use `--no-vault --secrets none --env-secrets none` when neither store should deliver credentials.
 
 ## 3. Copy the repo and its worktrees
 
@@ -165,18 +165,28 @@ instabox exec "$BOX" --cwd "$DEST" -- 'git status --porcelain | sort; git rev-pa
 
 Compare with step 3. New `??` lines from the installs (for example a lockfile the project does not commit) are worth a mention; a modified tracked file is not expected: find which step did it.
 
-## 7. `.env` files: through the Vault, never copied
+## 7. `.env` values: explicit Secret import and selection
 
-The plan's `envLeftOut` lists them by name (`jq -r '.main.envLeftOut, (.worktrees[] | select(.move) | .envLeftOut) | .[]' "$W/plan.json"`). Do not open them. If the user wants them on the box, the Vault carries them as files under HOME, and a link puts each into the repo. With their go-ahead, per file (the CLI reads the file; nothing passes through you):
+The plan's `envLeftOut` lists excluded files by name (`jq -r '.main.envLeftOut, (.worktrees[] | select(.move) | .envLeftOut) | .[]' "$W/plan.json"`). Do not print their contents. The new Secret model stores individual key=value entries, not files, and does not create or link a `.env` in the repo.
+
+For a project that needs the real values, explain that env delivery makes them readable by code in the box. Use the user's authorization to import the intended file and select its names for this box. Import is org-wide and replaces existing entries with the same names: resolve conflicts and confirm any intended replacement before importing. Different projects needing different values under the same variable name should use separate orgs, or configure their applications to use distinct names; do not silently rename or overwrite a shared credential.
+
+After that choice, per approved file (the CLI reads values; saved JSON contains metadata only):
 
 ```bash
-R=$(basename "$DEST")
-instabox vault set-file ".config/instabox-move-repo/env/$R/<path in repo>" --from "<local path>" --selector repo="$R"
-instabox vault push "$BOX"
-instabox exec "$BOX" -- "mkdir -p '$DEST/<dir in repo>' && ln -sfn ~/.config/instabox-move-repo/env/$R/<path in repo> '$DEST/<path in repo>'"
+BOX_ORG=$(instabox get "$BOX" --json | jq -r '.orgId')
+instabox secrets show "$BOX" --json > "$W/selected-secrets.json"
+instabox secrets import "<local .env path>" --org "$BOX_ORG" --delivery env --json > "$W/imported-secrets.json"
+ENV_NAMES=$(jq -c -s '.[0].envSecrets + [.[1].items[].name] | unique' "$W/selected-secrets.json" "$W/imported-secrets.json")
+instabox secrets select "$BOX" --env-secrets "$ENV_NAMES"
+instabox secrets push "$BOX"
 ```
 
-The `--selector repo=<name>` keeps the file to boxes created with `--meta repo=<name>` (step 2). For tokens, git config and editor setup across all boxes, point the user to the `instabox-basic-setup` skill.
+This merges the approved env names with the box's current env selection and leaves its proxy selection unchanged. Import alone grants no env access to any box. Start a new login shell, or restart/reconfigure the application, to load the updated environment. Use silent presence checks; do not print values to verify delivery.
+
+For credentials sent literally in HTTPS headers, save them with `--delivery proxy --host <approved-host>` instead, and select the corresponding proxy names. Every entry in one import shares its delivery mode and host scope, so do not import a mixed `.env` as proxy credentials without separating those decisions. A native database client or a client that computes signatures needs an explicitly selected env value.
+
+If the application requires a physical `.env` or another credential file, it needs a separate, explicitly authorized file-transfer or guest-generation workflow with restricted file permissions. Such a file is readable in the guest and may be included in snapshots; it has no Secret-managed file cleanup. Report this requirement rather than claiming Secret import recreates the original file. Tokens and local editor or git configuration are separate setup decisions; metadata labels do not grant credentials.
 
 ## 8. Tell the user
 
@@ -184,7 +194,7 @@ The `--selector repo=<name>` keeps the file to boxes created with `--meta repo=<
 - Uncommitted work inside a submodule (a ` M <submodule>` line in step 3) did not come over: name each such submodule so the user can commit or copy that work themselves.
 - Sizes: on disk before, sent after, and the biggest things left out (they were rebuilt or reinstalled on the box).
 - What was installed, whether build and tests pass, and anything left to do (each FAILED step and note from `deps.sh` that is not fixed).
-- Again: git push/pull needs credentials set up on the box. Ignored files, build output and untracked `.env` files were not copied. Secrets in committed or staged files, anywhere in `.git` (such as a token in a remote URL in `.git/config`), in untracked files not named `.env*`, or in the copied history, did go over.
+- Again: git push/pull needs credentials set up on the box. State which Secret names and delivery modes were selected, if any; never include values. Ignored files, build output and untracked `.env` files were not copied. Secrets in committed or staged files, anywhere in `.git` (such as a token in a remote URL in `.git/config`), in untracked files not named `.env*`, or in the copied history, did go over.
 - How to pick up old conversations, kept short, with the session ids from step 4:
   - Claude Code, in the repo (or worktree) directory on the box: `claude --continue` (latest) or `claude --resume` (picker, or `claude --resume <id>`).
   - Codex, in that directory: `codex resume` (picker for this directory), `codex resume --last`, or `codex resume <id>`.

package/skills/instabox-snapshots/SKILL.md

@@ -18,7 +18,7 @@ instabox snapshot save work --name work-ready --description "deps installed, rep
 - 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), and the Vault's `file` items (its `env` items live on tmpfs and are not saved). Sign out of tools or remove secrets first if the snapshot will be shared or kept long.
+- A disk snapshot includes credential files written by applications, tool sign-ins, and historical Vault files. The managed Secret environment lives on tmpfs, but applications can copy real env values to disk; a suspend snapshot can also retain them in process memory. Do not describe snapshots as credential-free. Review copied credentials and rotate upstream when required before sharing or retaining them.
 - Pick names that say what is inside (`node20-playwright`, `api-db-seeded`); names must be unique among your snapshots.
 
 ## Load
@@ -50,7 +50,13 @@ instabox create --name work2 --snapshot work-copy
 instabox snapshot rm work-copy                          # optional; work2 is not affected
 ```
 
-The copy does not inherit `--no-vault`. If the box was created with `--no-vault`, pass it again: `instabox create --name work2 --snapshot work-copy --no-vault`.
+The copy gets a new sandbox identity and the selections in its creation request. Without Secret selection flags it keeps the existing Vault behavior and does not enroll in org Secrets; it does not inherit the source's explicit grants or exclusions. To disable new delivery from both stores, use:
+
+```sh
+instabox create --name work2 --snapshot work-copy --no-vault --secrets none --env-secrets none
+```
+
+To provide a database credential, select its env Secret explicitly with `--env-secrets DATABASE_URL`. At creation that flag alone also selects all org proxy Secrets; add `--secrets none` or specific names to narrow proxy access. Copied placeholders cannot authorize use as the source sandbox. New selections do not erase real credentials already present in copied files; a new proxy identity does not make those files safe to share.
 
 ## Clean up