agentcage 0.1.7 → 0.1.9

package/README.md

@@ -23,11 +23,6 @@ You need **Docker** (Docker Desktop on Windows/macOS, Docker Engine on Linux), *
 npm install -g agentcage           # also updates to the latest version
 ```
 
-```bash
-agentcage doctor        # checks all the prerequisites.
-```
-
-
 
 ## Quickstart
 
@@ -41,10 +36,36 @@ Run this in terminal:
 
 ```bash
 agentcage doctor        # checks all the prerequisites.
-agentcage               # Starts the container-creation dialogue
+agentcage               # Starts the CLI: UI or container-creation dialogue
+```
+
+
+## The agentcage window (UI)
+Agentcage UI gives you a graphical way to see and manage your devcontainers
+
+```bash
+agentcage ui            # opens the agentcage window
 ```
 
-Follow the steps
+Running `agentcage` without a command also offers it as the first choice in the menu.
+
+A local web UI with the same features as the terminal dialog:
+- **Containers:** each container's status, and Start, Stop, Open in IDE, Add to OpenCode, OpenCode providers (gear button: add model provider API keys), Rebuild and Remove.
+- **New container:** a dialog to create one from a folder, a git URL, or a repository picked from **GitHub** or **Azure Repos**.
+- **Connections:** reuses a logged-in `gh` / `az` CLI. Otherwise you paste a personal access token, which is stored in
+  `~/.agentcage/connections.json`. These tokens are only used on your computer to list and clone repositories. They never go
+  into a container.
+- **Settings** and **Help**.
+
+The window opens as an app window (Edge or Chrome `--app`), or as a normal browser tab if neither is installed.
+
+**Desktop icon:** the first `agentcage ui` offers to add an agentcage icon to the desktop and Start Menu (Windows) or app
+menu (Linux). Clicking it starts the UI without a console window. The window also offers it when it opens (until you add
+it or pick "Don't show this again"), and you can always add it under **Settings → Desktop icon** or with
+`agentcage ui --shortcut`; `--no-shortcut` removes it.
+
+**How it runs:** the UI is served by a small server on `127.0.0.1` only, protected by a random session token. It stops a
+few seconds after you close the window, unless a container is still being created. `--no-open` only prints the URL.
 
 ## Creating a container
 
@@ -77,6 +98,7 @@ AGENTCAGE_GIT_TOKEN=github_pat_... agentcage new https://github.com/me/repo.git
 
 ```bash
 agentcage                       # menu: create a container, or start/open/shell/upgrade/remove an existing one
+agentcage ui                    # the agentcage window: containers, create dialog, GitHub / Azure Repos, help
 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 container (opencode, claude, git ... work here)

package/bin/agentcage.js

@@ -2,16 +2,19 @@
 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 { adoptContainer, listContainers, loadContainer, removeContainer, state, up, upgradeContainer, openIde, ws } from '../src/container.js';
 import { ask, connectionInfo, newWizard, providerFlow, registerFlow, settingsWizard } from '../src/wizard.js';
 import { detectDesktop, latestVersion, setupProject } from '../src/opencode.js';
 import { ok, run } from '../src/run.js';
+import { loadSettings, saveSettings } from '../src/settings.js';
 
 process.removeAllListeners('warning'); // hide node:sqlite ExperimentalWarning
 
 const HELP = `agentcage: isolated dev containers for AI coding agents
 
-  agentcage                         interactive menu (create or manage containers)
+  agentcage                         menu: open the agentcage window, or create / manage containers in the terminal
+  agentcage ui                      open the agentcage window (containers, create dialog, GitHub / Azure Repos, help)
+                                      [--shortcut] add a desktop / menu icon  [--no-shortcut] remove it  [--no-open] only print the URL
   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                    containers, state, port, OpenCode version
@@ -34,7 +37,8 @@ const HELP = `agentcage: isolated dev containers for AI coding agents
 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' }, version: { type: 'boolean', short: 'v' } },
+    ide: { type: 'string' }, yes: { type: 'boolean', short: 'y' }, help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' },
+    shortcut: { type: 'boolean' }, 'no-shortcut': { type: 'boolean' }, detach: { type: 'boolean' }, 'no-open': { type: 'boolean' } },
 });
 const csv = s => s?.split(',').map(x => x.trim()).filter(Boolean);
 const container = () => loadContainer(arg ?? (() => { throw new Error(`Usage: agentcage ${cmd} <name>`); })());
@@ -51,6 +55,21 @@ async function start(b) {
 }
 
 const commands = {
+  // The UI. The desktop shortcut runs it with --detach: the server continues in the background without a console window.
+  async ui() {
+    const sc = await import('../src/shortcut.js');
+    if (f.shortcut || f['no-shortcut']) {
+      const files = f.shortcut ? sc.createShortcuts() : sc.removeShortcuts();
+      return console.log(files.length ? `${f.shortcut ? 'Created' : 'Removed'}:\n  ${files.join('\n  ')}` : 'No shortcuts found.');
+    }
+    if (f.detach) return sc.detach(!f['no-open']);
+    if (process.stdout.isTTY && !loadSettings().uiShortcutAsked && process.platform !== 'darwin') {
+      const add = await ask(p.confirm({ message: `Add an agentcage icon to ${sc.SHORTCUT_PLACES}?` }));
+      saveSettings({ ...loadSettings(), uiShortcutAsked: true });
+      if (add) p.log.success(`Added: ${sc.createShortcuts().join(', ')}`);
+    }
+    await (await import('../src/server.js')).serve({ open: !f['no-open'] });
+  },
   settings: settingsWizard,
   async version() {
     const v = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
@@ -82,9 +101,7 @@ const commands = {
   async upgrade() {
     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; });
-    saveContainer(b);
+    await upgradeContainer(b, v).then(() => s.stop(`Rebuilt with OpenCode ${v}`), e => { s.error('Rebuild failed'); throw e; });
     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() {
@@ -106,14 +123,16 @@ const commands = {
   },
   adopt() { const b = adoptContainer(arg); console.log(`Adopted '${b.name}' (${b.container}).`); },
 
-  // No command: menu
+  // No command: menu. The window (UI) comes first; the rest is the terminal flow.
   async menu() {
     const containers = listContainers();
-    if (!containers.length) return newWizard();
     p.intro('agentcage');
-    // '-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' },
+    // '-ui' and '-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: '-ui', label: 'Open the agentcage window', hint: 'containers, create dialog, GitHub / Azure Repos' },
+      { value: '', label: 'Create a new container (here in the terminal)' },
       ...containers.map(b => ({ value: b.name, label: b.name, hint: state(b) })), { value: '-settings', label: 'Settings' }] }));
+    if (pick === '-ui') return commands.ui();
     if (pick === '-settings') return settingsWizard();
     if (!pick) return newWizard();
     const action = await ask(p.select({ message: pick, options: [

package/package.json

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

package/src/catalog.js

@@ -24,5 +24,7 @@ const HOSTS = {
   'github.com': { user: 'x-access-token', help: p => `Create a fine-grained token: https://github.com/settings/personal-access-tokens/new\n  Repository access: Only select repositories → ${p}\n  Permissions: Contents → Read and write (add Pull requests if agents should open PRs)` },
   'gitlab.com': { user: 'oauth2', help: p => `Create a project access token: https://gitlab.com/${p}/-/settings/access_tokens\n  Role: Developer. Scopes: read_repository, write_repository` },
   'bitbucket.org': { user: 'x-token-auth', help: p => `Create a repository access token: https://bitbucket.org/${p}/admin/access-tokens\n  Permissions: Repositories → Write` },
+  // Azure accepts any username with a PAT. A PAT can't be limited to one repo: it reaches every repo in the organization.
+  'dev.azure.com': { user: 'pat', help: p => `Create a personal access token: https://dev.azure.com/${p.split('/')[0]}/_usersSettings/tokens\n  Organization: ${p.split('/')[0]}. Scopes: Code → Read & write\n  Note: Azure DevOps tokens cover every repo in the organization you can access, not only this one.` },
 };
 export const hostInfo = host => HOSTS[host] ?? { user: 'git', help: p => `Create an access token on ${host} with read/write access to ${p} only.` };

package/src/connections.js

@@ -0,0 +1,100 @@
+// GitHub and Azure DevOps connections for `agentcage ui`: list repos to create containers from, and clone them.
+// Tokens come from a logged-in `gh` / `az` CLI first, else from a PAT saved in ~/.agentcage/connections.json.
+// They are only used on this machine to list and clone; they never go into a container or to the browser.
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { parseRemote } from './git.js';
+import { runSync } from './run.js';
+
+const FILE = join(homedir(), '.agentcage', 'connections.json');
+const AZ_RESOURCE = '499b84ac-1321-427f-aa17-267ca6975798'; // Azure DevOps
+export const HOSTS = { github: 'github.com', azure: 'dev.azure.com' };
+
+const load = () => (existsSync(FILE) ? JSON.parse(readFileSync(FILE, 'utf8')) : {});
+function save(all) {
+  mkdirSync(join(FILE, '..'), { recursive: true });
+  writeFileSync(FILE, JSON.stringify(all, null, 2), { mode: 0o600 });
+  chmodSync(FILE, 0o600); // mode only applies to new files. On Windows the user profile's ACL protects it.
+}
+
+// az is az.cmd on Windows, which Node only runs through a shell; the command line is constant
+const azToken = () => spawnSync(`az account get-access-token --resource ${AZ_RESOURCE} --query accessToken -o tsv`,
+  { shell: true, encoding: 'utf8', windowsHide: true }).stdout?.trim() || null;
+
+// { token, source: 'gh'|'az'|'pat', bearer } or null
+export function token(id) {
+  const cli = id === 'github' ? runSync('gh', ['auth', 'token']) : azToken();
+  if (cli) return { token: cli, source: id === 'github' ? 'gh' : 'az', bearer: true };
+  const pat = load()[id]?.token;
+  return pat ? { token: pat, source: 'pat', bearer: id === 'github' } : null;
+}
+
+const auth = t => (t.bearer ? `Bearer ${t.token}` : `Basic ${Buffer.from(`:${t.token}`).toString('base64')}`);
+async function get(url, t) {
+  const r = await fetch(url, { headers: { authorization: auth(t), accept: 'application/json', 'user-agent': 'agentcage' } });
+  // Azure DevOps answers a bad token with an HTML sign-in page (203), not an error status
+  if (r.status === 401 || r.status === 203 || (r.ok && !r.headers.get('content-type')?.includes('json')))
+    throw new Error(`${new URL(url).host} did not accept the token. Check that it is valid, not expired, and has the needed scopes.`);
+  if (!r.ok) throw new Error(`${new URL(url).host}: HTTP ${r.status}`);
+  return { body: await r.json(), link: r.headers.get('link') };
+}
+
+// Azure DevOps organizations the token can see. Needs a token for "all accessible organizations";
+// orgs the user typed in are always included.
+async function azureOrgs(t) {
+  const saved = load().azure?.orgs ?? [];
+  try {
+    const { body: me } = await get('https://app.vssps.visualstudio.com/_apis/profile/profiles/me?api-version=7.1', t);
+    const { body } = await get(`https://app.vssps.visualstudio.com/_apis/accounts?memberId=${me.id}&api-version=7.1`, t);
+    return { user: me.emailAddress ?? me.displayName, orgs: [...new Set([...body.value.map(a => a.accountName), ...saved])] };
+  } catch { return { user: null, orgs: saved }; }
+}
+
+// Connection status for the UI, without tokens: { github: { source, user } | null, azure: { source, user, orgs } | null }
+export async function status() {
+  const gh = token('github'), az = token('azure');
+  return {
+    github: gh && { source: gh.source, user: (await get('https://api.github.com/user', gh).catch(() => null))?.body.login ?? null },
+    azure: az && { source: az.source, ...(await azureOrgs(az)) },
+  };
+}
+
+// Checks a pasted PAT before saving it. Azure: org is needed when the PAT is limited to one organization.
+export async function savePat(id, pat, org) {
+  const t = { token: pat, bearer: id === 'github' };
+  if (id === 'github') await get('https://api.github.com/user', t);
+  else await get(org ? `https://dev.azure.com/${encodeURIComponent(org)}/_apis/projects?api-version=7.1&$top=1`
+    : 'https://app.vssps.visualstudio.com/_apis/profile/profiles/me?api-version=7.1', t);
+  const all = load();
+  all[id] = { token: pat, ...(org && { orgs: [org] }) };
+  save(all);
+}
+export function removePat(id) { const all = load(); delete all[id]; save(all); }
+
+// [{ name, url, private }] with HTTPS clone URLs
+export async function repos(id, org) {
+  const t = token(id);
+  if (!t) throw new Error(`Not connected to ${id === 'github' ? 'GitHub' : 'Azure DevOps'}`);
+  if (id === 'azure') {
+    if (!org) throw new Error('Pick an Azure DevOps organization');
+    const { body } = await get(`https://dev.azure.com/${encodeURIComponent(org)}/_apis/git/repositories?api-version=7.1`, t);
+    return body.value.map(r => ({ name: `${r.project.name}/${r.name}`, url: r.remoteUrl.replace(/\/\/[^@/]+@/, '//'), private: r.project.visibility !== 'public' }))
+      .sort((a, b) => a.name.localeCompare(b.name));
+  }
+  const list = [];
+  let url = 'https://api.github.com/user/repos?per_page=100&sort=pushed&affiliation=owner,collaborator,organization_member';
+  for (let i = 0; url && i < 10; i++) {
+    const { body, link } = await get(url, t);
+    list.push(...body.map(r => ({ name: r.full_name, url: r.clone_url, private: r.private })));
+    url = link?.match(/<([^>]+)>;\s*rel="next"/)?.[1];
+  }
+  return list;
+}
+
+// Token to clone a URL with, if it is on a connected host: { token, header } (header: send as Bearer, for az tokens)
+export function cloneToken(url) {
+  const id = Object.keys(HOSTS).find(k => HOSTS[k] === parseRemote(url)?.host), t = id && token(id);
+  return t ? { token: t.token, header: t.source === 'az' } : null;
+}

package/src/container.js

@@ -37,6 +37,9 @@ export function nameTaken(n) {
   const px = loadSettings().containerPrefix;
   return hasContainer(n) || ok('docker', ['inspect', px + n]) || ok('docker', ['volume', 'inspect', `${px}${n}-src`]);
 }
+// Why a container name can't be used, or undefined if it can
+export const nameError = v => (!/^[a-z0-9][a-z0-9-]*$/.test(v ?? '') ? 'Use lowercase letters, digits and -'
+  : nameTaken(v) ? `A container named '${v}' already exists` : undefined);
 
 const bindable = port => new Promise(r => {
   const s = createServer().once('error', () => r(false)).listen(port, '127.0.0.1', () => s.close(() => r(true)));
@@ -82,11 +85,20 @@ export async function up(b, rebuild) {
 }
 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.
+// Rebuild with another OpenCode version (and the current template); volumes are kept
+export async function upgradeContainer(b, version) {
+  b.opencodeVersion = version;
+  writeDevcontainer(b);
+  await up(b, true);
+  saveContainer(b);
+}
+
+// o: { src, name, tools, git: 'token'|'forward'|'none', token, remote, opencodeVersion, cloneToken, cloneBearer }.
+// 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), s = loadSettings(), px = s.containerPrefix;
   const b = {
-    name, dir: join(ROOT, name), container: px + name, serverName: s.serverPrefix + name, projectName: s.projectPrefix + name, color: s.color,
+    name, dir: join(ROOT, name), container: px + name, serverName: s.serverPrefix + name, projectName: s.projectPrefix + name, color: s.color, projectIcon: s.projectIcon,
     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(),
@@ -94,7 +106,8 @@ export async function createContainer(o, step = (_, f) => f()) {
   saveContainer(b);
   writeDevcontainer(b);
   await run('docker', ['volume', 'create', b.volumes.src]);
-  await step('Copying the source into the container', () => seed(b.volumes.src, { ...o, src }));
+  // Clone with the repo token, else with a connection token (o.cloneToken, from agentcage ui); none is kept in the container
+  await step('Copying the source into the container', () => seed(b.volumes.src, { src, token: o.token ?? o.cloneToken, bearer: !o.token && o.cloneBearer }));
   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);
@@ -134,6 +147,14 @@ export function pinIdeFolder(b) {
   }
 }
 
+// IDEs that can attach to a container, found on PATH or in their usual install folder: [{ value: command, label }]
+export function findIdes() {
+  const found = cmd => !!runSync(process.platform === 'win32' ? 'where' : 'which', [cmd]);
+  const ag = process.platform === 'win32' ? join(process.env.LOCALAPPDATA ?? '', 'Programs', 'Antigravity IDE', 'bin', 'antigravity-ide.cmd') : 'antigravity-ide';
+  return [['cursor', 'Cursor'], ['code', 'VS Code'], [ag, 'Antigravity']].filter(([c]) => existsSync(c) || found(c))
+    .map(([value, label]) => ({ value, label }));
+}
+
 // Opens a VS Code-based IDE attached to the running container
 export function openIde(b, ide) {
   pinIdeFolder(b);

package/src/git.js

@@ -6,9 +6,10 @@ import { run, runSync } from './run.js';
 import { hostInfo } from './catalog.js';
 
 // https://host/owner/repo(.git), git@host:owner/repo(.git), ssh://git@host/owner/repo → { host, path, https }
+// Azure DevOps URLs (https://[org@]dev.azure.com/org/project/_git/repo) have no .git suffix
 export function parseRemote(url) {
   const m = url?.match(/^(?:(?:https?|ssh|git):\/\/(?:[^@/]+@)?|[^@\s/]+@)([^/:]+)[:/](.+?)(?:\.git)?\/?$/);
-  return m && { host: m[1], path: m[2], https: `https://${m[1]}/${m[2]}.git` };
+  return m && { host: m[1], path: m[2], https: `https://${m[1]}/${m[2]}${m[1] === 'dev.azure.com' ? '' : '.git'}` };
 }
 export const isGitUrl = s => /^(https?|ssh|git):\/\/|^[^@\s/]+@[^:]+:/.test(s);
 export const localRemote = dir => runSync('git', ['-C', dir, 'remote', 'get-url', 'origin']) || null;
@@ -17,12 +18,16 @@ export const localRemote = dir => runSync('git', ['-C', dir, 'remote', 'get-url'
 const TAR = 'cd /src && tar -cf - --exclude=node_modules --exclude=.venv --exclude=.next . | tar -xf - -C /dst';
 const seedFolder = (vol, dir) => run('docker', ['run', '--rm', '-v', `${vol}:/dst`, '-v', `${dir}:/src:ro`, 'alpine', 'sh', '-c', TAR]);
 
-export async function seed(vol, { src, git, token }) {
+// token: clone with it (a repo token, or a GitHub / Azure connection token). bearer: send it as a Bearer header
+// (Microsoft Entra tokens from `az`) instead of as a password.
+export async function seed(vol, { src, token, bearer }) {
   if (!isGitUrl(src)) await seedFolder(vol, src);
-  else if (git === 'token') {
+  else if (token) {
     // Clone in a throwaway container; the token travels as an env var, never in the URL or on disk
     const helper = '!f() { echo username=$GIT_USER; echo password=$GIT_TOKEN; }; f';
-    await run('docker', ['run', '--rm', '-e', 'GIT_USER', '-e', 'GIT_TOKEN', '-v', `${vol}:/dst`, 'alpine/git', '-c', `credential.helper=${helper}`, 'clone', src, '/dst'],
+    const clone = bearer ? ['--entrypoint', 'sh', 'alpine/git', '-c', 'git -c "http.extraHeader=Authorization: Bearer $GIT_TOKEN" clone "$0" /dst', src]
+      : ['alpine/git', '-c', `credential.helper=${helper}`, 'clone', src, '/dst'];
+    await run('docker', ['run', '--rm', '-e', 'GIT_USER', '-e', 'GIT_TOKEN', '-v', `${vol}:/dst`, ...clone],
       { env: { GIT_USER: hostInfo(parseRemote(src).host).user, GIT_TOKEN: token } });
   } else {
     // Clone on the host with the user's own git credentials (private repos work), then copy in
@@ -45,11 +50,12 @@ export async function copyIdentity(container) {
 
 // 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).
+// $2 is host/path exactly as cloned (with .git, or without for Azure): useHttpPath matches the credential on it.
 const TOKEN_SETUP = `IFS= read -r T; umask 077
-printf 'https://%s:%s@%s/%s.git\\n' "$1" "$T" "$2" "$3" > ~/.git-credentials
-git remote set-url origin "https://$2/$3.git"
+printf 'https://%s:%s@%s\\n' "$1" "$T" "$2" > ~/.git-credentials
+git remote set-url origin "https://$2"
 git config --local --unset-all credential.helper
 git config --local --add credential.helper '' && git config --local --add credential.helper store && git config --local credential.useHttpPath true`;
 
 export const setupToken = (container, dir, remote, token) =>
-  run('docker', ['exec', '-i', '-u', 'node', '-w', dir, container, 'sh', '-c', TOKEN_SETUP, '_', hostInfo(remote.host).user, remote.host, remote.path], { input: token + '\n' });
+  run('docker', ['exec', '-i', '-u', 'node', '-w', dir, container, 'sh', '-c', TOKEN_SETUP, '_', hostInfo(remote.host).user, remote.https.slice(8)], { input: token + '\n' });

package/src/icon.js

@@ -2,6 +2,7 @@
 // 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 { readFileSync } from 'node:fs';
 import { deflateSync } from 'node:zlib';
 
 const SIZE = 128, SS = 4, BG = [20, 83, 45], FG = [255, 255, 255]; // SS: supersampling for smooth edges
@@ -110,11 +111,26 @@ 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') => {
+export const projectIcon = (name, prefix = 'ac') =>
+  `data:image/png;base64,${png(render([[prefix.replace(/[^a-z0-9]/g, ''), 3], [name.slice(0, 3).toUpperCase(), 6]], name)).toString('base64')}`;
+
+// The agentcage app icon (UI, shortcuts): src/logo.svg, with logo.png rendered from it at 256 px
+export const appIcon = () => readFileSync(new URL('./logo.png', import.meta.url));
+
+// The app icon as .ico for Windows shortcuts: one 256 px PNG entry (size bytes 0 mean 256)
+export function appIco() {
+  const p = appIcon(), head = Buffer.alloc(22);
+  head.writeUInt16LE(1, 2); head.writeUInt16LE(1, 4); // ICONDIR: icon type, one image
+  head.writeUInt16LE(1, 10); head.writeUInt16LE(32, 12); head.writeUInt32LE(p.length, 14); head.writeUInt32LE(22, 18);
+  return Buffer.concat([head, p]);
+}
+
+// rows: [[text, scale]] stacked and centered above the accent band; seed picks the band's hue. Returns RGBA pixels.
+function render(rows, seed) {
   const dim = SIZE * SS, img = Buffer.alloc(dim * dim * 3);
-  const band = accent(name);
+  const band = accent(seed);
   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);
+  rows = rows.filter(([t]) => t);
   const gap = 12, total = rows.reduce((n, [, s]) => n + 7 * s, 0) + gap * (rows.length - 1);
   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; }
@@ -128,5 +144,5 @@ export const projectIcon = (name, prefix = 'ac') => {
     const o = (py * SIZE + px) * 4, n = SS * SS;
     out[o] = Math.round(r / n); out[o + 1] = Math.round(g / n); out[o + 2] = Math.round(b / n); out[o + 3] = 255;
   }
-  return `data:image/png;base64,${png(out).toString('base64')}`;
-};
+  return out;
+}

package/src/logo.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#1f7a44"/><stop offset="1" stop-color="#14532d"/></linearGradient>
+  </defs>
+  <rect width="256" height="256" rx="56" fill="url(#bg)"/>
+  <g stroke-linecap="round" stroke-linejoin="round" fill="none">
+    <!-- side faces, lightly shaded -->
+    <path d="M56 92 L128 134 L128 216 L56 174 Z" fill="#fff" fill-opacity=".08" stroke="none"/>
+    <path d="M128 134 L200 92 L200 174 L128 216 Z" fill="#fff" fill-opacity=".16" stroke="none"/>
+    <!-- lid -->
+    <path d="M128 50 L200 92 L128 134 L56 92 Z" fill="#bbf7d0" stroke="#fff" stroke-width="10"/>
+    <!-- bars -->
+    <path d="M80 106 V188 M104 120 V202 M152 120 V202 M176 106 V188" stroke="#fff" stroke-width="8"/>
+    <!-- outline -->
+    <path d="M56 92 V174 L128 216 L200 174 V92 M128 134 V216" stroke="#fff" stroke-width="10"/>
+  </g>
+</svg>

package/src/opencode.js

@@ -31,6 +31,10 @@ export function detectDesktop() {
 export const desktopRunning = () => P === 'win32'
   ? /^OpenCode\.exe/im.test(runSync('tasklist', ['/FI', 'IMAGENAME eq OpenCode.exe', '/NH']))
   : ok('pgrep', ['-x', 'OpenCode']);
+// Same check without blocking (agentcage ui polls it)
+export const desktopRunningAsync = () => (P === 'win32'
+  ? run('tasklist', ['/FI', 'IMAGENAME eq OpenCode.exe', '/NH']).then(o => /^OpenCode\.exe/im.test(o))
+  : run('pgrep', ['-x', 'OpenCode']).then(() => true)).catch(() => false);
 
 export const latestVersion = async () => (await (await fetch('https://registry.npmjs.org/@opencode/cli/latest')).json()).version;
 
@@ -81,18 +85,27 @@ export const removeDesktopServers = urls => serverState((s, d) => {
 // 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 its generated icon in the container's OpenCode server. Asking about the folder creates the project first.
+// JSON calls to the container's OpenCode server API (over the published loopback port, with its password)
+const serverApi = c => (path, init) => fetch(`http://127.0.0.1:${c.port}/api${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}`))));
+
+// Stores a model provider API key in the container's OpenCode (its home volume), without a terminal
+export const setProviderKey = (c, id, key) =>
+  serverApi(c)('/credential', { method: 'POST', body: JSON.stringify({ integrationID: id, label: 'agentcage', value: { type: 'key', key } }) });
+
+// Sets the project's name and icon (generated image or plain 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}`))));
+  const api = serverApi(c), dir = `/workspaces/${c.name}`;
   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, override: projectIcon(c.name, s.projectPrefix) } }) });
+      // An empty override clears an earlier generated image, so the plain color shows
+      const override = (c.projectIcon ?? s.projectIcon) === 'color' ? '' : projectIcon(c.name, s.projectPrefix);
+      return await api(`/project/${id}`, { method: 'PATCH', body: JSON.stringify({ name, icon: { color, override } }) });
     } catch (e) { if (i >= 15) throw e; await new Promise(r => setTimeout(r, 2000)); }
   }
 }

package/src/run.js

@@ -1,4 +1,5 @@
 // Process helpers. Arguments are always passed as arrays (no shell), so paths never get mangled.
+// windowsHide: on Windows, no console window flashes up for each command when agentcage ui runs without a terminal.
 import { spawn, spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
@@ -8,15 +9,15 @@ const fail = (cmd, args, code, err) =>
 
 // Quick commands: returns trimmed stdout ('' if the command is missing and check is off)
 export function runSync(cmd, args = [], { check = false, input } = {}) {
-  const r = spawnSync(cmd, args, { encoding: 'utf8', input });
+  const r = spawnSync(cmd, args, { encoding: 'utf8', input, windowsHide: true });
   if (check && r.status !== 0) throw fail(cmd, args, r.status, r.stderr || r.error?.message);
   return (r.stdout || '').trim();
 }
-export const ok = (cmd, args) => spawnSync(cmd, args, { stdio: 'ignore' }).status === 0;
+export const ok = (cmd, args) => spawnSync(cmd, args, { stdio: 'ignore', windowsHide: true }).status === 0;
 
 // Long-running commands (keeps spinners animating). input: string sent on stdin; tty: hand over the terminal
 export const run = (cmd, args = [], { input, env, tty } = {}) => new Promise((resolve, reject) => {
-  const p = spawn(cmd, args, { env: { ...process.env, ...env }, stdio: tty ? 'inherit' : 'pipe' });
+  const p = spawn(cmd, args, { env: { ...process.env, ...env }, stdio: tty ? 'inherit' : 'pipe', windowsHide: true });
   let out = '', err = '';
   p.stdout?.on('data', d => (out += d));
   p.stderr?.on('data', d => (err += d));
@@ -29,9 +30,11 @@ export const run = (cmd, args = [], { input, env, tty } = {}) => new Promise((re
 const DC = join(dirname(createRequire(import.meta.url).resolve('@devcontainers/cli/package.json')), 'devcontainer.js');
 export const devcontainer = args => run(process.execPath, [DC, ...args]);
 
-// IDE launchers (cursor, code) are .cmd shims on Windows and need a shell there
+// IDE launchers (cursor, code) are .cmd shims on Windows and need a shell there; its console window is hidden.
+// Programs given by .exe path (the browser) start directly, since hiding would hide their window too.
 export function launch(cmd, args) {
-  const win = process.platform === 'win32';
+  const shell = process.platform === 'win32' && !/\.exe$/i.test(cmd);
   const line = [cmd, ...args].map(a => (/[\s&|<>^]/.test(a) ? `"${a}"` : a)).join(' ');
-  return spawn(win ? line : cmd, win ? [] : args, { shell: win, stdio: 'ignore', detached: true }).unref();
+  const c = spawn(shell ? line : cmd, shell ? [] : args, { shell, stdio: 'ignore', detached: true, windowsHide: shell });
+  c.on('error', () => {}).unref(); // a missing program must not crash a long-running process (agentcage ui)
 }