@agenthippo-ai/agenthippo 0.1.1 → 1.110.9

package/out/cli/deps.js

@@ -37,12 +37,14 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getDepsDir = getDepsDir;
+exports.resolveFromOwnDeps = resolveFromOwnDeps;
 exports.areDepsInstalled = areDepsInstalled;
 exports.installDeps = installDeps;
 exports.isAutoInstallDisabled = isAutoInstallDisabled;
 exports.ensureDeps = ensureDeps;
 exports.getClaudeSdkCliPath = getClaudeSdkCliPath;
 exports.getCodexSdkBinaryPath = getCodexSdkBinaryPath;
+exports.installedEngineVersion = installedEngineVersion;
 /**
  * CLI Dependency Management
  *
@@ -50,6 +52,7 @@ exports.getCodexSdkBinaryPath = getCodexSdkBinaryPath;
  * This lets npm/bun handle platform-specific binaries automatically.
  */
 const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
 const utils_1 = require("./utils");
@@ -84,11 +87,60 @@ function resolveEngineDeps() {
 // Dependencies required for the engines (resolved once at startup).
 const ENGINE_DEPS = resolveEngineDeps();
 /**
- * Get the deps directory (next to the binary)
+ * Where engine SDKs are installed.
+ *
+ * Normally beside the binary — a self-contained install that survives `$HOME` changes. But
+ * `process.execPath` is the *interpreter* when the CLI runs as `node out/cli/index.js`, which
+ * on a locked-down host means `/usr/bin`, and the first run dies with
+ * `EACCES: mkdir '/usr/bin/.agenthippo-deps'` (observed on Amazon Linux, 2026-07-27). A
+ * runtime must not need write access to the system bin dir, so fall back to the agent home.
  */
 function getDepsDir() {
     const binaryDir = path.dirname(process.execPath);
-    return path.join(binaryDir, branding_1.AGENTIDE_DEPS_DIR_NAME);
+    const beside = path.join(binaryDir, branding_1.AGENTIDE_DEPS_DIR_NAME);
+    if (fs.existsSync(beside)) {
+        return beside;
+    }
+    try {
+        fs.accessSync(binaryDir, fs.constants.W_OK);
+        return beside;
+    }
+    catch {
+        // Not writable (system node, read-only image, non-root user): use the agent home.
+        return path.join(os.homedir(), branding_1.AGENTIDE_DIR_NAME, branding_1.AGENTIDE_DEPS_DIR_NAME);
+    }
+}
+/**
+ * Engine SDKs resolved from the CLI's OWN dependency tree.
+ *
+ * When the runtime ships as a node app (`node out/cli/index.js` beside a `node_modules/`) the
+ * SDKs are already installed as ordinary dependencies — there is nothing to fetch, and asking
+ * the user to set CLAUDE_CODE_PATH by hand for a dependency we declare ourselves is a
+ * papercut that costs a deployment. `require.resolve` finds them wherever the tree lives.
+ */
+function resolveFromOwnDeps(pkgName, relativeFile) {
+    // A node_modules walk, deliberately, rather than `require.resolve`. Neither SDK can be
+    // resolved by specifier: @anthropic-ai/claude-agent-sdk publishes an `exports` map that
+    // omits ./cli.js (deep resolve → ERR_PACKAGE_PATH_NOT_EXPORTED) and @openai/codex declares
+    // no main/exports at all, only a `bin` (bare resolve → MODULE_NOT_FOUND). Both were
+    // verified against the shipped versions on 2026-07-27. Walking for the file we actually
+    // want is immune to how a package chooses to advertise itself.
+    let dir = __dirname;
+    for (let hops = 0; hops < 8; hops++) {
+        const candidate = path.join(dir, 'node_modules', ...pkgName.split('/'), ...relativeFile.split('/'));
+        try {
+            if (fs.existsSync(candidate)) {
+                return candidate;
+            }
+        }
+        catch { /* keep walking */ }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    return undefined;
 }
 /**
  * Check if engine dependencies are installed
@@ -183,6 +235,14 @@ async function ensureDeps(verbose = false) {
     if (areDepsInstalled()) {
         return;
     }
+    // Already satisfied by our own dependency tree (node-app runtime): nothing to install, and
+    // attempting it would fail on a read-only or non-writable install dir for no benefit.
+    if (resolveFromOwnDeps('@anthropic-ai/claude-agent-sdk', 'cli.js') && resolveFromOwnDeps('@openai/codex', 'bin/codex.js')) {
+        if (verbose) {
+            console.error(`${utils_1.COLORS.dim}Engine SDKs resolved from the CLI's own node_modules — skipping install.${utils_1.COLORS.reset}`);
+        }
+        return;
+    }
     if (isAutoInstallDisabled()) {
         if (verbose) {
             console.error(`${utils_1.COLORS.dim}AGENTHIPPO_NO_AUTO_INSTALL set — skipping engine dependency install (expecting a self-contained image).${utils_1.COLORS.reset}`);
@@ -236,3 +296,47 @@ function getCodexPlatform() {
     }
     return undefined;
 }
+/**
+ * The engine version actually installed next to this binary.
+ *
+ * Reported on the lease poll so the console can answer "what is the fleet really running?" —
+ * pack version alone cannot explain a behaviour change that came from an engine upgrade, and the
+ * CLI is NOT engine-version agnostic (see AGENTIDE_CODEX_CONFIG_VERSION: config we write is only
+ * valid on codex >= 0.131, and getting it wrong silently cancels headless tool calls).
+ *
+ * Best effort by design: a deployment that vendors its engines elsewhere reports nothing rather
+ * than guessing, and the console shows a dash. Never throws — this is on the boot path.
+ *
+ * Expect nothing under a CONTAINER sandbox: there the engine runs inside the sandbox image, not
+ * beside serve, so serve genuinely does not know its version and the image digest is what
+ * identifies that build. Reporting serve's own (absent) copy would be a guess about someone
+ * else's filesystem. Process sandboxes and in-process runs share this binary's deps, so those
+ * report truthfully.
+ */
+function installedEngineVersion(engine) {
+    const pkg = engine === 'codex' ? path.join('@openai', 'codex')
+        : engine === 'claude' ? path.join('@anthropic-ai', 'claude-agent-sdk')
+            : undefined;
+    if (!pkg) {
+        return undefined;
+    }
+    const candidates = [
+        path.join(getDepsDir(), 'node_modules', pkg, 'package.json'),
+        // Runtime images install engines globally rather than beside the binary.
+        path.join('/usr/local/lib/node_modules', pkg, 'package.json'),
+        path.join('/usr/lib/node_modules', pkg, 'package.json'),
+    ];
+    for (const candidate of candidates) {
+        try {
+            if (!fs.existsSync(candidate)) {
+                continue;
+            }
+            const parsed = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+            if (parsed.version) {
+                return parsed.version;
+            }
+        }
+        catch { /* unreadable or malformed — try the next candidate */ }
+    }
+    return undefined;
+}

package/out/cli/idp-init.js

@@ -0,0 +1,338 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) AgentHippo.ai. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderIdpArtifacts = renderIdpArtifacts;
+/**
+ * `agenthippo idp init` — generator for the central IdP stack (PLAN/deploy.md, "customer 0").
+ *
+ * Why this exists: the org IdP used to be static files checked into this source repo
+ * (enterprise-deploy/idp/), which meant the actual identity routes could drift from
+ * renderIdentityLayer() (fixed once already) AND — the bigger problem — an enterprise
+ * customer standing up their own IdP had no way to get any of it at all, since they only
+ * receive the compiled `agenthippo` binary, never this repo. Generating it here, from the
+ * same shared identity/auth-env/Dockerfile renderers every `deploy init` target already
+ * uses, fixes both: it ships in the binary, and it can never drift from what agents expect.
+ *
+ * AgentHippo's own auth.agenthippo.ai instance is "customer 0" — stood up with this exact
+ * command, not a bespoke internal setup.
+ */
+const identity_1 = require("./deploy/layers/identity");
+const deploy_init_1 = require("./deploy-init");
+function resolveCookieDomain(ctx) {
+    if (ctx.cookieDomain?.trim()) {
+        return ctx.cookieDomain.trim();
+    }
+    const parts = ctx.hostname.split('.');
+    return parts.length > 2 ? `.${parts.slice(-2).join('.')}` : `.${ctx.hostname}`;
+}
+function renderIdpComposeYaml() {
+    return [
+        '# Central IdP. See PLAN/deploy-runbook.md scenario E/F.',
+        '#',
+        '#   ./run.sh',
+        '#',
+        '# Env split (matches `agenthippo deploy init`):',
+        '#   ~/.agent-hippo/.env (+ optional ./.env)           — hostname only',
+        '#   ~/.agent-hippo/.env.auth (+ optional ./.env.auth) — JWT/OAuth; broker + oauth2-proxy ONLY',
+        '# Profiles: edge (SSO stack), tunnel (Cloudflare → Caddy)',
+        '# Org identity infra only — no agent runs here. Per-agent edges are generated separately',
+        '# by `agenthippo deploy init` and deployed on their own host/service.',
+        'services:',
+        '  oauth2-proxy:',
+        '    profiles: ["edge"]',
+        '    image: quay.io/oauth2-proxy/oauth2-proxy:v7.7.1',
+        '    env_file:',
+        '      - path: ${HOME}/.agent-hippo/.env',
+        '        required: false',
+        '      - path: .env',
+        '        required: false',
+        '      - path: ${HOME}/.agent-hippo/.env.auth',
+        '        required: false',
+        '      - path: .env.auth',
+        '        required: false',
+        '    environment:',
+        '      OAUTH2_PROXY_HTTP_ADDRESS: 0.0.0.0:4180',
+        '      OAUTH2_PROXY_UPSTREAMS: file:///dev/null',
+        '      OAUTH2_PROXY_SET_XAUTHREQUEST: "true"',
+        '      OAUTH2_PROXY_PASS_AUTHORIZATION_HEADER: "true"',
+        '      OAUTH2_PROXY_SKIP_PROVIDER_BUTTON: "true"',
+        '      OAUTH2_PROXY_REVERSE_PROXY: "true"',
+        '    expose: ["4180"]',
+        '',
+        '  auth-broker:',
+        '    profiles: ["edge"]',
+        '    build:',
+        '      context: .',
+        '      dockerfile: Dockerfile.auth-broker',
+        '    env_file:',
+        '      - path: ${HOME}/.agent-hippo/.env',
+        '        required: false',
+        '      - path: .env',
+        '        required: false',
+        '      - path: ${HOME}/.agent-hippo/.env.auth',
+        '        required: false',
+        '      - path: .env.auth',
+        '        required: false',
+        '    environment:',
+        '      AGENTHIPPO_AUTH_PORT: "9780"',
+        '      AGENTHIPPO_AUTH_DATA_DIR: /data',
+        '      # The broker now defaults to binding 127.0.0.1 and REFUSES a public bind unless told',
+        '      # otherwise. Here it must listen on the container interface, because Caddy reaches it',
+        '      # as `auth-broker:9780` over the compose network — a loopback bind makes it unreachable.',
+        '      # Safe: the port is `expose`d, never published to the host, so the only thing that can',
+        '      # dial it is another service on this network.',
+        '      AGENTHIPPO_AUTH_BIND: "0.0.0.0"',
+        '      AGENTHIPPO_AUTH_ALLOW_PUBLIC_BIND: "1"',
+        '      # Shared secret proving an X-Auth-Request-Email came from THIS Caddy. Without it the',
+        '      # broker treats that header as unverified and 401s the forward_auth-gated routes.',
+        '      # No default on purpose: compose FAILS to start rather than silently running with an',
+        '      # empty secret on both sides, which would accept every caller. Put it in ./.env.',
+        '      AGENTHIPPO_AUTH_PROXY_SECRET: "${AGENTHIPPO_AUTH_PROXY_SECRET:?set AGENTHIPPO_AUTH_PROXY_SECRET in .env (openssl rand -hex 32)}"',
+        '      # Proxy hops in front of the broker: 1 = Caddy only (edge profile), 2 = Cloudflare',
+        '      # Tunnel → Caddy (run.sh sets 2; at 1 the rate limiter would key every tunnel',
+        '      # client on cloudflared\'s IP — one shared bucket).',
+        '      AGENTHIPPO_XFF_TRUSTED_HOPS: ${AGENTHIPPO_XFF_TRUSTED_HOPS:-1}',
+        '    volumes: ["auth-broker-data:/data"]',
+        '    expose: ["9780"]',
+        '',
+        '  caddy:',
+        '    profiles: ["edge"]',
+        '    image: caddy:2.8-alpine',
+        '    env_file:',
+        '      - path: ${HOME}/.agent-hippo/.env',
+        '        required: false',
+        '      - path: .env',
+        '        required: false',
+        '    # With the tunnel profile, set AGENTHIPPO_CADDY_BIND=127.0.0.1 so a public-IP host',
+        '    # cannot be hit directly on 80/443, bypassing Cloudflare.',
+        '    # Bare-metal / BYO nginx or ALB already on 80/443? Set AGENTHIPPO_CADDY_HTTP_PORT /',
+        '    # AGENTHIPPO_CADDY_HTTPS_PORT to alternate host ports and point your own reverse proxy',
+        '    # at them — the container still listens on 80 internally, only the host mapping moves.',
+        '    ports:',
+        '      - "${AGENTHIPPO_CADDY_BIND:-0.0.0.0}:${AGENTHIPPO_CADDY_HTTP_PORT:-80}:80"',
+        '      - "${AGENTHIPPO_CADDY_BIND:-0.0.0.0}:${AGENTHIPPO_CADDY_HTTPS_PORT:-443}:443"',
+        '    environment:',
+        '      # Caddy stamps this on the two broker hops that forward a verified X-Auth-Request-Email',
+        '      # (/oauth/authorize, /oauth/browser-login). Same value the broker checks; same fail-closed',
+        '      # rule — compose refuses to start rather than send an empty secret.',
+        '      AGENTHIPPO_AUTH_PROXY_SECRET: "${AGENTHIPPO_AUTH_PROXY_SECRET:?set AGENTHIPPO_AUTH_PROXY_SECRET in .env (openssl rand -hex 32)}"',
+        '    volumes:',
+        '      - ./Caddyfile:/etc/caddy/Caddyfile:ro',
+        '      # Colocated agents (deploy init --colocate) drop a route snippet here — see Caddyfile.',
+        '      - ./agents:/etc/caddy/agents:ro',
+        '    networks: [default, colocate]',
+        '    depends_on: [oauth2-proxy, auth-broker]',
+        '',
+        '  cloudflared:',
+        '    profiles: ["tunnel"]',
+        '    image: cloudflare/cloudflared:2024.12.2',
+        '    restart: unless-stopped',
+        '    command: tunnel --config /etc/cloudflared/config.yml run',
+        '    volumes:',
+        '      - ./cloudflared.yml:/etc/cloudflared/config.yml:ro',
+        '      # Set by run.sh from its argument (./run.sh /path/to/tunnel-credentials.json);',
+        '      # falls back to the conventional location for a direct `docker compose` invocation.',
+        '      - ${AGENTHIPPO_TUNNEL_CREDENTIALS:-${HOME}/.agent-hippo/tunnel-credentials.json}:/etc/cloudflared/credentials.json:ro',
+        '    depends_on: [caddy]',
+        '',
+        'volumes:',
+        '  auth-broker-data:',
+        '',
+        'networks:',
+        '  default:',
+        '  # Stable, explicitly-named network (not the implicit "idp_default") so a colocated agent\'s',
+        '  # own compose project can join it reliably regardless of which directory `docker compose`',
+        '  # runs from. Only Caddy needs it — its per-agent snippets `reverse_proxy` straight to the',
+        '  # agent container by name; auth-broker is reached over the (already-shared) default network.',
+        '  colocate:',
+        '    name: agenthippo-idp-colocate',
+        '',
+    ].join('\n');
+}
+function renderIdpCaddyfile() {
+    const identityLines = (0, identity_1.renderIdentityLayer)({
+        mode: 'self-issued',
+        oauth2ProxyAddr: 'oauth2-proxy:4180',
+        authBrokerAddr: 'auth-broker:9780',
+        healthProxy: ['    reverse_proxy auth-broker:9780'],
+        // No agent behind the IdP: a Bearer request to /v1/* doesn't exist here (404, not a
+        // silent pass-through), and an unauthenticated browser sees a plain confirmation once
+        // past the SSO gate.
+        agentProxy: ['    respond "not_found" 404'],
+        catchallBody: ['    respond "AgentHippo IdP" 200'],
+    });
+    return [
+        '# SSO edge + Cloudflare Tunnel. Set AGENTHIPPO_PUBLIC_HOSTNAME in .env (Caddy reads it below).',
+        '# TLS terminates at Cloudflare; origin listens on HTTP only.',
+        '{',
+        '  auto_https off',
+        '}',
+        '',
+        '# Same-host colocation: agents deployed with `deploy init --ingress edge-fed --colocate`',
+        '# on THIS host ship a route snippet instead of their own Caddy/oauth2-proxy/auth-broker.',
+        '# Drop it in ./agents/<name>.caddy (mounted in docker-compose.yml) and',
+        '# `docker compose exec caddy caddy reload --config /etc/caddy/Caddyfile` to pick it up —',
+        '# no rebuild, no restart of the IdP itself.',
+        'import agents/*.caddy',
+        '',
+        `http://{$AGENTHIPPO_PUBLIC_HOSTNAME} {`,
+        ...identityLines,
+        '}',
+        '',
+    ].join('\n');
+}
+/** Render every artifact for `agenthippo idp init` (relative path → file content). Pure: no fs writes. */
+function renderIdpArtifacts(ctx) {
+    const cookieDomain = resolveCookieDomain(ctx);
+    return {
+        'docker-compose.yml': renderIdpComposeYaml(),
+        'Dockerfile.auth-broker': (0, deploy_init_1.renderAuthBrokerDockerfile)(),
+        'Caddyfile': renderIdpCaddyfile(),
+        '.env.example': [
+            '# Caddy hostname for the central IdP. No agent runs on this stack — auth secrets:',
+            '# see .env.auth.example → ~/.agent-hippo/.env.auth (broker + oauth2-proxy only).',
+            '',
+            `AGENTHIPPO_PUBLIC_HOSTNAME=${ctx.hostname}`,
+            '',
+            '# REQUIRED. Shared secret between Caddy and auth-broker, proving that an',
+            '# X-Auth-Request-Email reached the broker through this Caddy rather than from a client',
+            '# that merely found the port. The broker 401s that header without a matching secret, and',
+            '# docker compose refuses to start if this is unset — an empty secret on both sides would',
+            '# accept everyone. It lives HERE (not .env.auth) because Caddy needs it too, and Caddy',
+            '# must not be handed the OAuth client secret or the JWT signing key.',
+            '#   openssl rand -hex 32',
+            'AGENTHIPPO_AUTH_PROXY_SECRET=',
+            '',
+            '# Proxy hops / Caddy bind (optional; run.sh sets XFF hops=2 for tunnel)',
+            '# AGENTHIPPO_XFF_TRUSTED_HOPS=1',
+            '# AGENTHIPPO_CADDY_BIND=0.0.0.0',
+            '',
+            '# Bare metal / BYO nginx or ALB already on 80/443? Rebind Caddy to alternate host ports',
+            '# and point your reverse proxy at them (container still listens on 80 internally):',
+            '# AGENTHIPPO_CADDY_HTTP_PORT=8080',
+            '# AGENTHIPPO_CADDY_HTTPS_PORT=8443',
+            '',
+        ].join('\n'),
+        '.env.auth.example': (0, deploy_init_1.renderAuthEnvExample)({ hostname: ctx.hostname, fed: false, cookieDomain }),
+        'cloudflared.yml.example': [
+            '# Copy to cloudflared.yml; the credentials JSON lives in ~/.agent-hippo/ (never in the repo).',
+            '#   cloudflared tunnel create agenthippo-auth',
+            '#   cp ~/.cloudflared/<tunnel-id>.json ~/.agent-hippo/tunnel-credentials.json',
+            `#   cloudflared tunnel route dns agenthippo-auth ${ctx.hostname}`,
+            'tunnel: REPLACE_WITH_TUNNEL_ID',
+            'credentials-file: /etc/cloudflared/credentials.json',
+            'ingress:',
+            `  - hostname: ${ctx.hostname}`,
+            '    service: http://caddy:80',
+            '  - service: http_status:404',
+            '',
+        ].join('\n'),
+        'run.sh': [
+            '#!/usr/bin/env bash',
+            '# Start central IdP: Caddy + oauth2-proxy + auth-broker (+ Cloudflare tunnel, if requested).',
+            '# No agent here — per-agent edges are generated separately by `agenthippo deploy init`.',
+            '#',
+            '# Usage:',
+            '#   ./run.sh                                       bare metal / BYO nginx or ALB in front',
+            '#   ./run.sh /path/to/tunnel-credentials.json       Cloudflare Tunnel',
+            '#',
+            '# Bare metal / BYO nginx or ALB: run with no argument — starts --profile edge only.',
+            '# If 80/443 are already taken by your reverse proxy, set AGENTHIPPO_CADDY_HTTP_PORT/',
+            '# _HTTPS_PORT in .env first so Caddy rebinds elsewhere.',
+            'set -euo pipefail',
+            'cd "$(dirname "$0")"',
+            'if [[ $# -ge 1 ]]; then',
+            '  export AGENTHIPPO_TUNNEL_CREDENTIALS="$1"',
+            '  [[ -f "$AGENTHIPPO_TUNNEL_CREDENTIALS" ]] || {',
+            '    echo "Tunnel credentials file not found: $AGENTHIPPO_TUNNEL_CREDENTIALS" >&2; exit 1; }',
+            '  # Two proxy hops behind the tunnel (cloudflared → Caddy) — see docker-compose.yml.',
+            '  export AGENTHIPPO_XFF_TRUSTED_HOPS="${AGENTHIPPO_XFF_TRUSTED_HOPS:-2}"',
+            '  docker compose --profile edge --profile tunnel up -d --build',
+            `  echo "IdP: https://\${AGENTHIPPO_PUBLIC_HOSTNAME:-${ctx.hostname}} (via Cloudflare Tunnel)"`,
+            'else',
+            '  echo "No tunnel credentials path given — starting --profile edge only (no tunnel)."',
+            '  echo "Front this host with your own nginx/ALB; see AGENTHIPPO_CADDY_HTTP_PORT/AGENTHIPPO_CADDY_BIND in .env."',
+            '  echo "(To use a Cloudflare Tunnel instead: ./run.sh /path/to/tunnel-credentials.json)"',
+            '  docker compose --profile edge up -d --build',
+            `  echo "IdP: http://\${AGENTHIPPO_PUBLIC_HOSTNAME:-${ctx.hostname}} (behind your own reverse proxy)"`,
+            'fi',
+            '',
+        ].join('\n'),
+        'agents/README.md': [
+            '# Colocated agent routes',
+            '',
+            'Drop `*.caddy` route snippets here for agents deployed on **this same host** via:',
+            '',
+            '```bash',
+            'agenthippo deploy init <pack> --target compose --ingress edge-fed --colocate',
+            '```',
+            '',
+            'That command generates `deploy/agent-route.caddy` (copy it here, renamed to something',
+            'identifying the agent) plus a `docker-compose.yml` containing only the `agent` service',
+            '(no Caddy/oauth2-proxy/auth-broker of its own — it joins this IdP\'s',
+            '`agenthippo-idp-colocate` network and rides the IdP\'s existing edge).',
+            '',
+            'After copying a new snippet in:',
+            '',
+            '```bash',
+            'docker compose exec caddy caddy reload --config /etc/caddy/Caddyfile',
+            '```',
+            '',
+            'No rebuild, no restart of the IdP itself. See `../Caddyfile`\'s `import agents/*.caddy` and',
+            '`PLAN/deploy-runbook.md` scenario F for the full picture.',
+            '',
+        ].join('\n'),
+        'README.md': [
+            '# Central IdP',
+            '',
+            '**One per organization.** Hosts Google SSO (oauth2-proxy) and the IDE auth-broker only —',
+            'no agent runs here. Agent edges are generated and deployed separately.',
+            '',
+            'Generated by `agenthippo idp init` — regenerate (don\'t hand-edit `Caddyfile`, which comes',
+            'straight from the same identity module every agent\'s Caddyfile uses) if you need to change',
+            'routing: that lives in the CLI itself, not in this output.',
+            '',
+            'This stack runs on **any host with Docker** — local laptop, team VM, cloud VM, or on-prem.',
+            '`./run.sh` picks the path below based on whether you pass it a tunnel credentials path.',
+            '',
+            '## Quick start',
+            '',
+            '```bash',
+            'cp .env.example ~/.agent-hippo/.env',
+            'cp .env.auth.example ~/.agent-hippo/.env.auth   # fill in; never put AGENTHIPPO_AUTH_JWT_SECRET in .env',
+            '',
+            '# REQUIRED: the Caddy↔broker proxy secret. It must be visible to `docker compose`',
+            '# ITSELF (compose interpolates it into both services), so it goes in ./.env here —',
+            '# not only in ~/.agent-hippo/.env, which is read by containers but not by compose.',
+            'echo "AGENTHIPPO_AUTH_PROXY_SECRET=$(openssl rand -hex 32)" >> .env',
+            '```',
+            '',
+            'Without it `docker compose up` fails immediately with a message naming the variable. That',
+            'is deliberate: the broker refuses an `X-Auth-Request-Email` that arrives without a matching',
+            '`x-agenthippo-proxy-secret`, so an empty secret on both sides would accept every caller.',
+            '',
+            '**Cloudflare Tunnel** (no public ports to manage yourself):',
+            '',
+            '```bash',
+            'cp cloudflared.yml.example cloudflared.yml   # set tunnel id',
+            'cloudflared tunnel create agenthippo-auth     # writes ~/.cloudflared/<tunnel-id>.json',
+            'cp ~/.cloudflared/<tunnel-id>.json ~/.agent-hippo/tunnel-credentials.json',
+            './run.sh ~/.agent-hippo/tunnel-credentials.json',
+            '```',
+            '',
+            '**Bare metal / BYO nginx or ALB already fronting this host:**',
+            '',
+            '```bash',
+            '# skip cloudflared.yml entirely. If 80/443 are already taken by your reverse proxy,',
+            '# set AGENTHIPPO_CADDY_HTTP_PORT/AGENTHIPPO_CADDY_HTTPS_PORT in .env first.',
+            './run.sh   # no argument — starts --profile edge only',
+            '# point your nginx/ALB at this host\'s Caddy (AGENTHIPPO_CADDY_BIND / _HTTP_PORT above)',
+            '```',
+            '',
+            'Agent edges (e.g. `cs.corp.example`) are separate — see `PLAN/deploy-runbook.md` scenarios E/F.',
+            '',
+        ].join('\n'),
+    };
+}