All configuration is through environment variables. Organised by service.
| Type |
Default |
Required |
string |
postgresql://postgres:postgres@localhost:5432/undolog_dev |
Yes |
PostgreSQL connection string for effect storage, sessions, approvals, and tool registry.
Format: postgresql://[user[:password]@][host][:port][/database][?params]
| Type |
Default |
Required |
string |
0.0.0.0:50051 |
Yes |
IP:port for the tonic gRPC server that handles Intercept, Commit, Fail, Approve, Reject RPCs.
| Type |
Default |
Required |
string |
0.0.0.0:9090 |
Yes |
IP:port for the HTTP health endpoint (GET / → {"status":"ok","service":"undolog-engine"}).
| Type |
Default |
Valid Values |
string |
info |
trace, debug, info, warn, error |
Log level for the Rust engine. Used as the default directive for tracing_subscriber::EnvFilter.
| Type |
Default |
Description |
uint64 |
60 |
Interval in seconds between tool registry refreshes from the database. The engine loads undolog_tool_registry into an in-memory cache on startup and refreshes periodically at this interval. |
| Type |
Default |
Description |
uint32 |
3 |
Maximum number of attempts to acquire a PostgreSQL advisory lock for a call signature before returning AdvisoryLockTimeout. |
| Type |
Default |
Description |
uint64 |
100 |
Delay in milliseconds between advisory lock acquisition attempts. |
| Type |
Default |
Required |
string |
:8080 |
Yes |
HTTP bind address for the MCP proxy server.
| Type |
Default |
Description |
int |
15 |
Maximum seconds the server waits for request headers. |
| Type |
Default |
Description |
int |
15 |
Maximum seconds the server waits while writing responses. |
| Type |
Default |
Description |
int |
30 |
Maximum seconds for graceful shutdown before force closing connections. |
| Type |
Default |
Description |
int |
30 |
Maximum seconds for tool execution and engine RPC calls. Applied as a context timeout on the interception flow and as the upstream tool executor client timeout. |
| Type |
Default |
Description |
int |
15 |
Seconds the server waits to read request headers before it drops the connection. Guards against slow-loris style timeouts. |
| Type |
Default |
Description |
int |
60 |
Seconds a keep-alive connection may sit idle between requests before the server closes it. |
| Type |
Default |
Description |
int |
1048576 |
Maximum total bytes the server parses for request headers, including the request line. |
| Type |
Default |
Description |
int |
1048576 |
Maximum request body size in bytes for /mcp/tool_call and the approval decision endpoints. Larger bodies are rejected with HTTP 413. |
| Type |
Default |
Description |
int |
3 |
Maximum number of attempts for transient Commit/Fail RPC failures. The engine connection itself is created lazily and reconnects automatically, so it has no retry budget. Deterministic failures (for example an invalid state transition) are never retried. Setting this to 1 disables Commit/Fail retries. |
| Type |
Default |
Description |
int |
100 |
Base delay in milliseconds between Commit/Fail retry attempts, scaled linearly per attempt. |
| Type |
Default |
Description |
int |
128 |
Per-organisation SSE channel buffer size for dashboard event delivery. Events beyond this size are dropped (non-blocking). |
| Type |
Default |
Description |
int |
60 |
Seconds between reconciliations of pending approvals from the engine database. Reconciliation also runs once on startup. |
| Type |
Default |
Description |
int |
86400 |
Age in seconds after which a resolved approval is swept from the proxy store. Stale pending approvals (no longer confirmed by the engine) age from creation; approvals the engine still reports as pending are always kept so a human can still decide. |
| Type |
Default |
Required |
string |
localhost:50051 |
Yes |
Address of the Rust UndoLog Engine gRPC endpoint. Used by the proxy to forward interception, commit, fail, approve, and reject requests.
| Type |
Default |
Required |
string |
"" |
No (required for tool execution) |
HTTP endpoint that receives forwarded tool calls. When empty, tool execution is not available.
| Type |
Default |
Valid Values |
string |
info |
debug, info, warn, error |
Log level for the proxy server. Shared env var name across both engine and proxy.
| Type |
Default |
Description |
string |
"" |
Comma-separated key=org_id pairs for API key authentication. Example: sk-abc123=org-xyz,sk-def456=org-uvw. At least one pair is required: the proxy refuses to start with none configured, and keys are compared as SHA-256 digests in constant time. |
| Type |
Default |
Services |
string |
info |
Engine, Proxy |
Shared log level variable. When set, affects both the Rust engine and Go proxy.
| Variable |
Service |
Type |
Default |
Required |
DATABASE_URL |
Engine |
string |
postgresql://postgres:postgres@localhost:5432/undolog_dev |
Yes |
UNDOLOG_ENGINE_GRPC_ADDR |
Engine |
string |
0.0.0.0:50051 |
Yes |
UNDOLOG_ENGINE_HEALTH_ADDR |
Engine |
string |
0.0.0.0:9090 |
Yes |
UNDOLOG_LOG_LEVEL |
Engine, Proxy |
string |
info |
No |
UNDOLOG_REGISTRY_REFRESH_SECS |
Engine |
uint64 |
60 |
No |
UNDOLOG_LOCK_MAX_ATTEMPTS |
Engine |
uint32 |
3 |
No |
UNDOLOG_LOCK_RETRY_MS |
Engine |
uint64 |
100 |
No |
UNDOLOG_PROXY_LISTEN_ADDR |
Proxy |
string |
:8080 |
Yes |
UNDOLOG_PROXY_READ_TIMEOUT_SECS |
Proxy |
int |
15 |
No |
UNDOLOG_PROXY_WRITE_TIMEOUT_SECS |
Proxy |
int |
15 |
No |
UNDOLOG_PROXY_SHUTDOWN_TIMEOUT_SECS |
Proxy |
int |
30 |
No |
UNDOLOG_PROXY_REQUEST_TIMEOUT_SECS |
Proxy |
int |
30 |
No |
UNDOLOG_PROXY_READ_HEADER_TIMEOUT_SECS |
Proxy |
int |
15 |
No |
UNDOLOG_PROXY_IDLE_TIMEOUT_SECS |
Proxy |
int |
60 |
No |
UNDOLOG_PROXY_MAX_HEADER_BYTES |
Proxy |
int |
1048576 |
No |
UNDOLOG_PROXY_MAX_BODY_BYTES |
Proxy |
int |
1048576 |
No |
UNDOLOG_PROXY_ENGINE_RETRY_MAX_ATTEMPTS |
Proxy |
int |
3 |
No |
UNDOLOG_PROXY_ENGINE_RETRY_BASE_MS |
Proxy |
int |
100 |
No |
UNDOLOG_PROXY_DASHBOARD_EVENT_CHAN_SIZE |
Proxy |
int |
128 |
No |
UNDOLOG_PROXY_APPROVAL_RECONCILE_INTERVAL_SECS |
Proxy |
int |
60 |
No |
UNDOLOG_PROXY_APPROVAL_RETENTION_SECS |
Proxy |
int |
86400 |
No |
UNDOLOG_PROXY_ENGINE_GRPC_ADDR |
Proxy |
string |
localhost:50051 |
Yes |
UNDOLOG_PROXY_UPSTREAM_TOOL_URL |
Proxy |
string |
"" |
No |
UNDOLOG_PROXY_API_KEYS |
Proxy |
string |
"" |
Yes |