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`.

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.

Runtime reliability¶

Variable	Default	Purpose
`KNEO_SERV_PROVIDER_RETRIES`	`0`	Provider/runtime retry count.
`KNEO_SERV_PROVIDER_RETRY_BACKOFF_SECONDS`	`0.25`	Provider/runtime retry backoff.
`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.25`	MCP retry backoff.
`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`	Structured logging level.
`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.

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.
`KNEO_SERV_RETENTION_ARTIFACTS_DAYS`	unset	Delete old artifact files.
`KNEO_SERV_RETENTION_LOGS_DAYS`	unset	Delete old log files.

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.