Configuration

Settings are read, in increasing precedence, from the defaults below, a YAML file (config.yaml, or the path in INTERLOCK_CONFIG_PATH), and environment variables. A nested key section.key is the environment variable INTERLOCK_SECTION__KEY. Unknown keys are rejected at start.

Top level

Key	Environment variable	Default	Meaning
environment	INTERLOCK_ENVIRONMENT	development	development, test or production. Production enforces the security settings.
service_role	INTERLOCK_SERVICE_ROLE	all	Which service this process runs; production checks apply only to the settings that service uses.

gateway

Gateway listeners and limits.

Key	Environment variable	Default	Meaning
gateway.host	INTERLOCK_GATEWAY__HOST	0.0.0.0	Interface the gateway’s HTTP/MCP and PostgreSQL listeners bind to.
gateway.http_port	INTERLOCK_GATEWAY__HTTP_PORT	3000	Port for the HTTP proxy and MCP endpoints.
gateway.pg_port	INTERLOCK_GATEWAY__PG_PORT	5432	Port for the PostgreSQL wire listener.
gateway.upstream_pg_host	INTERLOCK_GATEWAY__UPSTREAM_PG_HOST	localhost	Default upstream PostgreSQL host, used when a source does not name its own.
gateway.upstream_pg_port	INTERLOCK_GATEWAY__UPSTREAM_PG_PORT	5433	Default upstream PostgreSQL port, used when a source does not name its own.
gateway.mcp_port	INTERLOCK_GATEWAY__MCP_PORT	8001	Reserved: not read by the current runtime.
gateway.http_workers	INTERLOCK_GATEWAY__HTTP_WORKERS	4	Reserved: not read by the current runtime.
gateway.pg_workers	INTERLOCK_GATEWAY__PG_WORKERS	2	Reserved: not read by the current runtime.
gateway.mcp_workers	INTERLOCK_GATEWAY__MCP_WORKERS	2	Reserved: not read by the current runtime.
gateway.pg_max_startup_bytes	INTERLOCK_GATEWAY__PG_MAX_STARTUP_BYTES	10000	Largest PostgreSQL startup packet accepted, in bytes.
gateway.pg_max_message_bytes	INTERLOCK_GATEWAY__PG_MAX_MESSAGE_BYTES	16777216	Largest single PostgreSQL protocol message accepted, in bytes.
gateway.pg_max_result_bytes	INTERLOCK_GATEWAY__PG_MAX_RESULT_BYTES	67108864	Largest result the PostgreSQL listener buffers for one query, in bytes.
gateway.pg_startup_timeout_seconds	INTERLOCK_GATEWAY__PG_STARTUP_TIMEOUT_SECONDS	10.0	Time a client has to send its startup packet.
gateway.pg_auth_timeout_seconds	INTERLOCK_GATEWAY__PG_AUTH_TIMEOUT_SECONDS	15.0	Time a client has to complete authentication.
gateway.pg_frame_timeout_seconds	INTERLOCK_GATEWAY__PG_FRAME_TIMEOUT_SECONDS	30.0	Time allowed to receive the rest of a partly sent message.
gateway.pg_idle_timeout_seconds	INTERLOCK_GATEWAY__PG_IDLE_TIMEOUT_SECONDS	300.0	Reserved: not read by the current runtime.
gateway.pg_max_clients	INTERLOCK_GATEWAY__PG_MAX_CLIENTS	256	Most concurrent PostgreSQL client connections.
gateway.pg_tls_cert_file	INTERLOCK_GATEWAY__PG_TLS_CERT_FILE	unset	Certificate for TLS on the PostgreSQL listener.
gateway.pg_tls_key_file	INTERLOCK_GATEWAY__PG_TLS_KEY_FILE	unset	Private key for TLS on the PostgreSQL listener.
gateway.pg_require_client_tls	INTERLOCK_GATEWAY__PG_REQUIRE_CLIENT_TLS	false	Refuse PostgreSQL clients that do not negotiate TLS.
gateway.pg_trusted_tls_offload	INTERLOCK_GATEWAY__PG_TRUSTED_TLS_OFFLOAD	false	TLS is terminated in front of the gateway, so client TLS is not required here.
gateway.mcp_max_body_bytes	INTERLOCK_GATEWAY__MCP_MAX_BODY_BYTES	1048576	Largest MCP request body accepted, in bytes.
gateway.mcp_max_results	INTERLOCK_GATEWAY__MCP_MAX_RESULTS	1000	Upper bound on rows or results an MCP tool returns.
gateway.mcp_allowed_origins	INTERLOCK_GATEWAY__MCP_ALLOWED_ORIGINS	[]	Browser Origin values allowed to call /mcp; empty allows none.
gateway.http_max_request_body_bytes	INTERLOCK_GATEWAY__HTTP_MAX_REQUEST_BODY_BYTES	10485760	Largest request body the HTTP proxy forwards, in bytes.
gateway.http_max_response_body_bytes	INTERLOCK_GATEWAY__HTTP_MAX_RESPONSE_BODY_BYTES	52428800	Largest upstream response the HTTP proxy relays, in bytes.
gateway.http_max_connections	INTERLOCK_GATEWAY__HTTP_MAX_CONNECTIONS	100	Most concurrent upstream connections the HTTP proxy opens.
gateway.http_max_keepalive_connections	INTERLOCK_GATEWAY__HTTP_MAX_KEEPALIVE_CONNECTIONS	20	Most idle upstream connections the HTTP proxy keeps.
gateway.http_timeout_seconds	INTERLOCK_GATEWAY__HTTP_TIMEOUT_SECONDS	30.0	Upstream request timeout for the HTTP proxy.

admin

Admin console.

Key	Environment variable	Default	Meaning
admin.host	INTERLOCK_ADMIN__HOST	127.0.0.1	Interface the Admin console binds to. Containers set 0.0.0.0.
admin.port	INTERLOCK_ADMIN__PORT	9090	Port for the Admin console and API.
admin.secret_key	INTERLOCK_ADMIN__SECRET_KEY	""	Key that signs session and CSRF cookies. Required in production (32+ characters); empty uses a random key that resets on restart.
admin.bootstrap_password	INTERLOCK_ADMIN__BOOTSTRAP_PASSWORD	""	Password for the first admin, admin, when none exists. Unset, the first admin gets the default admin and must change it at first sign-in.
admin.session_ttl_seconds	INTERLOCK_ADMIN__SESSION_TTL_SECONDS	28800	Lifetime of an Admin session.
admin.cookie_secure	INTERLOCK_ADMIN__COOKIE_SECURE	false	Mark Admin cookies Secure (HTTPS only). Required in production.
admin.cookie_name	INTERLOCK_ADMIN__COOKIE_NAME	interlock_admin_session	Name of the Admin session cookie.
admin.csrf_cookie_name	INTERLOCK_ADMIN__CSRF_COOKIE_NAME	interlock_admin_csrf	Name of the cookie carrying the CSRF token.
admin.catalog_on_startup	INTERLOCK_ADMIN__CATALOG_ON_STARTUP	true	At start, queue a first catalog scan for every enabled source never scanned.

worker

Background workers.

Key	Environment variable	Default	Meaning
worker.worker_id	INTERLOCK_WORKER__WORKER_ID	worker-1	Name this worker reports in heartbeats and job leases.
worker.concurrency	INTERLOCK_WORKER__CONCURRENCY	8	Jobs a worker processes at once.
worker.heartbeat_interval	INTERLOCK_WORKER__HEARTBEAT_INTERVAL	5.0	Seconds between worker heartbeats.
worker.lease_seconds	INTERLOCK_WORKER__LEASE_SECONDS	300	How long a claimed job stays leased before another worker may take it.

database

Control database.

Key	Environment variable	Default	Meaning
database.host	INTERLOCK_DATABASE__HOST	localhost	Control database host.
database.port	INTERLOCK_DATABASE__PORT	5432	Control database port.
database.database	INTERLOCK_DATABASE__DATABASE	onyx	Control database name.
database.user	INTERLOCK_DATABASE__USER	onyx	Control database user.
database.password	INTERLOCK_DATABASE__PASSWORD	""	Control database password.
database.min_pool	INTERLOCK_DATABASE__MIN_POOL	2	Connections kept open to the control database.
database.max_pool	INTERLOCK_DATABASE__MAX_POOL	10	Most connections opened to the control database.
database.ssl_mode	INTERLOCK_DATABASE__SSL_MODE	disable	TLS mode for the control database. Production requires verify-full.
database.ssl_ca_file	INTERLOCK_DATABASE__SSL_CA_FILE	unset	CA certificate used to verify the control database.
database.ssl_cert_file	INTERLOCK_DATABASE__SSL_CERT_FILE	unset	Client certificate for the control database.
database.ssl_key_file	INTERLOCK_DATABASE__SSL_KEY_FILE	unset	Client key for the control database.

redis

Redis.

Key	Environment variable	Default	Meaning
redis.url	INTERLOCK_REDIS__URL	redis://localhost:6379/0	Redis URL, for sessions, rate limits, cache and coordination.
redis.max_connections	INTERLOCK_REDIS__MAX_CONNECTIONS	20	Most connections in the Redis pool.

auth

Agent authentication.

Key	Environment variable	Default	Meaning
auth.enabled	INTERLOCK_AUTH__ENABLED	true	Require agent authentication.
auth.session_ttl_seconds	INTERLOCK_AUTH__SESSION_TTL_SECONDS	3600	How long an authenticated agent session is cached.
auth.api_key_pepper	INTERLOCK_AUTH__API_KEY_PEPPER	""	Server-side secret mixed into API key hashes. Required in production (32+ characters); changing it invalidates every key.
auth.allow_legacy_sha256_keys	INTERLOCK_AUTH__ALLOW_LEGACY_SHA256_KEYS	true	Accept keys stored as plain SHA-256. Must be false in production.
auth.custom_api_key_min_length	INTERLOCK_AUTH__CUSTOM_API_KEY_MIN_LENGTH	32	Shortest API key an operator may supply.
auth.oidc.enabled	INTERLOCK_AUTH__OIDC__ENABLED	false	Use OpenID Connect for Admin sign-in and agent JWTs.
auth.oidc.issuer_url	INTERLOCK_AUTH__OIDC__ISSUER_URL	""	OIDC issuer; must be https in production.
auth.oidc.admin_client_id	INTERLOCK_AUTH__OIDC__ADMIN_CLIENT_ID	""	Client id for Admin sign-in.
auth.oidc.admin_client_secret	INTERLOCK_AUTH__OIDC__ADMIN_CLIENT_SECRET	""	Client secret for Admin sign-in.
auth.oidc.admin_redirect_uri	INTERLOCK_AUTH__OIDC__ADMIN_REDIRECT_URI	http://localhost:9090/auth/oidc/callback	Callback URL registered with the identity provider.
auth.oidc.agent_audience	INTERLOCK_AUTH__OIDC__AGENT_AUDIENCE	""	Audience agent JWTs must carry.
auth.oidc.scopes	INTERLOCK_AUTH__OIDC__SCOPES	["openid", "profile", "email", "groups"]	Scopes requested at sign-in; must include openid.
auth.oidc.flow_ttl_seconds	INTERLOCK_AUTH__OIDC__FLOW_TTL_SECONDS	600	Time allowed to complete a sign-in round trip.
auth.oidc.local_break_glass_enabled	INTERLOCK_AUTH__OIDC__LOCAL_BREAK_GLASS_ENABLED	true	Keep password sign-in for local owner/admin accounts while OIDC is on.
auth.oidc.allow_insecure_endpoints	INTERLOCK_AUTH__OIDC__ALLOW_INSECURE_ENDPOINTS	false	Allow http identity-provider endpoints. Development only.
auth.oidc.admin_group_role_map	INTERLOCK_AUTH__OIDC__ADMIN_GROUP_ROLE_MAP	{}	Identity-provider group names mapped to Admin roles.

cache

Response cache.

Key	Environment variable	Default	Meaning
cache.l1_max_size	INTERLOCK_CACHE__L1_MAX_SIZE	1000	Entries held in each process’s in-memory cache.
cache.l1_ttl_seconds	INTERLOCK_CACHE__L1_TTL_SECONDS	60	Lifetime of an in-memory cache entry.
cache.l2_ttl_seconds	INTERLOCK_CACHE__L2_TTL_SECONDS	300	Lifetime of a Redis cache entry.
cache.default_strategy	INTERLOCK_CACHE__DEFAULT_STRATEGY	lru	Reserved: not read by the current runtime. Each source chooses its own cache strategy.
cache.strict_write_barrier	INTERLOCK_CACHE__STRICT_WRITE_BARRIER	true	Refuse to serve from cache when the write-generation barrier is unavailable.
cache.source_generation_prefix	INTERLOCK_CACHE__SOURCE_GENERATION_PREFIX	interlock:cache:generation	Redis key prefix for per-source write generations. Every gateway and admin must share it.
cache.pubsub_reconnect_seconds	INTERLOCK_CACHE__PUBSUB_RECONNECT_SECONDS	1.0	Delay before reconnecting to the cache-invalidation channel.

pii

PII detection.

Key	Environment variable	Default	Meaning
pii.fast_enabled	INTERLOCK_PII__FAST_ENABLED	true	Run the regex PII scanner on responses.
pii.deep_enabled	INTERLOCK_PII__DEEP_ENABLED	false	Also run the Presidio scanner (needs the pii extra).
pii.deep_max_workers	INTERLOCK_PII__DEEP_MAX_WORKERS	2	Threads for the deep scanner.
pii.free_text_column_patterns	INTERLOCK_PII__FREE_TEXT_COLUMN_PATTERNS	["description", "notes", "comment", "bio", "message", "body", "content", "remarks", "summary", "text"]	Column-name fragments treated as free text and scanned for PII.

audit

Audit log.

Key	Environment variable	Default	Meaning
audit.enabled	INTERLOCK_AUDIT__ENABLED	true	Write an audit row for every governed request.
audit.partition_interval	INTERLOCK_AUDIT__PARTITION_INTERVAL	monthly	Reserved: not read by the current runtime. Partitions are monthly.
audit.buffer_max_size	INTERLOCK_AUDIT__BUFFER_MAX_SIZE	50000	Audit events held in memory before back-pressure.
audit.flush_interval_ms	INTERLOCK_AUDIT__FLUSH_INTERVAL_MS	100	How often the buffer is written.
audit.flush_batch_size	INTERLOCK_AUDIT__FLUSH_BATCH_SIZE	1000	Events written per batch.
audit.durability_mode	INTERLOCK_AUDIT__DURABILITY_MODE	retriable	best_effort drops on failure, retriable spools and retries, strict refuses the request when its audit row cannot be kept. Production requires strict.
audit.retry_max_attempts	INTERLOCK_AUDIT__RETRY_MAX_ATTEMPTS	5	Attempts to write a batch before spooling it.
audit.retry_base_delay_ms	INTERLOCK_AUDIT__RETRY_BASE_DELAY_MS	100	First retry delay; later ones back off.
audit.spool_path	INTERLOCK_AUDIT__SPOOL_PATH	/var/lib/interlock/audit-spool	Directory where unwritten audit events are spooled to disk.
audit.partition_maintenance_interval_seconds	INTERLOCK_AUDIT__PARTITION_MAINTENANCE_INTERVAL_SECONDS	3600	How often audit partitions are created and checked.
audit.partition_months_back	INTERLOCK_AUDIT__PARTITION_MONTHS_BACK	1	Past monthly partitions kept attached.
audit.partition_months_ahead	INTERLOCK_AUDIT__PARTITION_MONTHS_AHEAD	3	Future monthly partitions created in advance.

ingestion

Discovery ingestion.

Key	Environment variable	Default	Meaning
ingestion.enabled	INTERLOCK_INGESTION__ENABLED	false	Run ingestion (discovery indexing) jobs.
ingestion.max_retries	INTERLOCK_INGESTION__MAX_RETRIES	3	Attempts per ingestion job before it is marked failed.
ingestion.heartbeat_interval_seconds	INTERLOCK_INGESTION__HEARTBEAT_INTERVAL_SECONDS	10.0	Reserved: not read by the current runtime.
ingestion.job_timeout_seconds	INTERLOCK_INGESTION__JOB_TIMEOUT_SECONDS	300.0	Reserved: not read by the current runtime.

notifications

Approval notifications.

Key	Environment variable	Default	Meaning
notifications.enabled	INTERLOCK_NOTIFICATIONS__ENABLED	false	Send Slack notifications about write approvals.
notifications.slack_webhook_url	INTERLOCK_NOTIFICATIONS__SLACK_WEBHOOK_URL	unset	Deprecated literal webhook URL; use slack_webhook_url_ref.
notifications.slack_webhook_url_ref	INTERLOCK_NOTIFICATIONS__SLACK_WEBHOOK_URL_REF	unset	Secret reference to a Slack incoming-webhook URL.
notifications.slack_bot_token_ref	INTERLOCK_NOTIFICATIONS__SLACK_BOT_TOKEN_REF	unset	Secret reference to a Slack bot token; needs slack_channel.
notifications.slack_channel	INTERLOCK_NOTIFICATIONS__SLACK_CHANNEL	unset	Channel the bot posts to.
notifications.slack_api_base_url	INTERLOCK_NOTIFICATIONS__SLACK_API_BASE_URL	https://slack.com/api	Slack Web API base URL.
notifications.admin_base_url	INTERLOCK_NOTIFICATIONS__ADMIN_BASE_URL	unset	Console URL used to link a message to its approval.
notifications.approval_events	INTERLOCK_NOTIFICATIONS__APPROVAL_EVENTS	["pending", "approved", "rejected", "expired", "failed"]	Approval events that send a message.
notifications.timeout_seconds	INTERLOCK_NOTIFICATIONS__TIMEOUT_SECONDS	5.0	Timeout per delivery attempt.
notifications.max_attempts	INTERLOCK_NOTIFICATIONS__MAX_ATTEMPTS	3	Delivery attempts per message.
notifications.allow_private_egress	INTERLOCK_NOTIFICATIONS__ALLOW_PRIVATE_EGRESS	false	Allow delivery to private network addresses.

approvals

Write approvals.

Key	Environment variable	Default	Meaning
approvals.expiry_seconds	INTERLOCK_APPROVALS__EXPIRY_SECONDS	900	How long a queued write waits for a decision before it expires.
approvals.expiry_sweep_interval_seconds	INTERLOCK_APPROVALS__EXPIRY_SWEEP_INTERVAL_SECONDS	30	How often expired approvals are swept.

semantic_cache

Discovery embeddings; semantic cache serving is disabled.

Key	Environment variable	Default	Meaning
semantic_cache.default_auto_serve_threshold	INTERLOCK_SEMANTIC_CACHE__DEFAULT_AUTO_SERVE_THRESHOLD	0.98	Reserved: not read by the current runtime. Semantic cache serving is disabled.
semantic_cache.default_verify_threshold	INTERLOCK_SEMANTIC_CACHE__DEFAULT_VERIFY_THRESHOLD	0.92	Reserved: not read by the current runtime. Semantic cache serving is disabled.
semantic_cache.llm_timeout_ms	INTERLOCK_SEMANTIC_CACHE__LLM_TIMEOUT_MS	500	Reserved: not read by the current runtime.
semantic_cache.embedding_model	INTERLOCK_SEMANTIC_CACHE__EMBEDDING_MODEL	all-MiniLM-L6-v2	Reserved: not read by the current runtime.
semantic_cache.embedding_dimension	INTERLOCK_SEMANTIC_CACHE__EMBEDDING_DIMENSION	384	Dimension of the discovery embedding vectors.
semantic_cache.use_onnx	INTERLOCK_SEMANTIC_CACHE__USE_ONNX	false	Reserved: not read by the current runtime.

catalog

Source catalog.

Key	Environment variable	Default	Meaning
catalog.enabled	INTERLOCK_CATALOG__ENABLED	true	Capture each source’s structure into the catalog.
catalog.scan_on_save	INTERLOCK_CATALOG__SCAN_ON_SAVE	true	Queue a scan whenever a source is saved.
catalog.scheduled_refresh_enabled	INTERLOCK_CATALOG__SCHEDULED_REFRESH_ENABLED	true	Rescan sources on a schedule.
catalog.refresh_interval_seconds	INTERLOCK_CATALOG__REFRESH_INTERVAL_SECONDS	86400	Age at which a successful scan is refreshed.
catalog.failure_retry_seconds	INTERLOCK_CATALOG__FAILURE_RETRY_SECONDS	3600	Wait before retrying a source whose scan failed.
catalog.scheduler_tick_seconds	INTERLOCK_CATALOG__SCHEDULER_TICK_SECONDS	300	How often the scheduler looks for due sources.
catalog.scheduler_jitter_seconds	INTERLOCK_CATALOG__SCHEDULER_JITTER_SECONDS	120	Random delay added so scans do not start together.
catalog.worker_concurrency	INTERLOCK_CATALOG__WORKER_CONCURRENCY	1	Scans one worker runs at once.
catalog.poll_interval_seconds	INTERLOCK_CATALOG__POLL_INTERVAL_SECONDS	5.0	How often a worker checks for queued scans.
catalog.scan_timeout_seconds	INTERLOCK_CATALOG__SCAN_TIMEOUT_SECONDS	600	Longest a single scan may run.
catalog.lease_seconds	INTERLOCK_CATALOG__LEASE_SECONDS	120	How long a claimed scan stays leased.
catalog.max_attempts	INTERLOCK_CATALOG__MAX_ATTEMPTS	3	Attempts per scan before it is marked failed.
catalog.max_nodes	INTERLOCK_CATALOG__MAX_NODES	250000	Most catalog nodes one scan records.
catalog.max_schemas	INTERLOCK_CATALOG__MAX_SCHEMAS	500	Most schemas one scan records.
catalog.max_tables	INTERLOCK_CATALOG__MAX_TABLES	20000	Most tables one scan records.
catalog.max_columns_per_table	INTERLOCK_CATALOG__MAX_COLUMNS_PER_TABLE	2000	Most columns recorded per table.
catalog.max_change_rows_per_scan	INTERLOCK_CATALOG__MAX_CHANGE_ROWS_PER_SCAN	5000	Most drift rows one scan records.
catalog.scan_history_retention	INTERLOCK_CATALOG__SCAN_HISTORY_RETENTION	50	Scans kept per source.
catalog.change_retention_days	INTERLOCK_CATALOG__CHANGE_RETENTION_DAYS	90	Days drift rows are kept.

observability

Tracing, metrics and readiness.

Key	Environment variable	Default	Meaning
observability.enabled	INTERLOCK_OBSERVABILITY__ENABLED	true	Export traces and metrics over OTLP when an endpoint is set.
observability.otlp_endpoint	INTERLOCK_OBSERVABILITY__OTLP_ENDPOINT	unset	OTLP HTTP endpoint; unset exports nothing.
observability.instrument_asgi	INTERLOCK_OBSERVABILITY__INSTRUMENT_ASGI	true	Trace each HTTP request.
observability.readiness_enabled	INTERLOCK_OBSERVABILITY__READINESS_ENABLED	true	Reserved: not read by the current runtime.
observability.public_stats_enabled	INTERLOCK_OBSERVABILITY__PUBLIC_STATS_ENABLED	false	Serve the gateway’s /stats without authentication.
observability.readiness_timeout_seconds	INTERLOCK_OBSERVABILITY__READINESS_TIMEOUT_SECONDS	2.0	Timeout for each dependency check in /ready.