agentcage 0.1.5 → 0.1.6

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/
 ```
@@ -107,6 +107,10 @@ created afterwards.
 | 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>`) |
 
+**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:
@@ -131,6 +135,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentcage",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "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/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/wizard.js

@@ -3,9 +3,9 @@ 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';
 
@@ -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 })) }));
@@ -152,8 +176,10 @@ 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' : s[k] })),
+      { value: '-cleanup', label: 'Clean up dead containers', hint: 'configs and OpenCode servers whose container is gone' }, { value: '', label: 'Done' }] }));
     if (!key) break;
+    if (key === '-cleanup') { await cleanupFlow(); continue; }
     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 -') }));

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