agentcage 0.1.0 → 0.1.2

package/README.md

@@ -1,9 +1,9 @@
 # agentcage
 
-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
+Isolated dev containers for AI coding agents. Each project gets its own Linux container. **The project source lives
+in a Docker volume, not in a folder mounted from your laptop**, so agents in the container can't see your other files. Each container 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.
+call (bash, read, edit) runs in the container. Claude Code can be installed in the container too.
 
 Works on Windows, macOS and Linux, in any terminal (PowerShell, Terminal, bash).
 
@@ -13,25 +13,25 @@ You need **Docker** (Docker Desktop on Windows/macOS, Docker Engine on Linux), *
 **OpenCode Desktop** (open it once so its settings exist).
 
 ```bash
-npm install -g agentcage
+npm install -g agentcage           # also updates to the latest version
 agentcage doctor        # checks everything above
 ```
 
-## Create a box
+## Create a container
 
 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.
+2. **A name** for the container.
 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).
+7. **An IDE** to open the container 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
+Then it builds the container, adds it to OpenCode Desktop as server **ac-<name>** with the project
 `/workspaces/<name>` already open, and opens the IDE.
 
 The same works without the dialog:
@@ -44,53 +44,54 @@ AGENTCAGE_GIT_TOKEN=github_pat_... agentcage new https://github.com/me/repo.git
 ## Commands
 
 ```bash
-agentcage                       # menu: create a box, or start/open/shell/upgrade/remove an existing one
-agentcage list                  # boxes, state, port, OpenCode version
+agentcage                       # menu: create a container, or start/open/shell/upgrade/remove an existing one
+agentcage list                  # containers, 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 shell <name>          # shell in the container (opencode, claude, git ... work here)
+agentcage open <name> [ide]     # Cursor (default), VS Code, or another VS Code-based IDE attached to the container
+agentcage provider <name>       # add model provider API keys to OpenCode in the container
+agentcage connect <name>        # (re)register the container 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 version               # installed version and the latest on npm
 agentcage doctor
-agentcage adopt <name>          # import a box made by the old bash scripts in legacy/
+agentcage adopt <name>          # import a container 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.
+Container config lives in `~/.agentcage/<name>/` (`container.json` and the generated `.devcontainer/`). `node_modules`, `.venv` and
+`.next` are not copied. Instead the container 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:
+The copy in the container is separate from your laptop's, so changes leave the container 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
+  is stored with git's credential store in the container'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.
+  SSH agent are forwarded into the container, so pushing from the IDE just works. **While the IDE is attached, any agent in the
+  container can use them to push to every repository you have access to.** When no IDE is attached, the container 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.
+own git credentials, then copies the repo in. Both work with private repos. Your git name and email are copied into the container.
 
 ## 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.
+version in the container, because Desktop only talks to matching servers. `list`, `start` and `doctor` warn when the app has
+updated since; `agentcage upgrade <name>` rebuilds the container 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,
+Provider API keys are typed into OpenCode's own prompt inside the container. They are stored only in the container'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.
@@ -99,11 +100,11 @@ never on your laptop, and survive rebuilds.
 
 - ✅ 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`.
+- ⚠️ The container 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.
+- ⚠️ Use the IDE for editing, diffs and git. Its built-in AI agent runs outside the container's isolation, so run agents through
+  OpenCode or Claude Code in the container.
 
 ## Platform notes
 
@@ -144,11 +145,11 @@ The setup dialog should let the user choose the backend: **plain Docker containe
    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
+**Plan:** add a `backend: docker | sbx` choice to the dialog and `container.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.
+`legacy/` holds the original bash scripts this tool replaces. `agentcage adopt <name>` takes over a container they created.

package/bin/agentcage.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
 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 { adoptContainer, listContainers, loadContainer, removeContainer, saveContainer, state, up, writeDevcontainer, openIde, ws } from '../src/container.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';
@@ -10,35 +11,36 @@ 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]
+  agentcage                         interactive menu (create or manage containers)
+  agentcage new [folder|git-url]    create a container  [--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 list                    containers, state, port, OpenCode version
+  agentcage start <name>            start a container 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 shell <name>            shell in the container (run opencode, claude, git ... here)
+  agentcage open <name> [ide]       open Cursor (default), VS Code or another VS Code-based IDE attached to the container
+  agentcage connect <name>          (re)register the container in OpenCode Desktop (app must be closed)
+  agentcage provider <name>         add model provider API keys to OpenCode in the container
   agentcage upgrade <name>          rebuild with the Desktop app's OpenCode version (volumes kept)
   agentcage remove <name>           delete container, volumes and config
+  agentcage version                 installed version, and the latest on npm (update: npm i -g agentcage@latest)
   agentcage doctor                  check Docker, Node and OpenCode Desktop
-  agentcage adopt <name>            import a box made by the old devbox bash scripts
+  agentcage adopt <name>            import a container 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' } },
+    ide: { type: 'string' }, yes: { type: 'boolean', short: 'y' }, help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' } },
 });
 const csv = s => s?.split(',').map(x => x.trim()).filter(Boolean);
-const box = () => loadBox(arg ?? (() => { throw new Error(`Usage: agentcage ${cmd} <name>`); })());
+const container = () => loadContainer(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}`);
+    p.log.warn(`OpenCode Desktop is ${v}, container '${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
@@ -47,35 +49,40 @@ async function start(b) {
 }
 
 const commands = {
+  async version() {
+    const v = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+    const latest = await fetch('https://registry.npmjs.org/agentcage/latest').then(r => r.json()).then(j => j.version, () => undefined);
+    console.log(`agentcage ${v}${!latest ? '' : latest === v ? ' (latest)' : `\nNewer version ${latest} on npm. Update with: npm i -g agentcage@latest`}`);
+  },
   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 rows = listContainers().map(b => [b.name, state(b), b.tools.includes('opencode') ? String(b.port) : '-', b.opencodeVersion ?? '-', b.git]);
+    if (!rows.length) return console.log('No containers 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 start() { const b = container(); await start(b); console.log(`Container '${b.name}' is running.\n${b.tools.includes('opencode') ? connectionInfo(b) : ''}`); },
+  async stop() { await run('docker', ['stop', container().container]); },
+  async shell() { const b = container(); 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).');
+    const b = container(); await start(b); openIde(b, arg2 ?? f.ide ?? 'cursor');
+    if (b.git === 'token') p.log.warn('The IDE forwards your SSH agent into the container. 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 connect() { await registerFlow(container()); },
+  async provider() { const b = container(); await start(b); await providerFlow(b, csv(f.providers)); },
   async upgrade() {
-    const b = box(), v = detectDesktop().version ?? await latestVersion();
+    const b = container(), 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);
+    saveContainer(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}'.`);
+    const b = container();
+    if (!f.yes && !(await ask(p.confirm({ message: `Delete container '${b.name}' with its volumes? Unpushed work in the container is lost.`, initialValue: false })))) return;
+    await removeContainer(b); console.log(`Removed '${b.name}'.`);
   },
   doctor() {
     const d = detectDesktop(), [maj, min] = process.versions.node.split('.').map(Number);
@@ -84,19 +91,19 @@ const commands = {
       [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'],
+      [!!d.version, `OpenCode Desktop version: ${d.version ?? 'unknown'}${d.from ? ` (from ${d.from})` : ''}`, 'Version not found: containers 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}`);
+    for (const b of listContainers()) if (b.tools.includes('opencode') && d.version && b.opencodeVersion !== d.version) p.log.warn(`Container '${b.name}' has OpenCode ${b.opencodeVersion}: agentcage upgrade ${b.name}`);
   },
-  adopt() { const b = adoptBox(arg); console.log(`Adopted '${b.name}' (${b.container}).`); },
+  adopt() { const b = adoptContainer(arg); console.log(`Adopted '${b.name}' (${b.container}).`); },
 
   // No command: menu
   async menu() {
-    const boxes = listBoxes();
-    if (!boxes.length) return newWizard();
+    const containers = listContainers();
+    if (!containers.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) }))] }));
+    const pick = await ask(p.select({ message: 'What do you want to do?', options: [{ value: '', label: 'Create a new container' }, ...containers.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' },
@@ -109,6 +116,7 @@ const commands = {
   },
 };
 
+if (f.version) cmd = 'version';
 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,6 @@
 {
   "name": "agentcage",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Isolated dev containers for AI coding agents (OpenCode, Claude Code), connected to OpenCode Desktop",
   "type": "module",
   "bin": {

package/src/{box.js → container.js}

@@ -1,5 +1,5 @@
-// Box state (~/.agentcage/<name>/box.json), devcontainer.json generation and the box lifecycle.
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+// Container state (~/.agentcage/<name>/container.json), devcontainer.json generation and the container lifecycle.
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -11,29 +11,34 @@ 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');
+// Configs from before the box -> container rename are moved to container.json on first access
+const cfgFile = name => {
+  const f = join(ROOT, name, 'container.json'), old = join(ROOT, name, 'box.json');
+  if (!existsSync(f) && existsSync(old)) renameSync(old, f);
+  return f;
+};
 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 const hasContainer = name => existsSync(cfgFile(name));
+export function loadContainer(name) {
+  if (!hasContainer(name)) throw new Error(`No container named '${name}'. See: agentcage list`);
+  return JSON.parse(readFileSync(cfgFile(name), 'utf8'));
 }
-export function saveBox(b) {
+export function saveContainer(b) {
   mkdirSync(join(ROOT, b.name), { recursive: true });
-  writeFileSync(boxFile(b.name), JSON.stringify(b, null, 2));
+  writeFileSync(cfgFile(b.name), JSON.stringify(b, null, 2));
 }
-export const listBoxes = () => (existsSync(ROOT) ? readdirSync(ROOT).filter(hasBox).map(loadBox) : []);
+export const listContainers = () => (existsSync(ROOT) ? readdirSync(ROOT).filter(hasContainer).map(loadContainer) : []);
 
 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`]);
+export const nameTaken = n => hasContainer(n) || ok('docker', ['inspect', `ac-${n}`]) || ok('docker', ['volume', 'inspect', `ac-${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));
+  const used = new Set(listContainers().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;
 }
@@ -66,18 +71,18 @@ export const up = (b, rebuild) => devcontainer(['up', '--workspace-folder', b.di
 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()) {
+export async function createContainer(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` },
+    name, dir: join(ROOT, name), container: `ac-${name}`,
+    volumes: { src: `ac-${name}-src`, home: `ac-${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);
+  saveContainer(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('Copying the source into the container', () => 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);
@@ -86,7 +91,7 @@ export async function createBox(o, step = (_, f) => f()) {
   return b;
 }
 
-export async function removeBox(b) {
+export async function removeContainer(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 });
@@ -99,10 +104,10 @@ export function openIde(b, ide) {
   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) {
+// Import a container made by the old bash kit (~/devboxes/<name>, devbox-<name> container and volumes)
+export function adoptContainer(name) {
   const dir = join(homedir(), 'devboxes', name), cfg = join(dir, '.devcontainer', 'devcontainer.json');
-  if (!existsSync(cfg)) throw new Error(`No legacy box at ${dir}`);
+  if (!existsSync(cfg)) throw new Error(`No legacy container 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` },
@@ -110,6 +115,6 @@ export function adoptBox(name) {
     source: 'legacy devbox', git: 'forward', tools: ['opencode'], opencodeVersion: docker.match(/OPENCODE_VERSION=(\S+)/)?.[1],
     created: new Date().toISOString(), legacy: true,
   };
-  saveBox(b);
+  saveContainer(b);
   return b;
 }

package/src/git.js

@@ -1,4 +1,4 @@
-// Getting the source into the box, and git push credentials inside it.
+// Getting the source into the container, and git push credentials inside it.
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -43,7 +43,7 @@ export async function copyIdentity(container) {
   }
 }
 
-// Repo-scoped token: stored with git's credential store in the box's home volume, used for this repo only.
+// Repo-scoped token: stored with git's credential store in the container'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

package/src/opencode.js

@@ -1,4 +1,4 @@
-// OpenCode Desktop on the host: where it lives, its version, whether it runs, and registering boxes in it.
+// OpenCode Desktop on the host: where it lives, its version, whether it runs, and registering containers in it.
 import { copyFileSync, existsSync, readFileSync, readdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -33,17 +33,17 @@ export const desktopRunning = () => P === 'win32'
 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) {
+export async function connectDesktop(container) {
   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 d = new DatabaseSync(db), url = `http://127.0.0.1:${container.port}`, dir = `/workspaces/${container.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.list = s.list.filter(x => urlOf(x) !== url).concat({ type: 'http', http: { url, password: container.password }, displayName: `ac-${container.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', ?, ?)
@@ -51,7 +51,7 @@ export async function connectDesktop(box) {
   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 });
+// OpenCode only reads API keys from an interactive terminal, so hand the terminal to its own prompt inside the container.
+// The key goes straight into the container's home volume and never passes through agentcage or the host.
+export const loginProvider = (container, provider) =>
+  run('docker', ['exec', '-it', '-u', 'node', '-w', '/tmp', container.container, 'opencode', 'auth', 'login', provider, '--method', 'key'], { tty: true });

package/src/wizard.js

@@ -1,9 +1,9 @@
-// Interactive dialogs (@clack/prompts) on top of the box functions. Flags pre-fill answers; --yes takes defaults.
+// Interactive dialogs (@clack/prompts) on top of the container 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 { cleanName, createContainer, nameTaken, openIde, ws } from './container.js';
 import { isGitUrl, localRemote, parseRemote } from './git.js';
 import { connectDesktop, desktopRunning, detectDesktop, latestVersion, loginProvider } from './opencode.js';
 import { ok, runSync } from './run.js';
@@ -22,10 +22,10 @@ const step = async (label, fn) => {
 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
+const FORWARD_WARNING = `While Cursor or VS Code is attached to the container, your laptop's git credentials
+and SSH agent are forwarded into the container. Any agent running in the container 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.`;
+this one. When no IDE is attached, the container cannot push at all.`;
 
 // IDEs that can attach to a container, found on PATH or in their usual install folder
 function findIdes() {
@@ -42,21 +42,21 @@ async function waitForDocker() {
   }
 }
 
-// Registers the box in OpenCode Desktop, asking the user to close the app if needed
+// Registers the container 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' }));
+    const go = await ask(p.confirm({ message: 'Close OpenCode Desktop so the container 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)}`);
+  p.log.success(`OpenCode Desktop: added server "ac-${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 })) }));
+  ids ??= await ask(p.multiselect({ message: 'Which providers should OpenCode use in this container?', 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}).`);
@@ -66,7 +66,7 @@ export async function providerFlow(b, ids) {
 
 export async function newWizard(f = {}) {
   const pick = (flag, def, prompt) => (flag !== undefined ? flag : f.yes ? def : prompt());
-  p.intro('agentcage · new box');
+  p.intro('agentcage · new container');
   await waitForDocker();
 
   const src = f.src ?? await ask((await ask(p.select({ message: 'Where is the project?', options: [
@@ -77,15 +77,15 @@ export async function newWizard(f = {}) {
     : 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 })));
+  const nameOk = v => (!/^[a-z0-9][a-z0-9-]*$/.test(v ?? '') ? 'Use lowercase letters, digits and -' : nameTaken(v) ? `A container named '${v}' already exists` : undefined);
+  const name = await pick(f.name, cleanName(src), () => ask(p.text({ message: 'Container name (the Docker container and the OpenCode server get the prefix "ac-")', 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: [
+    git = await pick(f.git, 'forward', () => ask(p.select({ message: `How should the container 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' },
     ] })));
@@ -107,13 +107,13 @@ export async function newWizard(f = {}) {
   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() })));
+    opencodeVersion = d.version ?? await pick(undefined, await latestVersion(), async () => ask(p.text({ message: 'OpenCode Desktop not found. OpenCode version for the container', 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 })));
+    providers = await pick(f.providers, [], () => ask(p.multiselect({ message: 'Additional OpenCode 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');
+  const ide = await pick(f.ide, 'none', () => ides.length ? ask(p.select({ message: 'Open the container in an IDE when done?', options: [...ides, { value: 'none', label: 'No' }] })) : 'none');
 
   p.note([
     `Source     ${src}`, `Name       ${name}`,
@@ -121,22 +121,22 @@ export async function newWizard(f = {}) {
     `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.');
+  if (!f.yes && !(await ask(p.confirm({ message: 'Create the container?' })))) return p.cancel('Nothing created.');
 
   let b;
   try {
-    b = await createBox({ src, name, tools, git, token, remote: remoteUrl, opencodeVersion }, step);
+    b = await createContainer({ 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}`);
+    p.outro(`Container 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'); }
+  if (ide !== 'none') { openIde(b, ide); p.log.success('Opening the IDE attached to the container'); }
   p.outro([
-    `Box '${name}' is ready.`,
-    oc && `OpenCode Desktop: select "agentcage: ${name}" and start a session. Only sessions on that server are isolated.`,
+    `Container '${name}' is ready.`,
+    oc && `OpenCode Desktop: select "ac-${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'));