openpalm 0.9.7 → 0.9.9

package/bin/openpalm.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+import { runMain } from 'citty';
+import { mainCommand } from '../src/main.ts';
+
+runMain(mainCommand);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openpalm",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "type": "module",
   "license": "MPL-2.0",
   "description": "OpenPalm CLI — install and manage a self-hosted OpenPalm stack",
@@ -10,11 +10,13 @@
     "directory": "packages/cli"
   },
   "bin": {
-    "openpalm": "./src/main.ts"
+    "openpalm": "./bin/openpalm.js"
   },
   "scripts": {
     "start": "bun run src/main.ts",
     "test": "bun test",
+    "test:e2e": "npx playwright test",
+    "wizard:dev": "bun run src/setup-wizard/standalone.ts",
     "build": "bun build src/main.ts --compile --outfile dist/openpalm-cli",
     "build:linux-x64": "bun build src/main.ts --compile --target=bun-linux-x64 --outfile dist/openpalm-cli-linux-x64",
     "build:linux-arm64": "bun build src/main.ts --compile --target=bun-linux-arm64 --outfile dist/openpalm-cli-linux-arm64",

package/playwright.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from '@playwright/test';
+
+const WIZARD_PORT = 18200;
+
+export default defineConfig({
+	testDir: 'e2e',
+	webServer: {
+		command: `bun run e2e/start-wizard-server.ts ${WIZARD_PORT}`,
+		port: WIZARD_PORT,
+		stdout: 'pipe',
+		reuseExistingServer: !process.env.CI,
+	},
+	use: {
+		baseURL: `http://localhost:${WIZARD_PORT}`,
+	},
+});

package/src/commands/install-file.test.ts

@@ -0,0 +1,306 @@
+/**
+ * Tests for the --file install path in the install command.
+ *
+ * Mocks performSetupFromConfig and performSetup to avoid filesystem
+ * side effects, and verifies that the file-based install flow correctly
+ * reads, parses, and dispatches JSON/YAML config files.
+ */
+import { describe, expect, it, mock, afterEach, beforeEach } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync, chmodSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+const originalBunSpawn = Bun.spawn;
+const originalBunWhich = Bun.which;
+
+function mockDockerCli(): void {
+  Bun.which = mock((_cmd: string) => '/usr/bin/docker') as typeof Bun.which;
+  Bun.spawn = mock((_cmd: string[] | readonly string[], _opts?: unknown) => ({
+    pid: 0,
+    exited: Promise.resolve(0),
+    exitCode: null,
+    signalCode: null,
+    killed: false,
+    stdin: null,
+    stdout: null,
+    stderr: null,
+    kill: () => {},
+    ref: () => {},
+    unref: () => {},
+    [Symbol.asyncDispose]: async () => {},
+    resourceUsage: () => undefined,
+  })) as unknown as typeof Bun.spawn;
+}
+
+function restoreDockerCli(): void {
+  Bun.spawn = originalBunSpawn;
+  Bun.which = originalBunWhich;
+}
+
+function makeValidSetupConfig(): Record<string, unknown> {
+  return {
+    version: 1,
+    owner: { name: 'Test User', email: 'test@example.com' },
+    security: { adminToken: 'test-admin-token-12345' },
+    connections: [
+      {
+        id: 'openai-main',
+        name: 'OpenAI',
+        provider: 'openai',
+        baseUrl: 'https://api.openai.com',
+        apiKey: 'sk-test-key-123',
+      },
+    ],
+    assignments: {
+      llm: { connectionId: 'openai-main', model: 'gpt-4o' },
+      embeddings: { connectionId: 'openai-main', model: 'text-embedding-3-small' },
+    },
+    memory: { userId: 'test_user' },
+  };
+}
+
+function makeLegacySetupInput(): Record<string, unknown> {
+  return {
+    adminToken: 'test-admin-token-12345',
+    ownerName: 'Test User',
+    ownerEmail: 'test@example.com',
+    memoryUserId: 'test_user',
+    ollamaEnabled: false,
+    connections: [
+      {
+        id: 'openai-main',
+        name: 'OpenAI',
+        provider: 'openai',
+        baseUrl: 'https://api.openai.com',
+        apiKey: 'sk-test-key-123',
+      },
+    ],
+    assignments: {
+      llm: { connectionId: 'openai-main', model: 'gpt-4o' },
+      embeddings: { connectionId: 'openai-main', model: 'text-embedding-3-small' },
+    },
+  };
+}
+
+// ── Test Suite ────────────────────────────────────────────────────────────
+
+describe('install --file', () => {
+  let tempBase: string;
+  let configDir: string;
+  let dataDir: string;
+  let stateDir: string;
+  let workDir: string;
+
+  const savedEnv: Record<string, string | undefined> = {};
+  const originalFetch = globalThis.fetch;
+  const originalLog = console.log;
+  const originalWarn = console.warn;
+
+  beforeEach(() => {
+    tempBase = mkdtempSync(join(tmpdir(), 'openpalm-install-file-'));
+    configDir = join(tempBase, 'config');
+    dataDir = join(tempBase, 'data');
+    stateDir = join(tempBase, 'state');
+    workDir = join(tempBase, 'work');
+    const binDir = join(stateDir, 'bin');
+
+    mkdirSync(binDir, { recursive: true });
+    writeFileSync(join(binDir, 'varlock'), '#!/bin/sh\nexit 0\n');
+    chmodSync(join(binDir, 'varlock'), 0o755);
+
+    savedEnv.OPENPALM_CONFIG_HOME = process.env.OPENPALM_CONFIG_HOME;
+    savedEnv.OPENPALM_DATA_HOME = process.env.OPENPALM_DATA_HOME;
+    savedEnv.OPENPALM_STATE_HOME = process.env.OPENPALM_STATE_HOME;
+    savedEnv.OPENPALM_WORK_DIR = process.env.OPENPALM_WORK_DIR;
+    savedEnv.ADMIN_TOKEN = process.env.ADMIN_TOKEN;
+    savedEnv.OPENPALM_ADMIN_TOKEN = process.env.OPENPALM_ADMIN_TOKEN;
+
+    process.env.OPENPALM_CONFIG_HOME = configDir;
+    process.env.OPENPALM_DATA_HOME = dataDir;
+    process.env.OPENPALM_STATE_HOME = stateDir;
+    process.env.OPENPALM_WORK_DIR = workDir;
+    delete process.env.ADMIN_TOKEN;
+    delete process.env.OPENPALM_ADMIN_TOKEN;
+
+    mockDockerCli();
+    globalThis.fetch = mock(async (input: string | URL) => {
+      const url = String(input);
+      if (url.includes('/docker-compose.yml')) return new Response('services: {}\n', { status: 200 });
+      if (url.includes('/Caddyfile')) return new Response(':80 {\n}\n', { status: 200 });
+      if (url.endsWith('.schema') || url.endsWith('.schema.json')) return new Response('KEY=string\n', { status: 200 });
+      // Return valid content for asset files needed by FilesystemAssetProvider
+      if (url.includes('/ollama.yml')) return new Response('services:\n  ollama:\n    image: ollama/ollama\n', { status: 200 });
+      if (url.includes('/AGENTS.md')) return new Response('# Agents\n', { status: 200 });
+      if (url.includes('/opencode.jsonc') || url.includes('/admin-opencode.jsonc'))
+        return new Response('{"$schema":"https://opencode.ai/config.json"}\n', { status: 200 });
+      if (url.includes('/cleanup-logs.yml')) return new Response('name: cleanup-logs\nschedule: daily\n', { status: 200 });
+      if (url.includes('/cleanup-data.yml')) return new Response('name: cleanup-data\nschedule: weekly\n', { status: 200 });
+      if (url.includes('/validate-config.yml')) return new Response('name: validate-config\nschedule: hourly\n', { status: 200 });
+      return new Response('', { status: 503 });
+    }) as typeof fetch;
+    console.log = mock(() => {}) as typeof console.log;
+    console.warn = mock(() => {}) as typeof console.warn;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    console.log = originalLog;
+    console.warn = originalWarn;
+    restoreDockerCli();
+    process.env.OPENPALM_CONFIG_HOME = savedEnv.OPENPALM_CONFIG_HOME;
+    process.env.OPENPALM_DATA_HOME = savedEnv.OPENPALM_DATA_HOME;
+    process.env.OPENPALM_STATE_HOME = savedEnv.OPENPALM_STATE_HOME;
+    process.env.OPENPALM_WORK_DIR = savedEnv.OPENPALM_WORK_DIR;
+    process.env.ADMIN_TOKEN = savedEnv.ADMIN_TOKEN;
+    process.env.OPENPALM_ADMIN_TOKEN = savedEnv.OPENPALM_ADMIN_TOKEN;
+    rmSync(tempBase, { recursive: true, force: true });
+  });
+
+  it('--file missing.json throws "Setup config file not found"', async () => {
+    const { bootstrapInstall } = await import('./install.ts');
+    const missingPath = join(tempBase, 'missing.json');
+
+    const err = await bootstrapInstall({
+      force: true,
+      version: 'main',
+      noStart: false,
+      noOpen: true,
+      file: missingPath,
+    }).catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).toContain('Setup config file not found');
+  });
+
+  it('--file config.txt throws "Unsupported config file format"', async () => {
+    const { bootstrapInstall } = await import('./install.ts');
+    const txtPath = join(tempBase, 'config.txt');
+    writeFileSync(txtPath, 'some text content');
+
+    const err = await bootstrapInstall({
+      force: true,
+      version: 'main',
+      noStart: false,
+      noOpen: true,
+      file: txtPath,
+    }).catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).toContain('Unsupported config file format');
+  });
+
+  it('--file broken.json with invalid JSON throws "Failed to parse setup config"', async () => {
+    const { bootstrapInstall } = await import('./install.ts');
+    const brokenPath = join(tempBase, 'broken.json');
+    writeFileSync(brokenPath, '{ invalid json !!!');
+
+    const err = await bootstrapInstall({
+      force: true,
+      version: 'main',
+      noStart: false,
+      noOpen: true,
+      file: brokenPath,
+    }).catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).toContain('Failed to parse setup config');
+  });
+
+  it('--file config.json with version: 1 calls performSetupFromConfig path', async () => {
+    const { bootstrapInstall } = await import('./install.ts');
+    const configPath = join(tempBase, 'config.json');
+    const config = makeValidSetupConfig();
+    writeFileSync(configPath, JSON.stringify(config));
+
+    // This will call performSetupFromConfig which needs filesystem dirs.
+    // The function will fail at staging since we don't have the full
+    // filesystem setup, but the important thing is it reaches the right
+    // code path (version 1 -> performSetupFromConfig).
+    const err = await bootstrapInstall({
+      force: true,
+      version: 'main',
+      noStart: true,
+      noOpen: true,
+      file: configPath,
+    }).catch((e: unknown) => e);
+
+    // If setup fails it will throw "Setup failed: ..." — but NOT
+    // "Unsupported config file format" or "Failed to parse" which
+    // confirms the JSON was parsed and routed to performSetupFromConfig.
+    if (err) {
+      expect((err as Error).message).not.toContain('Unsupported config file format');
+      expect((err as Error).message).not.toContain('Failed to parse');
+      // It may fail with "Setup failed" due to missing filesystem state
+      // or it may succeed; either is acceptable for this routing test.
+    }
+  });
+
+  it('--file setup.yaml with valid YAML is parsed correctly', async () => {
+    const { bootstrapInstall } = await import('./install.ts');
+    const yamlPath = join(tempBase, 'setup.yaml');
+    const yamlContent = [
+      'version: 1',
+      'security:',
+      '  adminToken: test-admin-token-12345',
+      'connections:',
+      '  - id: openai-main',
+      '    name: OpenAI',
+      '    provider: openai',
+      '    baseUrl: https://api.openai.com',
+      '    apiKey: sk-test-key-123',
+      'assignments:',
+      '  llm:',
+      '    connectionId: openai-main',
+      '    model: gpt-4o',
+      '  embeddings:',
+      '    connectionId: openai-main',
+      '    model: text-embedding-3-small',
+    ].join('\n');
+    writeFileSync(yamlPath, yamlContent);
+
+    const err = await bootstrapInstall({
+      force: true,
+      version: 'main',
+      noStart: true,
+      noOpen: true,
+      file: yamlPath,
+    }).catch((e: unknown) => e);
+
+    // If it gets past parsing, it will NOT throw a parse error.
+    if (err) {
+      expect((err as Error).message).not.toContain('Unsupported config file format');
+      expect((err as Error).message).not.toContain('Failed to parse');
+    }
+  });
+
+  it('--file config.json --no-start exits after setup without compose up', async () => {
+    const { bootstrapInstall } = await import('./install.ts');
+    const configPath = join(tempBase, 'config.json');
+    const config = makeValidSetupConfig();
+    writeFileSync(configPath, JSON.stringify(config));
+
+    const err = await bootstrapInstall({
+      force: true,
+      version: 'main',
+      noStart: true,
+      noOpen: true,
+      file: configPath,
+    }).catch((e: unknown) => e);
+
+    // Check Bun.spawn calls — docker compose up should NOT have been called
+    const spawnCalls = (Bun.spawn as ReturnType<typeof mock>).mock.calls;
+    const composeUpCalls = spawnCalls.filter((call: unknown[]) => {
+      const args = call[0] as string[];
+      return Array.isArray(args) && args.includes('compose') && args.includes('up');
+    });
+    expect(composeUpCalls).toHaveLength(0);
+
+    // With --no-start, should print "Config written" message (if setup succeeds)
+    // or throw a setup error. Either way, no docker compose up.
+    if (err) {
+      expect((err as Error).message).not.toContain('Unsupported config file format');
+    }
+  });
+});

package/src/commands/install-services.test.ts

@@ -2,23 +2,28 @@ import { describe, expect, it } from 'bun:test';
 import { buildDeployStatusEntries, buildInstallServiceNames } from './install-services.ts';
 
 describe('install service helpers', () => {
-  it('appends admin services to managed services', () => {
-    expect(buildInstallServiceNames(['caddy', 'memory'])).toEqual([
-      'caddy',
+  it('passes managed services through unchanged', () => {
+    expect(buildInstallServiceNames(['memory', 'assistant'])).toEqual([
+      'memory',
+      'assistant',
+    ]);
+  });
+
+  it('includes admin services when they are in managed list', () => {
+    expect(buildInstallServiceNames(['memory', 'caddy', 'admin', 'docker-socket-proxy'])).toEqual([
       'memory',
+      'caddy',
       'admin',
       'docker-socket-proxy',
     ]);
   });
 
   it('builds deploy status entries for the full install service list', () => {
-    const services = buildInstallServiceNames(['caddy', 'memory']);
+    const services = buildInstallServiceNames(['memory', 'assistant']);
 
     expect(buildDeployStatusEntries(services, 'pending', 'Waiting...')).toEqual([
-      { service: 'caddy', status: 'pending', label: 'Waiting...' },
       { service: 'memory', status: 'pending', label: 'Waiting...' },
-      { service: 'admin', status: 'pending', label: 'Waiting...' },
-      { service: 'docker-socket-proxy', status: 'pending', label: 'Waiting...' },
+      { service: 'assistant', status: 'pending', label: 'Waiting...' },
     ]);
   });
 });

package/src/commands/install-services.ts

@@ -1,7 +1,7 @@
 export type DeployStatusState = 'pending' | 'pulling';
 
 export function buildInstallServiceNames(managedServices: string[]): string[] {
-  return [...managedServices, 'admin', 'docker-socket-proxy'];
+  return [...managedServices];
 }
 
 export function buildDeployStatusEntries(

package/src/commands/install.ts

@@ -4,18 +4,20 @@ 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 { isAdminReachable, adminRequest } from '../lib/admin.ts';
 import { ensureDirectoryTree, fetchAsset, runDockerCompose, openBrowser } from '../lib/docker.ts';
-import { ensureOpenCodeConfig, ensureOpenCodeSystemConfig, ensureAdminOpenCodeConfig, FilesystemAssetProvider } from '@openpalm/lib';
+import {
+  ensureOpenCodeConfig, ensureOpenCodeSystemConfig, ensureAdminOpenCodeConfig, FilesystemAssetProvider,
+  performSetupFromConfig,
+  type SetupConfig, type SetupResult,
+} 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';
 import { buildInstallServiceNames, buildDeployStatusEntries } from './install-services.ts';
 
-const DEFAULT_INSTALL_REF = cliPkg.version ? `v${cliPkg.version}` : 'main';
-const SETUP_WIZARD_PORT = 8100;
+const DEFAULT_INSTALL_REF = 'main';
+const SETUP_WIZARD_PORT = Number(process.env.OPENPALM_SETUP_PORT) || 8100;
 
 export default defineCommand({
   meta: {
@@ -30,7 +32,7 @@ export default defineCommand({
     },
     version: {
       type: 'string',
-      description: 'Install specific release ref (default: current CLI version)',
+      description: 'Install specific repository ref (default: main)',
       default: DEFAULT_INSTALL_REF,
     },
     start: {
@@ -43,25 +45,19 @@ export default defineCommand({
       description: 'Open browser after install (use --no-open to skip)',
       default: true,
     },
+    file: {
+      type: 'string',
+      alias: 'f',
+      description: 'Path to setup config file (JSON or YAML) — skips wizard',
+    },
   },
   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 isAdminReachable()) {
-      const token = await loadAdminToken();
-      if (token) {
-        console.log(JSON.stringify(await adminRequest('/admin/install', { method: 'POST' }), null, 2));
-        return;
-      }
-      // No token available — fall through to bootstrap install which doesn't need auth.
-      console.warn('Stack is running but no admin token is configured. Proceeding with bootstrap install.');
-    }
-
     await bootstrapInstall({
       force: args.force,
       version: args.version,
       noStart: !args.start,
       noOpen: !args.open,
+      file: args.file,
     });
   },
 });
@@ -71,6 +67,7 @@ type InstallOptions = {
   version: string;
   noStart: boolean;
   noOpen: boolean;
+  file?: string;
 };
 
 export async function bootstrapInstall(options: InstallOptions): Promise<void> {
@@ -117,16 +114,20 @@ export async function bootstrapInstall(options: InstallOptions): Promise<void> {
   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);
+  for (const schemaFile of ['secrets.env.schema', 'stack.env.schema', 'setup-config.schema.json']) {
+    try {
+      const content = await fetchAsset(options.version, schemaFile);
+      await Bun.write(join(dataHome, schemaFile), content);
+      await Bun.write(join(stateHome, 'artifacts', schemaFile), content);
+    } catch (err) {
+      console.warn(`Warning: could not download schema '${schemaFile}': ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
 
   // Download remaining assets needed by FilesystemAssetProvider
   const assetFiles: Array<{ remote: string; localPath: string }> = [
     { remote: 'ollama.yml', localPath: join(dataHome, 'ollama.yml') },
+    { remote: 'admin.yml', localPath: join(dataHome, 'admin.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') },
@@ -183,11 +184,84 @@ export async function bootstrapInstall(options: InstallOptions): Promise<void> {
     // Varlock install/execution failures are non-fatal during install
   }
 
-  if (options.noStart) {
+  if (options.noStart && !options.file) {
     console.log('OpenPalm files prepared. Run `openpalm start` to start services.');
     return;
   }
 
+  // ── File-based install (--file / -f) ──────────────────────────────────
+  // Read a JSON or YAML setup config file and call performSetup() or
+  // performSetupFromConfig() directly — no wizard needed.
+
+  if (options.file) {
+    console.log(`Reading setup config from ${options.file}...`);
+
+    if (!(await Bun.file(options.file).exists())) {
+      throw new Error(`Setup config file not found: ${options.file}. Check the --file path and try again.`);
+    }
+    let raw: string;
+    try {
+      raw = await Bun.file(options.file).text();
+    } catch (err) {
+      throw new Error(`Failed to read setup config file '${options.file}': ${err instanceof Error ? err.message : String(err)}`);
+    }
+
+    const ext = options.file.toLowerCase();
+    let parsed: unknown;
+    try {
+      if (ext.endsWith('.yaml') || ext.endsWith('.yml')) {
+        const { parse } = await import('yaml');
+        parsed = parse(raw);
+      } else if (ext.endsWith('.json')) {
+        parsed = JSON.parse(raw);
+      } else {
+        throw new Error(`Unsupported config file format: ${options.file}. Use .json or .yaml.`);
+      }
+    } catch (err) {
+      if (err instanceof Error && err.message.startsWith('Unsupported config file format:')) {
+        throw err;
+      }
+      throw new Error(`Failed to parse setup config '${options.file}': ${err instanceof Error ? err.message : String(err)}`);
+    }
+
+    const fsAssets = new FilesystemAssetProvider(dataHome);
+    const config = parsed as Record<string, unknown>;
+    let result: SetupResult;
+
+    if (typeof config.version !== "number") {
+      throw new Error(
+        `Setup config file is missing a 'version' field. Use 'version: 1' for the current format.`
+      );
+    }
+    if (config.version === 1) {
+      result = await performSetupFromConfig(config as SetupConfig, fsAssets);
+    } else {
+      throw new Error(`Unsupported setup config version: ${config.version}. Only version 1 is supported.`);
+    }
+
+    if (!result.ok) throw new Error(`Setup failed: ${result.error}`);
+    console.log('Setup complete.');
+
+    if (options.noStart) {
+      console.log('Config written. Run `openpalm start` to start services.');
+      return;
+    }
+
+    // Deploy (same as existing update-mode code)
+    console.log('Starting services...');
+    const state = await ensureStagedState();
+    const composeArgs = fullComposeArgs(state);
+    const managedServices = buildManagedServiceNames(state);
+    const allServices = buildInstallServiceNames(managedServices);
+
+    await runDockerCompose([...composeArgs, 'pull', ...allServices]).catch(() => {
+      console.warn('Warning: image pull failed.');
+    });
+    await runDockerCompose([...composeArgs, 'up', '-d', ...allServices]);
+    console.log(JSON.stringify({ ok: true, mode: 'install', services: allServices }, null, 2));
+    return;
+  }
+
   // ── Setup Wizard ──────────────────────────────────────────────────────
   // First-time install: serve the setup wizard locally and wait for user
   // to complete it. The wizard calls performSetup() from @openpalm/lib
@@ -197,7 +271,16 @@ export async function bootstrapInstall(options: InstallOptions): Promise<void> {
   if (!updateMode) {
     console.log('Starting setup wizard...');
 
-    const wizard = createSetupServer(SETUP_WIZARD_PORT, { configDir: configHome });
+    let wizard;
+    try {
+      wizard = createSetupServer(SETUP_WIZARD_PORT, { configDir: configHome });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes('EADDRINUSE') || msg.includes('address already in use') || msg.includes('Failed to start')) {
+        throw new Error(`Port ${SETUP_WIZARD_PORT} is in use. Stop the conflicting process or set OPENPALM_SETUP_PORT=<port>.`);
+      }
+      throw err;
+    }
     const wizardUrl = `http://localhost:${wizard.server.port}/setup`;
     console.log(`Setup wizard running at ${wizardUrl}`);
 
@@ -225,13 +308,13 @@ export async function bootstrapInstall(options: InstallOptions): Promise<void> {
 
       wizard.updateDeployStatus(buildDeployStatusEntries(allServices, 'pending', 'Waiting...'));
 
-      await runDockerCompose([...composeArgs, '--profile', 'admin', 'pull', ...allServices]).catch(() => {
-        // Pull failure is non-fatal — images may already be cached
+      await runDockerCompose([...composeArgs, 'pull', ...allServices]).catch(() => {
+        console.warn('Warning: image pull failed — if this is your first install, check your network connection.');
       });
 
       wizard.updateDeployStatus(buildDeployStatusEntries(allServices, 'pulling', 'Starting...'));
 
-      await runDockerCompose([...composeArgs, '--profile', 'admin', 'up', '-d', ...allServices]);
+      await runDockerCompose([...composeArgs, 'up', '-d', ...allServices]);
 
       wizard.markAllRunning();
 
@@ -264,7 +347,7 @@ export async function bootstrapInstall(options: InstallOptions): Promise<void> {
   const managedServices = buildManagedServiceNames(state);
   const allServices = buildInstallServiceNames(managedServices);
 
-  await runDockerCompose([...composeArgs, '--profile', 'admin', 'up', '-d', ...allServices]);
+  await runDockerCompose([...composeArgs, 'up', '-d', ...allServices]);
 
   console.log(JSON.stringify({
     ok: true,