3.2 KiB

Raw Blame History

NODE.DC Environment Contract

This contract separates local feature testing from deployed runtime.

Profiles

local

Runs Launcher, Engine, Ops/Gateway, AI Workspace Assistant, databases, and fixtures on the developer machine.
May use the deployed AI Hub only as a thin relay for a remote Codex worker.
Must not call production Launcher, Engine, Ops, Authentik, or Gateway endpoints.

tunnel-local-e2e

Explicit escape hatch for Tailscale/ngrok-style testing.
Same business services are still local, but relay URLs may use tunnel/private addresses.
Must be opt-in through NODEDC_ENV=tunnel-local-e2e.

staging

Deployed test stack with staging data and staging Authentik/OIDC clients.
Used after local smoke is green.

prod

Production data and production public domains.
Only deploy artifacts that passed local and staging checks.

URL Classes

Browser URL: opened by a user browser.
Internal service URL: used by one backend to call another backend.
Relay URL: used only to move messages between a local assistant and a remote worker.
Downstream app URL: used by an assistant adapter to read or mutate its owning app.

Do not mix these classes. A remote worker must not call Launcher, Engine, Ops, or Authentik directly in local.

Local Remote Worker Chain

local Engine
  -> local AI Workspace Assistant
  -> deployed AI Hub relay
  -> remote Codex worker
  -> deployed AI Hub relay
  -> local AI Workspace Assistant
  -> local Launcher / local Engine / local Ops

The deployed AI Hub is transport only. It must not decide product access, own app routes, or force production downstream URLs.

Required Local Defaults

Engine local server:

NODEDC_ENV=local
NODEDC_LAUNCHER_INTERNAL_URL=http://127.0.0.1:5173
NODEDC_LAUNCHER_ORIGIN=http://launcher.local.nodedc
AUTHENTIK_PUBLIC_BASE_URL=http://auth.local.nodedc
NODEDC_AI_WORKSPACE_ASSISTANT_URL=http://127.0.0.1:18082
OPS_RETENTION_ENABLED=false

Platform local stack:

NODEDC_ENV=local
AI_WORKSPACE_HUB_PUBLIC_URL=wss://ai-hub.nodedc.ru/api/ai-workspace/hub
AI_WORKSPACE_HUB_INTERNAL_URL=https://ai-hub.nodedc.ru
AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ENABLED=true
AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ID=local-dev

The AI Hub URLs above are allowed only because they are relay URLs. Production app URLs such as https://hub.nodedc.ru, https://engine.nodedc.ru, https://ops.nodedc.ru, and https://id.nodedc.ru are forbidden in local app config.

Assistant action calls in local must use the relay route:

remote worker assistant_action_call
  -> deployed AI Hub /api/ai-workspace/hub/v1/assistant-relays/<relayId>/actions
  -> local AI Workspace Assistant long-poll
  -> local Launcher / Engine / Ops adapter

Do not route local assistant actions through the deployed Assistant or deployed product backends.

Guardrail

Run the complete local testing gate before local AI Workspace testing:

sh platform/infra/scripts/check-local-test-system.sh

Run this narrower env-only guard when changing env files:

node platform/infra/scripts/check-local-environment-safety.mjs

Run the broader AI Workspace contract check before changing worker/assistant routing:

platform/infra/scripts/check-ai-workspace-config-contract.sh

3.2 KiB Raw Blame History