openpalm 0.9.4 → 0.9.5

package/README.md

@@ -1,26 +1,53 @@
 # @openpalm/cli
 
-Bun CLI for bootstrapping and managing an OpenPalm installation. Handles the initial install (directory creation, asset download, secret seeding) and delegates to the Admin API once the stack is running.
+Bun CLI for bootstrapping and managing an OpenPalm installation. The CLI is the primary orchestrator -- all commands work without the admin container. When admin is running, commands optionally delegate to the admin API.
+
+## Self-Sufficient Mode
+
+The CLI operates directly against Docker Compose without requiring an admin container:
+
+- **Install** -- creates XDG dirs, downloads assets, serves the setup wizard locally via `Bun.serve()`, stages artifacts, starts core services
+- **All lifecycle commands** -- stage artifacts from `@openpalm/lib` using `FilesystemAssetProvider`, then run Docker Compose directly
+- **Admin delegation** -- the `install` command checks for a running admin and delegates if reachable. Other commands operate directly via Docker Compose.
+
+The admin container is optional. Use `--with-admin` to include the admin UI profile.
 
 ## Commands
 
 | Command | Description |
 |---|---|
-| `openpalm install` | Bootstrap XDG dirs, download assets, start admin + docker-socket-proxy, open setup wizard |
+| `openpalm install` | Bootstrap XDG dirs, download assets, run setup wizard, start core services |
 | `openpalm uninstall` | Stop and remove the stack (preserves config and data) |
 | `openpalm update` | Pull latest images and recreate containers |
 | `openpalm start [svc...]` | Start all or named services |
+| `openpalm start --with-admin` | Start all services including admin UI and docker-socket-proxy |
 | `openpalm stop [svc...]` | Stop all or named services |
 | `openpalm restart [svc...]` | Restart all or named services |
 | `openpalm logs [svc...]` | Tail last 100 log lines |
 | `openpalm status` | Show container status |
-| `openpalm service <sub> [svc...]` | Alias — subcommands: `start`, `stop`, `restart`, `logs`, `status`, `update` |
+| `openpalm service <sub> [svc...]` | Alias -- subcommands: `start`, `stop`, `restart`, `logs`, `status`, `update` |
+| `openpalm validate` | Validate `secrets.env` against the schema (requires prior install) |
+| `openpalm scan` | Scan for leaked secrets in config files |
 
 ### Install options
 
-`--force` skip "already installed" check, `--version TAG` install a specific ref (default `main`), `--no-start` prepare files only, `--no-open` skip browser launch.
+`--force` skip "already installed" check, `--version TAG` install a specific ref (default: current CLI version), `--no-start` prepare files only, `--no-open` skip browser launch.
+
+### Admin profile
+
+Admin and docker-socket-proxy use Docker Compose profiles. They start only when explicitly requested:
+
+```bash
+openpalm start --with-admin     # Start core + admin profile
+openpalm start admin            # Start admin service specifically
+openpalm stop admin             # Stop admin service specifically
+```
+
+## Setup Wizard
+
+On first install, the CLI serves a setup wizard on port 8100 via `Bun.serve()`. The wizard runs entirely in the browser (vanilla HTML/JS) and calls `performSetup()` from `@openpalm/lib` to write secrets, connection profiles, memory config, and stage artifacts. No admin container is involved.
 
-## Environment variables
+## Environment Variables
 
 | Variable | Default | Purpose |
 |---|---|---|
@@ -28,20 +55,21 @@ Bun CLI for bootstrapping and managing an OpenPalm installation. Handles the ini
 | `OPENPALM_DATA_HOME` | `~/.local/share/openpalm` | Persistent service data |
 | `OPENPALM_STATE_HOME` | `~/.local/state/openpalm` | Assembled runtime |
 | `OPENPALM_WORK_DIR` | `~/openpalm` | Assistant working directory |
-| `OPENPALM_ADMIN_API_URL` | `http://localhost:8100` | Admin API endpoint |
+| `OPENPALM_ADMIN_API_URL` | `http://localhost:8100` | Admin API endpoint (for optional delegation) |
 | `OPENPALM_ADMIN_TOKEN` | (from `secrets.env`) | Admin API auth token |
 
-## How it works
+## How It Works
 
-1. **Bootstrap** (no stack running) — creates XDG directory tree, downloads `docker-compose.yml` + `Caddyfile` from GitHub, seeds `secrets.env` and `stack.env`, starts core services via `docker compose`
-2. **Running stack** — all commands delegate to the Admin API (`/admin/install`, `/admin/containers/*`, etc.) using `x-admin-token` auth
+1. **Bootstrap** (first install) -- creates XDG directory tree, downloads core assets from GitHub, seeds `secrets.env` and `stack.env`, serves setup wizard, stages artifacts via `@openpalm/lib`, starts core services via `docker compose up`
+2. **Running stack** -- commands stage artifacts locally using `FilesystemAssetProvider`, then execute Docker Compose directly.
+3. **Admin absent** -- all commands work identically. Admin is never required for any operation.
 
-Follows the file-assembly principle: copies whole files, never renders templates. See [`docs/core-principles.md`](../../docs/technical/core-principles.md).
+Follows the file-assembly principle: copies whole files, never renders templates. See [`core-principles.md`](../../docs/technical/core-principles.md).
 
 ## Building
 
 ```bash
-bun run build                  # Current platform → dist/openpalm-cli
+bun run build                  # Current platform -> dist/openpalm-cli
 bun run build:linux-x64        # Cross-compile (also: linux-arm64, darwin-x64, darwin-arm64, windows-x64, windows-arm64)
 ```
 
@@ -53,4 +81,4 @@ bun run start -- install --no-start
 bun test
 ```
 
-See also: [`scripts/install.sh`](../../scripts/install.sh) (binary installer), [`scripts/setup.sh`](../../scripts/setup.sh) (shell-based installer).
+See also: [`scripts/setup.sh`](../../scripts/setup.sh) (shell-based installer).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openpalm",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "type": "module",
   "license": "MPL-2.0",
   "description": "OpenPalm CLI — install and manage a self-hosted OpenPalm stack",
@@ -24,6 +24,7 @@
     "build:windows-arm64": "bun build src/main.ts --compile --target=bun-windows-arm64 --outfile dist/openpalm-cli-windows-arm64.exe"
   },
   "dependencies": {
+    "@openpalm/lib": "workspace:*",
     "citty": "^0.2.1"
   }
 }

package/src/commands/install.ts

@@ -4,18 +4,22 @@ import { rm } from 'node:fs/promises';
 import cliPkg from '../../package.json' with { type: 'json' };
 import { defaultConfigHome, defaultDataHome, defaultStateHome, defaultWorkDir } from '../lib/paths.ts';
 import { ensureSecrets, ensureStackEnv } from '../lib/env.ts';
-import { ADMIN_URL, isStackRunning, adminRequest, waitForAdminHealthy } from '../lib/admin.ts';
-import { ensureDirectoryTree, fetchAsset, runDockerCompose, composeProjectArgs, ensureOpenCodeConfig, ensureOpenCodeSystemConfig, openBrowser } from '../lib/docker.ts';
+import { isAdminReachable, adminRequest } from '../lib/admin.ts';
+import { ensureDirectoryTree, fetchAsset, runDockerCompose, openBrowser } from '../lib/docker.ts';
+import { ensureOpenCodeConfig, ensureOpenCodeSystemConfig, ensureAdminOpenCodeConfig, FilesystemAssetProvider } from '@openpalm/lib';
 import { ensureVarlock, prepareVarlockDir } from '../lib/varlock.ts';
 import { detectHostInfo } from '../lib/host-info.ts';
 import { loadAdminToken } from '../lib/env.ts';
+import { ensureStagedState, fullComposeArgs, buildManagedServiceNames } from '../lib/staging.ts';
+import { createSetupServer } from '../setup-wizard/server.ts';
 
 const DEFAULT_INSTALL_REF = cliPkg.version ? `v${cliPkg.version}` : 'main';
+const SETUP_WIZARD_PORT = 8100;
 
 export default defineCommand({
   meta: {
     name: 'install',
-    description: 'Bootstrap XDG dirs, download assets, start admin + docker-socket-proxy, open setup wizard',
+    description: 'Bootstrap XDG dirs, download assets, run setup wizard, start core services',
   },
   args: {
     force: {
@@ -42,7 +46,7 @@ export default defineCommand({
   async run({ args }) {
     // If the stack is already running AND we have a valid admin token,
     // delegate to the admin API. Otherwise fall through to bootstrap.
-    if (await isStackRunning()) {
+    if (await isAdminReachable()) {
       const token = await loadAdminToken();
       if (token) {
         console.log(JSON.stringify(await adminRequest('/admin/install', { method: 'POST' }), null, 2));
@@ -111,15 +115,46 @@ export async function bootstrapInstall(options: InstallOptions): Promise<void> {
   await Bun.write(join(stateHome, 'artifacts', 'docker-compose.yml'), composeContent);
   await Bun.write(join(stateHome, 'artifacts', 'Caddyfile'), caddyContent);
 
+  // Download schemas to both DATA_HOME (for FilesystemAssetProvider) and STATE_HOME (for varlock validation)
   const secretsSchemaContent = await fetchAsset(options.version, 'secrets.env.schema');
   const stackSchemaContent = await fetchAsset(options.version, 'stack.env.schema');
+  await Bun.write(join(dataHome, 'secrets.env.schema'), secretsSchemaContent);
+  await Bun.write(join(dataHome, 'stack.env.schema'), stackSchemaContent);
   await Bun.write(join(stateHome, 'artifacts', 'secrets.env.schema'), secretsSchemaContent);
   await Bun.write(join(stateHome, 'artifacts', 'stack.env.schema'), stackSchemaContent);
 
+  // Download remaining assets needed by FilesystemAssetProvider
+  const assetFiles: Array<{ remote: string; localPath: string }> = [
+    { remote: 'ollama.yml', localPath: join(dataHome, 'ollama.yml') },
+    { remote: 'AGENTS.md', localPath: join(dataHome, 'assistant', 'AGENTS.md') },
+    { remote: 'opencode.jsonc', localPath: join(dataHome, 'assistant', 'opencode.jsonc') },
+    { remote: 'admin-opencode.jsonc', localPath: join(dataHome, 'admin', 'opencode.jsonc') },
+    { remote: 'cleanup-logs.yml', localPath: join(dataHome, 'automations', 'cleanup-logs.yml') },
+    { remote: 'cleanup-data.yml', localPath: join(dataHome, 'automations', 'cleanup-data.yml') },
+    { remote: 'validate-config.yml', localPath: join(dataHome, 'automations', 'validate-config.yml') },
+  ];
+  await Promise.all(
+    assetFiles.map(async ({ remote, localPath }) => {
+      try {
+        const content = await fetchAsset(options.version, remote);
+        await Bun.write(localPath, content);
+      } catch (err) {
+        console.warn(`Warning: could not download asset '${remote}': ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }),
+  );
+
   await ensureSecrets(configHome);
   await ensureStackEnv(configHome, dataHome, stateHome, workDir, options.version);
-  await ensureOpenCodeConfig(configHome);
-  await ensureOpenCodeSystemConfig(dataHome);
+  // Seed OpenCode config — non-fatal since performSetup() also seeds these
+  try {
+    const fsAssets = new FilesystemAssetProvider(dataHome);
+    ensureOpenCodeConfig();
+    ensureOpenCodeSystemConfig(fsAssets);
+    ensureAdminOpenCodeConfig(fsAssets);
+  } catch {
+    // Assets may not be available yet on first install; performSetup() will retry
+  }
 
   // Non-fatal validation
   try {
@@ -152,19 +187,89 @@ export async function bootstrapInstall(options: InstallOptions): Promise<void> {
     return;
   }
 
-  await runDockerCompose([
-    ...composeProjectArgs(),
-    'up',
-    '-d',
-    'docker-socket-proxy',
-    'admin',
-  ]);
-
-  await waitForAdminHealthy();
-  const targetUrl = updateMode ? `${ADMIN_URL}/` : `${ADMIN_URL}/setup`;
-  if (!options.noOpen) {
-    await openBrowser(targetUrl);
+  // ── Setup Wizard ──────────────────────────────────────────────────────
+  // First-time install: serve the setup wizard locally and wait for user
+  // to complete it. The wizard calls performSetup() from @openpalm/lib
+  // which writes secrets, connection profiles, memory config, and stages
+  // all artifacts. No admin container needed.
+
+  if (!updateMode) {
+    console.log('Starting setup wizard...');
+
+    const wizard = createSetupServer(SETUP_WIZARD_PORT, { configDir: configHome });
+    const wizardUrl = `http://localhost:${wizard.server.port}/setup`;
+    console.log(`Setup wizard running at ${wizardUrl}`);
+
+    if (!options.noOpen) {
+      await openBrowser(wizardUrl);
+    }
+
+    // Block until user completes the wizard
+    const result = await wizard.waitForComplete();
+
+    if (!result.ok) {
+      wizard.stop();
+      throw new Error(`Setup failed: ${result.error ?? 'unknown error'}`);
+    }
+
+    console.log('Setup complete. Starting services...');
+
+    // Keep wizard server running for deploy status polling from the browser.
+    // Stage artifacts and start services while the wizard shows progress.
+    try {
+      const state = await ensureStagedState();
+      const composeArgs = fullComposeArgs(state);
+      const managedServices = buildManagedServiceNames(state);
+
+      wizard.updateDeployStatus(
+        managedServices.map(s => ({ service: s, status: 'pending', label: 'Waiting...' })),
+      );
+
+      await runDockerCompose([...composeArgs, 'pull', ...managedServices]).catch(() => {
+        // Pull failure is non-fatal — images may already be cached
+      });
+
+      wizard.updateDeployStatus(
+        managedServices.map(s => ({ service: s, status: 'pulling', label: 'Starting...' })),
+      );
+
+      await runDockerCompose([...composeArgs, 'up', '-d', ...managedServices]);
+
+      wizard.markAllRunning();
+
+      console.log(JSON.stringify({
+        ok: true,
+        mode: 'install',
+        services: managedServices,
+      }, null, 2));
+
+      // Give the browser a moment to poll the final status, then stop
+      await new Promise(resolve => setTimeout(resolve, 3000));
+    } catch (err) {
+      wizard.setDeployError(String(err));
+      // Keep server alive briefly so user can see the error
+      await new Promise(resolve => setTimeout(resolve, 10000));
+      throw err;
+    } finally {
+      wizard.stop();
+    }
+
+    return;
   }
 
-  console.log(JSON.stringify({ ok: true, mode: updateMode ? 'update' : 'install', url: targetUrl }, null, 2));
+  // ── Start Core Services (update mode — no wizard) ────────────────────
+  // Stage artifacts and start all managed services directly via Docker
+  // Compose. No admin container required for lifecycle operations.
+
+  const state = await ensureStagedState();
+  const composeArgs = fullComposeArgs(state);
+  const managedServices = buildManagedServiceNames(state);
+
+  await runDockerCompose([...composeArgs, 'up', '-d', ...managedServices]);
+
+  console.log(JSON.stringify({
+    ok: true,
+    mode: 'update',
+    services: managedServices,
+  }, null, 2));
 }

package/src/commands/logs.ts

@@ -1,21 +1,10 @@
 import { defineCommand } from 'citty';
-import { composeProjectArgs } from '../lib/docker.ts';
+import { runDockerCompose } from '../lib/docker.ts';
+import { ensureStagedState, fullComposeArgs } from '../lib/staging.ts';
 
 export async function runLogsAction(services: string[]): Promise<void> {
-  const composeArgs = [
-    'compose',
-    ...composeProjectArgs(),
-    'logs',
-    '--tail',
-    '100',
-    ...services,
-  ];
-
-  const proc = Bun.spawn(['docker', ...composeArgs], { stdout: 'inherit', stderr: 'inherit', stdin: 'inherit' });
-  const exitCode = await proc.exited;
-  if (exitCode !== 0) {
-    throw new Error(`Docker compose logs command failed (exit code ${exitCode})`);
-  }
+  const state = await ensureStagedState();
+  await runDockerCompose([...fullComposeArgs(state), 'logs', '--tail', '100', ...services]);
 }
 
 export default defineCommand({

package/src/commands/restart.ts

@@ -1,5 +1,7 @@
 import { defineCommand } from 'citty';
-import { adminRequest, getServiceNames } from '../lib/admin.ts';
+import { tryAdminRequest, getServiceNames } from '../lib/admin.ts';
+import { runDockerCompose } from '../lib/docker.ts';
+import { ensureStagedState, fullComposeArgs, buildManagedServiceNames } from '../lib/staging.ts';
 
 export default defineCommand({
   meta: {
@@ -21,23 +23,49 @@ export default defineCommand({
 
 export async function runRestartAction(services: string[]): Promise<void> {
   if (services.length === 0) {
-    const status = await adminRequest('/admin/containers/list');
-    const serviceNames = getServiceNames(status);
-    for (const service of serviceNames) {
-      const result = await adminRequest('/admin/containers/restart', {
-        method: 'POST',
-        body: JSON.stringify({ service }),
-      });
-      console.log(JSON.stringify(result, null, 2));
+    // Try admin delegation first
+    const adminResult = await tryAdminRequest('/admin/containers/list');
+    if (adminResult !== null) {
+      const serviceNames = getServiceNames(adminResult);
+      for (const service of serviceNames) {
+        const result = await tryAdminRequest('/admin/containers/restart', {
+          method: 'POST',
+          body: JSON.stringify({ service }),
+        });
+        if (result !== null) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.warn(`Warning: failed to restart ${service} via admin API`);
+        }
+      }
+      return;
     }
+
+    // Direct compose restart
+    const state = await ensureStagedState();
+    const managedServices = buildManagedServiceNames(state);
+    await runDockerCompose([...fullComposeArgs(state), 'restart', ...managedServices]);
     return;
   }
 
+  // Restart specific services
   for (const service of services) {
-    const result = await adminRequest('/admin/containers/restart', {
+    const adminResult = await tryAdminRequest('/admin/containers/restart', {
       method: 'POST',
       body: JSON.stringify({ service }),
     });
-    console.log(JSON.stringify(result, null, 2));
+    if (adminResult !== null) {
+      console.log(JSON.stringify(adminResult, null, 2));
+      continue;
+    }
+
+    // Direct compose restart for specific service
+    const state = await ensureStagedState();
+    const composeArgs = fullComposeArgs(state);
+    if (service === 'admin' || service === 'docker-socket-proxy') {
+      await runDockerCompose([...composeArgs, '--profile', 'admin', 'restart', service]);
+    } else {
+      await runDockerCompose([...composeArgs, 'restart', service]);
+    }
   }
 }

package/src/commands/service.ts

@@ -1,5 +1,7 @@
 import { defineCommand } from 'citty';
-import { adminRequest } from '../lib/admin.ts';
+import { tryAdminRequest } from '../lib/admin.ts';
+import { runDockerCompose } from '../lib/docker.ts';
+import { ensureStagedState, fullComposeArgs, buildManagedServiceNames } from '../lib/staging.ts';
 import { runLogsAction } from './logs.ts';
 import { runStartAction } from './start.ts';
 import { runStopAction } from './stop.ts';
@@ -40,14 +42,38 @@ const logsCmd = defineCommand({
 const updateCmd = defineCommand({
   meta: { name: 'update', description: 'Pull latest images' },
   async run() {
-    console.log(JSON.stringify(await adminRequest('/admin/containers/pull', { method: 'POST' }), null, 2));
+    // Try admin delegation first
+    const adminResult = await tryAdminRequest('/admin/containers/pull', { method: 'POST' });
+    if (adminResult !== null) {
+      console.log(JSON.stringify(adminResult, null, 2));
+      return;
+    }
+
+    // Direct compose pull + recreate (scoped to managed services)
+    const state = await ensureStagedState();
+    const composeArgs = fullComposeArgs(state);
+    const managedServices = buildManagedServiceNames(state);
+    console.log('Pulling latest images...');
+    await runDockerCompose([...composeArgs, 'pull', ...managedServices]);
+    console.log('Recreating containers...');
+    await runDockerCompose([...composeArgs, 'up', '-d', '--force-recreate', ...managedServices]);
+    console.log('Update complete.');
   },
 });
 
 const statusCmd = defineCommand({
   meta: { name: 'status', description: 'Show container status' },
   async run() {
-    console.log(JSON.stringify(await adminRequest('/admin/containers/list'), null, 2));
+    // Try admin delegation first
+    const adminResult = await tryAdminRequest('/admin/containers/list');
+    if (adminResult !== null) {
+      console.log(JSON.stringify(adminResult, null, 2));
+      return;
+    }
+
+    // Direct compose ps
+    const state = await ensureStagedState();
+    await runDockerCompose([...fullComposeArgs(state), 'ps', '--format', 'table']);
   },
 });
 

package/src/commands/start.ts

@@ -1,7 +1,7 @@
 import { defineCommand } from 'citty';
-import { adminRequest, isStackRunning } from '../lib/admin.ts';
-import { loadAdminToken } from '../lib/env.ts';
-import { runDockerCompose, composeProjectArgs } from '../lib/docker.ts';
+import { tryAdminRequest } from '../lib/admin.ts';
+import { runDockerCompose } from '../lib/docker.ts';
+import { ensureStagedState, fullComposeArgs, buildManagedServiceNames } from '../lib/staging.ts';
 
 export default defineCommand({
   meta: {
@@ -14,35 +14,66 @@ export default defineCommand({
       description: 'Service names to start (omit for all)',
       required: false,
     },
+    'with-admin': {
+      type: 'boolean',
+      description: 'Include admin UI and docker-socket-proxy',
+      default: false,
+    },
   },
   async run({ args }) {
     const services = args._ ?? [];
-    await runStartAction(services);
+    const withAdmin = args['with-admin'] ?? false;
+    await runStartAction(services, { withAdmin });
   },
 });
 
-export async function runStartAction(services: string[]): Promise<void> {
+export async function runStartAction(
+  services: string[],
+  opts?: { withAdmin?: boolean },
+): Promise<void> {
+  const withAdmin = opts?.withAdmin ?? false;
+
   if (services.length === 0) {
-    // If admin is reachable and we have a token, use the admin API.
-    // Otherwise fall back to docker compose up directly — this handles
-    // the fresh-install case where no token exists yet.
-    const running = await isStackRunning();
-    const token = await loadAdminToken();
-    if (running && token) {
-      console.log(JSON.stringify(await adminRequest('/admin/install', { method: 'POST' }), null, 2));
+    // Try admin delegation first (gives admin's scheduler/audit a chance to observe)
+    const adminResult = await tryAdminRequest('/admin/install', { method: 'POST' });
+    if (adminResult !== null) {
+      console.log(JSON.stringify(adminResult, null, 2));
       return;
     }
 
-    // Direct docker compose — works without auth
-    await runDockerCompose([...composeProjectArgs(), 'up', '-d']);
+    // Direct compose — stage artifacts and start managed services
+    const state = await ensureStagedState();
+    const composeArgs = fullComposeArgs(state);
+    const managedServices = buildManagedServiceNames(state);
+
+    if (withAdmin) {
+      // Include the admin profile — starts admin + docker-socket-proxy
+      await runDockerCompose([...composeArgs, '--profile', 'admin', 'up', '-d', ...managedServices, 'admin', 'docker-socket-proxy']);
+    } else {
+      await runDockerCompose([...composeArgs, 'up', '-d', ...managedServices]);
+    }
     return;
   }
 
+  // Start specific services — try admin first, fall back to direct compose
   for (const service of services) {
-    const result = await adminRequest('/admin/containers/up', {
+    const adminResult = await tryAdminRequest('/admin/containers/up', {
       method: 'POST',
       body: JSON.stringify({ service }),
     });
-    console.log(JSON.stringify(result, null, 2));
+    if (adminResult !== null) {
+      console.log(JSON.stringify(adminResult, null, 2));
+      continue;
+    }
+
+    // Direct compose for specific service
+    const state = await ensureStagedState();
+    const composeArgs = fullComposeArgs(state);
+    // If starting admin explicitly, include the admin profile
+    if (service === 'admin' || service === 'docker-socket-proxy') {
+      await runDockerCompose([...composeArgs, '--profile', 'admin', 'up', '-d', service]);
+    } else {
+      await runDockerCompose([...composeArgs, 'up', '-d', service]);
+    }
   }
 }

package/src/commands/status.ts

@@ -1,5 +1,7 @@
 import { defineCommand } from 'citty';
-import { adminRequest } from '../lib/admin.ts';
+import { tryAdminRequest } from '../lib/admin.ts';
+import { runDockerCompose } from '../lib/docker.ts';
+import { ensureStagedState, fullComposeArgs } from '../lib/staging.ts';
 
 export default defineCommand({
   meta: {
@@ -7,6 +9,15 @@ export default defineCommand({
     description: 'Show container status',
   },
   async run() {
-    console.log(JSON.stringify(await adminRequest('/admin/containers/list'), null, 2));
+    // Try admin delegation first for richer output
+    const adminResult = await tryAdminRequest('/admin/containers/list');
+    if (adminResult !== null) {
+      console.log(JSON.stringify(adminResult, null, 2));
+      return;
+    }
+
+    // Direct compose ps
+    const state = await ensureStagedState();
+    await runDockerCompose([...fullComposeArgs(state), 'ps', '--format', 'table']);
   },
 });

package/src/commands/stop.ts

@@ -1,7 +1,7 @@
 import { defineCommand } from 'citty';
-import { adminRequest, isStackRunning } from '../lib/admin.ts';
-import { loadAdminToken } from '../lib/env.ts';
-import { runDockerCompose, composeProjectArgs } from '../lib/docker.ts';
+import { tryAdminRequest, getServiceNames } from '../lib/admin.ts';
+import { runDockerCompose } from '../lib/docker.ts';
+import { ensureStagedState, fullComposeArgs } from '../lib/staging.ts';
 
 export default defineCommand({
   meta: {
@@ -23,23 +23,48 @@ export default defineCommand({
 
 export async function runStopAction(services: string[]): Promise<void> {
   if (services.length === 0) {
-    const running = await isStackRunning();
-    const token = await loadAdminToken();
-    if (running && token) {
-      console.log(JSON.stringify(await adminRequest('/admin/uninstall', { method: 'POST' }), null, 2));
+    // Try admin delegation — stop each managed container
+    const adminResult = await tryAdminRequest('/admin/containers/list');
+    if (adminResult !== null) {
+      const serviceNames = getServiceNames(adminResult);
+      for (const service of serviceNames) {
+        const result = await tryAdminRequest('/admin/containers/down', {
+          method: 'POST',
+          body: JSON.stringify({ service }),
+        });
+        if (result !== null) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.warn(`Warning: failed to stop ${service} via admin API`);
+        }
+      }
       return;
     }
 
-    // Direct docker compose — works without auth
-    await runDockerCompose([...composeProjectArgs(), 'down']);
+    // Direct compose down — include admin profile to tear down all services
+    const state = await ensureStagedState();
+    await runDockerCompose([...fullComposeArgs(state), '--profile', 'admin', 'down']);
     return;
   }
 
+  // Stop specific services
   for (const service of services) {
-    const result = await adminRequest('/admin/containers/down', {
+    const adminResult = await tryAdminRequest('/admin/containers/down', {
       method: 'POST',
       body: JSON.stringify({ service }),
     });
-    console.log(JSON.stringify(result, null, 2));
+    if (adminResult !== null) {
+      console.log(JSON.stringify(adminResult, null, 2));
+      continue;
+    }
+
+    // Direct compose stop for specific service
+    const state = await ensureStagedState();
+    const composeArgs = fullComposeArgs(state);
+    if (service === 'admin' || service === 'docker-socket-proxy') {
+      await runDockerCompose([...composeArgs, '--profile', 'admin', 'stop', service]);
+    } else {
+      await runDockerCompose([...composeArgs, 'stop', service]);
+    }
   }
 }