@plosson/agentio 0.7.5 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plosson/agentio",
-  "version": "0.7.5",
+  "version": "0.8.1",
   "description": "CLI for LLM agents to interact with communication and tracking services",
   "type": "module",
   "license": "MIT",

package/src/commands/teleport.test.ts

@@ -394,21 +394,44 @@ describe('runTeleport — preflight failures', () => {
     );
   });
 
-  test('app already exists → CliError + warning', async () => {
+  test('app already exists → rebuild in place (no create, key preserved)', async () => {
     const deps = makeDeps({
       existingApp: { name: 'mcp', url: 'https://mcp.existing.com' },
     });
-    await expect(runTeleport({ name: 'mcp' }, deps)).rejects.toThrow(
-      /already exists/
-    );
-    // A warning was emitted before the throw so the user has context.
-    expect(deps.warnLines.some((l) => l.includes('siteio apps rm'))).toBe(
-      true
-    );
-    // Must not have attempted to create/set/deploy.
+    const result = await runTeleport({ name: 'mcp' }, deps);
+
     const methods = deps.calls.map((c) => c.method);
+    // Rebuild MUST NOT create the app — it already exists.
     expect(methods).not.toContain('createApp');
-    expect(methods).not.toContain('deploy');
+    // But it MUST push env + redeploy so the image is rebuilt.
+    expect(methods).toContain('setApp');
+    expect(methods).toContain('deploy');
+
+    // setApp on rebuild preserves AGENTIO_SERVER_API_KEY by omitting it
+    // from the env map (siteio merges env vars).
+    const setCall = deps.calls.find((c) => c.method === 'setApp');
+    expect(setCall).toBeDefined();
+    const envVars = (setCall!.args as { envVars?: Record<string, string> })
+      .envVars;
+    expect(envVars).toBeDefined();
+    expect(Object.keys(envVars!).sort()).toEqual([
+      'AGENTIO_CONFIG',
+      'AGENTIO_KEY',
+    ]);
+    expect(envVars!.AGENTIO_SERVER_API_KEY).toBeUndefined();
+
+    // Result signals a rebuild: no new server API key emitted.
+    expect(result.serverApiKey).toBe('');
+
+    // Log messages surface the rebuild intent, and the success banner
+    // is distinct from a fresh deploy.
+    const logs = deps.logLines.join('\n');
+    expect(logs).toMatch(/rebuild/i);
+    expect(logs).toContain('Rebuild complete!');
+    expect(logs).not.toContain('Teleport complete!');
+    // We do NOT print the onboarding snippet on rebuild — clients
+    // already have their bearer.
+    expect(logs).not.toContain('To add to Claude Code:');
   });
 });
 

package/src/commands/teleport.ts

@@ -513,27 +513,52 @@ export async function runTeleport(
   }
   deps.log(`Found ${profileCount} local profile(s).`);
 
-  // App must not already exist.
+  // Check whether the app already exists on siteio. If it does, we
+  // REBUILD in place: skip createApp, preserve the existing
+  // AGENTIO_SERVER_API_KEY (so Claude clients keep their /authorize PIN
+  // and their issued bearers), backfill /data if needed, and redeploy
+  // the freshly generated image. If it doesn't exist, fall through to
+  // the fresh-deploy path.
   deps.log(`Checking if siteio app "${opts.name}" already exists…`);
   const existing = await deps.runner.findApp(opts.name);
-  if (existing) {
-    deps.warn(
-      `A siteio app named "${opts.name}" already exists. ` +
-        `Run \`siteio apps rm ${opts.name}\` if you want to redeploy from scratch.`
+  const isRebuild = Boolean(existing);
+  if (isRebuild) {
+    deps.log(
+      `Found existing siteio app "${opts.name}" — will rebuild image in place (API key and clients preserved).`
     );
-    throw new CliError(
-      'INVALID_PARAMS',
-      `App "${opts.name}" already exists on siteio`
+  } else {
+    deps.log(
+      `No existing siteio app "${opts.name}" — will create a fresh one.`
     );
   }
 
-  // Generate a fresh server API key for the remote.
-  const serverApiKey = deps.generateServerApiKey();
+  // Only generate a new operator API key on fresh deploys. On rebuild
+  // the remote's AGENTIO_SERVER_API_KEY is left untouched (siteio's
+  // `apps set -e` merges env vars, so omitting a key preserves it).
+  const serverApiKey = isRebuild ? '' : deps.generateServerApiKey();
 
-  // Export the local config.
-  deps.log('Exporting local configuration…');
+  // Export the local config (always — we want rebuild to also pick up
+  // any profile additions since the last deploy).
+  deps.log(
+    isRebuild
+      ? 'Re-exporting local configuration…'
+      : 'Exporting local configuration…'
+  );
   const exported = await deps.generateExportData();
 
+  // On rebuild, detect whether /data is already mounted so we backfill
+  // the persistent volume if it's missing (same logic as --sync).
+  let needsVolumeBackfill = false;
+  if (isRebuild) {
+    const detail = await deps.runner.appInfo(opts.name);
+    needsVolumeBackfill = !hasDataVolumeMount(detail);
+    if (needsVolumeBackfill) {
+      deps.log(
+        `No persistent volume mounted at ${DATA_VOLUME_PATH} — will attach ${volumeNameFor(opts.name)}:${DATA_VOLUME_PATH} as part of this rebuild.`
+      );
+    }
+  }
+
   // Resolve git mode settings up front so dry-run can show the same
   // command shape the real run would use.
   const isGitMode = Boolean(opts.gitBranch);
@@ -562,21 +587,37 @@ export async function runTeleport(
   // Dry-run: report what would happen and exit.
   if (opts.dryRun) {
     deps.log('--- Dry run: the following commands would be executed ---');
-    if (gitSettings) {
-      deps.log(
-        `siteio apps create ${opts.name} -g ${gitSettings.repoUrl} --branch ${gitSettings.branch} --dockerfile ${TELEPORT_DOCKERFILE_PATH} -p 9999`
-      );
-    } else {
-      deps.log(
-        `siteio apps create ${opts.name} -f <tempfile> -p 9999`
-      );
+    if (!isRebuild) {
+      if (gitSettings) {
+        deps.log(
+          `siteio apps create ${opts.name} -g ${gitSettings.repoUrl} --branch ${gitSettings.branch} --dockerfile ${TELEPORT_DOCKERFILE_PATH} -p 9999`
+        );
+      } else {
+        deps.log(
+          `siteio apps create ${opts.name} -f <tempfile> -p 9999`
+        );
+      }
     }
-    deps.log(
-      `siteio apps set ${opts.name} -e AGENTIO_KEY=<redacted> -e AGENTIO_CONFIG=<${exported.config.length} chars> -e AGENTIO_SERVER_API_KEY=${serverApiKey}`
-    );
+    const setParts = [
+      `siteio apps set ${opts.name}`,
+      '-e AGENTIO_KEY=<redacted>',
+      `-e AGENTIO_CONFIG=<${exported.config.length} chars>`,
+    ];
+    if (!isRebuild) {
+      setParts.push(`-e AGENTIO_SERVER_API_KEY=${serverApiKey}`);
+    }
+    if (!isRebuild || needsVolumeBackfill) {
+      setParts.push(`-v ${volumeNameFor(opts.name)}:${DATA_VOLUME_PATH}`);
+    }
+    deps.log(setParts.join(' '));
     deps.log(
       `siteio apps deploy ${opts.name}${opts.noCache ? ' --no-cache' : ''}`
     );
+    if (isRebuild) {
+      deps.log(
+        '(AGENTIO_SERVER_API_KEY is intentionally NOT touched — operator key on the remote stays the same.)'
+      );
+    }
     if (!gitSettings) {
       const dockerfile = deps.generateDockerfile();
       deps.log('--- Dockerfile that would be uploaded ---');
@@ -601,41 +642,62 @@ export async function runTeleport(
     : await deps.writeTempFile(deps.generateDockerfile());
 
   try {
-    deps.log(`Creating siteio app "${opts.name}"…`);
-    if (gitSettings) {
-      await deps.runner.createApp({
-        name: opts.name,
-        port: 9999,
-        git: {
-          repoUrl: gitSettings.repoUrl,
-          branch: gitSettings.branch,
-          dockerfilePath: TELEPORT_DOCKERFILE_PATH,
-        },
-      });
+    if (!isRebuild) {
+      deps.log(`Creating siteio app "${opts.name}"…`);
+      if (gitSettings) {
+        await deps.runner.createApp({
+          name: opts.name,
+          port: 9999,
+          git: {
+            repoUrl: gitSettings.repoUrl,
+            branch: gitSettings.branch,
+            dockerfilePath: TELEPORT_DOCKERFILE_PATH,
+          },
+        });
+      } else {
+        await deps.runner.createApp({
+          name: opts.name,
+          dockerfilePath: tempPath!,
+          port: 9999,
+        });
+      }
+    }
+
+    // On rebuild, omit AGENTIO_SERVER_API_KEY so siteio's env-merge
+    // preserves the existing value (clients keep their bearer). Only
+    // attach /data when not already mounted — siteio REPLACES the
+    // volumes list on update, so blindly passing it would clobber
+    // other mounts the operator added.
+    const envVars: Record<string, string> = {
+      AGENTIO_KEY: exported.key,
+      AGENTIO_CONFIG: exported.config,
+      ...(isRebuild ? {} : { AGENTIO_SERVER_API_KEY: serverApiKey }),
+    };
+    const attachVolume = !isRebuild || needsVolumeBackfill;
+
+    if (isRebuild) {
+      deps.log(
+        attachVolume
+          ? 'Updating env vars + attaching persistent volume on siteio…'
+          : 'Updating environment variables on siteio…'
+      );
     } else {
-      await deps.runner.createApp({
-        name: opts.name,
-        dockerfilePath: tempPath!,
-        port: 9999,
-      });
+      deps.log('Setting environment variables and persistent volume…');
     }
 
-    deps.log('Setting environment variables and persistent volume…');
     await deps.runner.setApp({
       name: opts.name,
-      envVars: {
-        AGENTIO_KEY: exported.key,
-        AGENTIO_CONFIG: exported.config,
-        AGENTIO_SERVER_API_KEY: serverApiKey,
-      },
-      // Persistent named volume mounted at /data so config.server.tokens
-      // (issued OAuth bearers) survive container restarts. Without this
-      // mount, every restart wipes the bearer and connected clients
-      // would re-run the OAuth flow.
-      volumes: { [volumeNameFor(opts.name)]: DATA_VOLUME_PATH },
+      envVars,
+      ...(attachVolume
+        ? { volumes: { [volumeNameFor(opts.name)]: DATA_VOLUME_PATH } }
+        : {}),
     });
 
-    deps.log('Deploying (this may take a minute — Docker is building your image)…');
+    deps.log(
+      isRebuild
+        ? 'Rebuilding (this may take a minute — Docker is rebuilding your image)…'
+        : 'Deploying (this may take a minute — Docker is building your image)…'
+    );
     await deps.runner.deploy({
       name: opts.name,
       // In git mode, there's no -f to re-pass on deploy — siteio uses
@@ -693,7 +755,7 @@ export async function runTeleport(
       : null;
 
     deps.log('');
-    deps.log('Teleport complete!');
+    deps.log(isRebuild ? 'Rebuild complete!' : 'Teleport complete!');
     if (url) {
       deps.log(`  URL:       ${url}`);
       deps.log(`  Health:    ${url}/health`);
@@ -703,10 +765,14 @@ export async function runTeleport(
         `  URL:       (siteio did not return a URL — run \`siteio apps info ${opts.name}\` to look it up)`
       );
     }
-    deps.log(`  API key:   ${serverApiKey}`);
-    deps.log('             (you will type this into the Authorize page when Claude Code first connects)');
+    if (isRebuild) {
+      deps.log('  API key:   (unchanged — existing clients keep their bearer)');
+    } else {
+      deps.log(`  API key:   ${serverApiKey}`);
+      deps.log('             (you will type this into the Authorize page when Claude Code first connects)');
+    }
     deps.log('');
-    if (claudeCmd) {
+    if (claudeCmd && !isRebuild) {
       deps.log('To add to Claude Code:');
       deps.log(`  ${claudeCmd}`);
       deps.log(

package/src/server/http.test.ts

@@ -173,9 +173,10 @@ describe('handleRequest — /health adversarial paths', () => {
     expect(res.status).toBe(404);
   });
 
-  test('GET / (root) → 404', async () => {
+  test('GET / (root) → 200 setup page (login form)', async () => {
     const res = await dispatch(req('/'));
-    expect(res.status).toBe(404);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toBe('text/html; charset=utf-8');
   });
 });
 

package/src/server/http.ts

@@ -1,6 +1,7 @@
 import { handleMcpRequest } from './mcp-http';
 import type { OAuthStore } from './oauth-store';
 import { requireBearer, routeOAuth } from './oauth';
+import { routeSetup } from './setup-page';
 
 /**
  * Context passed to every fetch handler invocation. Built once at boot in
@@ -35,6 +36,11 @@ export async function handleRequest(
     return jsonResponse({ ok: true });
   }
 
+  // Root setup page — operator-facing UI (API-key gated) for picking
+  // profiles and generating the MCP URL.
+  const setupResponse = await routeSetup(req, ctx);
+  if (setupResponse) return setupResponse;
+
   // OAuth metadata + endpoints (Phase 3c onward).
   const oauthResponse = await routeOAuth(req, ctx);
   if (oauthResponse) return oauthResponse;

package/src/server/setup-page.test.ts

@@ -0,0 +1,325 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, mock, test } from 'bun:test';
+import { createHmac } from 'crypto';
+
+/**
+ * Tests for the operator-facing setup page at `/`. Covers:
+ *   - unauthenticated GET renders the login form
+ *   - POST credential validation (bad key → 401; good key → 302 + Set-Cookie)
+ *   - cookie attributes (HttpOnly, SameSite, Path, Max-Age; Secure only on https)
+ *   - HMAC-cookie authentication: valid cookie → profiles page; stale cookie → login form
+ *   - only services with ≥1 configured profile appear on the page
+ *   - embedded JSON payload escapes `<` to avoid `</script>` injection
+ *
+ * The page calls `listProfiles()` from ../config/config-manager, which reads
+ * the real ~/.config/agentio/config.json. Bun caches `os.homedir()` at
+ * process start, so HOME overrides don't work here — instead we use
+ * `mock.module` to replace `listProfiles` with a controllable stub.
+ */
+
+const API_KEY = 'srv_test_setup_page_api_key';
+const COOKIE_NAME = 'agentio_setup';
+const COOKIE_MAGIC = 'agentio-setup-v1';
+
+function expectedCookieValue(apiKey: string): string {
+  return createHmac('sha256', apiKey).update(COOKIE_MAGIC).digest('base64url');
+}
+
+interface FakeProfile {
+  service: string;
+  profiles: { name: string; readOnly?: boolean }[];
+}
+
+// Mutable container the mock consults on each call.
+let currentProfiles: FakeProfile[] = [];
+
+function setProfiles(fixture: Record<string, string[]>): void {
+  currentProfiles = Object.entries(fixture).map(([service, names]) => ({
+    service,
+    profiles: names.map((n) => ({ name: n })),
+  }));
+}
+
+type HandleRequest = (typeof import('./http'))['handleRequest'];
+type CreateOAuthStore = (typeof import('./oauth-store'))['createOAuthStore'];
+type ServerContext = import('./http').ServerContext;
+
+let handleRequest: HandleRequest;
+let createOAuthStore: CreateOAuthStore;
+let ctx: ServerContext;
+
+beforeAll(async () => {
+  // Load the real config-manager first so we can preserve every export
+  // other modules in the graph depend on (CONFIG_DIR, loadConfig, etc.),
+  // then override ONLY listProfiles with a controllable stub. This has
+  // to happen BEFORE the module-under-test is imported — once './http'
+  // loads, the dependency is bound.
+  const realConfig = await import('../config/config-manager');
+  mock.module('../config/config-manager', () => ({
+    ...realConfig,
+    listProfiles: async (service?: string) => {
+      if (service) {
+        return currentProfiles.filter((s) => s.service === service);
+      }
+      return currentProfiles;
+    },
+  }));
+
+  ({ handleRequest } = await import('./http'));
+  ({ createOAuthStore } = await import('./oauth-store'));
+  ctx = {
+    apiKey: API_KEY,
+    oauthStore: createOAuthStore({ save: async () => {} }),
+  };
+});
+
+beforeEach(() => {
+  currentProfiles = [];
+});
+
+afterEach(() => {
+  currentProfiles = [];
+});
+
+function req(
+  method: string,
+  path: string,
+  init: { cookie?: string; xfProto?: string; body?: string; contentType?: string } = {}
+): Request {
+  const headers = new Headers();
+  if (init.cookie) headers.set('cookie', init.cookie);
+  if (init.xfProto) headers.set('x-forwarded-proto', init.xfProto);
+  if (init.contentType) headers.set('content-type', init.contentType);
+  return new Request(`http://localhost:9999${path}`, {
+    method,
+    headers,
+    body: init.body,
+  });
+}
+
+function formBody(fields: Record<string, string>): string {
+  return new URLSearchParams(fields).toString();
+}
+
+const FORM = 'application/x-www-form-urlencoded';
+
+/* ------------------------------------------------------------------ */
+/* unauthenticated GET                                                 */
+/* ------------------------------------------------------------------ */
+
+describe('GET / — unauthenticated', () => {
+  test('renders HTML login form with 200', async () => {
+    const res = await handleRequest(req('GET', '/'), ctx);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toBe('text/html; charset=utf-8');
+    const html = await res.text();
+    expect(html).toContain('<title>agentio MCP setup</title>');
+    expect(html).toContain('name="api_key"');
+    expect(html).toContain('type="password"');
+    expect(html).toContain('action="/"');
+  });
+
+  test('does NOT set a cookie on the login form render', async () => {
+    const res = await handleRequest(req('GET', '/'), ctx);
+    expect(res.headers.get('set-cookie')).toBeNull();
+  });
+
+  test('does NOT leak profile data to an unauthenticated caller', async () => {
+    setProfiles({ gmail: ['work-secret', 'personal-secret'] });
+    const res = await handleRequest(req('GET', '/'), ctx);
+    const html = await res.text();
+    expect(html).not.toContain('work-secret');
+    expect(html).not.toContain('personal-secret');
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* POST login                                                          */
+/* ------------------------------------------------------------------ */
+
+describe('POST / — login', () => {
+  test('missing api_key → 401 with error message, no cookie', async () => {
+    const res = await handleRequest(
+      req('POST', '/', { contentType: FORM, body: formBody({}) }),
+      ctx
+    );
+    expect(res.status).toBe(401);
+    expect(await res.text()).toContain('Invalid API key');
+    expect(res.headers.get('set-cookie')).toBeNull();
+  });
+
+  test('wrong api_key → 401 with error message, no cookie', async () => {
+    const res = await handleRequest(
+      req('POST', '/', {
+        contentType: FORM,
+        body: formBody({ api_key: 'not-the-right-key' }),
+      }),
+      ctx
+    );
+    expect(res.status).toBe(401);
+    expect(await res.text()).toContain('Invalid API key');
+    expect(res.headers.get('set-cookie')).toBeNull();
+  });
+
+  test('correct api_key → 302 to /, sets cookie with expected attributes', async () => {
+    const res = await handleRequest(
+      req('POST', '/', {
+        contentType: FORM,
+        body: formBody({ api_key: API_KEY }),
+      }),
+      ctx
+    );
+    expect(res.status).toBe(302);
+    expect(res.headers.get('location')).toBe('/');
+
+    const setCookie = res.headers.get('set-cookie');
+    expect(setCookie).not.toBeNull();
+    expect(setCookie).toContain(`${COOKIE_NAME}=`);
+    expect(setCookie).toContain('HttpOnly');
+    expect(setCookie).toContain('SameSite=Strict');
+    expect(setCookie).toContain('Path=/');
+    expect(setCookie).toMatch(/Max-Age=\d+/);
+
+    // Cookie value is deterministic HMAC(apiKey, magic).
+    expect(setCookie).toContain(expectedCookieValue(API_KEY));
+  });
+
+  test('Secure flag added when x-forwarded-proto=https', async () => {
+    const res = await handleRequest(
+      req('POST', '/', {
+        contentType: FORM,
+        xfProto: 'https',
+        body: formBody({ api_key: API_KEY }),
+      }),
+      ctx
+    );
+    expect(res.headers.get('set-cookie')).toContain('Secure');
+  });
+
+  test('Secure flag NOT added on plain http', async () => {
+    const res = await handleRequest(
+      req('POST', '/', {
+        contentType: FORM,
+        body: formBody({ api_key: API_KEY }),
+      }),
+      ctx
+    );
+    expect(res.headers.get('set-cookie')).not.toContain('Secure');
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* authenticated GET                                                   */
+/* ------------------------------------------------------------------ */
+
+describe('GET / — authenticated (valid cookie)', () => {
+  const validCookie = () => `${COOKIE_NAME}=${expectedCookieValue(API_KEY)}`;
+
+  test('valid cookie → renders the profiles page', async () => {
+    setProfiles({ gmail: ['work'] });
+    const res = await handleRequest(
+      req('GET', '/', { cookie: validCookie() }),
+      ctx
+    );
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    expect(html).toContain('MCP URL');
+    expect(html).toContain('Claude Code command');
+    expect(html).toContain('type="checkbox"');
+  });
+
+  test('only services with ≥1 profile appear (empty services hidden)', async () => {
+    setProfiles({
+      gmail: ['work', 'personal'],
+      slack: ['team'],
+      jira: [], // empty — should NOT render a section
+    });
+    const res = await handleRequest(
+      req('GET', '/', { cookie: validCookie() }),
+      ctx
+    );
+    const html = await res.text();
+    expect(html).toContain('<h2>gmail</h2>');
+    expect(html).toContain('value="gmail:work"');
+    expect(html).toContain('value="gmail:personal"');
+    expect(html).toContain('<h2>slack</h2>');
+    expect(html).toContain('value="slack:team"');
+    expect(html).not.toContain('<h2>jira</h2>');
+  });
+
+  test('no configured profiles → empty-state message, no checkboxes', async () => {
+    setProfiles({});
+    const res = await handleRequest(
+      req('GET', '/', { cookie: validCookie() }),
+      ctx
+    );
+    const html = await res.text();
+    expect(html).toContain('No profiles configured');
+    expect(html).not.toContain('type="checkbox"');
+  });
+
+  test('embedded JSON does not contain `</` that would close the script tag', async () => {
+    setProfiles({ gmail: ['work'] });
+    const res = await handleRequest(
+      req('GET', '/', { cookie: validCookie() }),
+      ctx
+    );
+    const html = await res.text();
+    const marker = 'id="page-data"';
+    const scriptIdx = html.indexOf(marker);
+    expect(scriptIdx).toBeGreaterThan(-1);
+    const open = html.indexOf('>', scriptIdx) + 1;
+    const close = html.indexOf('</script>', open);
+    const dataJson = html.slice(open, close);
+    // No `</` inside the JSON — that's what the `\\u003c` escape guarantees.
+    expect(dataJson).not.toContain('</');
+    // The data block IS the JSON payload with origin set.
+    expect(JSON.parse(dataJson)).toEqual({ origin: 'http://localhost:9999' });
+  });
+
+  test('stale cookie (HMAC of a different api key) → renders login form', async () => {
+    setProfiles({ gmail: ['work'] });
+    const staleCookie = `${COOKIE_NAME}=${expectedCookieValue('some-old-key')}`;
+    const res = await handleRequest(
+      req('GET', '/', { cookie: staleCookie }),
+      ctx
+    );
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    expect(html).toContain('name="api_key"');
+    expect(html).not.toContain('MCP URL');
+  });
+
+  test('malformed cookie header does not crash', async () => {
+    const res = await handleRequest(
+      req('GET', '/', { cookie: 'garbage;;===;' }),
+      ctx
+    );
+    expect(res.status).toBe(200);
+    expect(await res.text()).toContain('name="api_key"');
+  });
+
+  test('origin reflects x-forwarded-host/proto (behind a proxy)', async () => {
+    setProfiles({ gmail: ['work'] });
+    const headers = new Headers();
+    headers.set('cookie', validCookie());
+    headers.set('x-forwarded-proto', 'https');
+    headers.set('x-forwarded-host', 'mcp.example.com');
+    const res = await handleRequest(
+      new Request('http://localhost:9999/', { method: 'GET', headers }),
+      ctx
+    );
+    const html = await res.text();
+    expect(html).toContain('{"origin":"https://mcp.example.com"}');
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* method dispatch                                                     */
+/* ------------------------------------------------------------------ */
+
+describe('method dispatch at /', () => {
+  test('DELETE / falls through to 404 (not handled by setup page)', async () => {
+    const res = await handleRequest(req('DELETE', '/'), ctx);
+    expect(res.status).toBe(404);
+  });
+});

package/src/server/setup-page.ts

@@ -0,0 +1,365 @@
+/**
+ * Setup page served at `/` — lets an operator (who holds the API key) pick
+ * services/profiles and generate the MCP URL + `claude mcp add` snippet.
+ *
+ * Auth model: a small login form asks for the API key, then we set an
+ * HttpOnly cookie whose value is HMAC(apiKey, magic). Every request
+ * re-derives that HMAC and compares. If the key rotates, old cookies
+ * stop validating — no session store needed.
+ */
+
+import { createHmac } from 'crypto';
+
+import { listProfiles } from '../config/config-manager';
+import type { ServerContext } from './http';
+import { constantTimeEquals, getRequestOrigin } from './oauth';
+
+const COOKIE_NAME = 'agentio_setup';
+const COOKIE_MAGIC = 'agentio-setup-v1';
+const COOKIE_MAX_AGE_SECONDS = 60 * 60 * 12; // 12h
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function signApiKey(apiKey: string): string {
+  return createHmac('sha256', apiKey).update(COOKIE_MAGIC).digest('base64url');
+}
+
+function parseCookies(header: string | null): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!header) return out;
+  for (const part of header.split(';')) {
+    const [name, ...rest] = part.trim().split('=');
+    if (!name) continue;
+    try {
+      out[name] = decodeURIComponent(rest.join('='));
+    } catch {
+      out[name] = rest.join('=');
+    }
+  }
+  return out;
+}
+
+function isAuthenticated(req: Request, ctx: ServerContext): boolean {
+  const cookies = parseCookies(req.headers.get('cookie'));
+  const token = cookies[COOKIE_NAME];
+  if (!token) return false;
+  return constantTimeEquals(token, signApiKey(ctx.apiKey));
+}
+
+function isHttps(req: Request): boolean {
+  const forwarded = req.headers.get('forwarded');
+  if (forwarded && /proto=https/i.test(forwarded)) return true;
+  const xfp = req.headers.get('x-forwarded-proto');
+  if (xfp && xfp.toLowerCase() === 'https') return true;
+  return new URL(req.url).protocol === 'https:';
+}
+
+function buildCookieHeader(value: string, secure: boolean): string {
+  const parts = [
+    `${COOKIE_NAME}=${encodeURIComponent(value)}`,
+    'HttpOnly',
+    'SameSite=Strict',
+    'Path=/',
+    `Max-Age=${COOKIE_MAX_AGE_SECONDS}`,
+  ];
+  if (secure) parts.push('Secure');
+  return parts.join('; ');
+}
+
+/* ------------------------------------------------------------------ */
+/* HTML                                                                */
+/* ------------------------------------------------------------------ */
+
+const BASE_CSS = `
+:root { color-scheme: light dark; }
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+  max-width: 640px;
+  margin: 6vh auto;
+  padding: 0 24px;
+  line-height: 1.5;
+}
+h1 { font-size: 1.4rem; margin-bottom: 0.4rem; }
+h2 {
+  font-size: 0.85rem;
+  margin: 0 0 0.5rem;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: #666;
+}
+.meta { color: #666; font-size: 0.9rem; margin-bottom: 1.5rem; }
+.meta code { font-size: 0.85rem; }
+form { display: flex; flex-direction: column; gap: 0.75rem; }
+label { font-weight: 600; }
+input[type=password], input[type=text], textarea {
+  padding: 0.6rem 0.75rem;
+  font-size: 0.95rem;
+  font-family: ui-monospace, "SF Mono", Menlo, monospace;
+  border: 1px solid #888;
+  border-radius: 6px;
+  width: 100%;
+  box-sizing: border-box;
+  background: transparent;
+  color: inherit;
+}
+textarea { resize: vertical; }
+button {
+  padding: 0.6rem 1rem;
+  font-size: 1rem;
+  font-weight: 600;
+  background: #2563eb;
+  color: white;
+  border: none;
+  border-radius: 6px;
+  cursor: pointer;
+}
+button:hover { background: #1d4ed8; }
+.error {
+  background: #fee;
+  color: #900;
+  padding: 0.6rem 0.75rem;
+  border-radius: 6px;
+  border: 1px solid #fcc;
+  margin: 0;
+}
+`;
+
+const PROFILES_CSS = `
+.services { display: flex; flex-direction: column; gap: 0.8rem; }
+section.service {
+  border: 1px solid #ddd;
+  border-radius: 6px;
+  padding: 0.6rem 0.9rem;
+}
+label.profile {
+  display: block;
+  font-weight: normal;
+  padding: 0.15rem 0;
+  font-family: ui-monospace, "SF Mono", Menlo, monospace;
+  font-size: 0.9rem;
+  cursor: pointer;
+}
+label.profile input { margin-right: 0.5rem; }
+.output { display: flex; flex-direction: column; gap: 0.4rem; margin-top: 1.4rem; }
+.output label { font-weight: 600; font-size: 0.9rem; }
+.output .row { display: flex; gap: 0.5rem; }
+.output .row input, .output .row textarea { flex: 1; }
+.output button {
+  align-self: flex-start;
+  font-size: 0.85rem;
+  padding: 0.5rem 0.9rem;
+}
+@media (prefers-color-scheme: dark) {
+  section.service { border-color: #444; }
+  input[type=password], input[type=text], textarea { border-color: #555; }
+}
+`;
+
+function loginFormHtml(errorMessage?: string): string {
+  const errorBlock = errorMessage
+    ? `<p class="error">${escapeHtml(errorMessage)}</p>`
+    : '';
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>agentio MCP setup</title>
+<style>${BASE_CSS}</style>
+</head>
+<body>
+<h1>agentio MCP setup</h1>
+<p class="meta">Enter your agentio API key to continue.</p>
+${errorBlock}
+<form method="post" action="/">
+  <label for="api_key">agentio API key</label>
+  <input id="api_key" name="api_key" type="password" autocomplete="off" autofocus required>
+  <button type="submit">Continue</button>
+</form>
+</body>
+</html>`;
+}
+
+interface ServiceProfileList {
+  service: string;
+  profiles: string[];
+}
+
+function profilesPageHtml(origin: string, configured: ServiceProfileList[]): string {
+  const dataJson = JSON.stringify({ origin }).replace(/</g, '\\u003c');
+
+  const sectionsHtml = configured
+    .map((s) => {
+      const items = s.profiles
+        .map((p) => {
+          const value = `${s.service}:${p}`;
+          return `    <label class="profile"><input type="checkbox" name="sp" value="${escapeHtml(
+            value
+          )}"> ${escapeHtml(p)}</label>`;
+        })
+        .join('\n');
+      return `  <section class="service">
+    <h2>${escapeHtml(s.service)}</h2>
+${items}
+  </section>`;
+    })
+    .join('\n');
+
+  const emptyMessage =
+    configured.length === 0
+      ? `<p class="meta">No profiles configured yet. Add some with <code>agentio &lt;service&gt; profile add</code> in the CLI that owns this server.</p>`
+      : '';
+
+  const body =
+    configured.length === 0
+      ? emptyMessage
+      : `<div class="services">
+${sectionsHtml}
+</div>
+<div class="output">
+  <label for="url">MCP URL</label>
+  <div class="row"><input id="url" type="text" readonly></div>
+  <button id="copy-url" type="button">Copy URL</button>
+</div>
+<div class="output">
+  <label for="snippet">Claude Code command</label>
+  <div class="row"><textarea id="snippet" readonly rows="2"></textarea></div>
+  <button id="copy-snippet" type="button">Copy command</button>
+</div>`;
+
+  const script =
+    configured.length === 0
+      ? ''
+      : `<script id="page-data" type="application/json">${dataJson}</script>
+<script>
+(function() {
+  const data = JSON.parse(document.getElementById('page-data').textContent);
+  const urlEl = document.getElementById('url');
+  const snipEl = document.getElementById('snippet');
+  const boxes = document.querySelectorAll('input[type=checkbox][name=sp]');
+
+  function recompute() {
+    const selected = Array.from(boxes).filter(b => b.checked).map(b => b.value);
+    const base = data.origin + '/mcp';
+    const url = selected.length
+      ? base + '?services=' + encodeURIComponent(selected.join(','))
+      : base;
+    urlEl.value = url;
+    snipEl.value = 'claude mcp add --scope local --transport http agentio "' + url + '"';
+  }
+
+  boxes.forEach(b => b.addEventListener('change', recompute));
+  recompute();
+
+  function wireCopy(btnId, targetId) {
+    const btn = document.getElementById(btnId);
+    btn.addEventListener('click', async () => {
+      const target = document.getElementById(targetId);
+      try {
+        await navigator.clipboard.writeText(target.value);
+      } catch {
+        target.select();
+        document.execCommand && document.execCommand('copy');
+      }
+      const old = btn.textContent;
+      btn.textContent = 'Copied!';
+      setTimeout(() => { btn.textContent = old; }, 1200);
+    });
+  }
+  wireCopy('copy-url', 'url');
+  wireCopy('copy-snippet', 'snippet');
+})();
+</script>`;
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>agentio MCP setup</title>
+<style>${BASE_CSS}${PROFILES_CSS}</style>
+</head>
+<body>
+<h1>agentio MCP setup</h1>
+<p class="meta">Tick the profiles to expose, then copy the MCP URL or the <code>claude mcp add</code> command.</p>
+${body}
+${script}
+</body>
+</html>`;
+}
+
+/* ------------------------------------------------------------------ */
+/* handlers                                                            */
+/* ------------------------------------------------------------------ */
+
+async function handleSetupGet(
+  req: Request,
+  ctx: ServerContext
+): Promise<Response> {
+  if (!isAuthenticated(req, ctx)) {
+    return new Response(loginFormHtml(), {
+      status: 200,
+      headers: { 'content-type': 'text/html; charset=utf-8' },
+    });
+  }
+
+  const origin = getRequestOrigin(req);
+  const all = await listProfiles();
+  const configured: ServiceProfileList[] = all
+    .filter((s) => s.profiles.length > 0)
+    .map((s) => ({
+      service: s.service,
+      profiles: s.profiles.map((p) => p.name),
+    }));
+
+  return new Response(profilesPageHtml(origin, configured), {
+    status: 200,
+    headers: { 'content-type': 'text/html; charset=utf-8' },
+  });
+}
+
+async function handleSetupPost(
+  req: Request,
+  ctx: ServerContext
+): Promise<Response> {
+  let form: URLSearchParams;
+  try {
+    const body = await req.text();
+    form = new URLSearchParams(body);
+  } catch {
+    return new Response(loginFormHtml('Could not read form body.'), {
+      status: 400,
+      headers: { 'content-type': 'text/html; charset=utf-8' },
+    });
+  }
+
+  const apiKey = form.get('api_key') ?? '';
+  if (!apiKey || !constantTimeEquals(apiKey, ctx.apiKey)) {
+    return new Response(loginFormHtml('Invalid API key.'), {
+      status: 401,
+      headers: { 'content-type': 'text/html; charset=utf-8' },
+    });
+  }
+
+  const cookie = buildCookieHeader(signApiKey(ctx.apiKey), isHttps(req));
+  return new Response(null, {
+    status: 302,
+    headers: { location: '/', 'set-cookie': cookie },
+  });
+}
+
+export async function routeSetup(
+  req: Request,
+  ctx: ServerContext
+): Promise<Response | null> {
+  const url = new URL(req.url);
+  if (url.pathname !== '/') return null;
+  if (req.method === 'GET') return handleSetupGet(req, ctx);
+  if (req.method === 'POST') return handleSetupPost(req, ctx);
+  return null;
+}