Home / Infrastructure / Gateway
Gateway Service
The gateway is the control plane of orchestrata (SPEC-014). It exposes a WebSocket JSON-RPC 2.0 API on port 8765. It does not serve HTML, JS or CSS. The VizInt UI is served on its own, on port 5000, and connects to the gateway through WebSocketBridge. The code is component gateway (orchestrata_ultimate.gateway; packages/gateway after the cut-over). It is started with python -m orchestrata_ultimate.gateway.cli serve.
Where it runs (measured 2026-10-23)
| Copy | Where | Bind | State | Deployed commit |
|---|---|---|---|---|
| prod | host unit orchestrata-gateway.service, from /opt/orchestrata |
GATEWAY_HOST=127.0.0.1 (ADR-0065); GATEWAY_HTTP_HOST=10.53.1.1, the prod bridge address |
disabled, inactive: DeepChat disabled it on 2026-10-21 | 4ac0db570 |
| test | orchestrata-gateway inside orchestrata-test:app |
CXP_WS_URI=ws://10.53.2.13:8765 (env/test.env) |
active | 22363abb2 (2026-10-12), 546 commits behind |
The prod unit
deploy/systemd/orchestrata-gateway.service runs from /opt/orchestrata, with EnvironmentFile=/opt/orchestrata/.env and env/prod.env.
ExecStartPrewaits up to 215 s for the graph (deploy/orchestrata-kg-ready.py), then up to 60 s for the kernel'sCXP_GRPC_PORT.Wants=andAfter=orchestrata-kernel.service.TimeoutStartSec=300.
The unit exists because a hand-started gateway kept its launch-time .env. After the 2026-07-26 graph cutover it served graph traffic against the retired Neo4j for about 17 hours. The detail is in section 4 of Host services.
Authentication
- The gateway's default auth mode is
jwt(create_authenticatorinauth_handler.py). Tokens are JWTs signed withJWT_SECRET, withTOKEN_EXPIRY_SECONDS=3600. scripts/mint_gateway_token.py [--user U]mints a token throughTokenAuthenticator.create_token.JWT_SECRETis in~/.config/orchestrata/.env, which is installed as/opt/orchestrata/.env(mode 600). Only the key name is given here.
orchestrata-mcp cannot authenticate (open decision)
orchestrata-mcp (ADR-0099) is the orchestrata MCP server Claude launches. It is a WebSocket JSON-RPC client of this gateway, and every mcp__orchestrata__* tool goes through it. On 2026-10-22 at 23:50, every call returned GATEWAY_UNAVAILABLE: GATEWAY_TOKEN is not set; this was measured on gateway_ping, gateway_info and volk_list.
- The transport reads
GATEWAY_TOKENfrom the environment, then from/opt/orchestrata/.env. Neither has it. - ADR-0099 rule 1 says it authenticates "with GATEWAY_TOKEN from the deployed environment". A JWT that expires after 3600 s cannot be a fixed entry in a secrets file.
- Even with a token, the prod gateway unit is disabled, so there is nothing to connect to.
The options are on Open decisions:
- A. Mint a token into the secrets file. It works for one hour.
- B. The transport mints its own short-lived JWT from
JWT_SECRETwhen it connects. This is the recommendation; it amends ADR-0099 rule 1. - C. A static, non-expiring token mode. This weakens auth for every client.
The kernel link
The gateway is the CXP client of the kernel: create_cxp_client is used by gateway/server.py. It connects over the cxpt transport (CXP_TRANSPORT=cxpt) to CXP_GRPC_PORT (50053). When the kernel is unreachable, it falls back to the in-process PipelineKernelClient (AGENTS.md Hard Rule 4). That fallback is a production resilience path, not a licence to test without a kernel. See Kernel.
Health check
# test fleet, from a checkout (reads env/test.env)
python scripts/start_test_services.py --status
# from a Claude session, once a token exists
mcp__orchestrata__gateway_ping
Rules
- The gateway is WebSocket-only for its API.
- The prod WebSocket plane binds
127.0.0.1(ADR-0065, ruling R15): every client of it runs on this host. - Every method needs a token,
gateway.pingincluded.