auto-model-router 0.5.0 → 0.6.1

package/.omp-plugin/marketplace.json

@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "auto-model-router: a local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
-    "version": "0.5.0",
+    "version": "0.6.1",
     "pluginRoot": "."
   },
   "plugins": [
     {
       "name": "auto-model-router",
       "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter. Runs in-process, routes per turn by price and task complexity, with budget caps, mid-stream escalation, and cache-aware hysteresis.",
-      "version": "0.5.0",
+      "version": "0.6.1",
       "author": {
         "name": "drewappling",
         "email": "drewappling@gmail.com"

package/README.md

@@ -1247,6 +1247,19 @@ override already pinned one. Every field is optional; a malformed header is
 ignored rather than failing the turn. The decision trail records what the
 policy changed (`policy: …`).
 
+## Using a remote router
+
+`auto-model-router connect --url <router> --key <key>` points this machine at a router
+running elsewhere: a shared instance on a LAN, or a team edition front door. It writes
+`<router home>/remote.json`, after which the omp extensions run in **remote mode**: the
+embed extension registers the remote router as omp's provider with that key instead of
+binding a local one, and the toast, `/router` hub and digest extensions talk to it. Nothing
+is classified or selected locally; the remote router is the router. The same command adds
+the extensions to omp's config, installs the Hermes plugins and points them at the remote,
+adds the Codex provider and the Aider settings, and prints (or with `--profile` persists)
+the environment lines for Claude Code. `--harness omp,hermes` restricts it; `--dry-run`
+shows the changes. Delete `remote.json` to go back to a local router. (`join` is an alias.)
+
 ## Multiple coding harnesses, one router
 
 **One router process for everything.** omp's embed extension binds a private

package/hermes-plugin/__init__.py

@@ -30,7 +30,11 @@ from providers.base import ProviderProfile
 
 # Fixed port the standalone router binds. Hermes points at this URL.
 PORT = int(os.environ.get("AUTO_MODEL_ROUTER_PORT", "8788"))
-BASE_URL = f"http://127.0.0.1:{PORT}/v1"
+# Remote mode: `auto-model-router connect` sets AUTO_MODEL_ROUTER_URL (and the
+# key) in $HERMES_HOME/.env; the plugin then points Hermes at that router and
+# spawns nothing locally.
+REMOTE_URL = os.environ.get("AUTO_MODEL_ROUTER_URL", "").rstrip("/")
+BASE_URL = f"{REMOTE_URL}/v1" if REMOTE_URL else f"http://127.0.0.1:{PORT}/v1"
 
 # The router binary, provided by `npm install -g auto-model-router`.
 BIN = "auto-model-router"
@@ -94,8 +98,8 @@ def _spawn_router() -> None:
     raise RuntimeError(f"auto-model-router did not come up on port {PORT}")
 
 
-_spawn_router()
-
+if not REMOTE_URL:
+    _spawn_router()
 profile = ProviderProfile(
     name="auto-model-router",
     api_mode="chat_completions",

package/omp-extension/remote-logic.ts

@@ -0,0 +1,93 @@
+/**
+ * Remote-router mode for the omp extensions. `auto-model-router connect`
+ * writes `<router home>/remote.json`; when it exists the embed extension
+ * registers the REMOTE router as omp's provider instead of binding a local
+ * one, and the toast, hub and digest extensions talk to it with the key.
+ * Nothing is classified or selected locally: the remote router is the router.
+ * A shared router on a LAN and the team edition are both remotes.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const REMOTE_FILE = "remote.json";
+/** The name the first release used; still read so nothing breaks on upgrade. */
+const LEGACY_FILE = "team.json";
+
+export interface RemoteRouter {
+	/** The remote router, no trailing slash, e.g. https://router.example.com */
+	url: string;
+	/** The key that router expects (`server.apiKey`, or a team user key). */
+	key: string;
+	userId: string;
+	name: string;
+	joinedAtMs: number;
+}
+
+export function remoteFilePath(routerHome: string): string {
+	return join(routerHome, REMOTE_FILE);
+}
+
+/** Parses remote.json defensively; anything malformed ⇒ not in remote mode. */
+export function parseRemoteRouter(text: string): RemoteRouter | null {
+	try {
+		const raw = JSON.parse(text) as Record<string, unknown>;
+		if (typeof raw.url !== "string" || typeof raw.key !== "string" || raw.url === "" || raw.key === "") return null;
+		return { url: raw.url.replace(/\/+$/, ""), key: raw.key, userId: typeof raw.userId === "string" ? raw.userId : "", name: typeof raw.name === "string" ? raw.name : "", joinedAtMs: typeof raw.joinedAtMs === "number" ? raw.joinedAtMs : 0 };
+	} catch {
+		return null;
+	}
+}
+
+export function readRemoteRouter(routerHome: string): RemoteRouter | null {
+	for (const path of [remoteFilePath(routerHome), join(routerHome, LEGACY_FILE)]) {
+		if (!existsSync(path)) continue;
+		try {
+			return parseRemoteRouter(readFileSync(path, "utf8"));
+		} catch {
+			return null;
+		}
+	}
+	return null;
+}
+
+/** The virtual models a remote router serves; costs are the fallback blend so omp can show estimates. */
+export const REMOTE_MODELS: readonly { id: string; name: string }[] = [
+	{ id: "auto", name: "auto (remote)" },
+	{ id: "auto-cheap", name: "auto-cheap (remote)" },
+	{ id: "auto-max", name: "auto-max (remote)" },
+];
+
+/**
+ * omp's provider registration for remote mode: the remote's /v1 with the key,
+ * the session and subagent tags, and the virtual models. Costs are USD per
+ * million tokens, like the embedded config.
+ */
+export function remoteProviderRegistration(remote: RemoteRouter, sessionId: string, subagent: boolean, blend: { inputPerMtok: number; outputPerMtok: number }): {
+	baseUrl: string;
+	api: string;
+	apiKey: string;
+	headers: Record<string, string>;
+	models: { id: string; name: string; api: string; reasoning: boolean; input: string[]; contextWindow: number; maxTokens: number; cost: { input: number; output: number; cacheRead: number; cacheWrite: number } }[];
+} {
+	const headers: Record<string, string> = {};
+	if (sessionId !== "") headers["X-Omp-Session"] = sessionId;
+	if (subagent) headers["X-Omp-Subagent"] = "1";
+	const round = (v: number): number => Math.round(v * 1e4) / 1e4;
+	return {
+		baseUrl: `${remote.url}/v1`,
+		api: "openai-completions",
+		apiKey: remote.key,
+		headers,
+		models: REMOTE_MODELS.map((m) => ({
+			id: m.id,
+			name: m.name,
+			api: "openai-completions",
+			reasoning: false,
+			input: ["text", "image"],
+			contextWindow: 200_000,
+			maxTokens: 32_000,
+			cost: { input: round(blend.inputPerMtok), output: round(blend.outputPerMtok), cacheRead: round(blend.inputPerMtok * 0.1), cacheWrite: round(blend.inputPerMtok * 1.25) },
+		})),
+	};
+}

package/omp-extension/router-embed.ts

@@ -26,6 +26,7 @@ import { join } from "node:path";
 import { ompModelsPath } from "../src/cli/config-cmd.ts";
 import { loadConfig } from "../src/config/load.ts";
 import { startServer } from "../src/server/http.ts";
+import { readRemoteRouter, remoteProviderRegistration } from "./remote-logic.ts";
 import type { StartedServer } from "../src/server/http.ts";
 import type { RouterConfig } from "../src/config/types.ts";
 
@@ -167,6 +168,17 @@ export default function (pi: ExtensionAPI): void {
 		// notifications to that exact session (see router-toast.ts).
 		const sessionId = ctx.sessionManager.getSessionId();
 
+		// Remote mode (`auto-model-router connect`): a router elsewhere is the
+		// router. Register it as the provider with its key and bind nothing
+		// locally; the other extensions find it through remote.json.
+		const remote = readRemoteRouter(routerHome());
+		if (remote !== null) {
+			pi.registerProvider(EMBED_PROVIDER_ID, remoteProviderRegistration(remote, sessionId, !ctx.hasUI, cfg.ledger.fallbackBlend));
+			pi.setLabel(`auto-model-router remote (${remote.url.replace(/^https?:\/\//, "")})`);
+			writeEmbedLog(`remote mode url=${remote.url} user=${remote.userId} session=${sessionId}`);
+			return;
+		}
+
 		// This module is cached per PROCESS, so `app` and `boundPort` are
 		// process-global even when omp loads the extension into more than one
 		// host. A router already bound in this process is therefore reusable:

package/omp-extension/router-toast.ts

@@ -23,40 +23,17 @@
  * the poll authenticates.
  */
 
-import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
 
-import { parse as parseYaml } from "yaml";
 
 import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
 
-import { embedPortPath, readEmbedPort } from "./embed-logic.ts";
-import { newestId, resolveRouterUrl, selectToasts, type ToastDecision } from "./toast-logic.ts";
+import { routerAuthHeaders, routerBaseUrl } from "./router-url.ts";
+import { newestId, selectToasts, type ToastDecision } from "./toast-logic.ts";
 
 /** Raw router config.yml, or null when there is none to read. */
-function readRouterConfig(): string | null {
-	const raw = process.env.AUTO_MODEL_ROUTER_HOME ?? join(homedir(), ".auto-model-router");
-	const home =
-		raw === "~" || raw.startsWith("~/") || raw.startsWith("~\\") ? join(homedir(), raw.slice(1)) : raw;
-	const path = join(home, "config.yml");
-	if (!existsSync(path)) return null;
-	try {
-		return readFileSync(path, "utf8");
-	} catch {
-		return null;
-	}
-}
 
 /** Absolute path of the shared embed port file (main session writes it). */
-function embedPortFile(): string {
-	const raw = process.env.AUTO_MODEL_ROUTER_HOME ?? join(homedir(), ".auto-model-router");
-	const home =
-		raw === "~" || raw.startsWith("~/") || raw.startsWith("~\\") ? join(homedir(), raw.slice(1)) : raw;
-	return embedPortPath(home);
-}
 
-const ROUTER_API_KEY = process.env.AUTO_MODEL_ROUTER_API_KEY;
 // This harness's id, matching the X-Omp-Harness header the router records.
 // Empty ⇒ toast every harness (single-harness default).
 const HARNESS_ID = process.env.OMP_HARNESS_ID ?? "";
@@ -91,19 +68,13 @@ export default function (pi: ExtensionAPI): void {
 				// The embedded router binds a free OS-assigned port, so the URL
 				// is resolved fresh each tick from the port file the embed
 				// extension writes at session_start.
-				const embedPort = readEmbedPort(embedPortFile());
-				const routerUrl = resolveRouterUrl(
-					process.env.AUTO_MODEL_ROUTER_URL,
-					readRouterConfig(),
-					parseYaml,
-					process.env.AUTO_MODEL_ROUTER_PORT,
-					embedPort,
-				);
+				// Remote mode resolves to the remote router with its key.
+				const routerUrl = routerBaseUrl();
 
 				let res: Response;
 				try {
 					res = await fetch(`${routerUrl}/v1/router/decisions?limit=20`, {
-						headers: ROUTER_API_KEY === undefined ? {} : { authorization: `Bearer ${ROUTER_API_KEY}` },
+						headers: routerAuthHeaders(),
 						signal: AbortSignal.timeout(3_000),
 					});
 				} catch {

package/omp-extension/router-url.ts

@@ -15,6 +15,7 @@ import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
 
 import { embedPortPath, readEmbedPort } from "./embed-logic.ts";
+import { readRemoteRouter } from "./remote-logic.ts";
 import { resolveRouterUrl } from "./toast-logic.ts";
 
 /** `$AUTO_MODEL_ROUTER_HOME` with `~` expanded, default `~/.auto-model-router`. */
@@ -36,6 +37,9 @@ export function readRouterConfigText(): string | null {
 
 /** Base URL of the router this omp process should talk to. */
 export function routerBaseUrl(): string {
+	// Remote mode: the router elsewhere is the router.
+	const remote = readRemoteRouter(routerHome());
+	if (remote !== null) return remote.url;
 	return resolveRouterUrl(
 		process.env.AUTO_MODEL_ROUTER_URL,
 		readRouterConfigText(),
@@ -47,6 +51,8 @@ export function routerBaseUrl(): string {
 
 /** Authorization header for a router configured with `server.apiKey`. */
 export function routerAuthHeaders(): Record<string, string> {
+	const remote = readRemoteRouter(routerHome());
+	if (remote !== null) return { authorization: `Bearer ${remote.key}` };
 	const key = process.env.AUTO_MODEL_ROUTER_API_KEY;
 	return key === undefined || key === "" ? {} : { authorization: `Bearer ${key}` };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-model-router",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "private": false,
   "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
   "type": "module",

package/src/cli/args.ts

@@ -20,6 +20,8 @@ export interface CliArgs {
  */
 const BOOLEAN_FLAGS: Record<string, true> = {
 	json: true,
+	profile: true,
+	"dry-run": true,
 	write: true,
 	print: true,
 	help: true,
@@ -31,6 +33,8 @@ const COMMANDS: Record<string, true> = {
 	stats: true,
 	report: true,
 	export: true,
+	connect: true,
+	join: true,
 	models: true,
 	explain: true,
 	config: true,

package/src/cli/connect.ts

@@ -0,0 +1,215 @@
+/**
+ * `auto-model-router connect --url <router> --key <key>`: point this machine
+ * at a remote router (a shared one on a LAN, or the team edition). Writes
+ * `<router home>/remote.json` (the omp extensions then run in remote mode and
+ * never bind a local router), and configures every harness it finds:
+ *
+ *   omp         the four extensions are added to ~/.omp/agent/config.yml
+ *   Hermes      the provider plugin and the native plugin are copied into
+ *               $HERMES_HOME/plugins and .env points them at the remote
+ *   Codex       ~/.codex/config.toml gains the auto-model-router provider
+ *   Aider       ~/.aider.conf.yml gains the base URL, key and model
+ *   Claude Code ANTHROPIC_BASE_URL / ANTHROPIC_API_KEY (printed; --profile persists)
+ *
+ * Every write is idempotent and announced. `--profile` persists the
+ * environment lines (shell rc on POSIX, user environment on Windows).
+ * `--dry-run` prints what would change. Honours PI_CODING_AGENT_DIR,
+ * HERMES_HOME and AUTO_MODEL_ROUTER_HOME, so a test can point it anywhere.
+ */
+
+import { appendFileSync, cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { remoteFilePath } from "../../omp-extension/remote-logic.ts";
+import { flagString, type CliArgs } from "./args.ts";
+
+export interface ConnectOptions {
+	url: string;
+	key: string;
+	userId: string;
+	name: string;
+	profile: boolean;
+	dryRun: boolean;
+	/** Restrict to these harnesses (omp, hermes, codex, aider, claude); empty ⇒ every one detected. */
+	only: string[];
+	env: Record<string, string | undefined>;
+	home: string;
+	/** Where this package lives (the extensions are referenced from here). */
+	packageDir: string;
+	platform: string;
+	pathHas: (bin: string) => boolean;
+}
+
+export interface ConnectReport {
+	remoteFile: string;
+	configured: string[];
+	skipped: string[];
+	envLines: string[];
+	notes: string[];
+}
+
+const expand = (raw: string, home: string): string => (raw === "~" || raw.startsWith("~/") || raw.startsWith("~\\") ? join(home, raw.slice(1)) : raw);
+
+function routerHomeOf(o: ConnectOptions): string {
+	return expand(o.env.AUTO_MODEL_ROUTER_HOME ?? join(o.home, ".auto-model-router"), o.home);
+}
+
+function ompAgentDir(o: ConnectOptions): string {
+	const d = o.env.PI_CODING_AGENT_DIR;
+	return d !== undefined && d !== "" ? expand(d, o.home) : join(o.home, ".omp", "agent");
+}
+
+function hermesHome(o: ConnectOptions): string {
+	const d = o.env.HERMES_HOME;
+	if (d !== undefined && d !== "") return expand(d, o.home);
+	return o.platform === "win32" ? join(o.env.LOCALAPPDATA ?? join(o.home, "AppData", "Local"), "hermes") : join(o.home, ".hermes");
+}
+
+const wants = (o: ConnectOptions, h: string): boolean => o.only.length === 0 || o.only.includes(h);
+
+/** Adds lines to a YAML `extensions:` list by text, keeping everything else byte-identical. */
+export function addExtensions(text: string, paths: readonly string[]): string {
+	const eol = text.includes("\r\n") ? "\r\n" : "\n";
+	const missing = paths.filter((p) => !text.includes(p));
+	if (missing.length === 0) return text;
+	const lines = missing.map((p) => `  - ${p}`);
+	const m = /^extensions:[ \t]*\r?\n/m.exec(text);
+	if (m === null) return `${text}${text.endsWith("\n") || text === "" ? "" : eol}extensions:${eol}${lines.join(eol)}${eol}`;
+	const at = m.index + m[0].length;
+	return `${text.slice(0, at)}${lines.join(eol)}${eol}${text.slice(at)}`;
+}
+
+/** Sets `KEY=value` lines in a dotenv-style file, replacing existing keys. */
+export function setDotenv(text: string, values: Record<string, string>): string {
+	const eol = text.includes("\r\n") ? "\r\n" : "\n";
+	let out = text;
+	for (const [k, v] of Object.entries(values)) {
+		const re = new RegExp(`^${k}=.*$`, "m");
+		if (re.test(out)) out = out.replace(re, `${k}=${v}`);
+		else out = `${out}${out === "" || out.endsWith("\n") ? "" : eol}${k}=${v}${eol}`;
+	}
+	return out;
+}
+
+export function codexBlock(url: string): string {
+	return `
+[model_providers.auto-model-router]
+name = "auto-model-router (remote)"
+base_url = "${url}/v1"
+env_key = "AUTO_MODEL_ROUTER_API_KEY"
+wire_api = "responses"
+http_headers = { "X-Omp-Harness" = "codex" }
+`;
+}
+
+export function connectRemote(o: ConnectOptions): ConnectReport {
+	const report: ConnectReport = { remoteFile: "", configured: [], skipped: [], envLines: [], notes: [] };
+	const write = (path: string, content: string): void => {
+		if (o.dryRun) return;
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, content, "utf8");
+	};
+
+	// 1. remote.json: what puts the omp extensions into remote mode.
+	const rh = routerHomeOf(o);
+	report.remoteFile = remoteFilePath(rh);
+	write(report.remoteFile, `${JSON.stringify({ url: o.url, key: o.key, userId: o.userId, name: o.name, joinedAtMs: Date.now() }, null, 2)}\n`);
+
+	// 2. omp
+	const agentDir = ompAgentDir(o);
+	if (wants(o, "omp") && existsSync(agentDir)) {
+		const cfgPath = join(agentDir, "config.yml");
+		const ext = ["router-toast", "router-embed", "router-configure", "router-digest"].map((n) => resolve(o.packageDir, "omp-extension", `${n}.ts`).replaceAll("\\", "/"));
+		const before = existsSync(cfgPath) ? readFileSync(cfgPath, "utf8") : "";
+		const after = addExtensions(before, ext);
+		if (after !== before) write(cfgPath, after);
+		report.configured.push(`omp (${cfgPath}; pick auto-model-router/auto as the model)`);
+	} else report.skipped.push("omp (no ~/.omp/agent)");
+
+	// 3. Hermes
+	const hh = hermesHome(o);
+	if (wants(o, "hermes") && existsSync(hh)) {
+		if (!o.dryRun) {
+			cpSync(join(o.packageDir, "hermes-plugin"), join(hh, "plugins", "model-providers", "auto-model-router"), { recursive: true });
+			cpSync(join(o.packageDir, "hermes-plugin", "native"), join(hh, "plugins", "auto-model-router"), { recursive: true });
+		}
+		const envPath = join(hh, ".env");
+		write(envPath, setDotenv(existsSync(envPath) ? readFileSync(envPath, "utf8") : "", { AUTO_MODEL_ROUTER_URL: o.url, AUTO_MODEL_ROUTER_API_KEY: o.key }));
+		report.configured.push(`Hermes (${hh}/plugins; restart Hermes and select auto-model-router/auto)`);
+	} else report.skipped.push("Hermes (no HERMES_HOME)");
+
+	// 4. Codex
+	const codexDir = join(o.home, ".codex");
+	if (wants(o, "codex") && existsSync(codexDir)) {
+		const p = join(codexDir, "config.toml");
+		const before = existsSync(p) ? readFileSync(p, "utf8") : "";
+		if (!before.includes("[model_providers.auto-model-router]")) write(p, before + codexBlock(o.url));
+		report.configured.push(`Codex (${p}; set model = "auto" and model_provider = "auto-model-router")`);
+		report.envLines.push(`AUTO_MODEL_ROUTER_API_KEY=${o.key}`);
+	} else report.skipped.push("Codex (no ~/.codex)");
+
+	// 5. Aider
+	const aiderConf = join(o.home, ".aider.conf.yml");
+	if (wants(o, "aider") && (existsSync(aiderConf) || o.pathHas("aider"))) {
+		const before = existsSync(aiderConf) ? readFileSync(aiderConf, "utf8") : "";
+		if (!before.includes("openai-api-base:")) write(aiderConf, `${before}${before === "" || before.endsWith("\n") ? "" : "\n"}openai-api-base: ${o.url}/v1\nopenai-api-key: ${o.key}\nmodel: openai/auto\n`);
+		report.configured.push(`Aider (${aiderConf})`);
+	} else report.skipped.push("Aider (not found)");
+
+	// 6. Claude Code: environment only.
+	if (wants(o, "claude") && o.pathHas("claude")) {
+		report.envLines.push(`ANTHROPIC_BASE_URL=${o.url}`, `ANTHROPIC_API_KEY=${o.key}`);
+		report.configured.push("Claude Code (environment)");
+	} else report.skipped.push("Claude Code (not on PATH)");
+	report.envLines.unshift(`AUTO_MODEL_ROUTER_URL=${o.url}`, `AUTO_MODEL_ROUTER_API_KEY=${o.key}`);
+	report.envLines = [...new Set(report.envLines)];
+
+	// 7. Persist the environment.
+	if (o.profile && !o.dryRun) {
+		if (o.platform === "win32") {
+			for (const line of report.envLines) {
+				const [k, ...v] = line.split("=");
+				Bun.spawnSync(["setx", k!, v.join("=")], { stdout: "ignore", stderr: "ignore" });
+			}
+			report.notes.push("user environment variables set with setx; open a new terminal");
+		} else {
+			const shell = o.env.SHELL ?? "";
+			const rc = shell.includes("zsh") ? join(o.home, ".zshrc") : join(o.home, ".bashrc");
+			const block = `\n# auto-model-router remote (added by \`auto-model-router connect\`)\n${report.envLines.map((l) => `export ${l}`).join("\n")}\n`;
+			const before = existsSync(rc) ? readFileSync(rc, "utf8") : "";
+			if (!before.includes("# auto-model-router remote") && !before.includes("# auto-model-router team")) appendFileSync(rc, block, "utf8");
+			else write(rc, before.replace(/\n# auto-model-router (?:remote|team)[^\n]*\n(?:export [^\n]*\n)*/, block));
+			report.notes.push(`environment appended to ${rc}; open a new shell or source it`);
+		}
+	} else report.notes.push("add the environment lines to your shell profile, or re-run with --profile");
+	return report;
+}
+
+export async function connectCommand(args: CliArgs): Promise<void> {
+	const url = (flagString(args, "url") ?? process.env.AUTO_MODEL_ROUTER_URL ?? "").replace(/\/+$/, "");
+	const key = flagString(args, "key") ?? process.env.AUTO_MODEL_ROUTER_API_KEY ?? "";
+	if (url === "" || key === "") throw new Error("connect needs --url <remote router> and --key <its key>");
+	const only = (flagString(args, "harness") ?? "").split(",").map((s) => s.trim().toLowerCase()).filter((s) => s !== "");
+	const pathHas = (bin: string): boolean => Bun.which(bin) !== null;
+	const packageDir = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+	// Verify the key against the route every router serves before touching anything.
+	let name = flagString(args, "name") ?? "";
+	let userId = flagString(args, "user-id") ?? "";
+	try {
+		const res = await fetch(`${url}/v1/models`, { headers: { authorization: `Bearer ${key}` }, signal: AbortSignal.timeout(10_000) });
+		if (res.status === 401) throw new Error("the remote router rejected this key");
+	} catch (err) {
+		if (err instanceof Error && err.message.includes("rejected")) throw err;
+		console.log(`warning: could not reach ${url} to verify the key (${err instanceof Error ? err.message : String(err)}); configuring anyway`);
+	}
+	// HOME wins when set (Git Bash, WSL, CI) so a caller can redirect every write; the OS profile otherwise.
+	const home = process.env.HOME !== undefined && process.env.HOME !== "" ? process.env.HOME : homedir();
+	const report = connectRemote({ url, key, userId, name, profile: args.flags.has("profile"), dryRun: args.flags.has("dry-run"), only, env: process.env, home, packageDir, platform: process.platform, pathHas });
+	console.log(`${args.flags.has("dry-run") ? "would write" : "wrote"} ${report.remoteFile}${name === "" ? "" : ` for ${name}`}`);
+	for (const c of report.configured) console.log(`  configured ${c}`);
+	for (const s of report.skipped) console.log(`  skipped    ${s}`);
+	console.log("environment:");
+	for (const l of report.envLines) console.log(`  ${process.platform === "win32" ? "$env:" : "export "}${process.platform === "win32" ? l.replace("=", '="') + '"' : l}`);
+	for (const n of report.notes) console.log(`note: ${n}`);
+}

package/src/index.ts

@@ -12,6 +12,7 @@ import { parseArgv } from "./cli/args.ts";
 import { configCommand } from "./cli/config-cmd.ts";
 import { explainCommand } from "./cli/explain.ts";
 import { exportCommand } from "./cli/export.ts";
+import { connectCommand } from "./cli/connect.ts";
 import { modelsCommand } from "./cli/models.ts";
 import { reportCommand } from "./cli/report.ts";
 import { serveCommand } from "./cli/serve.ts";
@@ -25,6 +26,7 @@ Usage: auto-model-router <command> [options]
   stats      Show routed spend, per-model share, and escalation rates
   report     Usage analytics: providers, models, tiers, cost, speed, cache hit rate
   export     One row per day, harness and model as CSV (--json for rows)
+  connect    Point this machine at a remote router (--url, --key; --profile persists the environment)
   models     Show what each complexity tier would consider, and why
   explain    Route a saved request without dispatching it, and explain the decision
   config     Interactive wizard over the router's own config.yml
@@ -78,6 +80,10 @@ async function main(): Promise<number> {
 		case "export":
 			await exportCommand(args);
 			return 0;
+		case "connect":
+		case "join": // the first release's name
+			await connectCommand(args);
+			return 0;
 		case "models":
 			await modelsCommand(args);
 			return 0;

package/test/remote.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { addExtensions, codexBlock, connectRemote, setDotenv, type ConnectOptions } from "../src/cli/connect.ts";
+import { parseRemoteRouter, readRemoteRouter, remoteProviderRegistration } from "../omp-extension/remote-logic.ts";
+
+/**
+ * Remote mode: remote.json puts the omp extensions on a router elsewhere,
+ * and `connect` configures every harness it finds without touching anything
+ * it does not recognise.
+ */
+
+describe("remote-logic", () => {
+	test("remote.json is parsed defensively and turned into omp's provider registration", () => {
+		expect(parseRemoteRouter("nope")).toBeNull();
+		expect(parseRemoteRouter(JSON.stringify({ url: "https://t/", key: "" }))).toBeNull();
+		const t = parseRemoteRouter(JSON.stringify({ url: "https://team.example/", key: "amrt_k", userId: "u_1", name: "Ada" }))!;
+		expect(t.url).toBe("https://team.example");
+		const reg = remoteProviderRegistration(t, "sess-1", true, { inputPerMtok: 1, outputPerMtok: 4 });
+		expect(reg).toMatchObject({ baseUrl: "https://team.example/v1", api: "openai-completions", apiKey: "amrt_k", headers: { "X-Omp-Session": "sess-1", "X-Omp-Subagent": "1" } });
+		expect(reg.models.map((m) => m.id)).toEqual(["auto", "auto-cheap", "auto-max"]);
+		expect(reg.models[0]!.cost).toEqual({ input: 1, output: 4, cacheRead: 0.1, cacheWrite: 1.25 });
+		const dir = mkdtempSync(join(tmpdir(), "amr-remote-"));
+		expect(readRemoteRouter(dir)).toBeNull();
+		writeFileSync(join(dir, "remote.json"), JSON.stringify({ url: "https://t", key: "k" }));
+		expect(readRemoteRouter(dir)?.key).toBe("k");
+		rmSync(join(dir, "remote.json"));
+		writeFileSync(join(dir, "team.json"), JSON.stringify({ url: "https://legacy", key: "k2" })); // the first release's name still works
+		expect(readRemoteRouter(dir)?.url).toBe("https://legacy");
+		rmSync(dir, { recursive: true, force: true });
+	});
+
+	test("text edits keep files byte-identical apart from the lines they add", () => {
+		expect(addExtensions("", ["/a.ts"])).toBe("extensions:\n  - /a.ts\n");
+		expect(addExtensions("foo: 1\nextensions:\n  - /x.ts\nbar: 2\n", ["/x.ts", "/a.ts"])).toBe("foo: 1\nextensions:\n  - /a.ts\n  - /x.ts\nbar: 2\n");
+		expect(addExtensions("foo: 1\r\n", ["/a.ts"])).toBe("foo: 1\r\nextensions:\r\n  - /a.ts\r\n");
+		expect(setDotenv("A=1\nB=2\n", { B: "3", C: "4" })).toBe("A=1\nB=3\nC=4\n");
+		expect(setDotenv("", { A: "1" })).toBe("A=1\n");
+		expect(codexBlock("https://t")).toContain('base_url = "https://t/v1"');
+	});
+});
+
+describe("connect", () => {
+	function scenario(extra: Partial<ConnectOptions> = {}): { home: string; o: ConnectOptions } {
+		const home = mkdtempSync(join(tmpdir(), "amr-connect-"));
+		const agent = join(home, ".omp", "agent");
+		mkdirSync(agent, { recursive: true });
+		writeFileSync(join(agent, "config.yml"), "extensions:\n  - E:/other/ext.ts\nsetupVersion: 2\n");
+		mkdirSync(join(home, ".hermes"), { recursive: true });
+		writeFileSync(join(home, ".hermes", ".env"), "OPENAI_API_KEY=x\n");
+		mkdirSync(join(home, ".codex"), { recursive: true });
+		writeFileSync(join(home, ".codex", "config.toml"), 'model = "gpt-5"\n');
+		const o: ConnectOptions = { url: "https://team.example", key: "amrt_key", userId: "u_ada", name: "Ada", profile: false, dryRun: false, only: [], env: { HOME: home, HERMES_HOME: join(home, ".hermes"), PI_CODING_AGENT_DIR: agent, AUTO_MODEL_ROUTER_HOME: join(home, ".auto-model-router") }, home, packageDir: process.cwd(), platform: "linux", pathHas: (b) => b === "claude" || b === "aider", ...extra };
+		return { home, o };
+	}
+
+	test("writes remote.json and configures omp, Hermes, Codex, Aider and Claude Code idempotently", () => {
+		const { home, o } = scenario();
+		const r1 = connectRemote(o);
+		expect(existsSync(r1.remoteFile)).toBe(true);
+		expect(JSON.parse(readFileSync(r1.remoteFile, "utf8"))).toMatchObject({ url: "https://team.example", key: "amrt_key", userId: "u_ada", name: "Ada" });
+		const ompCfg = readFileSync(join(home, ".omp", "agent", "config.yml"), "utf8");
+		expect(ompCfg).toContain("extensions:\n  - ");
+		expect(ompCfg).toContain("omp-extension/router-embed.ts");
+		expect(ompCfg).toContain("E:/other/ext.ts");
+		expect(ompCfg).toContain("setupVersion: 2");
+		expect(existsSync(join(home, ".hermes", "plugins", "model-providers", "auto-model-router", "__init__.py"))).toBe(true);
+		expect(existsSync(join(home, ".hermes", "plugins", "auto-model-router", "plugin.yaml"))).toBe(true);
+		expect(readFileSync(join(home, ".hermes", ".env"), "utf8")).toBe("OPENAI_API_KEY=x\nAUTO_MODEL_ROUTER_URL=https://team.example\nAUTO_MODEL_ROUTER_API_KEY=amrt_key\n");
+		expect(readFileSync(join(home, ".codex", "config.toml"), "utf8")).toContain("[model_providers.auto-model-router]");
+		expect(readFileSync(join(home, ".aider.conf.yml"), "utf8")).toContain("openai-api-base: https://team.example/v1");
+		expect(r1.configured.join("\n")).toMatch(/omp[\s\S]*Hermes[\s\S]*Codex[\s\S]*Aider[\s\S]*Claude Code/);
+		expect(r1.envLines).toEqual(["AUTO_MODEL_ROUTER_URL=https://team.example", "AUTO_MODEL_ROUTER_API_KEY=amrt_key", "ANTHROPIC_BASE_URL=https://team.example", "ANTHROPIC_API_KEY=amrt_key"]);
+		// Running again changes nothing.
+		const snapshot = [ompCfg, readFileSync(join(home, ".codex", "config.toml"), "utf8"), readFileSync(join(home, ".aider.conf.yml"), "utf8")];
+		connectRemote(o);
+		expect([readFileSync(join(home, ".omp", "agent", "config.yml"), "utf8"), readFileSync(join(home, ".codex", "config.toml"), "utf8"), readFileSync(join(home, ".aider.conf.yml"), "utf8")]).toEqual(snapshot);
+		rmSync(home, { recursive: true, force: true });
+	});
+
+	test("--harness restricts, --dry-run writes nothing, --profile appends once to the shell rc", () => {
+		const { home, o } = scenario({ only: ["omp"], dryRun: true });
+		const r = connectRemote(o);
+		expect(existsSync(r.remoteFile)).toBe(false);
+		expect(r.configured.some((c) => c.startsWith("omp"))).toBe(true);
+		expect(r.skipped.some((s) => s.startsWith("Hermes"))).toBe(true);
+		expect(existsSync(join(home, ".hermes", "plugins"))).toBe(false);
+		const { home: h2, o: o2 } = scenario({ profile: true, env: { SHELL: "/bin/zsh" } });
+		o2.env = { ...o.env, HOME: h2, HERMES_HOME: join(h2, ".hermes"), PI_CODING_AGENT_DIR: join(h2, ".omp", "agent"), AUTO_MODEL_ROUTER_HOME: join(h2, ".auto-model-router"), SHELL: "/bin/zsh" };
+		connectRemote(o2);
+		connectRemote(o2);
+		const rc = readFileSync(join(h2, ".zshrc"), "utf8");
+		expect(rc.split("# auto-model-router remote").length).toBe(2);
+		expect(rc).toContain("export ANTHROPIC_BASE_URL=https://team.example");
+		rmSync(home, { recursive: true, force: true });
+		rmSync(h2, { recursive: true, force: true });
+	});
+});