agentcage 0.1.5 → 0.1.7

package/README.md

@@ -87,7 +87,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 settings              # project color, name prefixes, clean up dead containers
 agentcage doctor
 agentcage adopt <name>          # import a container made by the old bash scripts in legacy/
 ```
@@ -106,10 +106,15 @@ created afterwards.
 | 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 token per project | `don't use` | `ask every time` asks token or forwarded credentials for each new container, `always use` always asks for a token. See [Git push access](#git-push-access) |
+
+**Clean up dead containers** (also in Settings) lists leftovers of containers that no longer exist in Docker: agentcage
+configs and OpenCode Desktop servers. Stopped containers are kept. A config whose volumes still hold code is not
+preselected, because removing it deletes those volumes.
 
 ## 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:
+The copy in the container is separate from your laptop's, so changes leave the container via **git push**. There are two ways. By default no token is used and the dialog doesn't ask; the **Git token per project** setting changes that:
 
 - **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
@@ -131,6 +136,12 @@ agentcage reads the Desktop app's version (from `opencode-cli.version` in its in
 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.
 
+The OpenCode server is the container's main process, so it runs after every start: `agentcage start`, Docker Desktop, or an
+IDE starting the container. Containers made by older agentcage versions get this after one `agentcage upgrade <name>`.
+
+Cursor and VS Code open `/workspaces/<name>` however you attach (agentcage, Remote Explorer, Docker extension, recent list):
+agentcage sets the folder in the IDE's attached-container config for the container.
+
 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

package/bin/agentcage.js

@@ -23,7 +23,7 @@ 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 settings                project color and name prefixes for new containers
+  agentcage settings                project color, name prefixes, clean up dead 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
@@ -85,6 +85,7 @@ const commands = {
     b.opencodeVersion = v; writeDevcontainer(b);
     await up(b, true).then(() => s.stop(`Rebuilt with OpenCode ${v}`), e => { s.error('Rebuild failed'); throw e; });
     saveContainer(b);
+    if (b.tools.includes('opencode')) await setupProject(b).catch(e => p.log.warn(`Could not set the project name and icon in OpenCode: ${e.message}`));
   },
   async remove() {
     const b = container();

package/package.json

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

package/src/container.js

@@ -41,9 +41,14 @@ export function nameTaken(n) {
 const bindable = port => new Promise(r => {
   const s = createServer().once('error', () => r(false)).listen(port, '127.0.0.1', () => s.close(() => r(true)));
 });
+// Host ports published by any Docker container, running or stopped (docker ps shows none for stopped ones)
+export function publishedPorts() {
+  const ids = runSync('docker', ['ps', '-aq']).split('\n').filter(Boolean);
+  const out = ids.length ? runSync('docker', ['inspect', '-f', '{{json .HostConfig.PortBindings}}', ...ids]) : '';
+  return new Set([...out.matchAll(/"HostPort":"(\d+)"/g)].map(m => +m[1]));
+}
 async function freePort() {
-  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]);
+  const used = new Set([...listContainers().map(b => b.port), ...publishedPorts()]);
   for (let p = 4100; ; p++) if (!used.has(p) && (await bindable(p))) return p;
 }
 
@@ -60,18 +65,21 @@ export function writeDevcontainer(b) {
     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 } : {},
+    containerEnv: { AGENTCAGE_WORKSPACE: ws(b), ...(oc && { OPENCODE_SERVER_PASSWORD: b.password }) },
     features: Object.fromEntries(tools.filter(t => t.feature).map(t => [t.feature, {}])),
     remoteUser: 'node',
     init: true,
+    overrideCommand: false, // run the image's CMD (agentcage-start) on every start, not only on devcontainer up
     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 async function up(b, rebuild) {
+  await devcontainer(['up', '--workspace-folder', b.dir, ...(rebuild ? ['--remove-existing-container'] : [])]);
+  pinIdeFolder(b);
+}
 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.
@@ -100,10 +108,35 @@ export async function removeContainer(b) {
   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 });
+  for (const d of ideConfigDirs()) rmSync(join(d, 'nameConfigs', `${b.container}.json`), { force: true });
+}
+
+// VS Code-based IDEs keep an attached-container config per container name (nameConfigs) and per image (imageConfigs).
+// Its workspaceFolder decides the folder that opens on any attach (Remote Explorer, Docker extension, recent list),
+// so point both at the code. Other keys in those files (e.g. extensions) are kept.
+const CONFIG_HOME = P => P === 'win32' ? process.env.APPDATA ?? '' : P === 'darwin' ? join(homedir(), 'Library', 'Application Support')
+  : process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+const ideConfigDirs = (root = CONFIG_HOME(process.platform)) => (existsSync(root) ? readdirSync(root) : [])
+  .map(app => join(root, app, 'User', 'globalStorage')).filter(existsSync)
+  .flatMap(gs => readdirSync(gs).filter(d => d.endsWith('remote-containers')).map(d => join(gs, d)));
+export function pinIdeFolder(b) {
+  const image = runSync('docker', ['inspect', '-f', '{{.Config.Image}}', b.container]);
+  for (const d of ideConfigDirs()) {
+    // image configs: only fix existing ones, they are shared by every container of that image
+    for (const f of [join(d, 'nameConfigs', `${b.container}.json`), ...(image ? [join(d, 'imageConfigs', `${image}.json`)].filter(existsSync) : [])]) {
+      try {
+        const cfg = existsSync(f) ? JSON.parse(readFileSync(f, 'utf8')) : {};
+        if (cfg.workspaceFolder === ws(b)) continue;
+        mkdirSync(join(f, '..'), { recursive: true });
+        writeFileSync(f, JSON.stringify({ ...cfg, workspaceFolder: ws(b) }, null, '\t'));
+      } catch {} // not plain JSON (hand-edited with comments): leave it alone
+    }
+  }
 }
 
 // Opens a VS Code-based IDE attached to the running container
 export function openIde(b, ide) {
+  pinIdeFolder(b);
   const hex = Buffer.from(JSON.stringify({ containerName: `/${b.container}` })).toString('hex');
   launch(ide, ['--folder-uri', `vscode-remote://attached-container+${hex}${ws(b)}`]);
 }

package/src/icon.js

@@ -1,11 +1,14 @@
 // Generates the 128x128 project icon for OpenCode: dark green background, white text in two rows —
-// the project prefix ("ac") in small letters on top, the first three letters of the container name below.
+// the project prefix ("ac") in small letters on top, the first three letters of the container name in capitals below —
+// and a light color band along the bottom, its hue picked from the name (looks random, stays the same per project).
 // A hand-rolled PNG encoder (zlib + CRC) with a 5x7 bitmap font keeps this dependency-free.
 import { deflateSync } from 'node:zlib';
 
 const SIZE = 128, SS = 4, BG = [20, 83, 45], FG = [255, 255, 255]; // SS: supersampling for smooth edges
 
-// 5x7 pixel font ('#' = ink); lowercase letters, digits and - cover all names and prefixes
+const BAND = 4; // bottom pixel rows in the accent color
+
+// 5x7 pixel font ('#' = ink); lowercase and capital letters, digits and - cover all names and prefixes
 const FONT = {
   a: ['.....', '.....', '.###.', '....#', '.####', '#...#', '.####'],
   b: ['#....', '#....', '####.', '#...#', '#...#', '#...#', '####.'],
@@ -44,6 +47,39 @@ const FONT = {
   8: ['.###.', '#...#', '#...#', '.###.', '#...#', '#...#', '.###.'],
   9: ['.###.', '#...#', '#...#', '.####', '....#', '....#', '.###.'],
   '-': ['.....', '.....', '.....', '.###.', '.....', '.....', '.....'],
+  A: ['.###.', '#...#', '#...#', '#####', '#...#', '#...#', '#...#'],
+  B: ['####.', '#...#', '#...#', '####.', '#...#', '#...#', '####.'],
+  C: ['.###.', '#...#', '#....', '#....', '#....', '#...#', '.###.'],
+  D: ['####.', '#...#', '#...#', '#...#', '#...#', '#...#', '####.'],
+  E: ['#####', '#....', '#....', '####.', '#....', '#....', '#####'],
+  F: ['#####', '#....', '#....', '####.', '#....', '#....', '#....'],
+  G: ['.###.', '#...#', '#....', '#.###', '#...#', '#...#', '.####'],
+  H: ['#...#', '#...#', '#...#', '#####', '#...#', '#...#', '#...#'],
+  I: ['.###.', '..#..', '..#..', '..#..', '..#..', '..#..', '.###.'],
+  J: ['..###', '...#.', '...#.', '...#.', '...#.', '#..#.', '.##..'],
+  K: ['#...#', '#..#.', '#.#..', '##...', '#.#..', '#..#.', '#...#'],
+  L: ['#....', '#....', '#....', '#....', '#....', '#....', '#####'],
+  M: ['#...#', '##.##', '#.#.#', '#.#.#', '#...#', '#...#', '#...#'],
+  N: ['#...#', '#...#', '##..#', '#.#.#', '#..##', '#...#', '#...#'],
+  O: ['.###.', '#...#', '#...#', '#...#', '#...#', '#...#', '.###.'],
+  P: ['####.', '#...#', '#...#', '####.', '#....', '#....', '#....'],
+  Q: ['.###.', '#...#', '#...#', '#...#', '#.#.#', '#..#.', '.##.#'],
+  R: ['####.', '#...#', '#...#', '####.', '#.#..', '#..#.', '#...#'],
+  S: ['.####', '#....', '#....', '.###.', '....#', '....#', '####.'],
+  T: ['#####', '..#..', '..#..', '..#..', '..#..', '..#..', '..#..'],
+  U: ['#...#', '#...#', '#...#', '#...#', '#...#', '#...#', '.###.'],
+  V: ['#...#', '#...#', '#...#', '#...#', '#...#', '.#.#.', '..#..'],
+  W: ['#...#', '#...#', '#...#', '#.#.#', '#.#.#', '#.#.#', '.#.#.'],
+  X: ['#...#', '#...#', '.#.#.', '..#..', '.#.#.', '#...#', '#...#'],
+  Y: ['#...#', '#...#', '.#.#.', '..#..', '..#..', '..#..', '..#..'],
+  Z: ['#####', '....#', '...#.', '..#..', '.#...', '#....', '#####'],
+};
+
+// Light accent color with a hue from the name, HSL(hue, 75%, 72%). Greens (hue 80-160) are skipped: no contrast with the background
+const accent = name => {
+  const h = (160 + [...name].reduce((n, ch) => (n * 31 + ch.charCodeAt(0)) >>> 0, 7) % 280) % 360, s = 0.75, l = 0.72;
+  const f = k => { const a = s * Math.min(l, 1 - l), t = (k + h / 30) % 12; return Math.round(255 * (l - a * Math.max(-1, Math.min(t - 3, 9 - t, 1)))); };
+  return [f(0), f(8), f(4)];
 };
 
 const crcTable = Array.from({ length: 256 }, (_, n) => { let c = n; for (let k = 0; k < 8; k++) c = c & 1 ? 0xEDB88320 ^ (c >>> 1) : c >>> 1; return c; });
@@ -76,10 +112,11 @@ const draw = (img, dim, text, s, y) => {
 // The icon as a data URL for OpenCode's project icon override
 export const projectIcon = (name, prefix = 'ac') => {
   const dim = SIZE * SS, img = Buffer.alloc(dim * dim * 3);
-  for (let i = 0; i < dim * dim; i++) { img[i * 3] = BG[0]; img[i * 3 + 1] = BG[1]; img[i * 3 + 2] = BG[2]; }
-  const rows = [[prefix.replace(/[^a-z0-9]/g, ''), 3], [name.slice(0, 3), 6]].filter(([t]) => t);
+  const band = accent(name);
+  for (let i = 0; i < dim * dim; i++) { const c = i >= dim * (SIZE - BAND) * SS ? band : BG; img[i * 3] = c[0]; img[i * 3 + 1] = c[1]; img[i * 3 + 2] = c[2]; }
+  const rows = [[prefix.replace(/[^a-z0-9]/g, ''), 3], [name.slice(0, 3).toUpperCase(), 6]].filter(([t]) => t);
   const gap = 12, total = rows.reduce((n, [, s]) => n + 7 * s, 0) + gap * (rows.length - 1);
-  let y = Math.round((SIZE - total) / 2);
+  let y = Math.round((SIZE - BAND - total) / 2) - 4; // centered above the band, then nudged up
   for (const [t, s] of rows) { draw(img, dim, t, s, y); y += 7 * s + gap; }
   const out = Buffer.alloc(SIZE * SIZE * 4); // downsample SS x SS blocks for smooth edges
   for (let py = 0; py < SIZE; py++) for (let px = 0; px < SIZE; px++) {

package/src/opencode.js

@@ -34,25 +34,50 @@ 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(container) {
+// Desktop has no API or deep link for adding a server, so edit its state DB (app must be closed). A backup is kept.
+const urlOf = x => (typeof x === 'string' ? x : x.http?.url ?? x.url);
+async function serverState(edit) {
   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');
+  if (edit && desktopRunning()) throw new Error('OpenCode Desktop is running. Close it first.');
   const { DatabaseSync } = await import('node:sqlite');
-  const d = new DatabaseSync(db), url = `http://127.0.0.1:${container.port}`, dir = `/workspaces/${container.name}`;
+  const d = new DatabaseSync(db, { readOnly: !edit });
   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: 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', ?, ?)
-    on conflict(name, key) do update set value = excluded.value, updated_at = excluded.updated_at`).run(JSON.stringify(s), Date.now());
+  if (edit) {
+    copyFileSync(db, db + '.agentcage-backup');
+    edit(s, d);
+    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();
+  return s;
 }
 
+export const connectDesktop = c => serverState(s => {
+  const url = `http://127.0.0.1:${c.port}`, dir = `/workspaces/${c.name}`;
+  s.list = s.list.filter(x => urlOf(x) !== url).concat({ type: 'http', http: { url, password: c.password }, displayName: serverName(c) });
+  s.projects[url] = [{ worktree: dir, expanded: true }];
+  s.lastProject[url] = dir;
+});
+
+// Servers on this machine (127.0.0.1:<port>) registered in Desktop: [{ url, port, name }]
+export const desktopServers = async () => (await serverState()).list.map(x => ({ url: urlOf(x), name: x.displayName ?? urlOf(x) }))
+  .map(x => ({ ...x, port: +x.url?.match(/^https?:\/\/(?:127\.0\.0\.1|localhost):(\d+)/)?.[1] })).filter(x => x.port);
+
+// Removes servers with everything Desktop keeps per server URL (UI history such as tabs is left to the app)
+export const removeDesktopServers = urls => serverState((s, d) => {
+  s.list = s.list.filter(x => !urls.includes(urlOf(x)));
+  for (const k of ['hidden', 'projects', 'lastProject', 'recentlyClosed']) for (const u of urls) delete s[k][u];
+  const del = d.prepare("delete from state where name='opencode.global.dat' and key=?");
+  for (const u of urls) del.run(u);
+  const row = d.prepare("select value from state where name='opencode.global.dat' and key='home.servers'").get(), h = row && JSON.parse(row.value);
+  if (h?.collapsed) {
+    for (const u of urls) delete h.collapsed[u];
+    d.prepare("update state set value=? where name='opencode.global.dat' and key='home.servers'").run(JSON.stringify(h));
+  }
+});
+
 // Names stored at creation; containers made before the settings existed use the current settings
 export const serverName = c => c.serverName ?? loadSettings().serverPrefix + c.name;
 

package/src/settings.js

@@ -6,10 +6,16 @@ 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 DEFAULTS = { color: 'green', containerPrefix: 'ac-', serverPrefix: 'ac-', projectPrefix: 'ac-', gitToken: 'never' };
 export const LABELS = {
   color: 'OpenCode project color', containerPrefix: 'Docker container prefix',
   serverPrefix: 'OpenCode server prefix', projectPrefix: 'OpenCode project prefix',
+  gitToken: 'Git token per project (GitHub, GitLab, Bitbucket)',
+};
+// Settings with fixed choices ({ value: label }); the others are free-text prefixes
+export const CHOICES = {
+  color: Object.fromEntries(COLORS.map(c => [c, c === 'gray' ? "gray (OpenCode's default)" : c])),
+  gitToken: { never: "don't use (push with the IDE's forwarded credentials)", ask: 'ask every time', always: 'always use' },
 };
 
 export const loadSettings = () => ({ ...DEFAULTS, ...(existsSync(FILE) && JSON.parse(readFileSync(FILE, 'utf8'))) });

package/src/wizard.js

@@ -3,11 +3,11 @@ 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, createContainer, nameTaken, openIde, ws } from './container.js';
+import { cleanName, createContainer, listContainers, nameTaken, openIde, publishedPorts, removeContainer, state, ws } from './container.js';
 import { isGitUrl, localRemote, parseRemote } from './git.js';
-import { connectDesktop, desktopRunning, detectDesktop, latestVersion, loginProvider, serverName, setupProject } from './opencode.js';
+import { connectDesktop, desktopRunning, desktopServers, detectDesktop, latestVersion, loginProvider, removeDesktopServers, serverName, setupProject } from './opencode.js';
 import { ok, runSync } from './run.js';
-import { COLORS, DEFAULTS, LABELS, loadSettings, saveSettings } from './settings.js';
+import { CHOICES, DEFAULTS, LABELS, loadSettings, saveSettings } from './settings.js';
 
 export const ask = async q => {
   const v = await q;
@@ -46,15 +46,39 @@ async function waitForDocker() {
 // 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 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}`);
-  }
+  if (!interactive && desktopRunning()) return p.log.warn(`OpenCode Desktop is open. Close it, then run: agentcage connect ${b.name}`);
+  if (!(await desktopClosed('Close OpenCode Desktop so the container can be added to it.'))) return p.log.info(`Later: agentcage connect ${b.name}`);
   await connectDesktop(b);
   p.log.success(`OpenCode Desktop: added server "${serverName(b)}" with project ${ws(b)}`);
 }
 
+// Desktop's state can only be written while the app is closed. Returns false if the user skips.
+async function desktopClosed(message) {
+  while (desktopRunning()) if (!(await ask(p.confirm({ message, active: 'It is closed now', inactive: 'Skip for now' })))) return false;
+  return true;
+}
+
+// Leftovers of containers that no longer exist in Docker: agentcage configs (with their volumes) and OpenCode Desktop servers.
+// Stopped containers still exist and are kept. Configs whose volumes still hold code are not preselected.
+export async function cleanupFlow() {
+  const ports = publishedPorts(), dead = listContainers().filter(b => state(b) === 'missing');
+  const servers = detectDesktop().hasDb ? (await desktopServers()).filter(x => !ports.has(x.port)) : [];
+  const hasCode = b => ok('docker', ['volume', 'inspect', b.volumes.src]);
+  const options = [
+    ...dead.map(b => ({ value: `c:${b.name}`, label: `agentcage config: ${b.name}`, hint: hasCode(b) ? 'also deletes its volumes and the code in them' : 'no volumes left' })),
+    ...servers.map(x => ({ value: `s:${x.url}`, label: `OpenCode Desktop server: ${x.name}`, hint: x.url })),
+  ];
+  if (!options.length) return p.log.success('Nothing to clean up: every agentcage config and OpenCode server has a Docker container.');
+  const picked = await ask(p.multiselect({ message: 'Remove leftovers of containers that no longer exist?', options, required: false,
+    initialValues: options.filter(o => !dead.some(b => o.value === `c:${b.name}` && hasCode(b))).map(o => o.value) }));
+  for (const b of dead.filter(b => picked.includes(`c:${b.name}`))) { await removeContainer(b); p.log.success(`Removed ${b.name}`); }
+  const urls = servers.filter(x => picked.includes(`s:${x.url}`)).map(x => x.url);
+  if (!urls.length) return;
+  if (!(await desktopClosed('Close OpenCode Desktop so its servers can be removed.'))) return p.log.info('OpenCode Desktop servers were not removed.');
+  await removeDesktopServers(urls);
+  p.log.success(`Removed ${urls.length} server${urls.length > 1 ? 's' : ''} from OpenCode Desktop`);
+}
+
 // 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 container?', options: PROVIDERS.map(x => ({ value: x.id, label: x.label, hint: x.hint })) }));
@@ -88,13 +112,17 @@ export async function newWizard(f = {}) {
   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 container push to ${remote.host}/${remote.path}?`, options: [
+    // The gitToken setting decides whether to ask (never / always skip the question); --git overrides it
+    const fixed = f.git ?? { never: 'forward', always: 'token' }[s.gitToken];
+    git = await pick(fixed, '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' },
     ] })));
     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 (fixed && !f.git) {
+      p.log.info(`Git push: your IDE's forwarded credentials, no repo token (change in: agentcage settings)`);
     } 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 });
@@ -152,10 +180,12 @@ export async function settingsWizard() {
   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' }] }));
+      ...Object.keys(DEFAULTS).map(k => ({ value: k, label: LABELS[k], hint: s[k] === '' ? 'none' : CHOICES[k]?.[s[k]] ?? s[k] })),
+      { value: '-cleanup', label: 'Clean up dead containers', hint: 'configs and OpenCode servers whose container is gone' }, { 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 })) })
+    if (key === '-cleanup') { await cleanupFlow(); continue; }
+    s[key] = await ask(CHOICES[key]
+      ? p.select({ message: LABELS[key], initialValue: s[key], options: Object.entries(CHOICES[key]).map(([value, label]) => ({ value, label })) })
       : 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);
   }

package/template/Dockerfile

@@ -12,3 +12,8 @@ RUN if [ -n "$OPENCODE_VERSION" ]; then npm install -g @opencode/cli@${OPENCODE_
 
 COPY post-create.sh /usr/local/bin/agentcage-post-create
 RUN chmod +x /usr/local/bin/agentcage-post-create
+
+# Main process: starts the OpenCode server on every container start (devcontainer.json sets overrideCommand: false)
+COPY start.sh /usr/local/bin/agentcage-start
+RUN chmod +x /usr/local/bin/agentcage-start
+CMD ["agentcage-start"]

package/template/start.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+# Container main process. Keeps the OpenCode server running as the node user, from every container start
+# (docker start, Docker Desktop restart, an IDE starting it), and restarts it if it exits.
+if [ -n "$OPENCODE_SERVER_PASSWORD" ]; then
+  cd "${AGENTCAGE_WORKSPACE:-/tmp}"
+  while :; do
+    # node opens the log: root may not write a node-owned file in /tmp (fs.protected_regular)
+    runuser -u node -- sh -c 'exec opencode serve --hostname 0.0.0.0 --port 4096 >> /tmp/opencode-serve.log 2>&1'
+    sleep 2
+  done &
+fi
+exec sleep infinity