Operations

Health checks

GET /health — process-level. Always 200 if the process is up.

curl ${CARC_RUNTIME_API_URL}/health
# { "status": "ok", "service": "runtime-control-engine", "version": "1.0.0", "timestamp": "..." }

Readiness checks

GET /ready — whether required internal modules (configuration, policy repository, agent registry) are initialized and reachable. Returns 503 if any check fails.

curl ${CARC_RUNTIME_API_URL}/ready
# { "status": "ready", "checks": { "configuration_loaded": true, "policy_repository": true, "agent_registry": true }, "timestamp": "..." }

Version endpoint

GET /version returns service name, service version, API version, a build id placeholder, and environment.

Logs

Structured JSON logs, one line per request, written to stdout. Fields: method, path, status, duration_ms, correlation_id, tenant_id, and (when the route resolves one) agent_id / session_id / run_id / decision_id. Errors additionally log error.name and error.message.

Never logged: request/response bodies, query strings, subject context, agent output, source document content, personally identifying information, secrets, or API keys. Configure verbosity with LOG_LEVEL.

Correlation IDs

Every request is stamped with an X-Correlation-ID — read from the incoming request header if present, generated otherwise — and echoed back on the response header, in every structured log line for that request, and in the error body if the request fails. Use it to trace one request across your integration and the engine's logs.

Environment variables

Variable	Default	Purpose
PORT	4000	HTTP port
HOST	0.0.0.0	Bind address
LOG_LEVEL	info	fatal | error | warn | info | debug | trace | silent
CORS_ALLOWED_ORIGINS	*	Comma-separated allowed origins, or *
API_KEY_REQUIRED	false	Reserved — not yet enforced (see Security)
DEFAULT_TENANT_ID	tenant_default	Fallback tenant when no X-Tenant-ID header is sent
SERVICE_NAME	runtime-control-engine	Reported on /health, /version, logs
SERVICE_VERSION	1.0.0	Reported on /health, /version
REQUEST_TIMEOUT_MS	30000	Reserved for future per-request timeout enforcement

Invalid critical values (e.g. a non-numeric PORT) fail startup immediately with a clear error — the engine never starts in a partially configured state. Copy services/runtime-control-engine/.env.example to get started.

Local development

npm install
npm run build:packages

npm run dev:engine
npm run dev:console
npm run dev:docs

Troubleshooting

Symptom	Likely cause
ECONNREFUSED from the SDK	Engine isn't running — check npm run dev:engine
404 on a resource you just created	Check X-Tenant-ID — you may be reading from a different tenant than you wrote to
409 on agent activation	Agent may already be active, or deprecated (terminal)
409 on Agent Run submission	Agent isn't active, or task_type isn't in its allowed_tasks
RuntimeSdkConfigError at construction	Missing baseUrl, or no fetch implementation available on your runtime
503 on /ready	A dependency check failed — inspect the checks object in the response