agentcage 0.1.3 → 0.1.4

package/README.md

@@ -21,24 +21,46 @@ You need **Docker** (Docker Desktop on Windows/macOS, Docker Engine on Linux), *
 
 ```bash
 npm install -g agentcage           # also updates to the latest version
-agentcage doctor        # checks everything above
 ```
 
-## Create a container
+```bash
+agentcage doctor        # checks all the prerequisites.
+```
+
+
+
+## Quickstart
+
+Prerequisites:
+
+- Node and Git installed
+- Docker is running
+- OpenCode installed
+
+Run this in terminal: 
+
+```bash
+agentcage doctor        # checks all the prerequisites.
+agentcage               # Starts the container-creation dialogue
+```
 
-Run `agentcage` and follow the dialog. It asks for:
+Follow the steps
+
+## Creating a container
+
+Run `agentcage` .  The wizard will ask you for this:
 
 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 container.
+  or a git URL (cloned).
+2. **A name** for the container. The Docker container, OpenCode server and OpenCode project get the prefix `ac-` (see [Settings](#settings)).
 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.
+  API key in your terminal. Additional Providers can be added later. 
 7. **An IDE** to open the container in when it's ready (Cursor, VS Code, Antigravity).
 
-Then it builds the container, adds it to OpenCode Desktop as server **ac-<name>** with the project
+Then it builds the container, adds it to OpenCode Desktop as server **ac-<name>** (a green project) with the project
 `/workspaces/<name>` already open, and opens the IDE.
 
 The same works without the dialog:
@@ -48,6 +70,8 @@ agentcage new ~/code/my-project --tools opencode,claude-code --git forward --ide
 AGENTCAGE_GIT_TOKEN=github_pat_... agentcage new https://github.com/me/repo.git --git token --yes
 ```
 
+
+
 ## Commands
 
 ```bash
@@ -62,6 +86,7 @@ agentcage upgrade <name>        # rebuild with the Desktop app's OpenCode versio
 agentcage stop <name>
 agentcage remove <name>         # delete container, volumes and config
 agentcage version               # installed version and the latest on npm
+agentcage settings              # project color and name prefixes for new containers
 agentcage doctor
 agentcage adopt <name>          # import a container made by the old bash scripts in legacy/
 ```
@@ -69,20 +94,32 @@ agentcage adopt <name>          # import a container made by the old bash script
 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.
 
+## Settings
+
+`agentcage settings` (or **Settings** in the menu) edits `~/.agentcage/settings.json`. Settings apply to containers
+created afterwards.
+
+| Setting | Default | |
+| --- | --- | --- |
+| OpenCode project color | `green` | also gray (OpenCode's default), pink, blue, red, purple, yellow, orange, cyan |
+| Docker container prefix | `ac-` | container and volume names, e.g. `ac-myproject`, `ac-myproject-src` |
+| OpenCode server prefix | `ac-` | the server's name in OpenCode Desktop |
+| OpenCode project prefix | `ac-` | the project's name in OpenCode (the folder stays `/workspaces/<name>`) |
+
 ## Git push access
 
 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 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.
+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 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 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.
+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 container.
@@ -106,12 +143,14 @@ never on your laptop, and survive rebuilds.
 ## 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.
+requires a random password.
 - ⚠️ 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 container's isolation, so run agents through
-  OpenCode or Claude Code in the container.
+OpenCode or Claude Code in the container.
+
+
 
 ## Platform notes
 
@@ -125,31 +164,33 @@ The setup dialog should let the user choose the backend: **plain Docker containe
 (`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.
+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.
+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.
+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.
+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).
+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>`.
+  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
+  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>`.
+  (`/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.
+  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.
+  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 `container.json`. The `sbx` backend maps our steps to
@@ -159,4 +200,4 @@ registration stay the same.
 
 ## Legacy
 
-`legacy/` holds the original bash scripts this tool replaces. `agentcage adopt <name>` takes over a container they created.
+`legacy/` holds the original bash scripts this tool replaces. `agentcage adopt <name>` takes over a container they created.

package/bin/agentcage.js

@@ -3,7 +3,7 @@ import { readFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
 import * as p from '@clack/prompts';
 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 { ask, connectionInfo, newWizard, providerFlow, registerFlow, settingsWizard } from '../src/wizard.js';
 import { detectDesktop, latestVersion } from '../src/opencode.js';
 import { ok, run } from '../src/run.js';
 
@@ -23,9 +23,11 @@ const HELP = `agentcage: isolated dev containers for AI coding agents
   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 settings                project color and name prefixes for new containers
+  agentcage version | -v            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 container made by the old devbox bash scripts
+  agentcage help | -h               this help
 
   In token mode, a token can also be passed in the AGENTCAGE_GIT_TOKEN environment variable.`;
 
@@ -49,6 +51,7 @@ async function start(b) {
 }
 
 const commands = {
+  settings: settingsWizard,
   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);
@@ -103,7 +106,10 @@ const commands = {
     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 container' }, ...containers.map(b => ({ value: b.name, label: b.name, hint: state(b) }))] }));
+    // '-settings' can't clash with a container name (names start with a letter or digit)
+    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) })), { value: '-settings', label: 'Settings' }] }));
+    if (pick === '-settings') return settingsWizard();
     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' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentcage",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Isolated dev containers for AI coding agents (OpenCode, Claude Code), connected to OpenCode Desktop",
   "type": "module",
   "bin": {

package/src/container.js

@@ -7,6 +7,7 @@ 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 { loadSettings } from './settings.js';
 import { copyIdentity, isGitUrl, parseRemote, seed, setupToken } from './git.js';
 
 export const ROOT = join(homedir(), '.agentcage');
@@ -32,7 +33,10 @@ export const listContainers = () => (existsSync(ROOT) ? readdirSync(ROOT).filter
 
 export const cleanName = s => s.replace(/\.git\/?$/, '').replace(/[\\/:]+$/, '').replace(/.*[:\\/]/, '')
   .toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
-export const nameTaken = n => hasContainer(n) || ok('docker', ['inspect', `ac-${n}`]) || ok('docker', ['volume', 'inspect', `ac-${n}-src`]);
+export function nameTaken(n) {
+  const px = loadSettings().containerPrefix;
+  return hasContainer(n) || ok('docker', ['inspect', px + n]) || ok('docker', ['volume', 'inspect', `${px}${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)));
@@ -72,10 +76,10 @@ export const state = b => runSync('docker', ['inspect', '-f', '{{.State.Status}}
 
 // o: { src, name, tools, git: 'token'|'forward'|'none', token, opencodeVersion }. step(label, fn) shows progress.
 export async function createContainer(o, step = (_, f) => f()) {
-  const { name } = o, src = isGitUrl(o.src) ? o.src : resolve(o.src);
+  const { name } = o, src = isGitUrl(o.src) ? o.src : resolve(o.src), s = loadSettings(), px = s.containerPrefix;
   const b = {
-    name, dir: join(ROOT, name), container: `ac-${name}`,
-    volumes: { src: `ac-${name}-src`, home: `ac-${name}-home` },
+    name, dir: join(ROOT, name), container: px + name, serverName: s.serverPrefix + name, projectName: s.projectPrefix + name, color: s.color,
+    volumes: { src: `${px}${name}-src`, home: `${px}${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(),
   };

package/src/opencode.js

@@ -3,6 +3,7 @@ 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';
+import { loadSettings } from './settings.js';
 
 const P = process.platform, H = homedir(), E = process.env;
 const DATA_DIR = P === 'win32' ? join(E.APPDATA ?? '', 'ai.opencode.desktop')
@@ -43,7 +44,7 @@ export async function connectDesktop(container) {
   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: container.password }, displayName: `ac-${container.name}` });
+  s.list = s.list.filter(x => urlOf(x) !== url).concat({ type: 'http', http: { url, password: container.password }, displayName: serverName(container) });
   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,6 +52,25 @@ export async function connectDesktop(container) {
   d.close();
 }
 
+// Names stored at creation; containers made before the settings existed use the current settings
+export const serverName = c => c.serverName ?? loadSettings().serverPrefix + c.name;
+
+// Sets the project's name and icon color in the container's OpenCode server. Asking about the folder creates the project first.
+// The server starts in the background after `devcontainer up`, so retry for ~30 s.
+export async function setupProject(c) {
+  const s = loadSettings(), name = c.projectName ?? s.projectPrefix + c.name, color = c.color ?? s.color;
+  const base = `http://127.0.0.1:${c.port}/api`, dir = `/workspaces/${c.name}`;
+  const api = (path, init) => fetch(base + path, { ...init, headers: { authorization: `Basic ${Buffer.from(`opencode:${c.password}`).toString('base64')}`, 'content-type': 'application/json' } })
+    .then(r => (r.ok ? r.json() : Promise.reject(new Error(`OpenCode API ${path}: HTTP ${r.status}`))));
+  for (let i = 0; ; i++) {
+    try {
+      await api(`/vcs?location[directory]=${encodeURIComponent(dir)}`);
+      const { id } = (await api('/project')).find(x => x.canonical === dir);
+      return await api(`/project/${id}`, { method: 'PATCH', body: JSON.stringify({ name, icon: { color } }) });
+    } catch (e) { if (i >= 15) throw e; await new Promise(r => setTimeout(r, 2000)); }
+  }
+}
+
 // 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) =>

package/src/settings.js

@@ -0,0 +1,19 @@
+// User settings (~/.agentcage/settings.json). Missing keys fall back to the defaults.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const FILE = join(homedir(), '.agentcage', 'settings.json');
+// Project icon colors OpenCode Desktop can show (others render as gray). green first: our default, gray: OpenCode's.
+export const COLORS = ['green', 'gray', 'pink', 'blue', 'red', 'purple', 'yellow', 'orange', 'cyan'];
+export const DEFAULTS = { color: 'green', containerPrefix: 'ac-', serverPrefix: 'ac-', projectPrefix: 'ac-' };
+export const LABELS = {
+  color: 'OpenCode project color', containerPrefix: 'Docker container prefix',
+  serverPrefix: 'OpenCode server prefix', projectPrefix: 'OpenCode project prefix',
+};
+
+export const loadSettings = () => ({ ...DEFAULTS, ...(existsSync(FILE) && JSON.parse(readFileSync(FILE, 'utf8'))) });
+export function saveSettings(s) {
+  mkdirSync(join(FILE, '..'), { recursive: true });
+  writeFileSync(FILE, JSON.stringify(s, null, 2) + '\n');
+}

package/src/wizard.js

@@ -5,8 +5,9 @@ import { join } from 'node:path';
 import { AGENTS, DEV_TOOLS, PROVIDERS, hostInfo } from './catalog.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 { connectDesktop, desktopRunning, detectDesktop, latestVersion, loginProvider, serverName, setupProject } from './opencode.js';
 import { ok, runSync } from './run.js';
+import { COLORS, DEFAULTS, LABELS, loadSettings, saveSettings } from './settings.js';
 
 export const ask = async q => {
   const v = await q;
@@ -51,7 +52,7 @@ export async function registerFlow(b, interactive = true) {
     if (!go) return p.log.info(`Later: agentcage connect ${b.name}`);
   }
   await connectDesktop(b);
-  p.log.success(`OpenCode Desktop: added server "ac-${b.name}" with project ${ws(b)}`);
+  p.log.success(`OpenCode Desktop: added server "${serverName(b)}" with project ${ws(b)}`);
 }
 
 // Hands the terminal to OpenCode's own key prompt for each provider
@@ -77,8 +78,10 @@ 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 s = loadSettings(), px = v => (v ? `"${v}"` : 'none');
+  if (!f.yes) p.log.info(`Name prefixes: Docker container ${px(s.containerPrefix)}, OpenCode server ${px(s.serverPrefix)}, OpenCode project ${px(s.projectPrefix)}. Change with: agentcage settings`);
   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 })));
+  const name = await pick(f.name, cleanName(src), () => ask(p.text({ message: 'Container name', initialValue: cleanName(src), validate: nameOk })));
   if (nameOk(name)) throw new Error(nameOk(name));
 
   // Git push access
@@ -132,12 +135,29 @@ export async function newWizard(f = {}) {
     process.exit(1);
   }
   if (providers.length) await providerFlow(b, providers);
+  if (oc) await setupProject(b).catch(e => p.log.warn(`Could not set the project name and color in OpenCode: ${e.message}`));
   if (oc) await registerFlow(b, !f.yes);
   if (ide !== 'none') { openIde(b, ide); p.log.success('Opening the IDE attached to the container'); }
   p.outro([
     `Container '${name}' is ready.`,
-    oc && `OpenCode Desktop: select "ac-${name}" and start a session. Only sessions on that server are isolated.`,
+    oc && `OpenCode Desktop: select "${serverName(b)}" 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'));
 }
+
+// Edit user settings one at a time until Done. They apply to containers created afterwards.
+export async function settingsWizard() {
+  p.intro('agentcage · settings');
+  const s = loadSettings();
+  for (;;) {
+    const key = await ask(p.select({ message: 'Which setting? (applies to new containers)', options: [
+      ...Object.keys(DEFAULTS).map(k => ({ value: k, label: LABELS[k], hint: s[k] === '' ? 'none' : s[k] })), { value: '', label: 'Done' }] }));
+    if (!key) break;
+    s[key] = await ask(key === 'color'
+      ? p.select({ message: LABELS.color, initialValue: s.color, options: COLORS.map(c => ({ value: c, label: c, hint: c === 'gray' ? "OpenCode's default" : undefined })) })
+      : p.text({ message: `${LABELS[key]} (empty for none)`, initialValue: s[key], defaultValue: '', validate: v => (/^[a-z0-9-]*$/.test(v ?? '') ? undefined : 'Use lowercase letters, digits and -') }));
+    saveSettings(s);
+  }
+  p.outro('Settings saved.');
+}