agentcage 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anton Frisk
+
+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

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# agentcage
 
-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.
+Isolated dev containers for AI coding agents. Each project gets its own Linux container ("box"). **The project source lives
+in a Docker volume, not in a folder mounted from your laptop**, so agents in the box can't see your other files. Each box can
+run an **OpenCode server** that the OpenCode Desktop app on your laptop connects to. The app is only the UI: every agent tool
+call (bash, read, edit) runs in the box. Claude Code can be installed in the box too.
+
+Works on Windows, macOS and Linux, in any terminal (PowerShell, Terminal, bash).
+
+## Install
+
+You need **Docker** (Docker Desktop on Windows/macOS, Docker Engine on Linux), **Node 22.13+**, **git**, and
+**OpenCode Desktop** (open it once so its settings exist).
+
+```bash
+npm install -g agentcage
+agentcage doctor        # checks everything above
+```
+
+## Create a box
+
+Run `agentcage` and follow the dialog. It asks for:
+
+1. **Where the project is:** a folder on this computer (copied once, including untracked files such as `.env.local`)
+   or a git URL (cloned).
+2. **A name** for the box.
+3. **Git push access** (if the project has a remote). See [Git push access](#git-push-access).
+4. **AI agents:** OpenCode (on by default) and/or Claude Code.
+5. **Extra dev tools:** Python, GitHub CLI, pnpm. Node 24 and uv are always included.
+6. **Model providers for OpenCode** (Anthropic, OpenAI, OpenRouter, Google, Groq). After the build, OpenCode asks for each
+   API key in your terminal.
+7. **An IDE** to open the box in when it's ready (Cursor, VS Code, Antigravity).
+
+Then it builds the box, adds it to OpenCode Desktop as server **agentcage: <name>** with the project
+`/workspaces/<name>` already open, and opens the IDE.
+
+The same works without the dialog:
+
+```bash
+agentcage new ~/code/my-project --tools opencode,claude-code --git forward --ide cursor --yes
+AGENTCAGE_GIT_TOKEN=github_pat_... agentcage new https://github.com/me/repo.git --git token --yes
+```
+
+## Commands
+
+```bash
+agentcage                       # menu: create a box, or start/open/shell/upgrade/remove an existing one
+agentcage list                  # boxes, state, port, OpenCode version
+agentcage start <name>          # start after a reboot, print the OpenCode server URL and password
+agentcage shell <name>          # shell in the box (opencode, claude, git ... work here)
+agentcage open <name> [ide]     # Cursor (default), VS Code, or another VS Code-based IDE attached to the box
+agentcage provider <name>       # add model provider API keys to OpenCode in the box
+agentcage connect <name>        # (re)register the box in OpenCode Desktop
+agentcage upgrade <name>        # rebuild with the Desktop app's OpenCode version (volumes kept)
+agentcage stop <name>
+agentcage remove <name>         # delete container, volumes and config
+agentcage doctor
+agentcage adopt <name>          # import a box made by the old bash scripts in legacy/
+```
+
+Box config lives in `~/.agentcage/<name>/` (`box.json` and the generated `.devcontainer/`). `node_modules`, `.venv` and
+`.next` are not copied. Instead the box runs `npm ci` / `uv sync` for every lockfile it finds.
+
+## Git push access
+
+The copy in the box is separate from your laptop's, so changes leave the box via **git push**. The dialog offers two ways:
+
+- **A token for this repo only (recommended).** The dialog shows how to create one: a fine-grained GitHub token limited to
+  the repo with *Contents: read and write*, a GitLab project access token, or a Bitbucket repository access token. The token
+  is stored with git's credential store in the box's home volume and used for this repo only. The repo's git config clears
+  any other credential helper, including the one an attached IDE forwards.
+  Cursor and VS Code still forward your **SSH agent**. To close that path too, set
+  `"dev.containers.copyGitConfig": false` and `"dev.containers.gitCredentialHelperConfigLocation": "none"` in the IDE's
+  settings and turn off SSH agent forwarding.
+- **Skip: use your IDE's forwarded credentials.** While Cursor or VS Code is attached, your laptop's git credentials and
+  SSH agent are forwarded into the box, so pushing from the IDE just works. **While the IDE is attached, any agent in the
+  box can use them to push to every repository you have access to.** When no IDE is attached, the box can't push at all.
+
+For a git URL, token mode clones inside a throwaway container with the token. Forward mode clones on your laptop with your
+own git credentials, then copies the repo in. Both work with private repos. Your git name and email are copied into the box.
+
+## OpenCode Desktop
+
+agentcage reads the Desktop app's version (from `opencode-cli.version` in its install folder) and installs the same OpenCode
+version in the box, because Desktop only talks to matching servers. `list`, `start` and `doctor` warn when the app has
+updated since; `agentcage upgrade <name>` rebuilds the box with the new version and keeps your code, logins and sessions.
+
+Desktop has no API or deep link for adding a server, so agentcage writes the app's own state DB (`drafts.sqlite` in the
+app's data folder, backed up as `drafts.sqlite.agentcage-backup`). **The app must be closed for this.** The dialog asks you
+to close it. This relies on the app's internal storage format (written against Desktop 2.0.23), so a future app update may
+break it. `agentcage start <name>` always prints the URL, username and password for adding the server by hand.
+
+Provider API keys are typed into OpenCode's own prompt inside the box. They are stored only in the box's home volume,
+never on your laptop, and survive rebuilds.
+
+⚠️ Only sessions on the **agentcage server** are isolated. Sessions on the app's built-in **Local** server run on your laptop.
+
+## What is and isn't isolated
+
+- ✅ No host folders mounted, no Docker socket, not privileged. The OpenCode server is published only on `127.0.0.1` and
+  requires a random password.
+- ⚠️ The box has internet access and can reach services on your laptop via `host.docker.internal`.
+- ⚠️ Secrets you copy in (for example `.env.local`) and provider keys can be read by agents. Use dev and test keys.
+- ⚠️ An attached IDE forwards your SSH agent, and in forward mode your git credentials (see above).
+- ⚠️ Use the IDE for editing, diffs and git. Its built-in AI agent runs outside the box's isolation, so run agents through
+  OpenCode or Claude Code in the box.
+
+## Platform notes
+
+Tested on Windows 11 with Docker Desktop. On macOS and Linux, the OpenCode Desktop install and data folders are best
+guesses (`/Applications/OpenCode.app`, `~/Library/Application Support/ai.opencode.desktop`, `~/.config/ai.opencode.desktop`).
+`agentcage doctor` shows what it found. Please report the real paths if they differ.
+
+## Future work: Docker Sandboxes as an alternative backend
+
+The setup dialog should let the user choose the backend: **plain Docker container (default)** or **Docker Sandboxes**
+(`sbx`). We tested `sbx` v0.48.0 on Windows 11 with the `alversjo-maps` repo:
+
+**What works, and is better than plain Docker**
+- Each sandbox is a microVM with its own kernel. Installed without admin rights (`winget install Docker.sbx`), created in ~10 s.
+- `sbx create --clone opencode <repo>` gives the agent a private clone. Commits made in the sandbox are fetched on the host
+  through a `sandbox-<name>` git remote, without touching the working tree. Only the clone is visible inside.
+- Provider keys via `sbx secret set anthropic --sandbox <name>` (also openai, openrouter, google, groq, xai...). The sandbox
+  only sees `proxy-managed` placeholders; a host proxy injects the real key, so keys never enter the sandbox.
+- A repo-scoped GitHub token works the same way: `sbx secret set github --sandbox <name>`. By default a sandbox has no GitHub
+  access.
+- `-p 127.0.0.1:4200:4096` publishes the OpenCode server port. OpenCode 2.0.23 served the Desktop/web UI from the sandbox
+  with the password.
+- Network policies (open / balanced / locked down) with a per-sandbox network log.
+- The image already has Node 22, uv, Python 3, git, gh, sudo and a Docker daemon. IDEs connect over SSH (`sbx setup ssh`,
+  then Remote-SSH to `<name>.sbx`; not tested yet).
+
+**What is missing for our use**
+1. **OpenCode version:** the image ships OpenCode 1.18.32 (`opencode-ai`, first on PATH). Desktop 2.0.23 needs a matching
+   server, so a kit or template must install `@opencode/cli@<desktop version>`.
+2. **Server lifetime:** the sandbox's agent is the OpenCode TUI and `sbx exec` has no detached mode. `opencode serve` started
+   with `nohup` dies when the exec session ends. It only stays up while a foreground `sbx exec ... opencode serve` runs on the
+   host. A kit must start the server at sandbox boot (to be tested).
+3. **Desktop registration** is still ours (the `drafts.sqlite` write), and the workspace path is the host path
+   (`/c/Users/...`), not `/workspaces/<name>`.
+4. **SSH agent forwarding is on by default:** the host's SSH keys were listed inside the sandbox. That is the cross-repo risk
+   we want to avoid, so it must be turned off or warned about.
+5. **Requirements:** Docker account sign-in for every user, macOS on Apple silicon only, Ubuntu 24.04+ with KVM only,
+   Windows 11 with Hypervisor Platform.
+6. OpenCode API keys: `opencode auth login` only accepts keys interactively, but with `sbx secret` this is not needed.
+
+**Plan:** add a `backend: docker | sbx` choice to the dialog and `box.json`. The `sbx` backend maps our steps to
+`sbx create --clone -p 127.0.0.1:<port>:4096 opencode <repo>`, `sbx secret set <provider|github> --sandbox <name>`, and
+an OpenCode kit that pins the Desktop version and starts `opencode serve` at boot. The wizard, version detection and Desktop
+registration stay the same.
+
+## Legacy
+
+`legacy/` holds the original bash scripts this tool replaces. `agentcage adopt <name>` takes over a box they created.

package/bin/agentcage.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import * as p from '@clack/prompts';
+import { adoptBox, listBoxes, loadBox, removeBox, saveBox, state, up, writeDevcontainer, openIde, ws } from '../src/box.js';
+import { ask, connectionInfo, newWizard, providerFlow, registerFlow } from '../src/wizard.js';
+import { detectDesktop, latestVersion } from '../src/opencode.js';
+import { ok, run } from '../src/run.js';
+
+process.removeAllListeners('warning'); // hide node:sqlite ExperimentalWarning
+
+const HELP = `agentcage: isolated dev containers for AI coding agents
+
+  agentcage                         interactive menu (create or manage boxes)
+  agentcage new [folder|git-url]    create a box  [--name x] [--tools opencode,claude-code,python,gh,pnpm]
+                                      [--git token|forward] [--providers anthropic,...] [--ide cursor|code|none] [--yes]
+  agentcage list                    boxes, state, port, OpenCode version
+  agentcage start <name>            start a box and print OpenCode connection details
+  agentcage stop <name>
+  agentcage shell <name>            shell in the box (run opencode, claude, git ... here)
+  agentcage open <name> [ide]       open Cursor (default), VS Code or another VS Code-based IDE attached to the box
+  agentcage connect <name>          (re)register the box in OpenCode Desktop (app must be closed)
+  agentcage provider <name>         add model provider API keys to OpenCode in the box
+  agentcage upgrade <name>          rebuild with the Desktop app's OpenCode version (volumes kept)
+  agentcage remove <name>           delete container, volumes and config
+  agentcage doctor                  check Docker, Node and OpenCode Desktop
+  agentcage adopt <name>            import a box made by the old devbox bash scripts
+
+  In token mode, a token can also be passed in the AGENTCAGE_GIT_TOKEN environment variable.`;
+
+let { values: f, positionals: [cmd, arg, arg2] } = parseArgs({
+  allowPositionals: true,
+  options: { name: { type: 'string' }, tools: { type: 'string' }, git: { type: 'string' }, providers: { type: 'string' },
+    ide: { type: 'string' }, yes: { type: 'boolean', short: 'y' }, help: { type: 'boolean', short: 'h' } },
+});
+const csv = s => s?.split(',').map(x => x.trim()).filter(Boolean);
+const box = () => loadBox(arg ?? (() => { throw new Error(`Usage: agentcage ${cmd} <name>`); })());
+
+function versionWarning(b) {
+  const v = detectDesktop().version;
+  if (b.tools.includes('opencode') && v && b.opencodeVersion !== v)
+    p.log.warn(`OpenCode Desktop is ${v}, box '${b.name}' has ${b.opencodeVersion}. If Desktop can't connect: agentcage upgrade ${b.name}`);
+}
+async function start(b) {
+  // devcontainer up (not docker start) so postStartCommand starts the OpenCode server
+  if (state(b) !== 'running') { const s = p.spinner(); s.start(`Starting '${b.name}'`); await up(b); s.stop(`Started '${b.name}'`); }
+  versionWarning(b);
+}
+
+const commands = {
+  async new() { await newWizard({ src: arg, name: f.name, tools: csv(f.tools), git: f.git, providers: csv(f.providers), ide: f.ide, yes: f.yes }); },
+  list() {
+    const rows = listBoxes().map(b => [b.name, state(b), b.tools.includes('opencode') ? String(b.port) : '-', b.opencodeVersion ?? '-', b.git]);
+    if (!rows.length) return console.log('No boxes yet. Create one with: agentcage new');
+    const all = [['NAME', 'STATE', 'PORT', 'OPENCODE', 'GIT'], ...rows], w = all[0].map((_, i) => Math.max(...all.map(r => r[i].length)));
+    console.log(all.map(r => r.map((c, i) => c.padEnd(w[i])).join('  ')).join('\n'));
+    const v = detectDesktop().version;
+    if (v) console.log(`\nOpenCode Desktop: ${v}`);
+  },
+  async start() { const b = box(); await start(b); console.log(`Box '${b.name}' is running.\n${b.tools.includes('opencode') ? connectionInfo(b) : ''}`); },
+  async stop() { await run('docker', ['stop', box().container]); },
+  async shell() { const b = box(); await start(b); await run('docker', ['exec', '-it', '-u', 'node', '-w', ws(b), b.container, 'bash', '-l'], { tty: true }).catch(() => {}); },
+  async open() {
+    const b = box(); await start(b); openIde(b, arg2 ?? f.ide ?? 'cursor');
+    if (b.git === 'token') p.log.warn('The IDE forwards your SSH agent into the box. Turn it off in the IDE settings to keep pushes limited to the repo token (see README).');
+  },
+  async connect() { await registerFlow(box()); },
+  async provider() { const b = box(); await start(b); await providerFlow(b, csv(f.providers)); },
+  async upgrade() {
+    const b = box(), v = detectDesktop().version ?? await latestVersion();
+    const s = p.spinner(); s.start(`Rebuilding '${b.name}' with OpenCode ${v} (volumes are kept)`);
+    b.opencodeVersion = v; writeDevcontainer(b);
+    await up(b, true).then(() => s.stop(`Rebuilt with OpenCode ${v}`), e => { s.error('Rebuild failed'); throw e; });
+    saveBox(b);
+  },
+  async remove() {
+    const b = box();
+    if (!f.yes && !(await ask(p.confirm({ message: `Delete box '${b.name}' with its volumes? Unpushed work in the box is lost.`, initialValue: false })))) return;
+    await removeBox(b); console.log(`Removed '${b.name}'.`);
+  },
+  doctor() {
+    const d = detectDesktop(), [maj, min] = process.versions.node.split('.').map(Number);
+    const checks = [
+      [maj > 22 || (maj === 22 && min >= 13), `Node ${process.versions.node}`, 'Install Node 22.13 or newer'],
+      [ok('docker', ['info']), 'Docker is running', 'Install/start Docker Desktop (Windows, macOS) or Docker Engine (Linux)'],
+      [ok('git', ['--version']), 'git installed', 'Install git'],
+      [d.hasDb, `OpenCode Desktop data: ${d.dataDir}`, 'Install OpenCode Desktop and open it once (or add servers by hand)'],
+      [!!d.version, `OpenCode Desktop version: ${d.version ?? 'unknown'}${d.from ? ` (from ${d.from})` : ''}`, 'Version not found: boxes use the newest OpenCode'],
+    ];
+    for (const [good, msg, fix] of checks) good ? p.log.success(msg) : p.log.warn(`${msg}\n${fix}`);
+    for (const b of listBoxes()) if (b.tools.includes('opencode') && d.version && b.opencodeVersion !== d.version) p.log.warn(`Box '${b.name}' has OpenCode ${b.opencodeVersion}: agentcage upgrade ${b.name}`);
+  },
+  adopt() { const b = adoptBox(arg); console.log(`Adopted '${b.name}' (${b.container}).`); },
+
+  // No command: menu
+  async menu() {
+    const boxes = listBoxes();
+    if (!boxes.length) return newWizard();
+    p.intro('agentcage');
+    const pick = await ask(p.select({ message: 'What do you want to do?', options: [{ value: '', label: 'Create a new box' }, ...boxes.map(b => ({ value: b.name, label: b.name, hint: state(b) }))] }));
+    if (!pick) return newWizard();
+    const action = await ask(p.select({ message: pick, options: [
+      { value: 'start', label: 'Start and show connection details' }, { value: 'open', label: 'Open in IDE' },
+      { value: 'shell', label: 'Shell' }, { value: 'provider', label: 'Add a model provider' },
+      { value: 'connect', label: 'Register in OpenCode Desktop' }, { value: 'upgrade', label: 'Upgrade OpenCode' },
+      { value: 'stop', label: 'Stop' }, { value: 'remove', label: 'Remove' },
+    ] }));
+    [cmd, arg] = [action, pick];
+    await commands[action]();
+  },
+};
+
+if (f.help || cmd === 'help') console.log(HELP);
+else if (cmd && !commands[cmd]) { console.error(`Unknown command '${cmd}'.\n\n${HELP}`); process.exit(1); }
+else await Promise.resolve().then(() => commands[cmd ?? 'menu']()).catch(e => { p.log.error(e.message); process.exit(1); });

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "agentcage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Isolated dev containers for AI coding agents (OpenCode, Claude Code), connected to OpenCode Desktop",
+  "type": "module",
+  "bin": {
+    "agentcage": "bin/agentcage.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "template"
+  ],
+  "engines": {
+    "node": ">=22.13"
+  },
+  "keywords": [
+    "devcontainer",
+    "opencode",
+    "claude-code",
+    "ai-agents",
+    "sandbox",
+    "docker"
+  ],
+  "author": "Anton Frisk",
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "@devcontainers/cli": "^0.89.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AntonFrisk/agentcage.git"
+  },
+  "homepage": "https://github.com/AntonFrisk/agentcage#readme",
+  "bugs": {
+    "url": "https://github.com/AntonFrisk/agentcage/issues"
+  }
+}

package/src/box.js

@@ -0,0 +1,115 @@
+// Box state (~/.agentcage/<name>/box.json), devcontainer.json generation and the box lifecycle.
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomBytes } from 'node:crypto';
+import { createServer } from 'node:net';
+import { devcontainer, launch, ok, run, runSync } from './run.js';
+import { TOOLS } from './catalog.js';
+import { copyIdentity, isGitUrl, parseRemote, seed, setupToken } from './git.js';
+
+export const ROOT = join(homedir(), '.agentcage');
+const TEMPLATE = fileURLToPath(new URL('../template/', import.meta.url));
+const boxFile = name => join(ROOT, name, 'box.json');
+export const ws = b => `/workspaces/${b.name}`;
+
+export const hasBox = name => existsSync(boxFile(name));
+export function loadBox(name) {
+  if (!hasBox(name)) throw new Error(`No box named '${name}'. See: agentcage list`);
+  return JSON.parse(readFileSync(boxFile(name), 'utf8'));
+}
+export function saveBox(b) {
+  mkdirSync(join(ROOT, b.name), { recursive: true });
+  writeFileSync(boxFile(b.name), JSON.stringify(b, null, 2));
+}
+export const listBoxes = () => (existsSync(ROOT) ? readdirSync(ROOT).filter(hasBox).map(loadBox) : []);
+
+export const cleanName = s => s.replace(/\.git\/?$/, '').replace(/[\\/:]+$/, '').replace(/.*[:\\/]/, '')
+  .toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
+export const nameTaken = n => hasBox(n) || ok('docker', ['volume', 'inspect', `agentcage-${n}-src`]);
+
+const bindable = port => new Promise(r => {
+  const s = createServer().once('error', () => r(false)).listen(port, '127.0.0.1', () => s.close(() => r(true)));
+});
+async function freePort() {
+  const used = new Set(listBoxes().map(b => b.port));
+  for (const m of runSync('docker', ['ps', '-a', '--format', '{{.Ports}}']).matchAll(/:(\d+)->/g)) used.add(+m[1]);
+  for (let p = 4100; ; p++) if (!used.has(p) && (await bindable(p))) return p;
+}
+
+export function writeDevcontainer(b) {
+  const dir = join(b.dir, '.devcontainer'), oc = b.tools.includes('opencode');
+  const tools = TOOLS.filter(t => b.tools.includes(t.id));
+  mkdirSync(dir, { recursive: true });
+  cpSync(TEMPLATE, dir, { recursive: true });
+  // Isolation: the source lives in a Docker volume, not a bind mount. No host paths, no Docker socket, not privileged.
+  const cfg = {
+    name: b.name,
+    build: { dockerfile: 'Dockerfile', args: { OPENCODE_VERSION: oc ? b.opencodeVersion : '', NPM_GLOBALS: tools.flatMap(t => t.npm ?? []).join(' ') } },
+    workspaceMount: `source=${b.volumes.src},target=${ws(b)},type=volume`,
+    workspaceFolder: ws(b),
+    mounts: [`source=${b.volumes.home},target=/home/node,type=volume`],
+    runArgs: [`--name=${b.container}`, `--label=agentcage.name=${b.name}`, ...(oc ? ['-p', `127.0.0.1:${b.port}:4096`] : [])],
+    containerEnv: oc ? { OPENCODE_SERVER_PASSWORD: b.password } : {},
+    features: Object.fromEntries(tools.filter(t => t.feature).map(t => [t.feature, {}])),
+    remoteUser: 'node',
+    init: true,
+    forwardPorts: [3000],
+    postCreateCommand: 'agentcage-post-create',
+    ...(oc && { postStartCommand: 'setsid nohup opencode serve --hostname 0.0.0.0 --port 4096 > /tmp/opencode-serve.log 2>&1 &' }),
+  };
+  writeFileSync(join(dir, 'devcontainer.json'), JSON.stringify(cfg, null, 2) + '\n');
+}
+
+export const up = (b, rebuild) => devcontainer(['up', '--workspace-folder', b.dir, ...(rebuild ? ['--remove-existing-container'] : [])]);
+export const state = b => runSync('docker', ['inspect', '-f', '{{.State.Status}}', b.container]) || 'missing';
+
+// o: { src, name, tools, git: 'token'|'forward'|'none', token, opencodeVersion }. step(label, fn) shows progress.
+export async function createBox(o, step = (_, f) => f()) {
+  const { name } = o, src = isGitUrl(o.src) ? o.src : resolve(o.src);
+  const b = {
+    name, dir: join(ROOT, name), container: `agentcage-${name}`,
+    volumes: { src: `agentcage-${name}-src`, home: `agentcage-${name}-home` },
+    port: await freePort(), password: randomBytes(16).toString('hex'),
+    source: src, git: o.git, tools: o.tools, opencodeVersion: o.opencodeVersion, created: new Date().toISOString(),
+  };
+  saveBox(b);
+  writeDevcontainer(b);
+  await run('docker', ['volume', 'create', b.volumes.src]);
+  await step('Copying the source into the box', () => seed(b.volumes.src, { ...o, src }));
+  await step('Building and starting the container (the first build takes a few minutes)', () => up(b));
+  await step('Setting up git', async () => {
+    await copyIdentity(b.container);
+    if (o.git === 'token') await setupToken(b.container, ws(b), parseRemote(o.remote ?? src), o.token);
+  });
+  return b;
+}
+
+export async function removeBox(b) {
+  await run('docker', ['rm', '-f', b.container]).catch(() => {});
+  for (const v of Object.values(b.volumes)) await run('docker', ['volume', 'rm', v]).catch(() => {});
+  rmSync(b.dir, { recursive: true, force: true });
+  rmSync(join(ROOT, b.name), { recursive: true, force: true });
+}
+
+// Opens a VS Code-based IDE attached to the running container
+export function openIde(b, ide) {
+  const hex = Buffer.from(JSON.stringify({ containerName: `/${b.container}` })).toString('hex');
+  launch(ide, ['--folder-uri', `vscode-remote://attached-container+${hex}${ws(b)}`]);
+}
+
+// Import a box made by the old bash kit (~/devboxes/<name>, devbox-<name> container and volumes)
+export function adoptBox(name) {
+  const dir = join(homedir(), 'devboxes', name), cfg = join(dir, '.devcontainer', 'devcontainer.json');
+  if (!existsSync(cfg)) throw new Error(`No legacy box at ${dir}`);
+  const text = readFileSync(cfg, 'utf8'), docker = readFileSync(join(dir, '.devcontainer', 'Dockerfile'), 'utf8');
+  const b = {
+    name, dir, container: `devbox-${name}`, volumes: { src: `devbox-${name}-src`, home: `devbox-${name}-home` },
+    port: +text.match(/127\.0\.0\.1:(\d+)/)[1], password: text.match(/"OPENCODE_SERVER_PASSWORD": "([^"]+)"/)[1],
+    source: 'legacy devbox', git: 'forward', tools: ['opencode'], opencodeVersion: docker.match(/OPENCODE_VERSION=(\S+)/)?.[1],
+    created: new Date().toISOString(), legacy: true,
+  };
+  saveBox(b);
+  return b;
+}

package/src/catalog.js

@@ -0,0 +1,28 @@
+// Tools offered in the setup dialog. feature = Dev Container Feature id, npm = global npm package installed in the image.
+export const AGENTS = [
+  { id: 'opencode', label: 'OpenCode', hint: 'agent server for OpenCode Desktop (recommended)' },
+  { id: 'claude-code', label: 'Claude Code', hint: 'run `claude` in `agentcage shell <name>`', feature: 'ghcr.io/anthropics/devcontainer-features/claude-code:1' },
+];
+export const DEV_TOOLS = [
+  { id: 'python', label: 'Python', hint: 'system Python (uv is always included)', feature: 'ghcr.io/devcontainers/features/python:1' },
+  { id: 'gh', label: 'GitHub CLI', hint: 'gh', feature: 'ghcr.io/devcontainers/features/github-cli:1' },
+  { id: 'pnpm', label: 'pnpm', hint: 'Node package manager', npm: 'pnpm' },
+];
+export const TOOLS = [...AGENTS, ...DEV_TOOLS];
+
+// OpenCode providers that log in with an API key (`opencode auth login <id> --method key`)
+export const PROVIDERS = [
+  { id: 'anthropic', label: 'Anthropic', hint: 'console.anthropic.com/settings/keys' },
+  { id: 'openai', label: 'OpenAI', hint: 'platform.openai.com/api-keys' },
+  { id: 'openrouter', label: 'OpenRouter', hint: 'openrouter.ai/settings/keys' },
+  { id: 'google', label: 'Google Gemini', hint: 'aistudio.google.com/apikey' },
+  { id: 'groq', label: 'Groq', hint: 'console.groq.com/keys' },
+];
+
+// How to make a token limited to one repo, per git host. user = username to send with the token over HTTPS.
+const HOSTS = {
+  'github.com': { user: 'x-access-token', help: p => `Create a fine-grained token: https://github.com/settings/personal-access-tokens/new\n  Repository access: Only select repositories → ${p}\n  Permissions: Contents → Read and write (add Pull requests if agents should open PRs)` },
+  'gitlab.com': { user: 'oauth2', help: p => `Create a project access token: https://gitlab.com/${p}/-/settings/access_tokens\n  Role: Developer. Scopes: read_repository, write_repository` },
+  'bitbucket.org': { user: 'x-token-auth', help: p => `Create a repository access token: https://bitbucket.org/${p}/admin/access-tokens\n  Permissions: Repositories → Write` },
+};
+export const hostInfo = host => HOSTS[host] ?? { user: 'git', help: p => `Create an access token on ${host} with read/write access to ${p} only.` };

package/src/git.js

@@ -0,0 +1,55 @@
+// Getting the source into the box, and git push credentials inside it.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { run, runSync } from './run.js';
+import { hostInfo } from './catalog.js';
+
+// https://host/owner/repo(.git), git@host:owner/repo(.git), ssh://git@host/owner/repo → { host, path, https }
+export function parseRemote(url) {
+  const m = url?.match(/^(?:(?:https?|ssh|git):\/\/(?:[^@/]+@)?|[^@\s/]+@)([^/:]+)[:/](.+?)(?:\.git)?\/?$/);
+  return m && { host: m[1], path: m[2], https: `https://${m[1]}/${m[2]}.git` };
+}
+export const isGitUrl = s => /^(https?|ssh|git):\/\/|^[^@\s/]+@[^:]+:/.test(s);
+export const localRemote = dir => runSync('git', ['-C', dir, 'remote', 'get-url', 'origin']) || null;
+
+// Copy a host folder into the volume. The folder is mounted read-only into a throwaway container only.
+const TAR = 'cd /src && tar -cf - --exclude=node_modules --exclude=.venv --exclude=.next . | tar -xf - -C /dst';
+const seedFolder = (vol, dir) => run('docker', ['run', '--rm', '-v', `${vol}:/dst`, '-v', `${dir}:/src:ro`, 'alpine', 'sh', '-c', TAR]);
+
+export async function seed(vol, { src, git, token }) {
+  if (!isGitUrl(src)) await seedFolder(vol, src);
+  else if (git === 'token') {
+    // Clone in a throwaway container; the token travels as an env var, never in the URL or on disk
+    const helper = '!f() { echo username=$GIT_USER; echo password=$GIT_TOKEN; }; f';
+    await run('docker', ['run', '--rm', '-e', 'GIT_USER', '-e', 'GIT_TOKEN', '-v', `${vol}:/dst`, 'alpine/git', '-c', `credential.helper=${helper}`, 'clone', src, '/dst'],
+      { env: { GIT_USER: hostInfo(parseRemote(src).host).user, GIT_TOKEN: token } });
+  } else {
+    // Clone on the host with the user's own git credentials (private repos work), then copy in
+    const tmp = mkdtempSync(join(tmpdir(), 'agentcage-'));
+    try {
+      await run('git', ['clone', src, join(tmp, 'src')], { env: { GIT_TERMINAL_PROMPT: '0' } });
+      await seedFolder(vol, join(tmp, 'src'));
+    } finally { rmSync(tmp, { recursive: true, force: true }); }
+  }
+  await run('docker', ['run', '--rm', '-v', `${vol}:/dst`, 'alpine', 'chown', '-R', '1000:1000', '/dst']);
+}
+
+// Host git name/email → container
+export async function copyIdentity(container) {
+  for (const k of ['user.name', 'user.email']) {
+    const v = runSync('git', ['config', '--global', k]);
+    if (v) await run('docker', ['exec', '-u', 'node', container, 'git', 'config', '--global', k, v]);
+  }
+}
+
+// Repo-scoped token: stored with git's credential store in the box's home volume, used for this repo only.
+// The empty credential.helper entry clears helpers set earlier (such as the one an attached IDE forwards).
+const TOKEN_SETUP = `IFS= read -r T; umask 077
+printf 'https://%s:%s@%s/%s.git\\n' "$1" "$T" "$2" "$3" > ~/.git-credentials
+git remote set-url origin "https://$2/$3.git"
+git config --local --unset-all credential.helper
+git config --local --add credential.helper '' && git config --local --add credential.helper store && git config --local credential.useHttpPath true`;
+
+export const setupToken = (container, dir, remote, token) =>
+  run('docker', ['exec', '-i', '-u', 'node', '-w', dir, container, 'sh', '-c', TOKEN_SETUP, '_', hostInfo(remote.host).user, remote.host, remote.path], { input: token + '\n' });

package/src/opencode.js

@@ -0,0 +1,57 @@
+// OpenCode Desktop on the host: where it lives, its version, whether it runs, and registering boxes in it.
+import { copyFileSync, existsSync, readFileSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ok, run, runSync } from './run.js';
+
+const P = process.platform, H = homedir(), E = process.env;
+const DATA_DIR = P === 'win32' ? join(E.APPDATA ?? '', 'ai.opencode.desktop')
+  : P === 'darwin' ? join(H, 'Library', 'Application Support', 'ai.opencode.desktop')
+  : join(E.XDG_CONFIG_HOME || join(H, '.config'), 'ai.opencode.desktop');
+// Folders holding the app's bundled opencode-cli.version (Windows verified; macOS/Linux are best guesses)
+const RESOURCE_DIRS = P === 'win32' ? [join(E.LOCALAPPDATA ?? '', 'Programs', '@opencodedesktop', 'resources')]
+  : P === 'darwin' ? ['/Applications/OpenCode.app/Contents/Resources', join(H, 'Applications/OpenCode.app/Contents/Resources')]
+  : ['/opt/OpenCode/resources', '/usr/lib/opencode-desktop/resources', '/usr/lib/OpenCode/resources', '/opt/opencode-desktop/resources'];
+
+const SEMVER = /^\d+\.\d+\.\d+$/;
+const cmp = (a, b) => a.split('.').reduce((r, x, i) => r || x - b.split('.')[i], 0);
+
+export function detectDesktop() {
+  const db = join(DATA_DIR, 'drafts.sqlite');
+  const file = RESOURCE_DIRS.map(d => join(d, 'opencode-cli.version')).find(existsSync);
+  const cliDir = join(DATA_DIR, 'cli');
+  let version = file && readFileSync(file, 'utf8').trim(), from = file;
+  if (!version && existsSync(cliDir)) [version, from] = [readdirSync(cliDir).filter(v => SEMVER.test(v)).sort(cmp).at(-1), cliDir];
+  if (!version) [version, from] = [runSync('opencode', ['--version']).match(/\d+\.\d+\.\d+/)?.[0], 'opencode on PATH'];
+  return { dataDir: DATA_DIR, db, hasDb: existsSync(db), version, from };
+}
+
+export const desktopRunning = () => P === 'win32'
+  ? /^OpenCode\.exe/im.test(runSync('tasklist', ['/FI', 'IMAGENAME eq OpenCode.exe', '/NH']))
+  : ok('pgrep', ['-x', 'OpenCode']);
+
+export const latestVersion = async () => (await (await fetch('https://registry.npmjs.org/@opencode/cli/latest')).json()).version;
+
+// Desktop has no API or deep link for adding a server, so write its state DB (app must be closed). A backup is kept.
+export async function connectDesktop(box) {
+  const { db, hasDb } = detectDesktop();
+  if (!hasDb) throw new Error(`OpenCode Desktop state not found at ${db}. Open the app once first.`);
+  if (desktopRunning()) throw new Error('OpenCode Desktop is running. Close it first.');
+  copyFileSync(db, db + '.agentcage-backup');
+  const { DatabaseSync } = await import('node:sqlite');
+  const d = new DatabaseSync(db), url = `http://127.0.0.1:${box.port}`, dir = `/workspaces/${box.name}`;
+  const row = d.prepare("select value from state where name='opencode.global.dat' and key='server'").get();
+  const s = { list: [], hidden: {}, projects: {}, lastProject: {}, recentlyClosed: {}, ...(row && JSON.parse(row.value)) };
+  const urlOf = x => (typeof x === 'string' ? x : x.http?.url ?? x.url);
+  s.list = s.list.filter(x => urlOf(x) !== url).concat({ type: 'http', http: { url, password: box.password }, displayName: `agentcage: ${box.name}` });
+  s.projects[url] = [{ worktree: dir, expanded: true }];
+  s.lastProject[url] = dir;
+  d.prepare(`insert into state(name, key, value, updated_at) values ('opencode.global.dat', 'server', ?, ?)
+    on conflict(name, key) do update set value = excluded.value, updated_at = excluded.updated_at`).run(JSON.stringify(s), Date.now());
+  d.close();
+}
+
+// OpenCode only reads API keys from an interactive terminal, so hand the terminal to its own prompt inside the box.
+// The key goes straight into the box's home volume and never passes through agentcage or the host.
+export const loginProvider = (box, provider) =>
+  run('docker', ['exec', '-it', '-u', 'node', '-w', '/tmp', box.container, 'opencode', 'auth', 'login', provider, '--method', 'key'], { tty: true });

package/src/run.js

@@ -0,0 +1,37 @@
+// Process helpers. Arguments are always passed as arrays (no shell), so paths never get mangled.
+import { spawn, spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+const fail = (cmd, args, code, err) =>
+  new Error(`${cmd} ${args.join(' ')} failed (exit ${code})${err ? ':\n' + err.trim().split('\n').slice(-15).join('\n') : ''}`);
+
+// Quick commands: returns trimmed stdout ('' if the command is missing and check is off)
+export function runSync(cmd, args = [], { check = false, input } = {}) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', input });
+  if (check && r.status !== 0) throw fail(cmd, args, r.status, r.stderr || r.error?.message);
+  return (r.stdout || '').trim();
+}
+export const ok = (cmd, args) => spawnSync(cmd, args, { stdio: 'ignore' }).status === 0;
+
+// Long-running commands (keeps spinners animating). input: string sent on stdin; tty: hand over the terminal
+export const run = (cmd, args = [], { input, env, tty } = {}) => new Promise((resolve, reject) => {
+  const p = spawn(cmd, args, { env: { ...process.env, ...env }, stdio: tty ? 'inherit' : 'pipe' });
+  let out = '', err = '';
+  p.stdout?.on('data', d => (out += d));
+  p.stderr?.on('data', d => (err += d));
+  p.on('error', e => reject(new Error(`${cmd}: ${e.message}`)));
+  p.on('close', code => (code === 0 ? resolve(out.trim()) : reject(fail(cmd, args, code, err || out))));
+  if (input !== undefined) p.stdin.end(input); else p.stdin?.end();
+});
+
+// Bundled @devcontainers/cli, so users don't need to install it
+const DC = join(dirname(createRequire(import.meta.url).resolve('@devcontainers/cli/package.json')), 'devcontainer.js');
+export const devcontainer = args => run(process.execPath, [DC, ...args]);
+
+// IDE launchers (cursor, code) are .cmd shims on Windows and need a shell there
+export function launch(cmd, args) {
+  const win = process.platform === 'win32';
+  const line = [cmd, ...args].map(a => (/[\s&|<>^]/.test(a) ? `"${a}"` : a)).join(' ');
+  return spawn(win ? line : cmd, win ? [] : args, { shell: win, stdio: 'ignore', detached: true }).unref();
+}

package/src/wizard.js

@@ -0,0 +1,143 @@
+// Interactive dialogs (@clack/prompts) on top of the box functions. Flags pre-fill answers; --yes takes defaults.
+import * as p from '@clack/prompts';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { AGENTS, DEV_TOOLS, PROVIDERS, hostInfo } from './catalog.js';
+import { cleanName, createBox, nameTaken, openIde, ws } from './box.js';
+import { isGitUrl, localRemote, parseRemote } from './git.js';
+import { connectDesktop, desktopRunning, detectDesktop, latestVersion, loginProvider } from './opencode.js';
+import { ok, runSync } from './run.js';
+
+export const ask = async q => {
+  const v = await q;
+  if (p.isCancel(v)) { p.cancel('Cancelled.'); process.exit(0); }
+  return v;
+};
+const step = async (label, fn) => {
+  const s = p.spinner();
+  s.start(label);
+  try { const r = await fn(); s.stop(label); return r; } catch (e) { s.error(label); throw e; }
+};
+
+export const connectionInfo = b =>
+  `Server    http://127.0.0.1:${b.port}\nUsername  opencode\nPassword  ${b.password}\nDirectory ${ws(b)}`;
+
+const FORWARD_WARNING = `While Cursor or VS Code is attached to the box, your laptop's git credentials
+and SSH agent are forwarded into the container. Any agent running in the box at
+that time can use them to push to EVERY repository you have access to, not only
+this one. When no IDE is attached, the box cannot push at all.`;
+
+// IDEs that can attach to a container, found on PATH or in their usual install folder
+function findIdes() {
+  const found = cmd => !!runSync(process.platform === 'win32' ? 'where' : 'which', [cmd]);
+  const ag = process.platform === 'win32' ? join(process.env.LOCALAPPDATA ?? '', 'Programs', 'Antigravity IDE', 'bin', 'antigravity-ide.cmd') : 'antigravity-ide';
+  return [['cursor', 'Cursor'], ['code', 'VS Code'], [ag, 'Antigravity']].filter(([c]) => existsSync(c) || found(c))
+    .map(([value, label]) => ({ value, label }));
+}
+
+async function waitForDocker() {
+  while (!ok('docker', ['info'])) {
+    p.log.warn('Docker is not running (or not installed). Start Docker Desktop / the Docker service.');
+    if (!(await ask(p.confirm({ message: 'Docker started. Check again?', active: 'Check again', inactive: 'Quit' })))) process.exit(1);
+  }
+}
+
+// Registers the box in OpenCode Desktop, asking the user to close the app if needed
+export async function registerFlow(b, interactive = true) {
+  if (!detectDesktop().hasDb) return p.note(connectionInfo(b), 'OpenCode Desktop not found. Add this server by hand');
+  while (desktopRunning()) {
+    if (!interactive) return p.log.warn(`OpenCode Desktop is open. Close it, then run: agentcage connect ${b.name}`);
+    const go = await ask(p.confirm({ message: 'Close OpenCode Desktop so the box can be added to it.', active: 'It is closed now', inactive: 'Skip for now' }));
+    if (!go) return p.log.info(`Later: agentcage connect ${b.name}`);
+  }
+  await connectDesktop(b);
+  p.log.success(`OpenCode Desktop: added server "agentcage: ${b.name}" with project ${ws(b)}`);
+}
+
+// Hands the terminal to OpenCode's own key prompt for each provider
+export async function providerFlow(b, ids) {
+  ids ??= await ask(p.multiselect({ message: 'Which providers should OpenCode use in this box?', options: PROVIDERS.map(x => ({ value: x.id, label: x.label, hint: x.hint })) }));
+  for (const id of ids) {
+    const pr = PROVIDERS.find(x => x.id === id);
+    p.log.step(`${pr.label}: paste your API key when OpenCode asks for it (get one at ${pr.hint}).`);
+    await loginProvider(b, id).catch(e => p.log.error(`${pr.label} was not added: ${e.message}`));
+  }
+}
+
+export async function newWizard(f = {}) {
+  const pick = (flag, def, prompt) => (flag !== undefined ? flag : f.yes ? def : prompt());
+  p.intro('agentcage · new box');
+  await waitForDocker();
+
+  const src = f.src ?? await ask((await ask(p.select({ message: 'Where is the project?', options: [
+    { value: 'folder', label: 'A folder on this computer', hint: 'copied once, incl. untracked files like .env.local' },
+    { value: 'git', label: 'A git repository', hint: 'cloned from a URL' },
+  ] }))) === 'folder'
+    ? p.path({ message: 'Project folder', directory: true, validate: v => (v && existsSync(v) ? undefined : 'Folder not found') })
+    : p.text({ message: 'Repository URL', placeholder: 'https://github.com/owner/repo.git', validate: v => (isGitUrl(v ?? '') ? undefined : 'Enter an https:// or git@ URL') }));
+  if (!isGitUrl(src) && !existsSync(src)) throw new Error(`Folder not found: ${src}`);
+
+  const nameOk = v => (!/^[a-z0-9][a-z0-9-]*$/.test(v ?? '') ? 'Use lowercase letters, digits and -' : nameTaken(v) ? `A box named '${v}' already exists` : undefined);
+  const name = await pick(f.name, cleanName(src), () => ask(p.text({ message: 'Box name', initialValue: cleanName(src), validate: nameOk })));
+  if (nameOk(name)) throw new Error(nameOk(name));
+
+  // Git push access
+  const remoteUrl = isGitUrl(src) ? src : localRemote(src), remote = parseRemote(remoteUrl);
+  let git = 'none', token;
+  if (remote) {
+    git = await pick(f.git, 'forward', () => ask(p.select({ message: `How should the box push to ${remote.host}/${remote.path}?`, options: [
+      { value: 'token', label: 'A token for this repo only', hint: 'recommended: agents can only push here' },
+      { value: 'forward', label: "Skip: use my IDE's forwarded credentials", hint: 'access to all your repos while the IDE is attached' },
+    ] })));
+    if (git === 'token') {
+      p.note(hostInfo(remote.host).help(remote.path), 'Repo token');
+      token = process.env.AGENTCAGE_GIT_TOKEN ?? await ask(p.password({ message: 'Paste the token', validate: v => (v ? undefined : 'Required') }));
+    } else if (!f.yes) {
+      p.note(FORWARD_WARNING, 'Warning: cross-repo access');
+      if (!(await ask(p.confirm({ message: 'Continue with forwarded credentials?', initialValue: false })))) return newWizard({ ...f, src, name });
+    }
+  }
+
+  const tools = await pick(f.tools, ['opencode'], async () => [
+    ...await ask(p.multiselect({ message: 'AI agents to install', options: AGENTS.map(t => ({ value: t.id, label: t.label, hint: t.hint })), initialValues: ['opencode'], required: false })),
+    ...await ask(p.multiselect({ message: 'Extra dev tools (Node 24 and uv are always included)', options: DEV_TOOLS.map(t => ({ value: t.id, label: t.label, hint: t.hint })), required: false })),
+  ]);
+  const oc = tools.includes('opencode');
+
+  let opencodeVersion, providers = [];
+  if (oc) {
+    const d = detectDesktop();
+    opencodeVersion = d.version ?? await pick(undefined, await latestVersion(), async () => ask(p.text({ message: 'OpenCode Desktop not found. OpenCode version for the box', initialValue: await latestVersion() })));
+    if (d.version) p.log.info(`OpenCode ${d.version} (matches your Desktop app)`);
+    providers = await pick(f.providers, [], () => ask(p.multiselect({ message: 'Model providers to connect (you paste each API key after the build)', options: PROVIDERS.map(x => ({ value: x.id, label: x.label, hint: x.hint })), required: false })));
+  }
+
+  const ides = findIdes();
+  const ide = await pick(f.ide, 'none', () => ides.length ? ask(p.select({ message: 'Open the box in an IDE when done?', options: [...ides, { value: 'none', label: 'No' }] })) : 'none');
+
+  p.note([
+    `Source     ${src}`, `Name       ${name}`,
+    `Git push   ${{ token: 'repo token', forward: 'forwarded IDE credentials', none: 'no remote' }[git]}`,
+    `Tools      ${tools.join(', ') || 'none'}${oc ? ` (OpenCode ${opencodeVersion})` : ''}`,
+    ...(providers.length ? [`Providers  ${providers.join(', ')}`] : []),
+  ].join('\n'), 'Summary');
+  if (!f.yes && !(await ask(p.confirm({ message: 'Create the box?' })))) return p.cancel('Nothing created.');
+
+  let b;
+  try {
+    b = await createBox({ src, name, tools, git, token, remote: remoteUrl, opencodeVersion }, step);
+  } catch (e) {
+    p.log.error(e.message);
+    p.outro(`Box creation failed. Fix the problem, then clean up with: agentcage remove ${name}`);
+    process.exit(1);
+  }
+  if (providers.length) await providerFlow(b, providers);
+  if (oc) await registerFlow(b, !f.yes);
+  if (ide !== 'none') { openIde(b, ide); p.log.success('Opening the IDE attached to the box'); }
+  p.outro([
+    `Box '${name}' is ready.`,
+    oc && `OpenCode Desktop: select "agentcage: ${name}" and start a session. Only sessions on that server are isolated.`,
+    tools.includes('claude-code') && `Claude Code: agentcage shell ${name}, then run claude to log in.`,
+    `Shell: agentcage shell ${name}    IDE: agentcage open ${name}`,
+  ].filter(Boolean).join('\n'));
+}

package/template/Dockerfile

@@ -0,0 +1,14 @@
+FROM mcr.microsoft.com/devcontainers/javascript-node:24-bookworm
+
+# Set by agentcage: OpenCode version matching the Desktop app (empty = no OpenCode), extra global npm tools
+ARG OPENCODE_VERSION=
+ARG NPM_GLOBALS=
+
+# uv manages Python versions + deps
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
+RUN if [ -n "$OPENCODE_VERSION" ]; then npm install -g @opencode/cli@${OPENCODE_VERSION}; fi \
+    && if [ -n "$NPM_GLOBALS" ]; then npm install -g $NPM_GLOBALS; fi \
+    && mkdir -p /workspaces && chown node:node /workspaces
+
+COPY post-create.sh /usr/local/bin/agentcage-post-create
+RUN chmod +x /usr/local/bin/agentcage-post-create

package/template/post-create.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Runs in the workspace folder after the container is created.
+set -e
+git config --global --replace-all safe.directory "$PWD"
+if [ -d .git ]; then
+  # Repo copied from Windows: use Linux git settings, convert CRLF back to LF where the repo stores LF,
+  # then clear files flagged modified that have no real content change (real changes are left untouched)
+  git config core.autocrlf input && git config core.symlinks true && git config core.ignorecase false
+  git ls-files --eol | awk -F'\t' '$1 ~ /^i\/lf +w\/crlf/ {print $2}' | xargs -r -d '\n' sed -i 's/\r$//'
+  comm -23 <(git ls-files -m | sort) <(git diff --name-only | sort) | xargs -r -d '\n' git add --
+fi
+# Install dependencies for every npm / uv project found
+find . -name package-lock.json -not -path '*/node_modules/*' -execdir npm ci \;
+find . -name uv.lock -not -path '*/.venv/*' -execdir uv sync \;