yolocage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yolocage contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# yolocage
+
+Sandboxed claude-code / codex in a container, with a built-in egress credential scrubber as the safety net. Run your AI coding agent in `--dangerously-skip-permissions` mode without worrying about accidentally leaking the `.env` file you just `cat`'d into context.
+
+```bash
+cd ~/dev/myproject
+npx yolocage claude        # or: yc claude
+```
+
+That's it. Claude starts in your project directory, using your existing claude.ai login, with HTTP egress to `api.anthropic.com` routed through an in-cage scrubber that catches credential-shaped strings before they reach the LLM.
+
+## What yolocage actually does
+
+When you accidentally `Read .env` or `git config --list` into an agent's context, that secret enters the conversation and gets re-sent to the LLM on every subsequent turn. Once it's in context, hooks can't reach it. Yolocage runs a mitmproxy-based scrubber inside the container that intercepts HTTPS to the LLM provider and same-length-redacts credential-shaped strings out of the request body before they leave the cage.
+
+Yolocage is the opinionated container + CLI wrapper. The scrubber library is published separately as [ssproxy](https://github.com/jlamendo/ssproxy).
+
+## Requirements
+
+- docker (CLI access; yolocage will sudo automatically if you're not in the docker group)
+- node 16+ (for npm/npx)
+
+That's it. Mac (Intel + Apple Silicon) and Debian/Ubuntu Linux supported.
+
+## Install
+
+```bash
+# One-shot: no install, just run
+npx yolocage claude
+
+# Or install globally
+npm i -g yolocage
+yc claude
+```
+
+> The global install registers both `yolocage` and `yc` as commands. Yandex Cloud's CLI also uses `yc` — if you have both, PATH order decides which wins. Invoke `yolocage` to disambiguate, or alias one of them. The conflict is rare enough that the short alias is worth shipping; document over remove.
+
+## Usage
+
+### Shortcut form (per-directory, persistent)
+
+```bash
+yc                  # defaults to claude in $(pwd)
+yc claude           # explicit
+yc codex            # codex instead of claude
+yc claude -- --resume   # pass-through args after --
+```
+
+Each project directory gets its own cage. The cage name is derived deterministically from the directory path (`yc-<type>-<basename>-<8hex>`), so re-running `yc claude` in the same dir either **resumes** the stopped cage or **attaches** to the running one — never spawns a duplicate. Claude is run with `--continue` by default so the prior in-cwd conversation is restored on re-attach.
+
+Three outcomes from a single `yc claude` invocation, picked automatically:
+
+- **No cage for this dir yet** → create, start, attach. Cage persists between sessions.
+- **Cage exists but is stopped** → `docker start -ai` (restart and reattach). Claude `--continue` resumes the prior session.
+- **Cage is already running** → `docker attach` to the live session. Press `Ctrl-P Ctrl-Q` to detach without stopping the cage; `Ctrl-C` exits claude (and stops the cage).
+
+Cages accumulate as you move between projects. Use `yc list` to see them and `yc rm <name>` to clean up. Volumes for the per-cage mitmproxy CA and any state live alongside the container — `yc rm` removes both.
+
+### Named cages (persistent)
+
+```bash
+yc create projectbox --type=claude --bind-workspace=./src
+yc run projectbox            # attach
+yc list                      # show all cages
+yc rm projectbox             # destroy
+yc logs projectbox           # tail
+yc pull                      # refresh yolocage images
+yc update                    # update yolocage CLI + images in one shot
+```
+
+### Updating yolocage
+
+```bash
+yc update              # binary + images
+yc update --check      # just report the version delta
+yc update --no-pull    # skip the docker pull
+yc update --force      # reinstall current version
+```
+
+`yc update` runs `npm install -g yolocage@latest` (with sudo if the global prefix needs root) and then re-pulls the cage images. If you installed via `npx` instead of a global install, `yc update` will tell you so and only refresh the images — the next `npx yolocage` invocation fetches the latest binary on its own.
+
+Named cages persist between runs. Use them when you want to maintain in-container state across sessions (with `--tmux`) or want explicit naming for the cage holding your active claude session.
+
+### Configuration
+
+Precedence (lowest to highest):
+1. Type defaults (workspace = cwd, config dir = `~/.claude` for claude, `~/.codex` for codex)
+2. `~/.ycrc`
+3. `./.ycrc` (project-local)
+4. CLI flags
+
+#### `.ycrc` syntax
+
+Simple key=value, comments via `#`. Path values expand leading `~` and literal `$HOME` (no other shell expansion):
+
+```
+# ~/.ycrc — defaults applied to every cage
+type = claude
+memory = 4g
+tmux = true
+ssproxy_extensions = ~/.yolocage/scrubbers.json
+
+# Extra binds appended across layers
+extra_bind_dirs = ~/.aws:/home/agent/.aws:ro
+```
+
+```
+# ./.ycrc — project-local overrides
+image = yolocage/claude:1.4.2
+extra_bind_dirs = ./secrets:/etc/secrets:ro
+```
+
+#### Flags
+
+| flag | meaning |
+|---|---|
+| `--type=claude\|codex` | which agent (shortcut form embeds this in the verb) |
+| `--bind-workspace=PATH` | host path mounted at `/workspace` (default: cwd) |
+| `--config-dir=PATH` | host path for the type config dir |
+| `--bind-dirs=H:C[:M]` | replaces type defaults (repeatable) |
+| `--extra-bind-dirs=H:C[:M]` | appends extra binds (repeatable) |
+| `--ssproxy-extensions=PATH` | custom scrub pattern file |
+| `--tmux` / `--no-tmux` | run agent inside tmux (default: false) |
+| `--memory=2g`, `--cpus=2` | docker resource limits |
+| `--image=REPO:TAG` | override default image |
+
+### Cascade semantics
+
+| key | append or replace across layers |
+|---|---|
+| `type`, `image`, `workspace`, `config_dir`, `memory`, `cpus`, `tmux` | replace (later wins entirely) |
+| `bind_dirs` | replace (later layer wins entirely, including its absence) |
+| `extra_bind_dirs` | append (union of all layers, dedupe by `host:container`) |
+| `ssproxy_extensions` | replace |
+
+## Custom scrub patterns
+
+Companies can extend the scrubber with their own credential patterns:
+
+```bash
+yc claude --ssproxy-extensions=./.yolocage/scrubbers.json
+```
+
+```json
+[
+  { "id": "acme-internal-token", "regex": "\\bACME_[A-Z0-9]{32}\\b" },
+  { "id": "acme-deploy-key",     "regex": "\\b(acme_deploy_[a-f0-9]{40})(?:[\\x60'\"\\s;]|\\\\[nr]|$)" }
+]
+```
+
+Patterns are byte-stream regex over the request body. **Use the boundary-anchor convention** shown in the second example — the scrubber does same-length replacement, and a regex without a trailing anchor can overrun the secret boundary into a JSON-structural byte and break the upstream LLM's request parsing. See `docs/writing-scrub-extensions.md`.
+
+## Security model
+
+Yolocage is a **safety net for accidental leakage**, not a defense against a hostile agent.
+
+- The scrubber catches credential-shaped strings on egress to known LLM API hosts. It does not prevent an agent that's already been prompt-injected from exfiltrating data through other channels.
+- The cage runs `--dangerously-skip-permissions`. The agent CAN modify any file in your mounted workspace. Don't mount paths you don't want the agent to touch.
+- The mitmproxy CA cert lives in a per-cage docker volume; it signs intercepts only of LLM API hosts originating from inside that cage. Blast radius of a leaked CA is "someone with the same yolocage image already on your machine," which means they have bigger problems.
+
+## Open source
+
+- yolocage (this repo): MIT, the opinionated container + CLI
+- [ssproxy](https://github.com/jlamendo/ssproxy): MIT, the scrubber library
+
+## License
+
+MIT

package/lib/bind-spec.js

@@ -0,0 +1,104 @@
+// Bind-spec parser.
+//
+// Accepted shapes:
+//   host:container
+//   host:container:ro
+//   host:container:rw
+//
+// Trickiness: Mac paths can contain colons in volume names (rare) and
+// Windows-style C:\… isn't supported, but the parser must not choke on
+// "host paths that have colons" if the third-from-end token isn't a
+// recognized mode. The algorithm:
+//
+//   - Split on `:`.
+//   - If 2 tokens: host=tokens[0], container=tokens[1], mode=default.
+//   - If 3+ tokens: check if the LAST token is `ro`/`rw`. If yes:
+//       mode = last; container = second-to-last; host = everything else
+//       joined by `:`.
+//     Otherwise:
+//       container = last; host = everything else joined by `:`;
+//       mode = default.
+//
+// `~`-expansion happens on the host side (same rules as .ycrc).
+
+'use strict';
+
+const os = require('os');
+
+const VALID_MODES = new Set(['ro', 'rw']);
+const DEFAULT_MODE = 'rw';
+
+function expandHomeOnHost(p) {
+  if (typeof p !== 'string') return p;
+  if (p.startsWith('~/')) return os.homedir() + p.slice(1);
+  if (p === '~') return os.homedir();
+  return p.replace(/\$HOME(?![A-Za-z0-9_])/g, os.homedir());
+}
+
+function parseBindSpec(spec) {
+  if (typeof spec !== 'string' || spec.length === 0) {
+    throw new Error(`bind-spec: empty or non-string spec`);
+  }
+  const tokens = spec.split(':');
+  if (tokens.length < 2) {
+    throw new Error(`bind-spec: invalid spec ${JSON.stringify(spec)} (need at least host:container)`);
+  }
+
+  let host, container, mode;
+  if (tokens.length === 2) {
+    [host, container] = tokens;
+    mode = DEFAULT_MODE;
+  } else {
+    const last = tokens[tokens.length - 1];
+    if (VALID_MODES.has(last)) {
+      mode = last;
+      container = tokens[tokens.length - 2];
+      host = tokens.slice(0, tokens.length - 2).join(':');
+    } else {
+      mode = DEFAULT_MODE;
+      container = last;
+      host = tokens.slice(0, tokens.length - 1).join(':');
+    }
+  }
+
+  if (!host) throw new Error(`bind-spec: empty host path in ${JSON.stringify(spec)}`);
+  if (!container) throw new Error(`bind-spec: empty container path in ${JSON.stringify(spec)}`);
+  if (!container.startsWith('/')) {
+    throw new Error(`bind-spec: container path must be absolute, got ${JSON.stringify(container)}`);
+  }
+  host = expandHomeOnHost(host);
+
+  return { host, container, mode };
+}
+
+function formatBindSpec(b) {
+  return `${b.host}:${b.container}:${b.mode}`;
+}
+
+// Dedupe a list of bind specs by their host:container pair (mode is
+// not part of the dedupe key — later mode wins). Preserves input
+// order, dropping subsequent duplicates.
+function dedupeBindList(list) {
+  const seen = new Map(); // "host:container" -> index in out
+  const out = [];
+  for (const b of list) {
+    const key = `${b.host}:${b.container}`;
+    if (seen.has(key)) {
+      // Later layer's mode wins.
+      out[seen.get(key)] = b;
+    } else {
+      seen.set(key, out.length);
+      out.push(b);
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  parseBindSpec,
+  formatBindSpec,
+  dedupeBindList,
+  expandHomeOnHost,
+  VALID_MODES,
+  DEFAULT_MODE,
+};

package/lib/config.js

@@ -0,0 +1,158 @@
+// Configuration cascade.
+//
+// Precedence (lowest → highest):
+//   1. type defaults (claude / codex)
+//   2. ~/.ycrc
+//   3. ./.ycrc
+//   4. CLI flags
+//
+// Per-key cascade rule (matches the table in README.md §"Cascade semantics"):
+//
+//   type, image, workspace, config_dir, memory, cpus, tmux,
+//   ssproxy_extensions          → replace (later wins entirely)
+//   bind_dirs                   → replace (later layer wins entirely)
+//   extra_bind_dirs             → append + dedupe by host:container
+//
+// The output is a fully-resolved plain-object cage spec ready for
+// lib/docker.js to translate into a `docker run` argv.
+
+'use strict';
+
+const path = require('path');
+const os = require('os');
+
+const { getType } = require('./types');
+const { readYcrc } = require('./ycrc');
+const { parseBindSpec, dedupeBindList } = require('./bind-spec');
+
+const REPLACE_KEYS = new Set([
+  'type',
+  'image',
+  'workspace',
+  'config_dir',
+  'memory',
+  'cpus',
+  'tmux',
+  'ssproxy_extensions',
+  'bind_dirs', // replace, not append
+]);
+
+const APPEND_KEYS = new Set(['extra_bind_dirs']);
+
+// Resolve a raw cascade-merged spec into a normalized cage spec. The
+// raw spec carries .ycrc-shaped strings; the normalized spec carries
+// the values we'll hand to docker.
+function normalize(raw) {
+  const type = raw.type || 'claude';
+  const td = getType(type);
+
+  const workspace = raw.workspace
+    ? path.resolve(raw.workspace)
+    : path.resolve(process.cwd());
+
+  const configDirHost = raw.config_dir
+    ? path.resolve(raw.config_dir)
+    : td.configDirHost;
+
+  // bind_dirs (replace): if the user set it, use ONLY those + the
+  // workspace + the config_dir. If unset, generate the type defaults.
+  let bindDirs;
+  if (Array.isArray(raw.bind_dirs) && raw.bind_dirs.length > 0) {
+    bindDirs = raw.bind_dirs.map(parseBindSpec);
+  } else {
+    bindDirs = [
+      { host: workspace, container: '/workspace', mode: 'rw' },
+      { host: configDirHost, container: td.configDirContainer, mode: 'rw' },
+    ];
+  }
+
+  const extraBindDirs = (raw.extra_bind_dirs || []).map(parseBindSpec);
+  const allBinds = dedupeBindList([...bindDirs, ...extraBindDirs]);
+
+  const tmux = parseBool(raw.tmux);
+
+  return {
+    type,
+    image: raw.image || td.image,
+    workspace,
+    configDirHost,
+    configDirContainer: td.configDirContainer,
+    bindDirs: allBinds,
+    memory: raw.memory || null,
+    cpus: raw.cpus || null,
+    tmux,
+    ssproxyExtensions: raw.ssproxy_extensions || null,
+    cmd: td.cmd.slice(),
+    passthrough: Array.isArray(raw.passthrough) ? raw.passthrough.slice() : [],
+  };
+}
+
+function parseBool(v) {
+  if (typeof v === 'boolean') return v;
+  if (v === undefined || v === null || v === '') return false;
+  const s = String(v).toLowerCase();
+  return s === 'true' || s === '1' || s === 'yes' || s === 'on';
+}
+
+// Merge `incoming` into `acc`. Replace keys clobber; append keys union.
+function mergeLayer(acc, incoming) {
+  if (!incoming) return acc;
+  for (const k of Object.keys(incoming)) {
+    if (APPEND_KEYS.has(k)) {
+      const prev = Array.isArray(acc[k]) ? acc[k] : [];
+      const next = Array.isArray(incoming[k]) ? incoming[k] : [incoming[k]];
+      acc[k] = [...prev, ...next];
+    } else if (REPLACE_KEYS.has(k)) {
+      if (incoming[k] !== undefined) acc[k] = incoming[k];
+    } else {
+      // Unknown key — preserve last-wins like REPLACE for forward compat.
+      if (incoming[k] !== undefined) acc[k] = incoming[k];
+    }
+  }
+  return acc;
+}
+
+// Build the cascade.
+//   opts.type          — explicit type from argv ('claude'|'codex'|...)
+//   opts.homeYcrcPath  — typically ~/.ycrc
+//   opts.projectYcrcPath — typically ./.ycrc (cwd)
+//   opts.cliLayer      — already-parsed object from commander
+function resolveCascade(opts) {
+  const acc = {};
+
+  // Layer 1: type baseline — sets `type` only. Defaults for workspace
+  // / config_dir flow through normalize() based on cwd + $HOME.
+  if (opts.type) mergeLayer(acc, { type: opts.type });
+
+  // Layer 2: ~/.ycrc
+  let home = null;
+  try {
+    home = readYcrc(opts.homeYcrcPath);
+  } catch (e) {
+    throw new Error(`error reading ${opts.homeYcrcPath}: ${e.message}`);
+  }
+  if (home) mergeLayer(acc, home);
+
+  // Layer 3: ./.ycrc
+  let project = null;
+  try {
+    project = readYcrc(opts.projectYcrcPath);
+  } catch (e) {
+    throw new Error(`error reading ${opts.projectYcrcPath}: ${e.message}`);
+  }
+  if (project) mergeLayer(acc, project);
+
+  // Layer 4: CLI flags
+  if (opts.cliLayer) mergeLayer(acc, opts.cliLayer);
+
+  return normalize(acc);
+}
+
+module.exports = {
+  resolveCascade,
+  normalize,
+  mergeLayer,
+  parseBool,
+  REPLACE_KEYS,
+  APPEND_KEYS,
+};

package/lib/docker.js

@@ -0,0 +1,170 @@
+// Docker shell-out helpers.
+//
+// All docker invocations route through here. The module probes once on
+// first use for whether the current user can talk to the docker daemon
+// without sudo; if not, every command is prefixed with `sudo`. The
+// fix-it message ("add yourself to the docker group with …") is printed
+// at most once per process.
+//
+// Tests mock `child_process` to drive the probe branches.
+
+'use strict';
+
+const { spawnSync, execFileSync } = require('child_process');
+
+let _sudoChecked = false;
+let _useSudo = false;
+let _noticePrinted = false;
+
+function _probe(env) {
+  if (_sudoChecked) return _useSudo;
+  _sudoChecked = true;
+
+  // DOCKER_HOST suggests the user is talking to a non-local daemon
+  // (rootless, ssh:// tunnel, etc.) — don't try sudo in that case;
+  // the env tells us they've already wired it up themselves.
+  if (env.DOCKER_HOST) {
+    _useSudo = false;
+    return _useSudo;
+  }
+
+  // First try docker info as the calling user.
+  const direct = spawnSync('docker', ['info'], { stdio: 'ignore', env });
+  if (direct.status === 0) {
+    _useSudo = false;
+    return _useSudo;
+  }
+
+  // Try sudo. If sudo isn't installed or password-prompts, this fails
+  // and we fall through to "use direct + let the error tell the user".
+  const sudo = spawnSync('sudo', ['-n', 'docker', 'info'], { stdio: 'ignore', env });
+  if (sudo.status === 0) {
+    _useSudo = true;
+    return _useSudo;
+  }
+
+  // Couldn't reach docker either way. Don't trip sudo — let the next
+  // docker call surface the real error to the user.
+  _useSudo = false;
+  return _useSudo;
+}
+
+function maybeSudo(env) {
+  return _probe(env || process.env);
+}
+
+// Reset the module-level cache. For tests and re-init flows; not part
+// of the public CLI surface.
+function _resetProbeCache() {
+  _sudoChecked = false;
+  _useSudo = false;
+  _noticePrinted = false;
+}
+
+function _printNoticeOnce(stderr) {
+  if (_noticePrinted) return;
+  _noticePrinted = true;
+  stderr.write(
+    'yolocage: docker requires sudo on this system. To skip this, add ' +
+      'yourself to the docker group:\n' +
+      '    sudo usermod -aG docker $USER && newgrp docker\n'
+  );
+}
+
+// Build the docker argv for a given cage spec. Returns:
+//   { argv: [...], cmd: [...] }   for piping into spawnSync(argv[0], argv.slice(1).concat(cmd))
+function buildRunArgs(spec, opts) {
+  opts = opts || {};
+  const args = ['run'];
+  if (opts.rm !== false) args.push('--rm');
+  if (opts.interactive !== false) args.push('-it');
+  if (opts.detach) args.push('-d');
+  if (opts.name) args.push('--name', opts.name);
+
+  // Per-cage docker volume for mitmproxy CA + state. Shared across
+  // create/run for named cages so the CA persists.
+  const volName = opts.volName || (opts.name ? `${opts.name}-mitmproxy` : 'yolocage-mitmproxy-ephemeral');
+  args.push('-v', `${volName}:/home/agent/.mitmproxy`);
+
+  for (const b of spec.bindDirs) {
+    args.push('-v', `${b.host}:${b.container}:${b.mode}`);
+  }
+
+  if (spec.memory) args.push('--memory', spec.memory);
+  if (spec.cpus) args.push('--cpus', String(spec.cpus));
+
+  // Workdir defaults to /workspace.
+  args.push('-w', '/workspace');
+
+  // Env: tmux toggle + extensions path.
+  args.push('-e', `YC_TMUX=${spec.tmux ? '1' : '0'}`);
+  if (spec.ssproxyExtensions) {
+    // The host file is mounted RO into a stable container location.
+    args.push('-v', `${spec.ssproxyExtensions}:/etc/yolocage/scrub-extensions.json:ro`);
+    args.push('-e', 'SSPROXY_EXTENSIONS=/etc/yolocage/scrub-extensions.json');
+  }
+
+  args.push(spec.image);
+  const cmd = [...spec.cmd, ...(spec.passthrough || [])];
+  return { argv: args, cmd };
+}
+
+// Compose the final argv with sudo prefix as needed.
+function dockerArgv(args, env) {
+  env = env || process.env;
+  if (maybeSudo(env)) return ['sudo', '-n', 'docker', ...args];
+  return ['docker', ...args];
+}
+
+// Does a container with this name exist (running OR stopped)?
+// Uses `docker container inspect` which exits 0 for any state.
+function cageExists(name, opts) {
+  opts = opts || {};
+  const env = opts.env || process.env;
+  const argv = dockerArgv(['container', 'inspect', name], env);
+  const res = spawnSync(argv[0], argv.slice(1), { stdio: 'ignore', env });
+  return res.status === 0;
+}
+
+// Is the container with this name in the Running state? Returns false
+// for non-existent OR stopped containers.
+function cageRunning(name, opts) {
+  opts = opts || {};
+  const env = opts.env || process.env;
+  const argv = dockerArgv(
+    ['container', 'inspect', '-f', '{{.State.Running}}', name],
+    env
+  );
+  const res = spawnSync(argv[0], argv.slice(1), {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env,
+    encoding: 'utf8',
+  });
+  if (res.status !== 0) return false;
+  return String(res.stdout || '').trim() === 'true';
+}
+
+// Run a docker command synchronously, inheriting stdio. Returns the
+// exit status; callers may pass {stdio: 'pipe'} for captured output.
+function runDocker(args, opts) {
+  opts = opts || {};
+  const env = opts.env || process.env;
+  const stderr = opts.stderr || process.stderr;
+  if (maybeSudo(env)) _printNoticeOnce(stderr);
+  const argv = dockerArgv(args, env);
+  const res = spawnSync(argv[0], argv.slice(1), {
+    stdio: opts.stdio || 'inherit',
+    env,
+  });
+  return res;
+}
+
+module.exports = {
+  maybeSudo,
+  buildRunArgs,
+  dockerArgv,
+  runDocker,
+  cageExists,
+  cageRunning,
+  _resetProbeCache,
+};

package/lib/types.js

@@ -0,0 +1,64 @@
+// Type defaults table. The shortcut form (`yc claude`) and named-cage
+// `--type=…` flag pick from these. v0 ships claude + codex enabled; opencode
+// is sketched in but `v0:false` so the CLI errors cleanly if the operator
+// asks for it.
+//
+// Each entry's `bindDirs` describes the default mounts for a fresh cage:
+//   workspace: a host path mounted at /workspace (default = cwd)
+//   configDir: a host path for the agent's per-user config (claude.ai login
+//              cache + codex auth). Replaceable via --config-dir.
+//
+// `cmd` is the in-container command line the entrypoint exec()s by default.
+// CLI pass-through args (`yc claude -- --resume`) are appended after.
+
+'use strict';
+
+const path = require('path');
+const os = require('os');
+
+const HOME = os.homedir();
+
+const TYPE_DEFAULTS = {
+  claude: {
+    v0: true,
+    image: 'yolocage/claude:dev',
+    configDirHost: path.join(HOME, '.claude'),
+    configDirContainer: '/home/agent/.claude',
+    // --continue auto-resumes the most recent in-cwd conversation; harmless on
+    // first run (claude falls back to a fresh session). With per-cwd persistent
+    // cages, this is what the operator wants by default — `yc claude` always
+    // either resumes or starts fresh, never re-introduces itself mid-project.
+    cmd: ['claude', '--continue', '--dangerously-skip-permissions'],
+  },
+  codex: {
+    v0: true,
+    image: 'yolocage/codex:dev',
+    configDirHost: path.join(HOME, '.codex'),
+    configDirContainer: '/home/agent/.codex',
+    cmd: ['codex', '--full-auto'],
+  },
+  opencode: {
+    v0: false,
+    image: 'yolocage/opencode:dev',
+    configDirHost: path.join(HOME, '.config', 'opencode'),
+    configDirContainer: '/home/agent/.config/opencode',
+    cmd: ['opencode'],
+  },
+};
+
+function isKnownType(type) {
+  return Object.prototype.hasOwnProperty.call(TYPE_DEFAULTS, type);
+}
+
+function getType(type) {
+  if (!isKnownType(type)) {
+    throw new Error(`unknown --type=${type} (known: ${Object.keys(TYPE_DEFAULTS).join(', ')})`);
+  }
+  const t = TYPE_DEFAULTS[type];
+  if (!t.v0) {
+    throw new Error(`--type=${type} support coming in v2 (v0 ships claude + codex only)`);
+  }
+  return t;
+}
+
+module.exports = { TYPE_DEFAULTS, getType, isKnownType };