Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
refactor: no hardcoded port numbers anywhere - .env.template is the SSOT
trohitg875ffff27933
diff --git a/.env b/.envindex b328a587..f7faab5d 100644--- a/.env+++ b/.env@@ -1,8 +1,8 @@# Service Ports (used by start.js, vite, and docker-compose)VITE_CLIENT_PORT=5678PYTHON_BACKEND_PORT=5678-NODEJS_EXECUTOR_PORT=5680-WHATSAPP_RPC_PORT=5681+NODEJS_EXECUTOR_PORT=5682+WHATSAPP_RPC_PORT=5683REDIS_PORT=6379# Server Configuration@@ -51,7 +51,7 @@ CACHE_TTL=300# by pooch from https://temporal.download/cli/archive/latest on# ``company build`` (or first ``company start`` if build was skipped).TEMPORAL_ENABLED=true-TEMPORAL_SERVER_ADDRESS=localhost:5682+TEMPORAL_SERVER_ADDRESS=localhost:5681TEMPORAL_NAMESPACE=default# Durable Temporal wire identifier retained so upgrades can resume in-flight# workflows. New display/package identifiers use OpenCompany.@@ -60,12 +60,12 @@ TEMPORAL_PER_TYPE_DISPATCH=trueTEMPORAL_AGENT_WORKFLOW_ENABLED=true# gRPC frontend port the CLI dev server binds (``--port``). Default per# https://docs.temporal.io/references/configuration.-TEMPORAL_FRONTEND_GRPC_PORT=5682+TEMPORAL_FRONTEND_GRPC_PORT=5681# Web UI port (``--ui-port``). ``temporal server start-dev`` defaults# this to ``--port + 1000``; we override to 8080 to match the# historical OpenCompany port (kept for muscle memory + bookmarks).# Browse to http://<host>:<TEMPORAL_UI_PORT>/.-TEMPORAL_UI_PORT=5683+TEMPORAL_UI_PORT=5680# SQLite db file ``temporal server start-dev --db-filename`` opens.# Relative to DATA_DIR (= ~/.opencompany/) unless absolute. Flat under# DATA_DIR like ``credentials.db`` / ``workflow.db``. History isdiff --git a/.env.template b/.env.templateindex 07062e2b..bb8b8a4b 100644--- a/.env.template+++ b/.env.template@@ -3,18 +3,18 @@# 5678 THE APP (always — uvicorn serving API + WS + SPA in production;# the Vite dev server in dev, proxying backend prefixes),# 5679 backend uvicorn in dev, behind the Vite proxy (.env.dev),-# 5680 Node.js executor, 5681 WhatsApp RPC,-# 5682 Temporal gRPC, 5683 Temporal Web UI.+# 5680 Temporal Web UI, 5681 Temporal gRPC,+# 5682 Node.js executor, 5683 WhatsApp RPC.VITE_CLIENT_PORT=5678PYTHON_BACKEND_PORT=5678# Plugin-owned (read by nodes/code/, not core Settings). Related# optional vars: NODEJS_EXECUTOR_URL (external executor override),# NODEJS_EXECUTOR_TIMEOUT.-NODEJS_EXECUTOR_PORT=5680+NODEJS_EXECUTOR_PORT=5682# Plugin-owned (read by nodes/whatsapp/, not core Settings). Related# optional vars: WHATSAPP_RUNTIME_ENABLED, WHATSAPP_DATA_SUBDIR,# WHATSAPP_BINARY_PATH, WHATSAPP_BIND_HOST, WHATSAPP_RPC_URL.-WHATSAPP_RPC_PORT=5681+WHATSAPP_RPC_PORT=5683REDIS_PORT=6379# Server Configuration@@ -64,7 +64,7 @@ CACHE_TTL=300# by pooch from https://temporal.download/cli/archive/latest on# ``company build`` (or first ``company start`` if build was skipped).TEMPORAL_ENABLED=true-TEMPORAL_SERVER_ADDRESS=localhost:5682+TEMPORAL_SERVER_ADDRESS=localhost:5681TEMPORAL_NAMESPACE=default# Durable Temporal wire identifier retained so upgrades can resume in-flight# workflows. New display/package identifiers use OpenCompany.@@ -93,11 +93,11 @@ DEPLOYMENT_MODE=local# 32-core cloud: TEMPORAL_AI_HEAVY_CONCURRENCY=16 TEMPORAL_BROWSER_CONCURRENCY=8 TEMPORAL_CODE_EXEC_CONCURRENCY=32# gRPC frontend port the dev server binds (``--port``) — part of the# 5678-based serial port block (Temporal's own default is 7233).-TEMPORAL_FRONTEND_GRPC_PORT=5682+TEMPORAL_FRONTEND_GRPC_PORT=5681# Web UI port (``--ui-port``). ``temporal server start-dev`` defaults# this to ``--port + 1000``; pinned into the serial port block instead.# Browse to http://<host>:<TEMPORAL_UI_PORT>/.-TEMPORAL_UI_PORT=5683+TEMPORAL_UI_PORT=5680# SQLite db file ``temporal server start-dev --db-filename`` opens.# Relative to DATA_DIR (= ~/.opencompany/) unless absolute. Flat under# DATA_DIR like ``credentials.db`` / ``workflow.db``. History isdiff --git a/.github/workflows/predeploy.yml b/.github/workflows/predeploy.ymlindex 3c10c49b..3a799033 100644--- a/.github/workflows/predeploy.yml+++ b/.github/workflows/predeploy.yml@@ -72,10 +72,11 @@ jobs:if: runner.os != 'Windows'shell: bashrun: |+ APP_PORT=$(grep -E '^PYTHON_BACKEND_PORT=' .env.template | cut -d= -f2)pnpm run start &PID=$!for i in {1..15}; do- curl -sf http://localhost:5678/health > /dev/null 2>&1 && break+ curl -sf "http://localhost:${APP_PORT}/health" > /dev/null 2>&1 && breaksleep 2donekill -0 $PID 2>/dev/null && pnpm run stop || (echo FAILED; exit 1)diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 702c777a..98cb10e7 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -129,7 +129,7 @@ Development from source uses **pnpm** (not npm). The `scripts/preinstall.js` hoo```bashpnpm install # install workspace dependencies-pnpm run dev # start frontend + backend + Temporal + WhatsApp+pnpm run dev # start the app (Vite HMR + backend; Temporal starts from the backend when TEMPORAL_ENABLED, WhatsApp only on demand)pnpm run stop # stop everythingpnpm run build # production buildpnpm exec tsc --noEmit # typecheck client (from client/)diff --git a/cli/cli.py b/cli/cli.pyindex 8ac28f9b..b3c43a10 100644--- a/cli/cli.py+++ b/cli/cli.py@@ -105,7 +105,7 @@ def _build() -> None:@app.command("serve",- help="Run on a single public port (API + WebSocket + built SPA + sidecar). Used by `company deploy`.",+ help="Run on a single public port (API + WebSocket + built SPA). Used by `company deploy`.",)def _serve(port: int | None = typer.Option(@@ -195,7 +195,7 @@ def _deploy_up(source: str = typer.Option("local", "--source", help="Install source: local (npm pack) or release (npm registry)."),version: str = typer.Option("latest", "--version", help="opencompany version when --source release."),machine_type: str = typer.Option("e2-standard-2", "--machine-type", help="VM size."),- port: int = typer.Option(5678, "--port", help="Public port the app binds + the firewall opens."),+ port: int | None = typer.Option(None, "--port", help="Public port the app binds + the firewall opens (default: PYTHON_BACKEND_PORT from .env.template)."),allow_cidr: str = typer.Option("0.0.0.0/0", "--allow-cidr", help="Firewall source range (restrict to your IP/32)."),region: str | None = typer.Option(None, "--region", help="Cloud region (provider default if omitted)."),zone: str | None = typer.Option(None, "--zone", help="Cloud zone (provider default if omitted)."),@@ -203,6 +203,10 @@ def _deploy_up() -> None:from cli.commands.deploy.up import up_command+ if port is None:+ from cli.config import load_config++ port = load_config().backend_portup_command(provider=provider,region=region,diff --git a/cli/commands/deploy/_secrets.py b/cli/commands/deploy/_secrets.pyindex ff44c007..f48be373 100644--- a/cli/commands/deploy/_secrets.py+++ b/cli/commands/deploy/_secrets.py@@ -55,7 +55,6 @@ def build_app_env("TEMPORAL_ENABLED": "false","EVENT_FRAMEWORK_ENABLED": "false","REDIS_ENABLED": "false",- "NODEJS_EXECUTOR_PORT": "5680","LOG_FORMAT": "text","JWT_SECRET_KEY": new_key(),"SECRET_KEY": new_key(),diff --git a/cli/commands/deploy/status.py b/cli/commands/deploy/status.pyindex 8f9a8493..d00cf37a 100644--- a/cli/commands/deploy/status.py+++ b/cli/commands/deploy/status.py@@ -25,7 +25,7 @@ def status_command() -> None:wd = _state.workdir()ip = _terraform.tf_output(wd, "external_ip")url = _terraform.tf_output(wd, "url") or (- f"http://{ip}:{meta.get('port', 8080)}" if ip else None+ f"http://{ip}:{meta.get('port') or load_config().backend_port}" if ip else None)console.print(" Deployment: OpenCompany")diff --git a/docs-internal/ROADMAP.md b/docs-internal/ROADMAP.mdindex 04f9e931..3d37d95e 100644--- a/docs-internal/ROADMAP.md+++ b/docs-internal/ROADMAP.md@@ -381,7 +381,7 @@ When `TEMPORAL_ENABLED=true`, each workflow node executes as an independent Temp#### Configuration```envTEMPORAL_ENABLED=true-TEMPORAL_SERVER_ADDRESS=localhost:5682+TEMPORAL_SERVER_ADDRESS=localhost:5681TEMPORAL_NAMESPACE=defaultTEMPORAL_TASK_QUEUE=machina-tasks```diff --git a/docs-internal/SCRIPTS.md b/docs-internal/SCRIPTS.mdindex 5aa2128c..393241d8 100644--- a/docs-internal/SCRIPTS.md+++ b/docs-internal/SCRIPTS.md@@ -111,9 +111,9 @@ Key variables in `.env` (see `.env.template` for the full list):|----------|---------|-------------|| `VITE_CLIENT_PORT` | 5678 | App port (Vite dev server; proxies backend prefixes) || `PYTHON_BACKEND_PORT` | 5678 | Backend port (5679 in dev via `.env.dev`, behind the Vite proxy) |-| `WHATSAPP_RPC_PORT` | 5681 | WhatsApp API port |-| `NODEJS_EXECUTOR_PORT` | 5680 | Node.js code-executor sidecar |-| — | 5682 / 5683 | Temporal gRPC / Temporal Web UI |+| `WHATSAPP_RPC_PORT` | 5683 | WhatsApp API port |+| `NODEJS_EXECUTOR_PORT` | 5682 | Node.js code-executor sidecar |+| — | 5681 / 5680 | Temporal gRPC / Temporal Web UI |### Features| Variable | Default | Description |diff --git a/docs-internal/SETUP.md b/docs-internal/SETUP.mdindex c12af3fe..61b9317e 100644--- a/docs-internal/SETUP.md+++ b/docs-internal/SETUP.md@@ -12,7 +12,7 @@ OpenCompany/│ ├── routers/ # API endpoints│ ├── core/ # DI container, database, cache│ ├── models/ # SQLModel definitions-│ ├── whatsapp-rpc/ # Go WhatsApp service (port 5681)+│ ├── whatsapp-rpc/ # Go WhatsApp service (port 5683)│ └── requirements.txt├── scripts/ # Build and utility scripts└── package.json # Workspace root with npm scripts@@ -50,8 +50,8 @@ cd server && uv sync --extra local-embeddingsServices (production `company start`):- **App (API + WS + SPA)**: http://localhost:5678-- **WhatsApp Service**: http://localhost:5681 (backend-spawned on demand)-- **Temporal dev server**: gRPC :5682, Web UI :5683 (backend-spawned when `TEMPORAL_ENABLED`)+- **WhatsApp Service**: http://localhost:5683 (backend-spawned on demand)+- **Temporal dev server**: gRPC :5681, Web UI :5680 (backend-spawned when `TEMPORAL_ENABLED`)`company dev` serves the same URL (http://localhost:5678) from the Vite HMR server, which proxies /api /ws /webhook to the backend on :5679.@@ -76,7 +76,7 @@ Services (production `company start`):- `POST /api/ai/*` - AI model execution- `POST /api/android/*` - Android device operations-### WhatsApp Service (Go - Default Port 9400)+### WhatsApp Service (Go — optional, on-demand; port `WHATSAPP_RPC_PORT`)- Go service using whatsmeow library- QR code authentication (base64 PNG in memory, no file I/O)- Message send/receive via JSON-RPC@@ -86,7 +86,7 @@ Services (production `company start`):- Provides durable workflow execution with per-node retry and horizontal scaling- Official `temporal` CLI downloaded by `pooch` from `https://temporal.download/cli/archive/latest` on `company build` (or first backend boot with Temporal enabled)- Backend-owned: the FastAPI lifespan starts `temporal server start-dev` via `TemporalServerRuntime.ensure_started()` when `TEMPORAL_ENABLED` and the configured address is loopback (external clusters are detected via TCP probe and left alone) — SQLite at `~/.opencompany/temporal.db`-- Ports: gRPC 5682, Web UI 5683+- Ports: gRPC 5681, Web UI 5680- Embedded worker runs inside Python backend (`TemporalWorkerManager` in `main.py`)- Workflow auto-resumption disabled at startup (history preserved); see `TEMPORAL_TERMINATE_RUNNING_ON_STARTUP`- See [Temporal Architecture](./TEMPORAL_ARCHITECTURE.md) and [CLI Services Guide](./cli_services_integration.md)@@ -145,7 +145,7 @@ When `VITE_AUTH_ENABLED=false` (the default):| Command | Description ||---------|-------------|-| `npm run start` | Start all services |+| `npm run start` | Start the app (backend-owned daemons start on demand) || `npm run stop` | Stop all services || `npm run build` | Install dependencies || `npm run dev` | Start development server |diff --git a/docs-internal/TEMPORAL_ARCHITECTURE.md b/docs-internal/TEMPORAL_ARCHITECTURE.mdindex a306592b..7eee37f7 100644--- a/docs-internal/TEMPORAL_ARCHITECTURE.md+++ b/docs-internal/TEMPORAL_ARCHITECTURE.md@@ -30,7 +30,7 @@ Each workflow node executes as a **Temporal activity** with its own isolated con**Running with Temporal** — the Temporal server and the embedded worker start automatically with every launch script:```bash-npm run start # Starts Temporal server + all services+npm run start # Starts the app; the backend lifespan starts the Temporal dev server when TEMPORAL_ENABLEDnpm run dev # Starts Temporal server + all services (dev mode)npm run stop # Stops all services including Temporal```@@ -49,7 +49,7 @@ This invokes `run_standalone_worker()` from `services/temporal/worker.py`.## System Architecture```- TEMPORAL SERVER (port 5682)+ TEMPORAL SERVER (port 5681)|Task Queue: machina-tasks (workflows + framework activities)+---------------------------------------------------------------+@@ -577,7 +577,7 @@ client = await Client.connect(server_address, namespace=namespace, runtime=runtiThe Temporal binary + persistence are managed in-process by the plugin-folder pattern at [`server/services/temporal/`](../server/services/temporal/). Single supervised process — the official `temporal` CLI's `server start-dev` mode, per [docs.temporal.io/develop/python/set-up-your-local-python](https://docs.temporal.io/develop/python/set-up-your-local-python). Five sibling files (`_install.py`, `_runtime.py`, `_handlers.py`, `_refresh.py`, `client.py`, plus `__init__.py` for registry wiring) match the [Wave 11 plugin-folder pattern](./plugin_system.md#self-contained-plugin-folders) that `server/nodes/whatsapp/` uses for its Go binary.-**What runs**: one process — `temporal server start-dev --port 5682 --ui-port 5683 --db-filename ~/.opencompany/temporal.db --namespace default`. Both gRPC + Web UI bind to the same process (per docs.temporal.io/cli/server — "all running in a single process"). SQLite-backed durability; history persisted across restarts.+**What runs**: one process — `temporal server start-dev --port 5681 --ui-port 5680 --db-filename ~/.opencompany/temporal.db --namespace default`. Both gRPC + Web UI bind to the same process (per docs.temporal.io/cli/server — "all running in a single process"). SQLite-backed durability; history persisted across restarts.**Modern libs doing the heavy lifting** (zero custom infrastructure code):- **[`pooch`](https://pypi.org/project/pooch/)** — `services/temporal/_install.py` downloads the official `temporal` CLI archive from `https://temporal.download/cli/archive/latest?platform=<os>&arch=<arch>`. Cross-platform (Windows zip / macOS+Linux tar.gz), cached at `<DATA_DIR>/packages/temporal/` via `_cache_dir() = core.paths.package_dir("temporal")` (pooch's `path=` argument). The retrieve call passes an explicit `downloader=pooch.HTTPDownloader(timeout=300, progressbar=True)`: the timeout is per-socket-read (not total transfer), so arbitrarily slow links can finish the ~114 MB fetch — pooch's 30 s default aborted them — and `progressbar` must live on the downloader because `retrieve()` ignores its own kwarg when `downloader=` is explicit. Failed downloads never poison the cache (pooch writes to a temp file and renames atomically on success). Standalone entry: `python -m services.temporal._install` — invoked **fatally** by `company build` step [6/6] (so first `company start` doesn't pay the download; contract locked by `test_temporal_install_is_fatal_on_failure`) and **non-fatally** by npm postinstall (`scripts/install.js` try/catch — `TemporalServerRuntime._pre_spawn()` re-downloads lazily on first `company start`, so a failed eager fetch never fails `npm install -g`). The binary cache survives `company clean` (`packages` is in `_OPENCOMPANY_KEEP`, `cli/commands/clean.py`). Pre-fix this used `pooch.os_cache("opencompany-temporal")` (`~/.cache/OpenCompany/opencompany-temporal/` etc.) — a separate OS-cache namespace operators reported as "not local"; it now sits under DATA_DIR alongside the Stripe binary and the shared npm tree.@@ -589,7 +589,7 @@ The Temporal binary + persistence are managed in-process by the plugin-folder pa**Resumption toggle**: [`TemporalClientWrapper.terminate_running_workflows`](../server/services/temporal/client.py) — runs once at server lifespan startup, between client connect and worker start, gated on `TEMPORAL_TERMINATE_RUNNING_ON_STARTUP` (default `true`). Queries Visibility for every `Running` workflow and calls `handle.terminate(reason="OpenCompany startup: auto-resumption disabled")`. **History is preserved** (UI shows workflows as `Terminated`, not deleted); only active execution stops. Disables resumption while `DeploymentManager` has no boot-time reconcile against Temporal Visibility yet — resumed workflows would otherwise keep executing but be invisible to the OpenCompany UI. Flip to `false` once the reconcile lands.-**Port management**: Temporal owns ports 5682 (gRPC) + 5683 (Web UI). Both bound by the same `temporal.exe` process; both listed in `cli.config.Config.all_ports` so `company stop`'s port-freeing pre-flight covers them.+**Port management**: Temporal owns ports 5681 (gRPC) + 5680 (Web UI). Both bound by the same `temporal.exe` process; both listed in `cli.config.Config.all_ports` so `company stop`'s port-freeing pre-flight covers them.**Direct CLI access**: the pooch-installed `temporal` binary lives under `<DATA_DIR>/packages/temporal/` (= `~/.opencompany/packages/temporal/` by default, on every OS). Run `temporal --version`, `temporal workflow list`, etc. directly from there.@@ -598,13 +598,13 @@ The Temporal binary + persistence are managed in-process by the plugin-folder pa| Setting | Env var | `.env.template` default | Purpose ||---|---|---|---|| `temporal_enabled` | `TEMPORAL_ENABLED` | `true` | Master toggle. When false, `WorkflowService` falls back to the sequential executor. |-| `temporal_server_address` | `TEMPORAL_SERVER_ADDRESS` | `localhost:5682` | Address the Python SDK client connects to. |+| `temporal_server_address` | `TEMPORAL_SERVER_ADDRESS` | `localhost:5681` | Address the Python SDK client connects to. || `temporal_namespace` | `TEMPORAL_NAMESPACE` | `default` | Bootstrapped at server start. || `temporal_task_queue` | `TEMPORAL_TASK_QUEUE` | `machina-tasks` | Default task queue for the embedded worker. || `temporal_per_type_dispatch` | `TEMPORAL_PER_TYPE_DISPATCH` | `true` | F4.A flag — per-type activity dispatch. || `temporal_agent_workflow_enabled` | `TEMPORAL_AGENT_WORKFLOW_ENABLED` | `true` | F4.B flag — agent-as-child-workflow. |-| `temporal_frontend_grpc_port` | `TEMPORAL_FRONTEND_GRPC_PORT` | `5682` | gRPC port (`--port`). Drives the readiness probe. |-| `temporal_ui_port` | `TEMPORAL_UI_PORT` | `5683` | Web UI port (`--ui-port`). CLI default is `--port + 1000`; pinned into the serial 5678-block instead. |+| `temporal_frontend_grpc_port` | `TEMPORAL_FRONTEND_GRPC_PORT` | `5681` | gRPC port (`--port`). Drives the readiness probe. |+| `temporal_ui_port` | `TEMPORAL_UI_PORT` | `5680` | Web UI port (`--ui-port`). CLI default is `--port + 1000`; pinned into the serial 5678-block instead. || `temporal_sqlite_path` | `TEMPORAL_SQLITE_PATH` | `temporal.db` | SQLite file (`--db-filename`). Resolved relative to `DATA_DIR` (= `~/.opencompany/`) unless absolute — flat under `~/.opencompany/` like `credentials.db` / `workflow.db`. || `temporal_graceful_shutdown_seconds` | `TEMPORAL_GRACEFUL_SHUTDOWN_SECONDS` | `30` | `CTRL_BREAK_EVENT` (Windows) / `SIGTERM` (POSIX) → tree-kill grace window. Shared with the embedded worker shutdown. || `temporal_terminate_running_on_startup` | `TEMPORAL_TERMINATE_RUNNING_ON_STARTUP` | `true` | Resumption toggle (see above). |@@ -622,7 +622,7 @@ through `Settings`:## Debugging-The Web UI is at http://localhost:5683; the UI's HTTP API rides the gRPC port + 1000 (6682).+The Web UI is at http://localhost:5680; the UI's HTTP API rides the gRPC port + 1000 (6681).### Reading Temporal tracing output@@ -671,10 +671,10 @@ duplicate execution.```bash# Temporal Web UI-open http://localhost:5683+open http://localhost:5680# List workflows via the local CLI binary (under <DATA_DIR>/packages/temporal/)-~/.opencompany/packages/temporal/.../temporal.exe workflow list --address localhost:5682+~/.opencompany/packages/temporal/.../temporal.exe workflow list --address localhost:5681# Re-fetch the binary at any timeuv run python -m services.temporal._installdiff --git a/docs-internal/cli_agent_framework.md b/docs-internal/cli_agent_framework.mdindex 72c45cb5..4d04c866 100644--- a/docs-internal/cli_agent_framework.md+++ b/docs-internal/cli_agent_framework.md@@ -237,8 +237,8 @@ Lockfile path: `~/.claude/ide/<pid>.lock` (Claude) or `<tmpdir>/gemini/ide/gemin```json{- "port": 3010,- "url": "http://127.0.0.1:3010/mcp/ide",+ "port": 5678,+ "url": "http://127.0.0.1:5678/mcp/ide","authToken": "<32-byte hex>","workspaceFolders": ["<absolute path to per-task git worktree>"],"ideName": "opencompany",@@ -553,7 +553,7 @@ Live verification (needs a real Claude install + auth):3. Click Disconnect. Modal flips Disconnected (`claude auth logout` clears CLI creds + marker dropped).4. Add a `claude_code_agent` node, set `tasks=[{prompt:"echo A"},{prompt:"echo B"},{prompt:"echo C"}]`, run. Three distinct `claude:<task_id>` Terminal streams interleaved. Three distinct session_ids. Three worktrees created and removed. `summary.wall_clock_ms < sum(duration_ms)` (proves parallelism).5. With a Claude task running, `cat ~/.claude/ide/<pid>.lock` and confirm format. Stream-json shows an `mcp__opencompany__*` tool invocation.-6. `curl -H "Authorization: Bearer <wrong>" http://127.0.0.1:3010/mcp/ide/...` → 401.+6. `curl -H "Authorization: Bearer <wrong>" http://127.0.0.1:5678/mcp/ide/...` → 401.## Risks / open considerationsdiff --git a/docs-internal/cli_services_integration.md b/docs-internal/cli_services_integration.mdindex 9ebdcb05..f342d496 100644--- a/docs-internal/cli_services_integration.md+++ b/docs-internal/cli_services_integration.md@@ -4,11 +4,10 @@ OpenCompany integrates external services that manage their own lifecycle via CLI## Principles-1. **Install globally** -- CLI tools must be available system-wide (`npm install -g <package>`)-2. **Use the CLI** -- Check status, start, stop via the package's own commands. No port-sniffing, no TCP socket checks, no hardcoded port detection.-3. **Don't manage their ports** -- External service ports are NOT added to `allPorts` in `utils.js`. OpenCompany only kills ports it owns (client, backend, WhatsApp, Node.js executor).-4. **Handle "already running"** -- Before adding a service to `concurrently`, check if it's already up. If it is, skip it. This prevents `--kill-others` cascade kills in `start.js`.-5. **Keep dependencies in package.json** -- Even if installed globally, keep the package in `dependencies` so npm scripts (`npm run temporal:start`) work.+1. **Plugin-owned binaries** -- OpenCompany-managed CLIs/binaries install into `<DATA_DIR>/packages/` from the plugin's own `_install.py` (pooch or the shared npm tree); truly external tools stay system-installed.+2. **Backend-owned lifecycle** -- long-lived daemons are `BaseProcessSupervisor` subclasses in the plugin folder, spawned on demand and stopped by `shutdown_all_supervisors()` at lifespan shutdown.+3. **Ports are declared in `.env.template`** -- the single place port numbers live. The CLI frees only the ports in `cli.config.Config.all_ports`; plugin daemons own theirs.+4. **Status is passive** -- status refreshes and WS status commands consult the supervisor (`is_running()`), never spawn.## Integrated CLI Services@@ -23,8 +22,8 @@ Wraps the official `temporal` CLI's `server start-dev` mode (per [docs.temporal.**Ports (declared in `.env.template`, freed by `company stop`'s port-kill pre-flight):**| Service | Port | Env var ||---------|------|---------|-| gRPC | 5682 | `TEMPORAL_FRONTEND_GRPC_PORT` |-| Web UI | 5683 | `TEMPORAL_UI_PORT` (CLI default is 8233; we override) |+| gRPC | 5681 | `TEMPORAL_FRONTEND_GRPC_PORT` |+| Web UI | 5680 | `TEMPORAL_UI_PORT` (CLI default is 8233; we override) |Both bound by the same `temporal.exe` process. Killing the process releases both.@@ -42,81 +41,32 @@ cd server && python -m services.temporal.worker## Adding a New CLI Service-Follow this pattern when integrating a new external CLI service:--### 1. Install globally and add to dependencies--```bash-npm install -g <service-package>-npm install <service-package>-```--### 2. Add npm scripts in package.json--```json-{- "<service>:start": "<service-cli> start",- "<service>:stop": "<service-cli> stop",- "<service>:status": "<service-cli> status"-}-```--### 3. Integrate in start.js (with --kill-others protection)--```javascript-let serviceRunning = false;-try {- const status = execSync('<service-cli> status', {- encoding: 'utf-8', timeout: 5000, stdio: 'pipe'- });- serviceRunning = /running|UP/i.test(status);-} catch {- serviceRunning = false;-}--if (serviceRunning) {- log('<Service> already running, skipping');-}--// Add to services list only if not running-if (!serviceRunning) services.push('npm:<service>:start');--// Add ready-detection pattern only if not running-if (!serviceRunning) {- readyPatterns.push({- name: '<Service>',- pattern: /<service>.*started|<service>.*ready/i- });-}-```--### 4. Integrate in stop.js--```javascript-// Kill by process name pattern -- NOT by port-const pids = await killByPattern('<service>');-if (pids.length > 0) {- console.log(`Killed ${pids.length} <service> processes`);-}-```--### 5. Do NOT add ports to allPorts--The service manages its own ports. Do not add them to `loadEnvConfig().allPorts` in `utils.js`.--### 6. dev.js -- usually no special handling needed--`dev.js` does not use `--kill-others`, so services exiting early is harmless. Just add `npm:<service>:start` to the services list unconditionally.-----+Follow the plugin-runtime pattern (references: `nodes/whatsapp/_runtime.py`,+`nodes/code/_runtime.py`, `services/temporal/_runtime.py`):++1. **Install** — plugin-owned `_install.py` that materialises the binary+ under `<DATA_DIR>/packages/<name>/` (pooch for release archives, the+ shared npm tree for npm packages). Idempotent; callable one-shot from+ `company build` when pre-caching is worth it.+2. **Supervise** — a `BaseProcessSupervisor` subclass in the plugin folder+ (`_runtime.py`) owning argv/cwd/env, with `ensure_started()`+ (probe-or-spawn) for on-demand starts. Register the singleton via+ `services._supervisor.register_supervisor` from the plugin+ `__init__.py` so lifespan shutdown reaches it.+3. **Start on demand** — the demand signals own the starts: node+ execution, user-initiated connect/login WS commands, or deploy-time+ trigger prechecks. Never start from a status refresh.+4. **Configure via env** — the service's port/vars are declared in+ `.env.template` (annotated plugin-owned) and read through+ `core.env_defaults` — no fallback literals in code.## Common Mistakes to Avoid| Mistake | Why it's wrong | Correct approach ||---------|---------------|-----------------|-| TCP socket check (`net.connect(port)`) | Fragile, races with other services, hardcodes ports | Use `<service-cli> status` |-| Adding service ports to `allPorts` | `killPort()` would kill the service during startup | Service manages its own ports |+| Spawning from a status refresh | a passive probe boots an optional daemon | Consult the supervisor (`is_running()`); demand signals own the starts |+| Adding plugin-daemon ports to `Config.all_ports` | the CLI would kill a backend-owned daemon during startup | The backend supervises them; the CLI carries no plugin knowledge || Resolving `node_modules/.bin/<cli>` path | Breaks if not in PATH, tribal workaround | Install globally || Using `npx <service-cli>` in `execSync` | Slow, may use wrong version, npx overhead | Install globally, call directly || Wrapping CLI in a JS script | Unnecessary indirection | Use CLI commands directly |-| Hardcoding port numbers for detection | Breaks if service config changes | Use CLI status command |+| Hardcoding port numbers in code or docs | drifts when ports change | Declare in `.env.template`; read via `core.env_defaults` |diff --git a/docs-internal/credentials_panel.md b/docs-internal/credentials_panel.mdindex a7a0ba37..bd0e1c64 100644--- a/docs-internal/credentials_panel.md+++ b/docs-internal/credentials_panel.md@@ -181,7 +181,7 @@ No logout WebSocket handler — user can manually delete the credentials file or### 2.7 Pattern G — QR pairing (WhatsApp)-**Credentials stored**: nothing in OpenCompany DB. Session lives inside the bundled `whatsapp-rpc` Go service (default port 5681).+**Credentials stored**: nothing in OpenCompany DB. Session lives inside the bundled `whatsapp-rpc` Go service (default port 5683).**Happy path**:```diff --git a/docs-internal/errors.md b/docs-internal/errors.mdindex 172e4d13..cc795e28 100644--- a/docs-internal/errors.md+++ b/docs-internal/errors.md@@ -188,7 +188,7 @@ Also changed `receive_timeout=540` to `receive_timeout=None` on `ws_connect()` -**Symptom**: Backend logs show:```-WhatsApp RPC timeout - Go service not responding at ws://localhost:5681/ws/rpc+WhatsApp RPC timeout - Go service not responding at ws://localhost:5683/ws/rpc```WhatsApp service health check (`/health`) returns 200 OK, but the WebSocket RPC connection fails.diff --git a/docs-internal/event_framework.md b/docs-internal/event_framework.mdindex 2682884b..e974294f 100644--- a/docs-internal/event_framework.md+++ b/docs-internal/event_framework.md@@ -235,7 +235,7 @@ inspection surface:- **Visibility list**: `client.list_workflows(query="ExecutionStatus='Failed' AND EventWorkflowId='<deployment_workflow_id>'")` returns every failed run for a deployment. The same Search Attributes the cancel sweep uses for cleanup (per `services/temporal/search_attributes.py`) make this query work.- **Failure detail**: `client.get_workflow_history(workflow_id, run_id)` returns the full Event History, including the `ActivityTaskFailed` event's error message + stacktrace + each retry attempt timestamp.-- **Temporal Web UI**: http://localhost:5683 — the same data, browsable.+- **Temporal Web UI**: http://localhost:5680 — the same data, browsable.This is why Wave 12 explicitly does NOT add a custom `event_dlq` SQLModel table. Doing so would reinvent the Temporal primitives the rest of the framework was built AROUND, not against. The pre-Temporal `services/execution/models.py::DLQEntry` for the legacy `WorkflowExecutor` is a separate concern and stays where it is.diff --git a/docs-internal/frontend_architecture.md b/docs-internal/frontend_architecture.mdindex 6b62b4af..93440746 100644--- a/docs-internal/frontend_architecture.md+++ b/docs-internal/frontend_architecture.md@@ -560,7 +560,7 @@ The DIY widget registry (RHF + zod + a tester+rank dispatch) is modeled on n8n's```bash# from repo rootpnpm install # client deps + server Python deps via postinstall-pnpm run dev # concurrently: client (Vite :3000) + server (uvicorn :3010) + temporal + whatsapp+pnpm run dev # supervisor: Vite client (app port, proxying) + uvicorn backend; Temporal/WhatsApp are backend-owned on-demand daemonspnpm run build # full prod build; bundle analyzer at dist/stats.html if ANALYZE=1# client-onlydiff --git a/docs-internal/gcp_vm_deploy_runbook.md b/docs-internal/gcp_vm_deploy_runbook.mdindex c1311361..e3c74628 100644--- a/docs-internal/gcp_vm_deploy_runbook.md+++ b/docs-internal/gcp_vm_deploy_runbook.md@@ -63,7 +63,8 @@ print('ENC='+secrets.token_hex(24))"on **:3010**) plus an nginx reverse proxy on :80/:443 — it works on every release.**Releases after 0.0.95**: `company start` became single-port itself (uvicornserves the SPA; no :3000 static server) AND the default ports moved to the- serial 5678 block (backend :5678, WhatsApp :5681, Temporal :5682/:5683).+ serial 5678 block (backend :5678, Temporal UI :5680, Temporal gRPC :5681,+ Node.js executor :5682, WhatsApp :5683).When upgrading a VM past 0.0.95, point EVERY nginx `proxy_pass` in step 2(`/api/`, `/ws/`, `/webhook/`, `/health`, and `location /`) at`http://127.0.0.1:5678;` and reload nginx.@@ -411,7 +412,7 @@ gcloud compute ssh <VM_NAME> --zone=<ZONE> --quiet --command="sudo npm install -# flip an env toggle (sudo on EVERY command touching the 600 env file - pitfall 13c):gcloud compute ssh <VM_NAME> --zone=<ZONE> --quiet --command="sudo sed -i 's/TEMPORAL_ENABLED=false/TEMPORAL_ENABLED=true/' /etc/opencompany/opencompany.env; sudo systemctl restart opencompany"# Temporal Web UI (localhost-bound on the VM; gRPC :7233, UI :8080 on-# releases <= 0.0.95; :5682/:5683 after the serial-port change):+# releases <= 0.0.95; :5681/:5680 after the serial-port change):gcloud compute ssh <VM_NAME> --zone=<ZONE> --tunnel-through-iap -- -L 8080:localhost:8080# then open http://localhost:8080. Note: `company start` runs the Temporal dev# server regardless of TEMPORAL_ENABLED; the flag only controls whether thediff --git a/docs-internal/node-logic-flows/_TEMPLATE.md b/docs-internal/node-logic-flows/_TEMPLATE.mdindex 69ebe7a4..2c82bd3b 100644--- a/docs-internal/node-logic-flows/_TEMPLATE.md+++ b/docs-internal/node-logic-flows/_TEMPLATE.md@@ -85,7 +85,7 @@ flowchart TD## External Dependencies- **Credentials**: <provider key looked up via `auth_service.get_api_key('<provider>')`>-- **Services**: <e.g. WhatsApp RPC at `localhost:5681`, agent-browser CLI>+- **Services**: <e.g. WhatsApp RPC at `localhost:5683`, agent-browser CLI>- **Python packages**: <e.g. `httpx`, `xdk`, `apify-client`>- **Environment variables**: <if any>diff --git a/docs-internal/node-logic-flows/code_fs_process/javascriptExecutor.md b/docs-internal/node-logic-flows/code_fs_process/javascriptExecutor.mdindex b20f7f88..115b36e9 100644--- a/docs-internal/node-logic-flows/code_fs_process/javascriptExecutor.md+++ b/docs-internal/node-logic-flows/code_fs_process/javascriptExecutor.md@@ -13,7 +13,7 @@Runs user JavaScript through the persistent Node.js executor server (Express +tsx) that the Python backend spawns on startup. The plugin does **not** spawn-`node` per call - it POSTs the code to `http://localhost:5680/execute` via the+`node` per call - it POSTs the code to `http://localhost:5682/execute` via theshared `get_nodejs_client()` singleton (an async `aiohttp` client). The Node.jsserver evaluates the script and returns `{success, output, console_output, ...}`.@@ -40,7 +40,7 @@ into an `input_data` object, injects the workflow's `workspace_dir`## Node.js client singleton`get_nodejs_client()` in [`_nodejs.py`](../../../server/nodes/code/_nodejs.py) lazily-constructs one `NodeJSClient(base_url="http://localhost:5680", timeout=30)` shared+constructs one `NodeJSClient(base_url="http://localhost:5682", timeout=30)` sharedacross the JS + TS plugins. The defaults are hard-coded in the helper signature(no per-call kwargs from the plugin).@@ -72,7 +72,7 @@ flowchart TDC --> D[input_data = ctx.raw connected_outputs or {}<br/>inject workspace_dir]D --> F[get_nodejs_client<br/>lazy singleton]F --> G[client.execute<br/>POST /execute<br/>language=javascript]- G -- ClientConnectorError --> H1[raise NodeUserError<br/>JS executor not running on :3020]+ G -- ClientConnectorError --> H1[raise NodeUserError<br/>JS executor not running on :5682]G -- success=false --> H2[raise NodeUserError<br/>error=result.error]G -- success=true --> I[Return dict<br/>output, console_output]```@@ -91,13 +91,13 @@ flowchart TDplugin raises `NodeUserError(result["error"] or "JavaScript executor failed")`.- **Sidecar down**: `aiohttp.ClientConnectorError` is caught and re-raised as a`NodeUserError` telling the LLM the Node executor is unreachable on- localhost:5680 and to fall back to `python_executor`.+ localhost:5682 and to fall back to `python_executor`.## Side Effects- **Database writes**: none.- **Broadcasts**: none from this handler.-- **External API calls**: `POST http://localhost:5680/execute`+- **External API calls**: `POST http://localhost:5682/execute`(configurable via `NODEJS_EXECUTOR_URL`). Body:`{code, input_data, language: "javascript", timeout}`.- **File I/O**: none from Python; the Node.js server may read/write user@@ -110,7 +110,7 @@ flowchart TD## External Dependencies- **Credentials**: none.-- **Services**: Persistent Node.js executor at `http://localhost:5680`.+- **Services**: Persistent Node.js executor at `http://localhost:5682`.Must be running - the backend start script boots it alongside uvicorn.- **Python packages**: `aiohttp`.- **Environment variables**: `NODEJS_EXECUTOR_URL`,@@ -123,7 +123,7 @@ flowchart TDfirst call at the hard-coded `base_url`/`timeout`. Reset by setting`services.code._nodejs._client = None` (or `nodes.code._nodejs._client`).- **Node server down**: connection refused surfaces as- `error="Cannot connect to host localhost:5680 ssl:default [Connect call+ `error="Cannot connect to host localhost:5682 ssl:default [Connect callfailed]"` or similar aiohttp message. No automatic retry.- **`workspace_dir` key collision**: user code cannot read an upstream`workspace_dir` from `input_data` - the handler always overwrites it.diff --git a/docs-internal/node-logic-flows/code_fs_process/typescriptExecutor.md b/docs-internal/node-logic-flows/code_fs_process/typescriptExecutor.mdindex e03f1dc2..bb3c77e3 100644--- a/docs-internal/node-logic-flows/code_fs_process/typescriptExecutor.md+++ b/docs-internal/node-logic-flows/code_fs_process/typescriptExecutor.md@@ -40,7 +40,7 @@ by the executor for code-executor node types) and the workflow's## Node.js client singletonShares `get_nodejs_client()` in [`_nodejs.py`](../../../server/nodes/code/_nodejs.py)-with the JS plugin — one `NodeJSClient(base_url="http://localhost:5680",+with the JS plugin — one `NodeJSClient(base_url="http://localhost:5682",timeout=30)` instance, hard-coded defaults.## Outputs (handles)@@ -71,7 +71,7 @@ flowchart TDC --> D[input_data = ctx.raw connected_outputs or {}<br/>inject workspace_dir]D --> F[get_nodejs_client<br/>lazy singleton]F --> G[client.execute<br/>POST /execute<br/>language=typescript]- G -- ClientConnectorError --> H1[raise NodeUserError<br/>TS executor not running on :3020]+ G -- ClientConnectorError --> H1[raise NodeUserError<br/>TS executor not running on :5682]G -- success=false --> H2[raise NodeUserError<br/>error=result.error]G -- success=true --> I[Return dict<br/>output, console_output]```@@ -85,7 +85,7 @@ wire-level difference is the POST body's `language` field.- **Database writes**: none.- **Broadcasts**: none.-- **External API calls**: `POST http://localhost:5680/execute` with body+- **External API calls**: `POST http://localhost:5682/execute` with body`{code, input_data, language: "typescript", timeout}`.- **Subprocess**: none directly.- **Module-level state**: shares the `_nodejs_client` singleton with the JS@@ -93,7 +93,7 @@ wire-level difference is the POST body's `language` field.## External Dependencies-- **Services**: Persistent Node.js executor at `http://localhost:5680`.+- **Services**: Persistent Node.js executor at `http://localhost:5682`.The server must have `tsx` available (pinned in `server/nodejs/package.json`).- **Python packages**: `aiohttp`.- **Environment variables**: `NODEJS_EXECUTOR_URL`, `NODEJS_EXECUTOR_TIMEOUT`.diff --git a/docs-internal/node-logic-flows/telegram_social/socialSend.md b/docs-internal/node-logic-flows/telegram_social/socialSend.mdindex 3d50b607..45c4ad79 100644--- a/docs-internal/node-logic-flows/telegram_social/socialSend.md+++ b/docs-internal/node-logic-flows/telegram_social/socialSend.md@@ -144,7 +144,7 @@ flowchart TD- **External API calls**: delegated to the WhatsApp send handler resolved via`get_social_send_handler("whatsapp")` (the whatsapp plugin self-registers itfrom `nodes/whatsapp/__init__.py`), which hits the WhatsApp RPC service- (default `http://localhost:5681`).+ (default `http://localhost:5683`).- **File I/O**: none from this handler. `mediaSource=file` reads are delegated.- **Subprocess**: none.diff --git a/docs-internal/node-logic-flows/whatsapp/whatsappDb.md b/docs-internal/node-logic-flows/whatsapp/whatsappDb.mdindex f277e80d..fe77dc5c 100644--- a/docs-internal/node-logic-flows/whatsapp/whatsappDb.md+++ b/docs-internal/node-logic-flows/whatsapp/whatsappDb.md@@ -130,7 +130,7 @@ flowchart TD## External Dependencies- **Credentials**: none.-- **Services**: `whatsapp-rpc` Go service (default `ws://localhost:5681/ws/rpc`).+- **Services**: `whatsapp-rpc` Go service (default `ws://localhost:5683/ws/rpc`).- **Python packages**: `asyncio`.- **Environment variables**: `WHATSAPP_RPC_URL`.diff --git a/docs-internal/node-logic-flows/whatsapp/whatsappSend.md b/docs-internal/node-logic-flows/whatsapp/whatsappSend.mdindex aae0848a..90a8ef7a 100644--- a/docs-internal/node-logic-flows/whatsapp/whatsappSend.md+++ b/docs-internal/node-logic-flows/whatsapp/whatsappSend.md@@ -124,16 +124,16 @@ flowchart TD- **Database writes**: none directly from this handler. (API-usage cost is recorded by the `@Operation` `cost` metadata via `BaseNode.execute()`.)- **Broadcasts**: none directly - standard node_status transitions come from `BaseNode.execute()`.-- **External calls**: WebSocket RPC to the Go `whatsapp-rpc` service via [`nodes/whatsapp/_service.py::whatsapp_rpc_call`](../../../server/nodes/whatsapp/_service.py). Default URL `ws://localhost:5681/ws/rpc` (overridable via `WHATSAPP_RPC_URL`). For media URLs, `_service.py` additionally downloads via `httpx`.+- **External calls**: WebSocket RPC to the Go `whatsapp-rpc` service via [`nodes/whatsapp/_service.py::whatsapp_rpc_call`](../../../server/nodes/whatsapp/_service.py). Default URL `ws://localhost:5683/ws/rpc` (overridable via `WHATSAPP_RPC_URL`). For media URLs, `_service.py` additionally downloads via `httpx`.- **File I/O**: none in this handler - file uploads are handled in `_service.py`.- **Subprocess**: none.## External Dependencies- **Credentials**: none at the node handler level. Pairing state is owned by the Go service; the handler is credential-free.-- **Services**: `whatsapp-rpc` (Go) on port 5681 (default). `services.markdown_formatter.to_whatsapp` when `format_markdown` is enabled.+- **Services**: `whatsapp-rpc` (Go) on port 5683 (default). `services.markdown_formatter.to_whatsapp` when `format_markdown` is enabled.- **Python packages**: `asyncio`. (`httpx` is used inside `_service.py` for URL media fetches.)-- **Environment variables**: `WHATSAPP_RPC_URL` (optional, default `ws://localhost:5681/ws/rpc`).+- **Environment variables**: `WHATSAPP_RPC_URL` (optional, default `ws://localhost:5683/ws/rpc`).## Edge cases & known limitsdiff --git a/docs-internal/release_build_pipeline.md b/docs-internal/release_build_pipeline.mdindex 65cae473..333150f9 100644--- a/docs-internal/release_build_pipeline.md+++ b/docs-internal/release_build_pipeline.md@@ -110,7 +110,7 @@ Idempotent on re-runs (compileall only rewrites stale pyc; esbuild is determinis1. `pnpm --filter react-flow-client run typecheck` → <5s, zero errors.2. `ANALYZE=1 pnpm --filter react-flow-client run build` → open `client/dist/stats.html`. Expect: no chunk above 600 KB gz, main < 200 KB gz, `vendor-flow` split.-3. `cd server/nodejs && npm run build && node dist/index.js` → starts on :3020 in <100ms.+3. `cd server/nodejs && npm run build && node dist/index.js` → starts on :5682 in <100ms.4. `cd server && uv run python -m compileall -q -j 0 services` → plain `__pycache__/*.pyc` present (no `.opt-1.pyc` — nothing loads those).5. Cold-start: clean install + `company start > start.log 2>&1` → `Application startup complete` at ≤+50s (was +66.9s).6. `npm pack --dry-run` → `server/nodejs/dist/index.js` included; no `__pycache__/`; tarball size ≤ v0.0.76.diff --git a/docs-internal/stripe_service.md b/docs-internal/stripe_service.mdindex 02302781..b5b72818 100644--- a/docs-internal/stripe_service.md+++ b/docs-internal/stripe_service.md@@ -729,7 +729,7 @@ class attributes:| Binary name | `StripeListenSource.binary_name` | `"stripe"` || Daemon process key | `StripeListenSource.workflow_namespace` | `"_stripe"` (logical `ProcessService` key; cwd is the shared `daemons_dir()` = `<DATA_DIR>/daemons/`, not a per-namespace subdir) || Webhook path | `StripeWebhookSource.path` | `"stripe"` (i.e. `/webhook/stripe`) |-| Forward-to port | derived from `Settings().port` | typically `3010` |+| Forward-to port | derived from `Settings().port` | the app port (`PYTHON_BACKEND_PORT`) || Verifier | `StripeWebhookSource.verifier` | `StripeVerifier` || Action operation cost | `@Operation("run", cost=…)` | `{service: "stripe", action: "run", count: 1}` |diff --git a/docs/diagrams/system-overview.svg b/docs/diagrams/system-overview.svgindex 3f53835f..b36fadd3 100644--- a/docs/diagrams/system-overview.svg+++ b/docs/diagrams/system-overview.svg@@ -81,17 +81,17 @@<rect class="panel p-orange" x="230" y="726" width="960" height="120" rx="10"/><rect class="box p-orange" x="250" y="746" width="215" height="80" rx="8"/>- <text class="h2" x="357" y="772" text-anchor="middle">Node.js executor :5680</text>+ <text class="h2" x="357" y="772" text-anchor="middle">Node.js executor :5682</text><text class="small" x="357" y="792" text-anchor="middle">Express + tsx</text><text class="small" x="357" y="808" text-anchor="middle">JS/TS code nodes</text><rect class="box p-orange" x="485" y="746" width="215" height="80" rx="8"/>- <text class="h2" x="592" y="772" text-anchor="middle">WhatsApp RPC :5681</text>+ <text class="h2" x="592" y="772" text-anchor="middle">WhatsApp RPC :5683</text><text class="small" x="592" y="792" text-anchor="middle">Go whatsmeow binary</text><rect class="box p-orange" x="720" y="746" width="215" height="80" rx="8"/><text class="h2" x="827" y="772" text-anchor="middle">Temporal server</text>- <text class="small" x="827" y="792" text-anchor="middle">gRPC :5682 - Web UI :5683</text>+ <text class="small" x="827" y="792" text-anchor="middle">gRPC :5681 - Web UI :5680</text><rect class="box p-orange" x="955" y="746" width="215" height="80" rx="8"/><text class="h2" x="1062" y="772" text-anchor="middle">Temporal workers</text>diff --git a/install.ps1 b/install.ps1index 7042c362..674aa513 100644--- a/install.ps1+++ b/install.ps1@@ -209,7 +209,8 @@ function Main {Write-Host " company start"Write-Host ""Write-Host " Open in browser:"- Write-Host " http://localhost:5678"+ $appPort = (Select-String -Path ".env.template" -Pattern "^PYTHON_BACKEND_PORT=(\d+)" -ErrorAction SilentlyContinue).Matches.Groups[1].Value+ Write-Host " http://localhost:$appPort"Write-Host ""Write-Host " For development from source, install pnpm:"Write-Host " npm install -g pnpm"diff --git a/install.sh b/install.shindex a128f6d4..b12c928e 100755--- a/install.sh+++ b/install.sh@@ -315,7 +315,8 @@ main() {echo " company start"echo ""echo " Open in browser:"- echo " http://localhost:5678"+ APP_PORT=$(grep -E '^PYTHON_BACKEND_PORT=' .env.template 2>/dev/null | cut -d= -f2)+ echo " http://localhost:${APP_PORT}"echo ""echo " Optional: Enable JS-rendered web scraping:"echo " playwright install chromium"diff --git a/package.json b/package.jsonindex b87599eb..a0ea16fe 100644--- a/package.json+++ b/package.json@@ -73,8 +73,8 @@"serve": "python -m cli serve","start:temporal": "cross-env TEMPORAL_ENABLED=true python -m cli start","client:start": "cd client && npm run start",- "python:start": "cd server && uv run uvicorn main:app --host 127.0.0.1 --port 5678 --log-level warning",- "python:daemon": "cd server && uv run uvicorn main:app --host 0.0.0.0 --port 5678 --log-level warning",+ "python:start": "cd server && uv run python main.py",+ "python:daemon": "cd server && cross-env HOST=0.0.0.0 uv run python main.py","temporal:start": "temporal api","temporal:stop": "temporal stop","temporal:status": "temporal status",diff --git a/scripts/postinstall.js b/scripts/postinstall.jsindex cf7f3560..64176c59 100755--- a/scripts/postinstall.js+++ b/scripts/postinstall.js@@ -9,7 +9,7 @@import { spawn, execSync } from 'child_process';import { resolve, dirname } from 'path';import { fileURLToPath } from 'url';-import { existsSync, chmodSync } from 'fs';+import { existsSync, chmodSync, readFileSync } from 'fs';const __dirname = dirname(fileURLToPath(import.meta.url));const ROOT = resolve(__dirname, '..');@@ -129,7 +129,12 @@ async function main() {console.log('========================================');console.log('');console.log('Run: company start');- console.log('Open: http://localhost:5678');+ // App port comes from .env.template (the single place port numbers live).+ let appPort = '';+ try {+ appPort = /^PYTHON_BACKEND_PORT=(\d+)/m.exec(readFileSync(resolve(ROOT, '.env.template'), 'utf-8'))[1];+ } catch { /* template missing - skip the URL line */ }+ if (appPort) console.log(`Open: http://localhost:${appPort}`);console.log('');} catch (err) {diff --git a/server/core/env_defaults.py b/server/core/env_defaults.pynew file mode 100644index 00000000..6f6b39d5--- /dev/null+++ b/server/core/env_defaults.py@@ -0,0 +1,66 @@+"""Env accessor backed by the repo's canonical env files.++The default value for every OpenCompany env var lives in ONE place:+``<repo>/.env.template`` (overridden by ``<repo>/.env``, overridden by+the process environment — the same precedence ``cli.config.load_config``+uses). The CLI pushes that merged view into ``os.environ`` for every+process it spawns; entry points that bypass the CLI (direct ``uvicorn``+runs, ``python -m services.temporal.worker``, gunicorn, pytest when a+code path is actually exercised) resolve through this helper instead of+carrying fallback literals in code.++Stdlib-only and dependency-free so it is importable from anywhere+(gunicorn config, plugin folders, the stubbed-core test environment).+"""++from __future__ import annotations++import os+from functools import lru_cache+from pathlib import Path++_REPO_ROOT = Path(__file__).resolve().parents[2]+++def _parse_env_file(path: Path) -> dict[str, str]:+ """Minimal KEY=VALUE parser — mirrors ``cli.config._load_env_file``+ semantics (skip blanks/comments, first ``=`` splits, strip quotes)."""+ values: dict[str, str] = {}+ try:+ text = path.read_text(encoding="utf-8")+ except OSError:+ return values+ for line in text.splitlines():+ line = line.strip()+ if not line or line.startswith("#") or "=" not in line:+ continue+ key, _, value = line.partition("=")+ values[key.strip()] = value.strip().strip("'\"")+ return values+++@lru_cache(maxsize=1)+def _file_defaults() -> dict[str, str]:+ merged = _parse_env_file(_REPO_ROOT / ".env.template")+ merged.update(_parse_env_file(_REPO_ROOT / ".env"))+ return merged+++def env_value(key: str) -> str:+ """Resolve ``key`` from the process env, then ``.env`` / ``.env.template``.++ Raises ``RuntimeError`` with a pointer to the canonical file when the+ key is configured nowhere — a loud failure instead of a silent+ hardcoded fallback.+ """+ value = os.environ.get(key) or _file_defaults().get(key)+ if not value:+ raise RuntimeError(+ f"{key} is not configured. Set it in the environment or .env; "+ "canonical defaults live in .env.template."+ )+ return value+++def env_int(key: str) -> int:+ return int(env_value(key))diff --git a/server/gunicorn.conf.py b/server/gunicorn.conf.pyindex d587b502..6bad9bb0 100644--- a/server/gunicorn.conf.py+++ b/server/gunicorn.conf.py@@ -10,9 +10,12 @@ Usage:import osimport multiprocessing-# Load from environment (same vars used by config.py)+from core.env_defaults import env_value++# Load from environment (same vars used by config.py); the canonical+# PORT default lives in .env.template via core.env_defaults.host = os.getenv("HOST", "0.0.0.0")-port = os.getenv("PORT", "5678")+port = env_value("PORT")workers_env = os.getenv("WORKERS", "0") # 0 = auto-calculatelog_level = os.getenv("LOG_LEVEL", "INFO").lower()debug = os.getenv("DEBUG", "false").lower() == "true"diff --git a/server/nodejs/src/index.ts b/server/nodejs/src/index.tsindex 0014e000..9b5ffe0d 100644--- a/server/nodejs/src/index.ts+++ b/server/nodejs/src/index.ts@@ -12,7 +12,12 @@ import { fileURLToPath } from 'node:url';const __dirname = path.dirname(fileURLToPath(import.meta.url));// All configuration from environment variables-const PORT = parseInt(process.env.NODEJS_EXECUTOR_PORT ?? '', 10) || 5680;+const PORT = parseInt(process.env.NODEJS_EXECUTOR_PORT ?? '', 10);+if (!PORT) {+ // Spawned by nodes/code/_runtime.py, which always injects the port+ // (canonical default lives in .env.template). No hardcoded fallback.+ throw new Error('NODEJS_EXECUTOR_PORT is not set - defaults live in .env.template');+}const HOST = process.env.NODEJS_EXECUTOR_HOST ?? 'localhost';const BODY_LIMIT = process.env.NODEJS_EXECUTOR_BODY_LIMIT ?? '10mb';const USER_PACKAGES_DIR = process.env.NODEJS_USER_PACKAGES_DIR ?? path.join(__dirname, '..', 'user-packages');diff --git a/server/nodes/code/_client.py b/server/nodes/code/_client.pyindex 80f668fc..13d5f209 100644--- a/server/nodes/code/_client.py+++ b/server/nodes/code/_client.py@@ -14,7 +14,7 @@ class NodeJSClient:"""Initialize client with base URL and timeout.Args:- base_url: Base URL of Node.js server (e.g., http://127.0.0.1:5680)+ base_url: Base URL of Node.js server (composed from NODEJS_EXECUTOR_PORT; defaults live in .env.template)timeout: Default request timeout in seconds"""self._base_url = base_url.rstrip("/")diff --git a/server/nodes/code/_runtime.py b/server/nodes/code/_runtime.pyindex fcc2d39c..0ae86f22 100644--- a/server/nodes/code/_runtime.py+++ b/server/nodes/code/_runtime.py@@ -56,7 +56,9 @@ async def _probe_tcp_port(port: int, host: str = "localhost") -> bool:def executor_port() -> int:- return int(os.environ.get("NODEJS_EXECUTOR_PORT") or 5680)+ from core.env_defaults import env_int++ return env_int("NODEJS_EXECUTOR_PORT")def _sidecar_dir() -> Path:diff --git a/server/nodes/whatsapp/_runtime.py b/server/nodes/whatsapp/_runtime.pyindex b3e6e08a..da90fe01 100644--- a/server/nodes/whatsapp/_runtime.py+++ b/server/nodes/whatsapp/_runtime.py@@ -70,7 +70,9 @@ class WhatsAppRuntime(BaseProcessSupervisor):@propertydef port(self) -> int:- return int(os.environ.get("WHATSAPP_RPC_PORT") or 5681)+ from core.env_defaults import env_int++ return env_int("WHATSAPP_RPC_PORT")@propertydef bind_host(self) -> str:diff --git a/server/nodes/whatsapp/_service.py b/server/nodes/whatsapp/_service.pyindex 2d136ac5..cbb37935 100644--- a/server/nodes/whatsapp/_service.py+++ b/server/nodes/whatsapp/_service.py@@ -33,9 +33,18 @@ def qr_code_to_base64(code: str) -> str:logger = logging.getLogger(__name__)-WHATSAPP_RPC_URL = os.getenv("WHATSAPP_RPC_URL") or (- f"ws://localhost:{os.getenv('WHATSAPP_RPC_PORT') or 5681}/ws/rpc"-)+def rpc_url() -> str:+ """Configured RPC endpoint — env-driven, no hardcoded port.++ ``WHATSAPP_RPC_URL`` wins outright (external service override);+ otherwise the URL composes from the plugin-owned port, whose+ canonical default lives in ``.env.template`` (core.env_defaults).+ """+ from core.env_defaults import env_value++ return os.getenv("WHATSAPP_RPC_URL") or (+ f"ws://localhost:{env_value('WHATSAPP_RPC_PORT')}/ws/rpc"+ )def extract_phone_from_jid(jid: str | None) -> str | None:@@ -339,19 +348,20 @@ async def get_client(force_reconnect: bool = False, *, spawn: bool = True) -> RP_client = Noneif not _client or not _client.connected:- logger.info(f"[WhatsApp RPC] Creating new connection to {WHATSAPP_RPC_URL}")- _client = RPCClient(WHATSAPP_RPC_URL)+ url = rpc_url()+ logger.info(f"[WhatsApp RPC] Creating new connection to {url}")+ _client = RPCClient(url)try:await _client.connect()logger.info("[WhatsApp RPC] Connected successfully")except asyncio.TimeoutError:_client = None- logger.error(f"WhatsApp RPC timeout - Go service not responding at {WHATSAPP_RPC_URL}")+ logger.error(f"WhatsApp RPC timeout - Go service not responding at {url}")raise Exception("WhatsApp service timeout - is Go service running?")except (ConnectionRefusedError, OSError) as e:_client = Nonelogger.error(f"WhatsApp RPC connection refused: {e}")- raise Exception("WhatsApp service not running - start Go whatsmeow service on port 5681")+ raise Exception(f"WhatsApp service not running - start the Go whatsmeow service at {url}")except Exception as e:_client = Nonelogger.error(f"WhatsApp RPC error: {e}")diff --git a/server/package.json b/server/package.jsonindex 1e11cdfb..a7ce8ea6 100644--- a/server/package.json+++ b/server/package.json@@ -3,8 +3,8 @@"private": true,"version": "0.0.0","scripts": {- "start": "python -m uvicorn main:app --host 0.0.0.0 --port ${PORT:-5678}",- "dev": "python -m uvicorn main:app --host 127.0.0.1 --port ${PORT:-5678} --reload --reload-dir . --reload-exclude \"*.pyc\" --reload-exclude \"__pycache__\" --log-level warning"+ "start": "python -m uvicorn main:app --host 0.0.0.0 --port ${PORT:?not set - defaults live in .env.template}",+ "dev": "python -m uvicorn main:app --host 127.0.0.1 --port ${PORT:?not set - defaults live in .env.template} --reload --reload-dir . --reload-exclude \"*.pyc\" --reload-exclude \"__pycache__\" --log-level warning"},"dependencies": {"@react-three/drei": "^10.7.7",diff --git a/server/services/cli_agent/service.py b/server/services/cli_agent/service.pyindex 74e6fdaf..78ec9805 100644--- a/server/services/cli_agent/service.py+++ b/server/services/cli_agent/service.py@@ -163,12 +163,13 @@ class AICliService:)# Per-batch bearer token + MCP context+ from core.env_defaults import env_value+token = issue_token()port = mcp_port or int(- os.environ.get(- "OPENCOMPANY_BACKEND_PORT",- os.environ.get("MACHINA_BACKEND_PORT", "5678"),- )+ os.environ.get("OPENCOMPANY_BACKEND_PORT")+ or os.environ.get("MACHINA_BACKEND_PORT")+ or env_value("PYTHON_BACKEND_PORT"))ctx = BatchContext(workflow_id=workflow_id,diff --git a/server/services/events/admin_handlers.py b/server/services/events/admin_handlers.pyindex 59ede37f..e47f384b 100644--- a/server/services/events/admin_handlers.py+++ b/server/services/events/admin_handlers.py@@ -185,7 +185,8 @@ async def handle_get_workflow_failure_history(}Ops-only — no replay action available here. For more detail use- Temporal Web UI at http://localhost:5683 or the temporal CLI:+ the Temporal Web UI (http://localhost:<TEMPORAL_UI_PORT>) or the+ temporal CLI:temporal workflow show --workflow-id <id> --output json"""diff --git a/server/start.sh b/server/start.shindex 46642fcd..0c3497df 100644--- a/server/start.sh+++ b/server/start.sh@@ -5,4 +5,4 @@cd /app/nodejs && npm start &# Start Python server (foreground)-python -m uvicorn main:app --host 0.0.0.0 --port ${PORT:-5678} --log-level warning+python -m uvicorn main:app --host 0.0.0.0 --port ${PORT:?not set - defaults live in .env.template} --log-level warningdiff --git a/server/tests/conftest.py b/server/tests/conftest.pyindex ec39984a..8ff998df 100644--- a/server/tests/conftest.py+++ b/server/tests/conftest.py@@ -121,6 +121,18 @@ sys.modules["core.auth_cookies"] = _auth_cookies_mod_auth_cookies_spec.loader.exec_module(_auth_cookies_mod)setattr(_core_pkg, "auth_cookies", _auth_cookies_mod)+# core.env_defaults is stdlib-only (the .env.template-backed env+# resolver plugin folders use instead of hardcoded port fallbacks) —+# expose the real module so plugin imports resolve during collection.+_env_defaults_spec = _importlib_util.spec_from_file_location(+ "core.env_defaults",+ SERVER_DIR / "core" / "env_defaults.py",+)+_env_defaults_mod = _importlib_util.module_from_spec(_env_defaults_spec)+sys.modules["core.env_defaults"] = _env_defaults_mod+_env_defaults_spec.loader.exec_module(_env_defaults_mod)+setattr(_core_pkg, "env_defaults", _env_defaults_mod)+# core.encryption depends only on stdlib + cryptography, and its# fingerprint_credential is imported at module load by services.llm.unifier# and services.memory.vector_store, so expose the real module.