Skip to content

Self-improving AI Employees for everyone

refactor: no hardcoded port numbers anywhere - .env.template is the SSOT

trohitg875ffff27933
diff --git a/.env b/.env
index b328a587..f7faab5d 100644
--- a/.env
+++ b/.env
@@ -1,8 +1,8 @@
# Service Ports (used by start.js, vite, and docker-compose)
VITE_CLIENT_PORT=5678
PYTHON_BACKEND_PORT=5678
-NODEJS_EXECUTOR_PORT=5680
-WHATSAPP_RPC_PORT=5681
+NODEJS_EXECUTOR_PORT=5682
+WHATSAPP_RPC_PORT=5683
REDIS_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:5681
TEMPORAL_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=true
TEMPORAL_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 is
diff --git a/.env.template b/.env.template
index 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=5678
PYTHON_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=5683
REDIS_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:5681
TEMPORAL_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 is
diff --git a/.github/workflows/predeploy.yml b/.github/workflows/predeploy.yml
index 3c10c49b..3a799033 100644
--- a/.github/workflows/predeploy.yml
+++ b/.github/workflows/predeploy.yml
@@ -72,10 +72,11 @@ jobs:
if: runner.os != 'Windows'
shell: bash
run: |
+ 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 && break
sleep 2
done
kill -0 $PID 2>/dev/null && pnpm run stop || (echo FAILED; exit 1)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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
```bash
pnpm 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 everything
pnpm run build # production build
pnpm exec tsc --noEmit # typecheck client (from client/)
diff --git a/cli/cli.py b/cli/cli.py
index 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_port
up_command(
provider=provider,
region=region,
diff --git a/cli/commands/deploy/_secrets.py b/cli/commands/deploy/_secrets.py
index 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.py
index 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.md
index 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
```env
TEMPORAL_ENABLED=true
-TEMPORAL_SERVER_ADDRESS=localhost:5682
+TEMPORAL_SERVER_ADDRESS=localhost:5681
TEMPORAL_NAMESPACE=default
TEMPORAL_TASK_QUEUE=machina-tasks
```
diff --git a/docs-internal/SCRIPTS.md b/docs-internal/SCRIPTS.md
index 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.md
index 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-embeddings
Services (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.md
index 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_ENABLED
npm 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=runti
The 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 time
uv run python -m services.temporal._install
diff --git a/docs-internal/cli_agent_framework.md b/docs-internal/cli_agent_framework.md
index 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 considerations
diff --git a/docs-internal/cli_services_integration.md b/docs-internal/cli_services_integration.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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 root
pnpm 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 daemons
pnpm run build # full prod build; bundle analyzer at dist/stats.html if ANALYZE=1
# client-only
diff --git a/docs-internal/gcp_vm_deploy_runbook.md b/docs-internal/gcp_vm_deploy_runbook.md
index 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 (uvicorn
serves 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 the
diff --git a/docs-internal/node-logic-flows/_TEMPLATE.md b/docs-internal/node-logic-flows/_TEMPLATE.md
index 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.md
index 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 the
shared `get_nodejs_client()` singleton (an async `aiohttp` client). The Node.js
server 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)` shared
across 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 TD
C --> 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 TD
plugin 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 TD
first 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 call
failed]"` 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.md
index 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 singleton
Shares `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 TD
C --> 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.md
index 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 it
from `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.md
index 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.md
index 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 limits
diff --git a/docs-internal/release_build_pipeline.md b/docs-internal/release_build_pipeline.md
index 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 determinis
1. `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.md
index 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.svg
index 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.ps1
index 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.sh
index 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.json
index 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.js
index 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.py
new file mode 100644
index 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.py
index d587b502..6bad9bb0 100644
--- a/server/gunicorn.conf.py
+++ b/server/gunicorn.conf.py
@@ -10,9 +10,12 @@ Usage:
import os
import 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-calculate
log_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.ts
index 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.py
index 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.py
index 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.py
index b3e6e08a..da90fe01 100644
--- a/server/nodes/whatsapp/_runtime.py
+++ b/server/nodes/whatsapp/_runtime.py
@@ -70,7 +70,9 @@ class WhatsAppRuntime(BaseProcessSupervisor):
@property
def 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")
@property
def bind_host(self) -> str:
diff --git a/server/nodes/whatsapp/_service.py b/server/nodes/whatsapp/_service.py
index 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 = None
if 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 = None
logger.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 = None
logger.error(f"WhatsApp RPC error: {e}")
diff --git a/server/package.json b/server/package.json
index 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.py
index 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.py
index 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.sh
index 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 warning
diff --git a/server/tests/conftest.py b/server/tests/conftest.py
index 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.