feat: add configurable paseo home and port

packages/server/src/server/agent/agent-registry.ts

@@ -1,11 +1,10 @@
 import { randomUUID } from "node:crypto";
-import { existsSync } from "node:fs";
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { z } from "zod";
 
 import { AgentStatusSchema } from "../messages.js";
+import { resolvePaseoHome } from "../config.js";
 import { toStoredAgentRecord } from "./agent-projections.js";
 import type { ManagedAgent } from "./agent-manager.js";
 import type { AgentSessionConfig } from "./agent-sdk-types.js";
@@ -57,8 +56,7 @@ export class AgentRegistry {
   private filePath: string;
 
   constructor(filePath?: string) {
-    this.filePath =
-      filePath ?? path.join(resolveServerPackageRoot(), "agents.json");
+    this.filePath = filePath ?? path.join(resolvePaseoHome(), "agents.json");
   }
 
   async load(): Promise<StoredAgentRecord[]> {
@@ -188,22 +186,6 @@ export class AgentRegistry {
   }
 }
 
-function resolveServerPackageRoot(): string {
-  let currentDir = path.dirname(fileURLToPath(import.meta.url));
-  while (true) {
-    if (existsSync(path.join(currentDir, "package.json"))) {
-      return currentDir;
-    }
-    const parentDir = path.dirname(currentDir);
-    if (parentDir === currentDir) {
-      throw new Error(
-        "[AgentRegistry] Failed to locate server package root for agents.json"
-      );
-    }
-    currentDir = parentDir;
-  }
-}
-
 async function writeFileAtomically(targetPath: string, payload: string) {
   const directory = path.dirname(targetPath);
   const tempPath = path.join(

packages/server/src/server/agent/providers/claude-agent.ts

@@ -38,6 +38,7 @@ import type {
   ListPersistedAgentsOptions,
   PersistedAgentDescriptor,
 } from "../agent-sdk-types.js";
+import { resolvePaseoPort } from "../../config.js";
 
 const CLAUDE_CAPABILITIES: AgentCapabilityFlags = {
   supportsStreaming: true,
@@ -92,7 +93,7 @@ type ClaudeAgentSessionOptions = {
 };
 
 const DEFAULT_AGENT_CONTROL_MCP: AgentControlMcpConfig = {
-  url: "http://127.0.0.1:6767/mcp/agents",
+  url: `http://127.0.0.1:${resolvePaseoPort()}/mcp/agents`,
   headers: {
     Authorization: "Basic bW86Ym8=",
   },

packages/server/src/server/config.ts

@@ -0,0 +1,37 @@
+import os from "node:os";
+import path from "node:path";
+import { mkdirSync } from "node:fs";
+
+let cachedHomeDir: string | null = null;
+let cachedPort: number | null = null;
+
+function expandHomeDir(input: string): string {
+  if (input.startsWith("~/")) {
+    return path.join(os.homedir(), input.slice(2));
+  }
+  if (input === "~") {
+    return os.homedir();
+  }
+  return input;
+}
+
+export function resolvePaseoHome(): string {
+  if (cachedHomeDir) {
+    return cachedHomeDir;
+  }
+  const raw = process.env.PASEO_HOME ?? process.env.PASEO_HOME_DIR ?? "~/.paseo";
+  const expanded = path.resolve(expandHomeDir(raw));
+  mkdirSync(expanded, { recursive: true });
+  cachedHomeDir = expanded;
+  return cachedHomeDir;
+}
+
+export function resolvePaseoPort(): number {
+  if (cachedPort !== null) {
+    return cachedPort;
+  }
+  const raw = process.env.PASEO_PORT ?? process.env.PORT ?? "6767";
+  const parsed = Number.parseInt(raw, 10);
+  cachedPort = Number.isFinite(parsed) ? parsed : 6767;
+  return cachedPort;
+}

packages/server/src/server/index.ts

@@ -11,6 +11,7 @@ import { AgentManager } from "./agent/agent-manager.js";
 import { AgentRegistry } from "./agent/agent-registry.js";
 import { ClaudeAgentClient } from "./agent/providers/claude-agent.js";
 import { CodexAgentClient } from "./agent/providers/codex-agent.js";
+import { resolvePaseoPort } from "./config.js";
 import { initializeTitleGenerator } from "../services/agent-title-generator.js";
 import { attachAgentRegistryPersistence } from "./persistence-hooks.js";
 import { createAgentMcpServer } from "./agent/mcp-server.js";
@@ -73,7 +74,7 @@ function createServer() {
 }
 
 async function main() {
-  const port = parseInt(process.env.PORT || "6767", 10);
+  const port = resolvePaseoPort();
   const agentMcpRoute = "/mcp/agents";
   const agentMcpUrl = `http://127.0.0.1:${port}${agentMcpRoute}`;
   const [agentMcpUser, agentMcpPassword] =