Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

fix(cli): auto-derive streams + engine ports from REST anchor (#750) (#815)

Rohit Ghumare334e5ad81aee
diff --git a/src/cli.ts b/src/cli.ts
index 62d39734..4a52e684 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -154,7 +154,12 @@ Options:
--reset Wipe ~/.agentmemory/preferences.json and re-run onboarding
--tools all|core Tool visibility (default: all = 51 tools; core = 8 essentials)
--no-engine Skip auto-starting iii-engine
- --port <N> Override REST port (default: 3111)
+ --port <N> Override REST port (default: 3111). Streams (N+1), viewer
+ (N+2), and iii engine (N+46023) auto-derive from N so a
+ single flag relocates the whole quartet.
+ --instance <N> Shortcut for --port (3111 + N*100) to run multiple
+ daemons side-by-side without env gymnastics.
+ --instance 1 -> 3211/3212/3213/49234, etc. (max N=50)
Environment:
AGENTMEMORY_URL Full REST base URL (e.g. http://localhost:3111).
@@ -188,6 +193,23 @@ if (portIdx !== -1 && args[portIdx + 1]) {
process.env["III_REST_PORT"] = args[portIdx + 1];
}
+// `--instance N` picks a 100-port block off the 3111 base so multiple
+// agentmemory daemons can coexist on one host without env-var
+// gymnastics (#750). `--instance 0` keeps the canonical 3111/3112/3113/49134
+// quartet; `--instance 1` → 3211/3212/3213/49234; etc. REST acts as the
+// anchor — streams/viewer/engine derive from it via fixed offsets below
+// unless an env explicitly pins each one.
+const instanceIdx = args.indexOf("--instance");
+if (instanceIdx !== -1 && args[instanceIdx + 1]) {
+ const n = parseInt(args[instanceIdx + 1] || "", 10);
+ if (Number.isFinite(n) && n >= 0 && n <= 50) {
+ const base = 3111 + n * 100;
+ if (!process.env["III_REST_PORT"]) {
+ process.env["III_REST_PORT"] = String(base);
+ }
+ }
+}
+
const skipEngine = args.includes("--no-engine");
function getRestPort(): number {
@@ -255,17 +277,20 @@ function getViewerUrl(): string {
// subscribe. Honors both `III_STREAM_PORT` (the singular name the
// engine docs use post-0.11) and `III_STREAMS_PORT` (the name our
// own config.ts has used since 0.7) so a single source of truth in
-// either form lights up the ready panel.
+// either form lights up the ready panel. Falls back to REST+1 so
+// `--port 3211` auto-picks 3212 instead of colliding on 3112 (#750).
function getStreamPort(): number {
return (
parseInt(process.env["III_STREAM_PORT"] || "", 10) ||
parseInt(process.env["III_STREAMS_PORT"] || "", 10) ||
- 3112
+ getRestPort() + 1
);
}
// Bridge WebSocket port — the iii engine's internal worker bus.
-// Defaults to 49134 (engine convention) and is overridable via
+// Defaults derived from REST as REST+46023 so the canonical 3111
+// anchor yields 49134 and `--port 3211` auto-picks 49234 without a
+// second-instance collision (#750). Overridable via
// `III_ENGINE_PORT` or the legacy `III_ENGINE_URL=ws://host:port`.
function getEnginePort(): number {
const explicit = parseInt(process.env["III_ENGINE_PORT"] || "", 10);
@@ -277,7 +302,7 @@ function getEnginePort(): number {
if (parsed) return parseInt(parsed, 10);
} catch {}
}
- return 49134;
+ return getRestPort() + 46023;
}
async function isEngineRunning(): Promise<boolean> {
diff --git a/src/config.ts b/src/config.ts
index b3f8882d..f68da2e3 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -161,10 +161,24 @@ export function loadConfig(): AgentMemoryConfig {
const provider = detectProvider(env);
+ // Port quartet: REST is the anchor; streams/engine derive from it
+ // unless individually overridden. Default anchor 3111 yields the
+ // canonical 3112 streams / 49134 engine pair, but `III_REST_PORT=3211`
+ // auto-picks 3212 + 49234 so a second instance doesn't collide (#750).
+ const restPort = parseInt(env["III_REST_PORT"] || "3111", 10) || 3111;
+ const streamsPort =
+ parseInt(env["III_STREAM_PORT"] || env["III_STREAMS_PORT"] || "", 10) ||
+ restPort + 1;
+ const engineUrl =
+ env["III_ENGINE_URL"] ||
+ `ws://localhost:${
+ parseInt(env["III_ENGINE_PORT"] || "", 10) || restPort + 46023
+ }`;
+
return {
- engineUrl: env["III_ENGINE_URL"] || "ws://localhost:49134",
- restPort: parseInt(env["III_REST_PORT"] || "3111", 10) || 3111,
- streamsPort: parseInt(env["III_STREAMS_PORT"] || "3112", 10) || 3112,
+ engineUrl,
+ restPort,
+ streamsPort,
provider,
tokenBudget: safeParseInt(env["TOKEN_BUDGET"], 2000),
maxObservationsPerSession: safeParseInt(env["MAX_OBS_PER_SESSION"], 500),
diff --git a/test/multi-instance-port.test.ts b/test/multi-instance-port.test.ts
new file mode 100644
index 00000000..4343365b
--- /dev/null
+++ b/test/multi-instance-port.test.ts
@@ -0,0 +1,85 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { loadConfig } from "../src/config";
+
+const PORT_ENVS = [
+ "III_REST_PORT",
+ "III_STREAM_PORT",
+ "III_STREAMS_PORT",
+ "III_ENGINE_PORT",
+ "III_ENGINE_URL",
+] as const;
+
+describe("multi-instance port auto-derive (#750)", () => {
+ const saved: Record<string, string | undefined> = {};
+
+ beforeEach(() => {
+ for (const k of PORT_ENVS) {
+ saved[k] = process.env[k];
+ delete process.env[k];
+ }
+ });
+
+ afterEach(() => {
+ for (const k of PORT_ENVS) {
+ if (saved[k] === undefined) {
+ delete process.env[k];
+ } else {
+ process.env[k] = saved[k];
+ }
+ }
+ });
+
+ it("default REST anchor yields canonical 3111/3112/49134 quartet", () => {
+ const cfg = loadConfig();
+ expect(cfg.restPort).toBe(3111);
+ expect(cfg.streamsPort).toBe(3112);
+ expect(cfg.engineUrl).toBe("ws://localhost:49134");
+ });
+
+ it("relocating REST drags streams + engine with it", () => {
+ process.env["III_REST_PORT"] = "3211";
+ const cfg = loadConfig();
+ expect(cfg.restPort).toBe(3211);
+ expect(cfg.streamsPort).toBe(3212);
+ expect(cfg.engineUrl).toBe("ws://localhost:49234");
+ });
+
+ it("instance N=2 block (3311) lands on 3312 + 49334", () => {
+ process.env["III_REST_PORT"] = "3311";
+ const cfg = loadConfig();
+ expect(cfg.restPort).toBe(3311);
+ expect(cfg.streamsPort).toBe(3312);
+ expect(cfg.engineUrl).toBe("ws://localhost:49334");
+ });
+
+ it("explicit III_STREAM_PORT pins streams without affecting REST/engine", () => {
+ process.env["III_REST_PORT"] = "3211";
+ process.env["III_STREAM_PORT"] = "9999";
+ const cfg = loadConfig();
+ expect(cfg.restPort).toBe(3211);
+ expect(cfg.streamsPort).toBe(9999);
+ expect(cfg.engineUrl).toBe("ws://localhost:49234");
+ });
+
+ it("legacy III_STREAMS_PORT still honored", () => {
+ process.env["III_STREAMS_PORT"] = "9000";
+ const cfg = loadConfig();
+ expect(cfg.streamsPort).toBe(9000);
+ });
+
+ it("explicit III_ENGINE_PORT pins engine without affecting REST/streams", () => {
+ process.env["III_REST_PORT"] = "3211";
+ process.env["III_ENGINE_PORT"] = "55555";
+ const cfg = loadConfig();
+ expect(cfg.restPort).toBe(3211);
+ expect(cfg.streamsPort).toBe(3212);
+ expect(cfg.engineUrl).toBe("ws://localhost:55555");
+ });
+
+ it("legacy III_ENGINE_URL overrides derivation entirely", () => {
+ process.env["III_REST_PORT"] = "3211";
+ process.env["III_ENGINE_URL"] = "ws://remote-host:49999";
+ const cfg = loadConfig();
+ expect(cfg.engineUrl).toBe("ws://remote-host:49999");
+ });
+});