Project `.kneo/` config¶

Each project keeps a .kneo/ directory for local service configuration, generated artifacts, and logs. This page covers the contents and the overlay/policy story; for the runtime variables read from the environment (rather than from project config), see environment.md.

.kneo/
  config.yaml
  README.md
  artifacts/.gitkeep
  logs/.gitkeep

The .kneo/config.yaml demonstrates:

default project name and owner
service URL
local state/artifact/log paths
default spec
environment overlays
runtime defaults
model defaults
policy defaults
environment-variable secret references
retention windows (per-project)

Environment-specific policy enforcement can be configured under environments.<name>.policy_enforcement:

environments:
  dev:
    policy_enforcement:
      enabled: false
  staging:
    policy_enforcement:
      require_tool_permissions: true
      blocked_diagnostic_codes: [E_UNSAFE_TOOL_IMPORT, E_UNSAFE_FUNCTION_IMPORT]
  prod:
    policy_enforcement:
      require_tool_permissions: true
      deny_unrestricted_tools: true
      require_human_review: true
      require_guardrails: true
      blocked_diagnostic_codes: [E_UNSAFE_TOOL_IMPORT, E_UNSAFE_FUNCTION_IMPORT]

Policy enforcement runs after spec overlays and project defaults are applied. kneo spec validate --env prod, kneo spec compile --env prod, kneo spec policy-report --env prod, and kneo run --env prod all honor the resolved environment policy.

Retention¶

Retention windows for runs, checkpoints, queue records, continuations, audit events, idempotency records, artifacts, and log files live in a top-level retention: block. Each field is a count of days to keep; unset fields disable pruning for that category. Values must be zero or greater.

retention:
  runs_days: 30
  checkpoints_days: 14
  queue_days: 7
  continuations_days: 21
  audit_days: 45
  idempotency_days: 30
  artifacts_days: 60
  logs_days: 90

audit_days prunes the audit-event log purely by age (it reaps events with no associated run too); the audit table grows unbounded otherwise, so it is the table most likely to exhaust disk on a long-lived deployment.

The same eight retention fields can be overridden per-host via env vars (KNEO_SERV_RETENTION_RUNS_DAYS and friends; see environment.md § Retention). Precedence is env var > project config > unset. Set the project-config field for the per-project default; set the env var to deviate on a specific host (staging vs. prod, etc.) without editing the committed .kneo/config.yaml.

The retention values feed kneo_serv.maintenance.retention.RetentionPolicy.from_project_and_env(config.retention), which the operator can pass to PlatformManager.prune_retention(policy=...) on whatever cadence makes sense for the deployment (cron, scheduled workflow, manual operator action).

Local / self-hosted LLM endpoints¶

The native (openai) runtime can target any OpenAI-compatible server — Ollama, vLLM, llama.cpp, LocalAI — by setting base_url (and, if the server requires one, an API key) under the agent spec's model.extra:

agent:
  name: on-prem-assistant
  runtime_preferences:
    preferred_mode: native
    native_provider: openai
  model:
    provider: openai
    name: llama3            # the model the local server serves
    extra:
      base_url: http://localhost:11434/v1   # e.g. Ollama
      api_key_ref: LOCAL_LLM_KEY            # resolved from the env (see below)

base_url — the OpenAI-compatible endpoint. Omit it to use the hosted OpenAI API as before; this field is purely additive.
api_key_ref — the name of a secret reference, resolved at runtime through the SecretResolver (it reads the project extra_env map, falling back to an env var of the same name). Prefer this over a literal so the key is never baked into a persisted or signed spec bundle.
api_key — a literal-key escape hatch for throwaway/local use. It is a sensitive key, so it is redacted from audit events and list responses — but it still lives in the stored spec, so api_key_ref is the recommended path.

If neither key field is set, the runtime falls back to the provider's normal env var (OPENAI_API_KEY), which is fine for a keyless local server.

Project .kneo/ config¶

Retention¶

Local / self-hosted LLM endpoints¶

Project `.kneo/` config¶