Environment variables

Every environment variable read by kneo-serv, grouped by surface area. Defaults shown are the values used when the variable is unset.

For deployment templates that exercise these in context, see tutorial_postgres_deployment.md and deploy/*.env.example. The full HTTP contract that uses these knobs lives in service_api.md.

Project

Variable	Default	Purpose
KNEO_PROJECT_CONFIG	auto-discovery	Explicit path to .kneo/config.yaml.
KNEO_ENV	dev	Default project environment when --env is not provided.
KNEO_SERV_SPEC_SIGNING_KEY	unset	HMAC signing key used by kneo spec bundle sign and verify.
KNEO_SERV_SPEC_ROOT	process working directory	Allow-listed root for caller-supplied spec_path / overlays / skills[].source. Any such read (run, resume, /v1/specs/*) resolving outside the root — absolute, ..-traversal, or symlink escape — is rejected 422 spec_path_confined. Confinement is default-on as of 1.0.0 (opt-in through 0.12.x, where an out-of-root absolute path only logged a DeprecationWarning); when unset, the root is the process working directory. Set it explicitly when specs/skills live outside the working directory. See security_hardening.md.

Service auth

Variable	Default	Purpose
KNEO_SERV_AUTH_ENABLED	enabled when API keys are configured	Require API keys on protected HTTP routes.
KNEO_SERV_API_KEYS	empty	Semicolon-separated name:key:role_or_scope[,role_or_scope] entries.
KNEO_SERV_ADMIN_API_KEY	empty	Admin API key with all scopes.
KNEO_SERV_API_KEY	empty	Client API key used by ServiceClient and one-off CLI calls.
KNEO_SERV_IDEMPOTENCY_KEY	empty	Stable idempotency key for retry-safe service POST calls.

Persistence

Variable	Default	Purpose
KNEO_SERV_DATABASE_URL	empty	PostgreSQL DSN. When set, service stores use PostgreSQL instead of SQLite plus file continuations. Requires kneo-serv[postgres] or kneo-serv[deploy].
KNEO_SERV_PROFILES_PATH	~/.kneo_serv/profiles.json	CLI service-profile store location.

Service limits

Variable	Default	Purpose
KNEO_SERV_MAX_BODY_BYTES	1048576	Maximum HTTP request body size.
KNEO_SERV_MAX_INPUT_CHARS	20000	Maximum run input size.
KNEO_SERV_MAX_HUMAN_CONTENT_CHARS	20000	Maximum human response content size.
KNEO_SERV_MAX_INLINE_SPEC_BYTES	262144	Maximum inline spec payload size.
KNEO_SERV_MAX_OVERRIDES_BYTES	65536	Maximum spec override payload size.
KNEO_SERV_MAX_METADATA_BYTES	32768	Maximum request metadata payload size.
KNEO_SERV_MAX_LIST_ITEMS	100	Maximum requested list page size.
KNEO_SERV_MAX_PATH_CHARS	4096	Maximum path field size.

Run queue and workers

Variable	Default	Purpose
KNEO_SERV_WORKER_CONCURRENCY	1	In-process worker threads draining the run queue. Raise for provider-bound workloads so runs overlap on provider I/O. See performance.md.
KNEO_SERV_WORKER_IDLE_POLL_SECONDS	1.0	How long an idle worker waits before re-polling the queue when it finds no claimable run. Must be a finite number > 0. Lower for snappier pickup at the cost of more idle queue queries; raise to reduce store load on a mostly-idle deployment.
KNEO_SERV_WORKER_LEASE_SECONDS	300	Queue-lease liveness window per claimed run (not a run-time cap). A running worker renews its lease every ~1/3 of this interval (the lease heartbeat), so a healthy long run keeps its lease; only a dead or starved worker lets it expire, after which the run is re-claimed. Set it above a single step's wall-clock, not the whole run.
KNEO_SERV_QUEUE_MAX_ATTEMPTS	5	Dead-letter cap. A run re-leased more than this many times (e.g. one that repeatedly crashes its worker) is failed with a dead_letter reason instead of retried forever. 0 disables the cap.
KNEO_SERV_MAX_QUEUE_DEPTH	0	Overload backpressure: POST /v1/runs (async) returns 503 once this many runs are queued. 0 disables backpressure (unbounded queue).
KNEO_SERV_SHUTDOWN_TIMEOUT_SECONDS	30	How long SIGTERM shutdown waits for workers to finish their in-flight run. A run still executing past this is interrupted by process exit, then re-leased/retried after KNEO_SERV_WORKER_LEASE_SECONDS (not lost). Set this — and the orchestrator grace period — >= your longest run step to drain without a restart.

Runtime reliability

Variable	Default	Purpose
KNEO_SERV_TOKEN_BUDGET	unset	Deployment-wide per-run token ceiling (input + output across a run). A run that crosses it is failed with a token_budget_exceeded 4xx. This is a post-run / boundary check, not a mid-flight hard stop — the run completes the in-flight step, then fails. A spec's model.token_budget overrides this default per agent; unset disables the ceiling.
KNEO_SERV_PROVIDER_RETRIES	0	Provider/runtime retry count.
KNEO_SERV_PROVIDER_RETRY_BACKOFF_SECONDS	0.0	Provider/runtime retry backoff (seconds between attempts).
KNEO_SERV_PROVIDER_TIMEOUT_SECONDS	unset	Provider/runtime timeout.
KNEO_SERV_MCP_RETRIES	0	MCP tool retry count.
KNEO_SERV_MCP_RETRY_BACKOFF_SECONDS	0.0	MCP retry backoff (seconds between attempts).
KNEO_SERV_MCP_TIMEOUT_SECONDS	unset	MCP tool timeout.
KNEO_SERV_REQUIRE_PROVIDER_SECRETS	false	Fail native provider setup when provider secrets are absent.
KNEO_SERV_RUN_PROVIDER_INTEGRATION	false	Enable opt-in real provider integration tests. Requires provider credentials such as OPENAI_API_KEY.
KNEO_SERV_PROVIDER_TEST_MODEL	gpt-4o-mini	OpenAI model used by the opt-in provider integration smoke test.
KNEO_SERV_RUN_POSTGRES_INTEGRATION	false	Enable opt-in PostgreSQL persistence smoke tests. Requires KNEO_SERV_DATABASE_URL and the postgres extra.

CLI client

Variable	Default	Purpose
KNEO_SERV_CLIENT_TIMEOUT	120	HTTP client timeout in seconds.
KNEO_SERV_CLIENT_RETRIES	2	Service-client retry count for transient failures.
KNEO_SERV_CLIENT_RETRY_BACKOFF_SECONDS	0.25	Service-client retry backoff.

Observability

Variable	Default	Purpose
KNEO_SERV_REQUEST_LOGS	true	Enable structured request logs.
KNEO_SERV_LOG_LEVEL	INFO	Logging level for the whole stack — the kneo_serv.service (request), kneo_serv.platform (worker / lease / drain), and kneo_agent SDK loggers are all set from this one value at startup.
KNEO_SERV_AUDIT_EXPORT_ENABLED	false	When true, every persisted (already-redacted) audit event is also emitted as a JSON line on the kneo_serv.audit logger — attach a handler to forward it to a file / syslog / SIEM. Off = zero behavior change. See observability.md § Audit-event export.
KNEO_SERV_OTEL_ENABLED	false	Attach kneo_agent.observability.OpenTelemetryMiddleware to SDK-backed agents. Requires kneo-serv[telemetry] or kneo-serv[deploy].
KNEO_SERV_OTEL_RECORD_ARGUMENTS	false	Record tool-call arguments in SDK OpenTelemetry spans. Keep disabled when arguments may contain PII or secrets.
KNEO_SERV_OTEL_RECORD_RESULTS	false	Record tool results in SDK OpenTelemetry spans. Keep disabled for large or sensitive results.
KNEO_SERV_HEALTH_PROVIDERS	empty	Comma-separated provider secret names to include in readiness checks.
KNEO_SERV_HEALTH_MCP_SECRETS	empty	Comma-separated MCP secret names to include in readiness checks.
KNEO_SERV_METRICS_ENABLED	true	Mount the unauthenticated Prometheus /metrics endpoint. Restrict it to your monitoring network — see observability.md.

Retention

Variable	Default	Purpose
KNEO_SERV_RETENTION_RUNS_DAYS	unset	Delete old runs with terminal statuses.
KNEO_SERV_RETENTION_CHECKPOINTS_DAYS	unset	Delete old checkpoints.
KNEO_SERV_RETENTION_QUEUE_DAYS	unset	Delete old completed or failed queue records.
KNEO_SERV_RETENTION_CONTINUATIONS_DAYS	unset	Delete old continuations. Continuations of still-blocked runs are always protected regardless of age.
KNEO_SERV_RETENTION_IDEMPOTENCY_DAYS	unset	Delete idempotency records by updated_at (they carry full response payloads and grow with traffic).
KNEO_SERV_RETENTION_RUN_STATUSES	completed,failed,cancelled,timed_out,expired	Comma-separated terminal statuses eligible for the runs prune.
KNEO_SERV_RETENTION_AUDIT_DAYS	unset	Delete audit events older than this many days. The audit table grows unbounded otherwise — set this on long-lived deployments.
KNEO_SERV_RETENTION_ARTIFACTS_DAYS	unset	Delete old artifact files.
KNEO_SERV_RETENTION_LOGS_DAYS	unset	Delete old log files.
KNEO_SERV_ARTIFACT_PATH	unset	Root the artifacts retention pass prunes (artifacts_days no-ops without it).
KNEO_SERV_LOG_PATH	unset	Root the logs retention pass prunes (logs_days no-ops without it).
KNEO_SERV_TRACE_MAX_EVENTS	10000	Per-run trace buffer cap; 0 disables. Drops are counted and logged once.
KNEO_SERV_MCP_CONNECT_TIMEOUT_SECONDS	MCP per-attempt timeout, else 30	Bound on a lazy MCP session's connect; a hung server aborts instead of bricking the tool. Must be > 0. Connect timeouts cancel the connect coroutine cleanly, so configured MCP retries do retry them.
KNEO_SERV_IDEMPOTENCY_LOCK_TTL_SECONDS	300	Per-key idempotency lock TTL; raise it for deployments with long synchronous runs. Validated at startup.
KNEO_SERV_PROVIDER_RETRY_ON_TIMEOUT	false	Opt-in: retry a provider call after a per-attempt timeout. The timed-out attempt's thread is abandoned, not cancelled — only enable for idempotent call sites.
KNEO_SERV_WORKFLOW_RETRY_ON_TIMEOUT	false	Same opt-in for the workflow step/node retry surface (spec max_retries + timeout_seconds); restores the pre-0.9.0 retry-after-timeout behavior there.

Retention windows can also be set per-project in .kneo/config.yaml under a top-level retention: block — see project_config.md § Retention. Env-var precedence: an env var, if set, overrides the project-config value for that field. Use the env-var path as the operator escape hatch when the host needs to deviate from per-project defaults.

Checkpoint storage

Variable	Default	Purpose
KNEO_SERV_CHECKPOINT_COMPRESS_BYTES	65536	Compress checkpoint payloads at or above this size.
KNEO_SERV_CHECKPOINT_MAX_BYTES	1048576	Hard checkpoint payload limit after compression.
KNEO_SERV_CHECKPOINT_PREVIEW_CHARS	1200	Preview length for oversized checkpoint values.
KNEO_SERV_CHECKPOINT_MAX_LIST_ITEMS	20	Maximum list items retained in previews.
KNEO_SERV_CHECKPOINT_MAX_DICT_ITEMS	50	Maximum dict items retained in previews.