@nopeek/agent-bridge 0.1.1 → 0.2.1

package/README.md

@@ -4,13 +4,27 @@ Run your own AI agents as **end-to-end-encrypted NoPeek bots** — from your Mac
 
 The bridge is a small always-on process that:
 
-1. **Pairs** with your NoPeek account using a one-time pairing code (`npr_…`) from the NoPeek app ("Connect your computer").
+1. **Pairs** with your NoPeek account — one tap in the NoPeek app ("Connect this computer"), or a one-time pairing code (`npr_…`) if you prefer the terminal.
 2. **Runs every bot you own** — each bot connects as a real NoPeek user with its own server device, publishes MLS key packages, and decrypts messages locally like any other client. The server never sees plaintext.
 3. **Pipes each incoming message to your "brain"** — any shell command (message on stdin, reply on stdout) or any HTTP webhook — and sends the reply back into the encrypted channel.
 
 When you create a new bot in the NoPeek app, the bridge adopts it live over its control connection. No restart, no redeploy.
 
-## Quick start
+## Quick start — one command, then the app
+
+```bash
+npm install -g @nopeek/agent-bridge && nopeek-agent-bridge install
+```
+
+That installs the bridge as a background service (launchd on macOS, `systemd --user` on Linux) that starts at login and waits, **unpaired**. Then, in the NoPeek app on the same computer:
+
+1. **Contacts → My Bots → Connect this computer** — one tap. The app mints the pairing secret and hands it straight to the local bridge; you never see or paste it.
+2. Create bots; each one starts on your computer within seconds.
+3. Per bot: **⋯ → Choose brain…** — pick a detected agent (Hermes, Claude Code, `llm`, Ollama), a custom command, a webhook, or echo. Changes apply to the next message, no restart.
+
+Every bot you own answers in every chat it's a member of. Add a bot to a group in the NoPeek app and it just starts working.
+
+## Quick start — terminal-only (no app steps)
 
 ```bash
 # Zero config: bots run in echo mode ("You said: …") — a smoke test
@@ -23,7 +37,22 @@ npx @nopeek/agent-bridge \
   --brain-cmd 'HERMES_HOME=/Volumes/x10drive/hermes hermes --profile nopeek chat -Q -q "$(cat)"'
 ```
 
-That's it. Every bot you own answers in every chat it's a member of. Add a bot to a group in the NoPeek app and it just starts working.
+The `npr_…` code comes from Settings → Connect your computer (bots) in the app. `install` also accepts `--pair`/`--app-id` to pre-pair the service from the terminal.
+
+## Local control API
+
+The bridge serves a loopback-only HTTP API on `127.0.0.1:8790` — this is what the NoPeek app uses; you can script it too.
+
+| Endpoint | Auth | Purpose |
+| --- | --- | --- |
+| `GET /` | none | Minimal status: `{ok, service, version, paired, machine, uptime}` |
+| `POST /pair` | the `npr_…` secret itself; only accepted while **unpaired** | `{pairingSecret, appId, apiUrl?}` — validate, persist, start bots |
+| `GET /status` | `x-nopeek-runtime: rt_…` | Full status: bots, brains, runtime id |
+| `GET /detect` | `x-nopeek-runtime` | Agent runtimes found on PATH (hermes, claude, llm, ollama) with suggested commands |
+| `PUT /brains` | `x-nopeek-runtime` | `{brainCmd?, brainUrl?, map?: {"<handle>": {cmd|url|echo}|null}}` — applies live, persists |
+| `DELETE /pair` | `x-nopeek-runtime` | Unpair: stop bots, forget the secret (device keys kept) |
+
+The `x-nopeek-runtime` header is the runtime id — a capability only the owner's logged-in app can fetch from the NoPeek server, so a random webpage poking `127.0.0.1` can't read your bot list or change brain commands. Everything the app configures persists to `~/.nopeek-bridge/settings.json` (mode 600).
 
 ## How the brain works
 
@@ -118,17 +147,20 @@ Everything can be set three ways, highest precedence first: **CLI flag → envir
 
 | Flag | Env var | Default | Meaning |
 | --- | --- | --- | --- |
-| `--pair` | `NOPEEK_PAIRING_CODE` | *(required)* | One-time pairing code from the NoPeek app (`npr_…`) |
-| `--app-id` | `NOPEEK_APP_ID` | *(required)* | Your NoPeek app id (shown with the pairing code) |
+| `--pair` | `NOPEEK_PAIRING_CODE` | — | Pairing code (`npr_…`); optional — pairing from the app is easier |
+| `--app-id` | `NOPEEK_APP_ID` | — | Your NoPeek app id (set automatically when pairing from the app) |
 | `--api-url` | `NOPEEK_API_URL` | `https://d3qweh72vesa98.cloudfront.net` | NoPeek API base |
 | `--brain-cmd` | `BRAIN_CMD` | — | Global command brain |
 | `--brain-url` | `BRAIN_URL` | — | Global webhook brain |
 | `--brain-map` | `BRAIN_MAP` | `{}` | Per-handle overrides (JSON) |
 | `--brain-timeout-ms` | `BRAIN_TIMEOUT_MS` | `180000` | Brain timeout (generous: agent runtimes think slowly) |
-| `--port` | `NOPEEK_BRIDGE_PORT` | `8790` | Health endpoint port |
-| `--data-dir` | `NOPEEK_BRIDGE_DATA_DIR` | `./data` | Per-bot device-key store directory |
+| `--port` | `NOPEEK_BRIDGE_PORT` | `8790` | Local control API port (loopback only) |
+| `--data-dir` | `NOPEEK_BRIDGE_DATA_DIR` | `<home>/data` (legacy `./data` honored) | Per-bot device-key store directory |
+| `--home` | `NOPEEK_BRIDGE_HOME` | `~/.nopeek-bridge` | Settings, default data dir, service logs |
 | `--config` | — | `./nopeek-bridge.config.json` | Config file path |
 
+Precedence: CLI flag → env var → `nopeek-bridge.config.json` → `<home>/settings.json` (written when you pair or set brains from the app).
+
 Example config file:
 
 ```json
@@ -174,7 +206,7 @@ Example config file:
 
 ## Running it long-term
 
-Anything that keeps a process alive works. For example, on Linux:
+`nopeek-agent-bridge install` does this for you (launchd LaunchAgent on macOS, systemd user unit on Linux; `uninstall` removes it, `status` queries the running bridge). If you'd rather manage the process yourself, anything that keeps it alive works. For example, on Linux:
 
 ```ini
 # /etc/systemd/system/nopeek-bridge.service

package/dist/bot.d.ts

@@ -12,7 +12,6 @@ export declare class BotRunner {
     handled: number;
     brainKind: string;
     private cfg;
-    private brain;
     private np;
     private stopped;
     private refreshTimer;

package/dist/bot.js

@@ -16,7 +16,6 @@ export class BotRunner {
     handled = 0;
     brainKind;
     cfg;
-    brain;
     np = null;
     stopped = false;
     refreshTimer = null;
@@ -34,9 +33,7 @@ export class BotRunner {
     constructor(info, cfg) {
         this.info = info;
         this.cfg = cfg;
-        const resolved = resolveBrain(cfg, info.handle);
-        this.brain = resolved.brain;
-        this.brainKind = resolved.kind;
+        this.brainKind = resolveBrain(cfg, info.handle).kind;
         const tag = `[bot:@${info.handle}]`;
         this.log = (m) => console.log(`${tag} ${m}`);
         this.logErr = (m) => console.error(`${tag} ${m}`);
@@ -125,7 +122,7 @@ export class BotRunner {
         const np = await NoPeek.connect({
             apiUrl: this.cfg.apiUrl,
             sessionToken: session.sessionToken,
-            appId: this.cfg.appId,
+            appId: this.cfg.appId ?? "", // runners only exist while paired
             userId: this.info.userId,
             platform: "server",
             storage: store,
@@ -253,9 +250,13 @@ export class BotRunner {
         catch {
             /* typing is best-effort */
         }
+        // Resolve the brain PER MESSAGE: the NoPeek app can change it live over the
+        // local API (PUT /brains) and the very next message uses the new one.
+        const resolved = resolveBrain(this.cfg, this.info.handle);
+        this.brainKind = resolved.kind;
         let reply = "";
         try {
-            reply = await this.brain(text, {
+            reply = await resolved.brain(text, {
                 botHandle: this.info.handle,
                 botUserId: this.info.userId,
                 channelId: m.channelId,

package/dist/brain.d.ts

@@ -15,6 +15,6 @@ export interface ResolvedBrain {
 }
 /**
  * Pick the brain for one bot:
- * BRAIN_MAP[handle] (cmd beats url within an entry) > BRAIN_CMD > BRAIN_URL > echo.
+ * BRAIN_MAP[handle] (cmd beats url beats echo within an entry) > BRAIN_CMD > BRAIN_URL > echo.
  */
 export declare function resolveBrain(cfg: BridgeConfig, handle: string): ResolvedBrain;

package/dist/brain.js

@@ -117,7 +117,7 @@ function urlBrain(url, timeoutMs) {
 const echoBrain = async (text) => `You said: ${text}`;
 /**
  * Pick the brain for one bot:
- * BRAIN_MAP[handle] (cmd beats url within an entry) > BRAIN_CMD > BRAIN_URL > echo.
+ * BRAIN_MAP[handle] (cmd beats url beats echo within an entry) > BRAIN_CMD > BRAIN_URL > echo.
  */
 export function resolveBrain(cfg, handle) {
     const override = cfg.brainMap[handle.replace(/^@/, "")];
@@ -125,6 +125,8 @@ export function resolveBrain(cfg, handle) {
         return { brain: cmdBrain(override.cmd, cfg.brainTimeoutMs), kind: "cmd (per-bot)" };
     if (override?.url)
         return { brain: urlBrain(override.url, cfg.brainTimeoutMs), kind: "url (per-bot)" };
+    if (override?.echo)
+        return { brain: echoBrain, kind: "echo (per-bot)" };
     if (cfg.brainCmd)
         return { brain: cmdBrain(cfg.brainCmd, cfg.brainTimeoutMs), kind: "cmd" };
     if (cfg.brainUrl)

package/dist/bridge.d.ts

@@ -1,5 +1,50 @@
-import type { BridgeConfig } from "./config.js";
-export interface Bridge {
+import type { BridgeConfig, BrainSpec } from "./config.js";
+export declare const VERSION = "0.2.1";
+export interface PairRequest {
+    pairingSecret: string;
+    appId: string;
+    apiUrl?: string;
+}
+export interface BrainsPatch {
+    /** Global command brain; null clears it. */
+    brainCmd?: string | null;
+    /** Global webhook brain; null clears it. */
+    brainUrl?: string | null;
+    /** Per-handle entries; a null value removes that bot's override. */
+    map?: Record<string, BrainSpec | null>;
+}
+export declare class PairError extends Error {
+    readonly code: "ALREADY_PAIRED" | "PAIR_REJECTED" | "PAIR_UNREACHABLE" | "BAD_REQUEST";
+    constructor(code: "ALREADY_PAIRED" | "PAIR_REJECTED" | "PAIR_UNREACHABLE" | "BAD_REQUEST", message: string);
+}
+export declare class BridgeApp {
+    readonly cfg: BridgeConfig;
+    readonly startedAt: number;
+    private bots;
+    private control;
+    private stopped;
+    constructor(cfg: BridgeConfig);
+    get paired(): boolean;
+    /** Known once the control socket has authenticated at least once. */
+    get runtimeId(): string | null;
+    get controlConnected(): boolean;
+    start(): void;
     stop(): void;
+    /**
+     * Pair this bridge from the NoPeek app. Only accepted while UNPAIRED (an
+     * attacker on a webpage can't silently re-point an already-working bridge).
+     * The secret is validated against the API before anything is persisted.
+     */
+    pair(req: PairRequest): Promise<void>;
+    /** Undo pairing: stop everything, forget the credential (device keys stay). */
+    unpair(): void;
+    /** Apply a brain change live (next message uses it) and persist it. */
+    setBrains(patch: BrainsPatch): void;
+    statusMinimal(): Record<string, unknown>;
+    statusFull(): Record<string, unknown>;
+    private startBot;
+    /** Fetch the authoritative bot list and start anything we're missing. */
+    private syncBots;
+    private startCore;
+    private stopCore;
 }
-export declare function runBridge(cfg: BridgeConfig): Promise<Bridge>;

package/dist/bridge.js

@@ -1,24 +1,173 @@
-// Orchestrator: pairs this machine as a NoPeek runtime, discovers every bot it
-// owns (GET /runtime/bots), runs each as an isolated BotRunner, and keeps the
-// fleet current via the control WebSocket (adopt_bot arrives live — no restart).
-import { createServer } from "node:http";
+// Orchestrator. A bridge has two states:
+//   unpaired — local control API up, waiting for the NoPeek app to POST /pair
+//   paired   — runs every bot the runtime owns (GET /runtime/bots), keeps the
+//              fleet current via the control WebSocket (adopt_bot arrives live),
+//              and still serves the local API for status + live brain changes.
+// Pairing, unpairing and brain config all happen at runtime (from the app) and
+// persist to <home>/settings.json — no restart, no terminal.
+import { hostname } from "node:os";
+import { saveSettings } from "./config.js";
 import { BotRunner } from "./bot.js";
 import { ControlSocket } from "./control.js";
-export async function runBridge(cfg) {
-    const startedAt = Date.now();
-    const bots = new Map(); // botUserId -> runner
-    // ------------------------------------------------------------- bot fleet --
-    const startBot = (info) => {
-        if (bots.has(info.userId))
+import { resolveBrain } from "./brain.js";
+export const VERSION = "0.2.1";
+export class PairError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export class BridgeApp {
+    cfg;
+    startedAt = Date.now();
+    bots = new Map(); // botUserId -> runner
+    control = null;
+    stopped = false;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    get paired() {
+        return Boolean(this.cfg.pairingCode && this.cfg.appId);
+    }
+    /** Known once the control socket has authenticated at least once. */
+    get runtimeId() {
+        return this.control?.runtimeId ?? null;
+    }
+    get controlConnected() {
+        return this.control?.connected ?? false;
+    }
+    start() {
+        if (this.paired)
+            this.startCore();
+        else
+            console.log(`[bridge] not paired yet — open the NoPeek app: Bots -> Connect this computer`);
+    }
+    stop() {
+        this.stopped = true;
+        this.stopCore();
+    }
+    // ------------------------------------------------------------- pairing ----
+    /**
+     * Pair this bridge from the NoPeek app. Only accepted while UNPAIRED (an
+     * attacker on a webpage can't silently re-point an already-working bridge).
+     * The secret is validated against the API before anything is persisted.
+     */
+    async pair(req) {
+        if (this.paired) {
+            throw new PairError("ALREADY_PAIRED", "This bridge is already paired. Unpair it first (from the NoPeek app) or revoke the runtime.");
+        }
+        const pairingSecret = typeof req.pairingSecret === "string" ? req.pairingSecret.trim() : "";
+        const appId = typeof req.appId === "string" ? req.appId.trim() : "";
+        if (!pairingSecret || !appId) {
+            throw new PairError("BAD_REQUEST", "pairingSecret and appId are required.");
+        }
+        const apiUrl = (typeof req.apiUrl === "string" && req.apiUrl.trim() ? req.apiUrl.trim() : this.cfg.apiUrl).replace(/\/+$/, "");
+        // Validate before persisting: the bot list doubles as an auth probe.
+        let res;
+        try {
+            res = await fetch(`${apiUrl}/v1/apps/${appId}/runtime/bots`, {
+                headers: { authorization: `Bearer ${pairingSecret}` },
+                signal: AbortSignal.timeout(15_000),
+            });
+        }
+        catch (err) {
+            throw new PairError("PAIR_UNREACHABLE", `could not reach ${apiUrl}: ${err.message}`);
+        }
+        if (!res.ok) {
+            throw new PairError("PAIR_REJECTED", `the API rejected this pairing secret (HTTP ${res.status}).`);
+        }
+        this.cfg.apiUrl = apiUrl;
+        this.cfg.appId = appId;
+        this.cfg.pairingCode = pairingSecret;
+        saveSettings(this.cfg);
+        console.log(`[bridge] paired with app ${appId} — starting bots`);
+        this.startCore();
+    }
+    /** Undo pairing: stop everything, forget the credential (device keys stay). */
+    unpair() {
+        console.log(`[bridge] unpairing — stopping bots and forgetting the pairing secret`);
+        this.stopCore();
+        this.cfg.pairingCode = null;
+        this.cfg.appId = null;
+        saveSettings(this.cfg);
+    }
+    // -------------------------------------------------------------- brains ----
+    /** Apply a brain change live (next message uses it) and persist it. */
+    setBrains(patch) {
+        if (patch.brainCmd !== undefined)
+            this.cfg.brainCmd = patch.brainCmd || null;
+        if (patch.brainUrl !== undefined)
+            this.cfg.brainUrl = patch.brainUrl || null;
+        if (patch.map) {
+            for (const [rawHandle, spec] of Object.entries(patch.map)) {
+                const handle = rawHandle.replace(/^@/, "");
+                if (spec === null) {
+                    delete this.cfg.brainMap[handle];
+                }
+                else if (typeof spec.cmd === "string" && spec.cmd.trim()) {
+                    this.cfg.brainMap[handle] = { cmd: spec.cmd.trim() };
+                }
+                else if (typeof spec.url === "string" && spec.url.trim()) {
+                    this.cfg.brainMap[handle] = { url: spec.url.trim() };
+                }
+                else if (spec.echo === true) {
+                    this.cfg.brainMap[handle] = { echo: true };
+                }
+                else {
+                    delete this.cfg.brainMap[handle];
+                }
+            }
+        }
+        saveSettings(this.cfg);
+        console.log(`[bridge] brains updated: default=${this.cfg.brainCmd ? "cmd" : this.cfg.brainUrl ? "url" : "echo"}, ${Object.keys(this.cfg.brainMap).length} per-bot override(s)`);
+    }
+    // -------------------------------------------------------------- status ----
+    statusMinimal() {
+        return {
+            ok: this.paired ? this.controlConnected : true,
+            service: "nopeek-agent-bridge",
+            version: VERSION,
+            paired: this.paired,
+            machine: hostname(),
+            uptime: Math.round((Date.now() - this.startedAt) / 1000),
+        };
+    }
+    statusFull() {
+        return {
+            ...this.statusMinimal(),
+            runtime: this.runtimeId,
+            apiUrl: this.cfg.apiUrl,
+            appId: this.cfg.appId,
+            brains: {
+                default: this.cfg.brainCmd
+                    ? { cmd: this.cfg.brainCmd }
+                    : this.cfg.brainUrl
+                        ? { url: this.cfg.brainUrl }
+                        : { echo: true },
+                map: this.cfg.brainMap,
+            },
+            bots: [...this.bots.values()].map((b) => ({
+                handle: b.info.handle,
+                userId: b.info.userId,
+                connected: b.connected,
+                handled: b.handled,
+                brain: resolveBrain(this.cfg, b.info.handle).kind,
+            })),
+        };
+    }
+    // ---------------------------------------------------------------- core ----
+    startBot(info) {
+        if (this.bots.has(info.userId))
             return; // already running
-        const runner = new BotRunner(info, cfg);
-        bots.set(info.userId, runner);
+        const runner = new BotRunner(info, this.cfg);
+        this.bots.set(info.userId, runner);
         runner.start(); // background; failures are isolated inside the runner
-    };
+    }
     /** Fetch the authoritative bot list and start anything we're missing. */
-    const syncBots = async () => {
-        const res = await fetch(`${cfg.apiUrl}/v1/apps/${cfg.appId}/runtime/bots`, {
-            headers: { authorization: `Bearer ${cfg.pairingCode}` },
+    async syncBots() {
+        const res = await fetch(`${this.cfg.apiUrl}/v1/apps/${this.cfg.appId}/runtime/bots`, {
+            headers: { authorization: `Bearer ${this.cfg.pairingCode}` },
         });
         if (!res.ok) {
             const body = await res.text().catch(() => "");
@@ -27,61 +176,42 @@ export async function runBridge(cfg) {
         const { bots: list } = (await res.json());
         console.log(`[bridge] runtime owns ${list.length} bot(s): ${list.map((b) => `@${b.handle}`).join(", ") || "(none yet)"}`);
         for (const info of list)
-            startBot(info);
-    };
-    // ---------------------------------------------------------- control sock --
-    const control = new ControlSocket(cfg, {
-        onAuthed: () => {
-            // Initial connect AND every reconnect: catch up on bots created while
-            // we were away (adopt_bot frames we may have missed).
-            void syncBots().catch((err) => {
-                console.error(`[bridge] bot sync failed: ${err.message}`);
-            });
-        },
-        onAdoptBot: (f) => {
-            startBot({ userId: f.botUserId, handle: f.handle, ownerId: f.ownerUserId });
-        },
-        onGrantChanged: (f) => {
-            // Access changed for a bot — re-pull its allow list so enforcement is live
-            // (a revoked user stops being answered within seconds, no restart).
-            const runner = bots.get(f.botUserId);
-            if (runner)
-                void runner.refreshAccess();
-        },
-    });
-    // ---------------------------------------------------------------- health --
-    const health = createServer((_req, res) => {
-        res.setHeader("content-type", "application/json");
-        res.end(JSON.stringify({
-            ok: control.connected,
-            runtime: control.runtimeId,
-            bots: [...bots.values()].map((b) => ({
-                handle: b.info.handle,
-                userId: b.info.userId,
-                connected: b.connected,
-                handled: b.handled,
-            })),
-            uptime: Math.round((Date.now() - startedAt) / 1000),
-        }));
-    });
-    health.listen(cfg.port, () => console.log(`[health] http://localhost:${cfg.port}/ -> {ok, runtime, bots, uptime}`));
-    // ----------------------------------------------------------------- start --
-    // Bots first (so a control-socket hiccup doesn't delay serving), then the
-    // control socket, whose auth.ok triggers a redundant-but-safe re-sync.
-    try {
-        await syncBots();
-    }
-    catch (err) {
-        // Non-fatal: the control socket's onAuthed will retry the sync.
-        console.error(`[bridge] initial bot sync failed (will retry on control auth): ${err.message}`);
-    }
-    control.start();
-    return {
-        stop() {
-            control.stop();
-            for (const b of bots.values())
-                b.stop();
-            health.close();
-        },
-    };
+            this.startBot(info);
+    }
+    startCore() {
+        if (this.stopped || this.control)
+            return;
+        this.control = new ControlSocket(this.cfg, {
+            onAuthed: () => {
+                // Initial connect AND every reconnect: catch up on bots created while
+                // we were away (adopt_bot frames we may have missed).
+                void this.syncBots().catch((err) => {
+                    console.error(`[bridge] bot sync failed: ${err.message}`);
+                });
+            },
+            onAdoptBot: (f) => {
+                this.startBot({ userId: f.botUserId, handle: f.handle, ownerId: f.ownerUserId });
+            },
+            onGrantChanged: (f) => {
+                // Access changed for a bot — re-pull its allow list so enforcement is
+                // live (a revoked user stops being answered within seconds).
+                const runner = this.bots.get(f.botUserId);
+                if (runner)
+                    void runner.refreshAccess();
+            },
+        });
+        // Bots first (so a control-socket hiccup doesn't delay serving), then the
+        // control socket, whose auth.ok triggers a redundant-but-safe re-sync.
+        void this.syncBots().catch((err) => {
+            console.error(`[bridge] initial bot sync failed (will retry on control auth): ${err.message}`);
+        });
+        this.control.start();
+    }
+    stopCore() {
+        this.control?.stop();
+        this.control = null;
+        for (const b of this.bots.values())
+            b.stop();
+        this.bots.clear();
+    }
 }

package/dist/cli.js

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
 // @nopeek/agent-bridge — connect your own agent runtime to NoPeek as E2EE bots.
-//   npx @nopeek/agent-bridge --pair npr_… --app-id app_… --brain-cmd '…'
+//
+//   nopeek-agent-bridge install    one-time: background service, then pair FROM THE APP
+//   nopeek-agent-bridge [run]      foreground (unpaired bridges wait for the app)
+//   nopeek-agent-bridge status     ask the running bridge how it's doing
+//   nopeek-agent-bridge uninstall  remove the service
 import { loadConfig, HELP } from "./config.js";
-import { runBridge } from "./bridge.js";
+import { BridgeApp, VERSION } from "./bridge.js";
+import { startLocalApi } from "./localapi.js";
+import { installService, uninstallService, printStatus } from "./service.js";
 // ---------------------------------------------------------------- guards ----
 // The bridge must never die to a stray rejection deep inside a WS/crypto
 // callback — one flaky bot cannot take the fleet down.
@@ -16,25 +22,87 @@ if (typeof WebSocket === "undefined" || !globalThis.crypto?.subtle) {
     console.error(`@nopeek/agent-bridge needs Node >= 22 (global WebSocket + fetch + WebCrypto). Current: ${process.version}`);
     process.exit(1);
 }
-// ---------------------------------------------------------------- config ----
+// ----------------------------------------------------------- subcommands ----
+const argv = process.argv.slice(2);
+const SUBCOMMANDS = new Set(["install", "uninstall", "status", "run", "help"]);
+const sub = argv[0] && SUBCOMMANDS.has(argv[0]) ? argv[0] : "run";
+const rest = sub === argv[0] ? argv.slice(1) : argv;
+if (sub === "help") {
+    console.log(HELP);
+    process.exit(0);
+}
 // Config errors exit cleanly with guidance — never a crash loop.
 let cfg;
 try {
-    cfg = loadConfig();
+    cfg = loadConfig(rest);
 }
 catch (err) {
     console.error(`[config] ${err.message}\n`);
     console.error(HELP);
     process.exit(1);
 }
-console.log(`[bridge] NoPeek agent-bridge starting`);
-console.log(`[bridge] api=${cfg.apiUrl} app=${cfg.appId} data=${cfg.dataDir} health=:${cfg.port}`);
-console.log(`[bridge] default brain: ${cfg.brainCmd ? "cmd" : cfg.brainUrl ? "url" : "echo (set --brain-cmd or --brain-url to plug in your agent)"}` +
+if (sub === "uninstall") {
+    uninstallService();
+    process.exit(0);
+}
+if (sub === "status") {
+    await printStatus(cfg.port);
+    process.exit(process.exitCode ?? 0);
+}
+if (sub === "install") {
+    try {
+        await installService(cfg);
+    }
+    catch (err) {
+        console.error(`[install] ${err.message}`);
+        process.exit(1);
+    }
+    // Optional: `install --pair npr_… --app-id app_…` pre-pairs the fresh service
+    // through its local API (same path the app uses).
+    if (cfg.pairingCode && cfg.appId) {
+        try {
+            const res = await fetch(`http://127.0.0.1:${cfg.port}/pair`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ pairingSecret: cfg.pairingCode, appId: cfg.appId, apiUrl: cfg.apiUrl }),
+            });
+            const body = (await res.json().catch(() => ({})));
+            if (res.ok)
+                console.log(`[install] paired successfully`);
+            else
+                console.error(`[install] pairing failed: ${body.message ?? `HTTP ${res.status}`}`);
+        }
+        catch (err) {
+            console.error(`[install] pairing failed: ${err.message}`);
+        }
+    }
+    process.exit(0);
+}
+// ---------------------------------------------------------------- run -------
+console.log(`[bridge] NoPeek agent-bridge v${VERSION} starting`);
+console.log(`[bridge] api=${cfg.apiUrl} app=${cfg.appId ?? "(not paired)"} data=${cfg.dataDir} local-api=:${cfg.port} home=${cfg.homeDir}`);
+console.log(`[bridge] default brain: ${cfg.brainCmd ? "cmd" : cfg.brainUrl ? "url" : "echo (choose an agent in the NoPeek app, or set --brain-cmd)"}` +
     (Object.keys(cfg.brainMap).length ? ` + ${Object.keys(cfg.brainMap).length} per-bot override(s)` : ""));
-const bridge = await runBridge(cfg);
+const app = new BridgeApp(cfg);
+let localApi;
+try {
+    localApi = await startLocalApi(app);
+}
+catch (err) {
+    const e = err;
+    if (e.code === "EADDRINUSE") {
+        console.error(`[bridge] port ${cfg.port} is already in use — another bridge is probably running (try 'nopeek-agent-bridge status'). Exiting.`);
+    }
+    else {
+        console.error(`[bridge] could not start local API: ${e.message}`);
+    }
+    process.exit(1);
+}
+app.start();
 const shutdown = (signal) => {
     console.log(`[bridge] ${signal} — shutting down`);
-    bridge.stop();
+    app.stop();
+    localApi.close();
     // Give sockets a beat to close, then force-exit so systemd/launchd restarts cleanly.
     setTimeout(() => process.exit(0), 500).unref();
 };