Kiln Documentation

Start here

Configuration schema

Inspect the machine-readable defaults, constraints, environment mappings, migrations, and cross-field rules for kiln.toml.

Canonical schema for kiln.toml. Sections and fields are optional because the typed loader supplies defaults; unknown sections and fields are rejected. Each public environment override is mechanically named KILN_

_; alternate spellings are ignored.

Schema identity

Property Value
Title Kiln server configuration v1
$id https://ericflo.github.io/kiln/contracts/kiln-config-v1.schema.json
Dialect https://json-schema.org/draft/2020-12/schema
Root type object
Root object closed

Root fields

Field Required Type Constraints and default Description
server no server - Server. HTTP serving, scheduling limits, response metadata, and default thinking policy.
accelerator no accelerator - Accelerator. Process-lifetime accelerator execution, Vulkan device selection, ROCm synchronization, and graph-cache policy.
batching no batching - Batching. Production batching actor and direct-decode rendezvous policy.
model no model - Model. Model, tokenizer, snapshot, adapter, and served identity paths.
paths no paths - Paths. Process-lifetime filesystem locations shared by model and accelerator caches.
memory no memory - Memory. Accelerator capacity, live-governor, KV-cache, and graph allocation policy.
training no training - Training. Native training checkpoint, queue, retention, and webhook policy.
openenv no openenv - Openenv. Native OpenEnv discovery, stateful rollout, artifact retention, and GRPO handoff policy for the server HTTP/dashboard control plane.
logging no logging - Logging. Tracing filter and output format.
prefix_cache no prefix_cache - Prefix cache. Requested shared-prefix KV and recurrent-state retention policy. Backend qualification determines the effective capability.
speculative no speculative - Speculative. Fail-closed speculative-decoding method and geometry.
streaming_prefill no streaming_prefill - Streaming prefill. Backend-aware streaming-prefill dispatch and tile policy.
adapters no adapters - Adapters. Finalized adapter and composed-cache disk limits.
teachers no teachers - Teachers. Server-owned remote-teacher credential handles and authorized origins.
eval no eval - Eval. Evaluation registry, queue, retention, and webhook policy.
request_log no request_log - Request log. Durable bounded inference request/response logging.
agent no agent - Agent. Self-improvement schedule, embedded agent-run limits, and immutable pi runtime policy.

Composition and conditional rules

Show exact composition rules 
{
  "allOf": [
    {
      "if": {
        "properties": {
          "memory": {
            "properties": {
              "kv_force_blocks": {
                "minimum": 1
              }
            },
            "required": [
              "kv_force_blocks"
            ]
          }
        },
        "required": [
          "memory"
        ]
      },
      "then": {
        "properties": {
          "server": {
            "properties": {
              "serving_profile": {
                "const": "maintenance"
              }
            },
            "required": [
              "serving_profile"
            ]
          },
          "memory": {
            "properties": {
              "kv_autoscale": {
                "const": true
              }
            },
            "required": [
              "kv_autoscale"
            ]
          }
        },
        "required": [
          "server",
          "memory"
        ]
      }
    }
  ]
}

Kiln contract annotations

Show exact Kiln annotations and examples 
{
  "x-kiln-canonical-environment-count": 112,
  "x-kiln-compatibility-alias-count": 0,
  "x-kiln-compatibility-field-count": 0,
  "x-kiln-config-file-only-count": 5,
  "x-kiln-dynamic-field-template-count": 3,
  "x-kiln-field-count": 117,
  "x-kiln-removed-toml-field-count": 2,
  "x-kiln-removed-toml-field-replacements": {
    "speculative.enabled": "speculative.method",
    "streaming_prefill.enabled": "streaming_prefill.mode"
  },
  "x-kiln-retired-environment-count": 82,
  "x-kiln-retired-environment-replacements": {
    "KILN_ADAPTER_DIR": "KILN_MODEL_ADAPTER_DIR",
    "KILN_ADAPTER_LIBRARY_URL": "KILN_ADAPTERS_LIBRARY_URL",
    "KILN_AGENT_RUNS": "KILN_AGENT_RUNS_ACCESS",
    "KILN_BATCHING_ENGINE": "removed; every real backend uses the actor",
    "KILN_BATCH_DECODE_ROWWISE": "KILN_BATCHING_ROWWISE_DECODE",
    "KILN_BATCH_PREFILL_ADMISSION_QUANTUM": "KILN_BATCHING_PREFILL_ADMISSION_QUANTUM",
    "KILN_BATCH_PREFIX_AWARE_ADMISSION": "KILN_BATCHING_PREFIX_AWARE_ADMISSION",
    "KILN_CHAT_CONFIG_HASH_METADATA": "KILN_SERVER_CHAT_CONFIG_HASH_METADATA",
    "KILN_CHAT_PERFORMANCE_METADATA": "KILN_SERVER_CHAT_PERFORMANCE_METADATA",
    "KILN_CHECKPOINT_BOUNDARY_ANCHOR_STRIDE": "KILN_TRAINING_CHECKPOINT_BOUNDARY_ANCHOR_STRIDE",
    "KILN_CHECKPOINT_BOUNDARY_CACHE_GB": "KILN_TRAINING_CHECKPOINT_BOUNDARY_CACHE_GB",
    "KILN_CHECKPOINT_INTERVAL": "KILN_TRAINING_CHECKPOINT_INTERVAL",
    "KILN_CUDA_GRAPHS": "KILN_MEMORY_CUDA_GRAPHS",
    "KILN_DECODE_BATCHER": "removed; the direct worker no longer exists",
    "KILN_DECODE_BATCH_MAX": "removed; the direct worker no longer exists",
    "KILN_DECODE_BATCH_MIXED_SEQ": "removed; the direct worker no longer exists",
    "KILN_DECODE_BATCH_WAIT_US": "removed; the direct worker no longer exists",
    "KILN_DEFAULT_NO_THINK": "KILN_SERVER_DEFAULT_THINKING_ENABLED",
    "KILN_DEFAULT_THINKING_BUDGET_MS": "KILN_SERVER_DEFAULT_THINKING_BUDGET_MS",
    "KILN_DEFAULT_THINKING_BUDGET_TOKENS": "KILN_SERVER_DEFAULT_THINKING_BUDGET_TOKENS",
    "KILN_DEFAULT_THINKING_ENABLED": "KILN_SERVER_DEFAULT_THINKING_ENABLED",
    "KILN_DETACHED_FULL_ATTN_TILE_TOKENS": "KILN_STREAMING_PREFILL_DETACHED_FULL_ATTN_TILE_TOKENS",
    "KILN_DETERMINISTIC": "KILN_SERVER_DETERMINISTIC",
    "KILN_DISABLE_ROCM_BF16_MATMUL_F32_OUTPUT": "KILN_ACCELERATOR_ROCM_BF16_MATMUL_OUTPUT_MODE",
    "KILN_DISABLE_ROCM_STRIDED_BATCHED_MATMUL": "KILN_ACCELERATOR_ROCM_STRIDED_BATCHED_MATMUL_MODE",
    "KILN_EVAL_MODE": "KILN_SERVER_EVAL_MODE",
    "KILN_FOLD_REASONING_INTO_CONTENT": "KILN_SERVER_FOLD_REASONING_INTO_CONTENT",
    "KILN_FORCE_ROCM_BF16_MATMUL_F32_OUTPUT": "KILN_ACCELERATOR_ROCM_BF16_MATMUL_OUTPUT_MODE",
    "KILN_FORCE_ROCM_STRIDED_BATCHED_MATMUL": "KILN_ACCELERATOR_ROCM_STRIDED_BATCHED_MATMUL_MODE",
    "KILN_GPU_MEMORY_GB": "KILN_MEMORY_GPU_MEMORY_GB",
    "KILN_GRAD_CHECKPOINT_SEGMENTS": "KILN_TRAINING_GRAD_CHECKPOINT_SEGMENTS",
    "KILN_HOST": "KILN_SERVER_HOST",
    "KILN_HTTP_SEND_BUFFER_BYTES": "KILN_SERVER_HTTP_SEND_BUFFER_BYTES",
    "KILN_INFERENCE_MEMORY_FRACTION": "KILN_MEMORY_INFERENCE_MEMORY_FRACTION",
    "KILN_KV_AUTOSCALE": "KILN_MEMORY_KV_AUTOSCALE",
    "KILN_KV_CACHE_FP8": "KILN_MEMORY_KV_CACHE_FP8",
    "KILN_KV_FORCE_BLOCKS": "KILN_MEMORY_KV_FORCE_BLOCKS",
    "KILN_LOGIT_CACHE_DIR": "KILN_TRAINING_LOGIT_CACHE_DIR",
    "KILN_LOG_FORMAT": "KILN_LOGGING_FORMAT",
    "KILN_LOG_LEVEL": "KILN_LOGGING_LEVEL",
    "KILN_MAX_BATCH_TOKENS": "KILN_SERVER_MAX_BATCH_TOKENS",
    "KILN_MAX_DECODE_BATCH": "KILN_SERVER_MAX_DECODE_BATCH",
    "KILN_MAX_PREFILL_LAYERS_PER_CYCLE": "KILN_SERVER_MAX_PREFILL_LAYERS_PER_CYCLE",
    "KILN_MAX_PREFILL_TOKENS_PER_CYCLE": "KILN_SERVER_MAX_PREFILL_TOKENS_PER_CYCLE",
    "KILN_MODEL_ID": "KILN_MODEL_MODEL_ID",
    "KILN_NO_GRAD_CHECKPOINT": "KILN_TRAINING_NO_GRAD_CHECKPOINT",
    "KILN_NUM_BLOCKS": "KILN_MEMORY_NUM_BLOCKS",
    "KILN_PI_BIN": "KILN_AGENT_PI_BIN",
    "KILN_PI_SESSIONS_DIR": "KILN_AGENT_PI_SESSIONS_DIR",
    "KILN_PORT": "KILN_SERVER_PORT",
    "KILN_RECOMPUTE_BOUNDARY_THRESHOLD_TOKENS": "KILN_TRAINING_RECOMPUTE_BOUNDARY_THRESHOLD_TOKENS",
    "KILN_RECOMPUTE_CHECKPOINT_BOUNDARIES": "KILN_TRAINING_RECOMPUTE_CHECKPOINT_BOUNDARIES",
    "KILN_REQUEST_TIMEOUT_SECS": "KILN_SERVER_REQUEST_TIMEOUT_SECS",
    "KILN_ROCM_GRAPHS": "KILN_ACCELERATOR_ROCM_GRAPH_MODE",
    "KILN_ROCM_GRAPH_CACHE_MAX": "KILN_ACCELERATOR_ROCM_GRAPH_CACHE_ENTRIES",
    "KILN_ROCM_GRAPH_CAPTURE": "KILN_ACCELERATOR_ROCM_GRAPH_MODE",
    "KILN_SERVED_MODEL_ID": "KILN_MODEL_SERVED_MODEL_ID",
    "KILN_SERVING_PROFILE": "KILN_SERVER_SERVING_PROFILE",
    "KILN_SHUTDOWN_TIMEOUT_SECS": "KILN_SERVER_SHUTDOWN_TIMEOUT_SECS",
    "KILN_SLOW_REQUEST_WARN_SECS": "KILN_SERVER_SLOW_REQUEST_WARN_SECS",
    "KILN_SPECULATIVE_ENABLED": "KILN_SPECULATIVE_METHOD",
    "KILN_SPEC_DRAFT_LAYERS": "KILN_SPECULATIVE_DRAFT_LAYERS",
    "KILN_SPEC_ENABLED": "KILN_SPECULATIVE_METHOD",
    "KILN_SPEC_METHOD": "KILN_SPECULATIVE_METHOD",
    "KILN_SPEC_NUM_TOKENS": "KILN_SPECULATIVE_NUM_SPECULATIVE_TOKENS",
    "KILN_STREAMING_LAST_TOKEN_LM_HEAD": "KILN_STREAMING_PREFILL_LAST_TOKEN_LM_HEAD",
    "KILN_STREAMING_PREFILL": "KILN_STREAMING_PREFILL_MODE",
    "KILN_STREAMING_PREFILL_ENABLED": "KILN_STREAMING_PREFILL_MODE",
    "KILN_STREAMING_TILE_TOKENS": "KILN_STREAMING_PREFILL_TILE_TOKENS",
    "KILN_STREAM_STALL_GRACE_MS": "KILN_SERVER_STREAM_STALL_GRACE_MS",
    "KILN_TAPE_STREAMING_TILE_TOKENS": "KILN_STREAMING_PREFILL_TAPE_TILE_TOKENS",
    "KILN_TERMINAL": "KILN_SERVER_TERMINAL_ACCESS",
    "KILN_TOKENIZER_PATH": "KILN_MODEL_TOKENIZER_PATH",
    "KILN_TRAINING_MEMORY_GB": "KILN_MEMORY_TRAINING_MEMORY_GB",
    "KILN_VULKAN_BUFFER_POOL_GB": "KILN_MEMORY_VULKAN_BUFFER_POOL_GB",
    "KILN_VULKAN_DEVICE": "KILN_ACCELERATOR_VULKAN_DEVICE_INDEX",
    "KILN_VULKAN_VALIDATION": "KILN_ACCELERATOR_VULKAN_VALIDATION",
    "KILN_BATCHING_DIRECT_DECODE_RENDEZVOUS_MAX_BATCH": "removed; the direct worker no longer exists",
    "KILN_BATCHING_DIRECT_DECODE_RENDEZVOUS_MIXED_SEQ_LENS": "removed; the direct worker no longer exists",
    "KILN_BATCHING_DIRECT_DECODE_RENDEZVOUS_MODE": "removed; the direct worker no longer exists",
    "KILN_BATCHING_DIRECT_DECODE_RENDEZVOUS_WAIT_US": "removed; the direct worker no longer exists",
    "KILN_BATCHING_MODE": "removed; every real backend uses the actor"
  },
  "x-kiln-toml-compatibility-field-count": 0
}

Definitions

serverHTTP serving, scheduling limits, response metadata, and default thinking policy.22 fields

Type: object. Constraints: default {}; closed object.

Field Required Type and default Canonical environment target Alternate environment spelling Profile gate Validation and semantics
server.serving_profile no string enum; "stable" KILN_SERVER_SERVING_PROFILE (implemented) none none stable, experimental, or maintenance, case-insensitive. Process-lifetime policy; restart required.
server.deterministic no boolean; false KILN_SERVER_DETERMINISTIC (implemented) none none Enables deterministic tensor behavior and forces the effective concurrent decode width to one.
server.host no string; "127.0.0.1" KILN_SERVER_HOST (implemented) none none Must be non-empty. Binding beyond loopback exposes an unauthenticated inference and training API; use a trusted network or authenticated reverse proxy.
server.port no unsigned 16-bit integer; 8420 KILN_SERVER_PORT (implemented) none none 1..=65535.
server.request_timeout_secs no unsigned integer; 600 KILN_SERVER_REQUEST_TIMEOUT_SECS (implemented) none none Must be greater than zero. Bounds a request, including model work and cleanup settlement.
server.terminal_access no string enum; "loopback_only" KILN_SERVER_TERMINAL_ACCESS (implemented) none none loopback_only, enabled, or disabled. This capability can execute arbitrary code; changing it requires restart.
server.http_send_buffer_bytes no optional unsigned integer; omitted (None) KILN_SERVER_HTTP_SEND_BUFFER_BYTES (implemented) none none When set, 1024..=16777216. Applied to accepted sockets. Startup preflights the listener and rejects an OS read-back smaller than requested.
server.stream_stall_grace_ms no unsigned integer; 2000 KILN_SERVER_STREAM_STALL_GRACE_MS (implemented) none none 10..=2000. A request retaining KV state with no streaming delivery progress is selected for cancellation after this grace.
server.max_batch_tokens no unsigned integer; 512 KILN_SERVER_MAX_BATCH_TOKENS (implemented) none none 2..=65536. Combined decode-plus-prefill token budget for one batching-actor cycle.
server.max_prefill_tokens_per_cycle no unsigned integer; 256 KILN_SERVER_MAX_PREFILL_TOKENS_PER_CYCLE (implemented) none none 1..=65536. Independent new-prompt-token ceiling within the combined actor budget. ROCm actor serving requires equality with the effective streaming tile, tiled streaming-prefill dispatch no later than that boundary, and server.max_batch_tokens >= tile + effective max_decode_batch; unsafe combinations fail startup.
server.max_prefill_layers_per_cycle no unsigned integer; 4 KILN_SERVER_MAX_PREFILL_LAYERS_PER_CYCLE (implemented) none none 1..=1024. Number of transformer layers an in-flight prefill chunk may execute before yielding to decode.
server.max_decode_batch no "auto" or unsigned integer; "auto" KILN_SERVER_MAX_DECODE_BATCH (implemented) none none auto, backend, and backend_policy all delegate to backend policy; an integer must be 1..=65536. Deterministic mode and max_batch_tokens may lower the final width. Explicit values require backend-specific correctness, memory, and latency qualification; qualification receipts never mutate this field.
server.eval_mode no boolean; false KILN_SERVER_EVAL_MODE (implemented) none none Enables deterministic eval-serving defaults, headers, adapter warnings, and transient-cache cleanup behavior. serve --eval-mode applies a typed override after environment resolution and wins without mutating process environment.
server.debug_model_state no boolean; false KILN_SERVER_DEBUG_MODEL_STATE (implemented) none none Enables trusted GET /v1/debug/model-state diagnostics without changing inference, cache, or eval semantics. server.eval_mode=true also enables the endpoint. The response contains model/configuration/runtime state but no prompt or user-message contents.
server.default_thinking_enabled no optional boolean; omitted (None) KILN_SERVER_DEFAULT_THINKING_ENABLED (implemented) none none None preserves the model template default. Requests may override with chat_template_kwargs.enable_thinking. The canonical environment override accepts strict booleans; there is no environment value that restores None.
server.default_thinking_budget_tokens no optional unsigned integer; omitted (None) KILN_SERVER_DEFAULT_THINKING_BUDGET_TOKENS (implemented) none none Integer values include 0, which closes thinking immediately. Case-insensitive unlimited clears a TOML limit back to None. Requests may inherit, replace, or explicitly disable the limit.
server.default_thinking_budget_ms no optional unsigned integer; omitted (None) KILN_SERVER_DEFAULT_THINKING_BUDGET_MS (implemented) none none Integer values include 0. unlimited clears a TOML limit. The clock starts at the first decode candidate, after queueing and prefill. The first token or time limit reached forces the model's closing sequence.
server.fold_reasoning_into_content no boolean; false KILN_SERVER_FOLD_REASONING_INTO_CONTENT (implemented) none none Copies separated reasoning into content for compatibility clients. A request can override it.
server.chat_performance_metadata no boolean; false KILN_SERVER_CHAT_PERFORMANCE_METADATA (implemented) none none Default for chat response performance metadata; requests can override with include_performance.
server.chat_config_hash_metadata no boolean; false KILN_SERVER_CHAT_CONFIG_HASH_METADATA (implemented) none none Default for chat response config hashes; requests can override with include_config_hashes.
server.slow_request_warn_secs no unsigned integer; 30 KILN_SERVER_SLOW_REQUEST_WARN_SECS (implemented) none none 0 disables slow-request warnings; otherwise a request at least this old emits a structured warning.
server.shutdown_timeout_secs no unsigned integer; 5 KILN_SERVER_SHUTDOWN_TIMEOUT_SECS (implemented) none none Must be greater than zero. Hard ceiling for graceful drain before forced exit.
acceleratorProcess-lifetime accelerator execution, Vulkan device selection, ROCm synchronization, and graph-cache policy.15 fields

Type: object. Constraints: default {}; closed object.

Field Required Type and default Canonical environment target Alternate environment spelling Profile gate Validation and semantics
accelerator.kt_api_mode no string enum; "auto" KILN_ACCELERATOR_KT_API_MODE (implemented) none none auto, all, or disabled, case-insensitive. auto enables qualified routes, all enables every adapter route, and disabled forces legacy fallbacks. Restart required.
accelerator.full_attention_score_budget_mib no unsigned integer MiB; 2048 KILN_ACCELERATOR_FULL_ATTENTION_SCORE_BUDGET_MIB (implemented) none none 64..=2048. Immutable ceiling for exact full-attention materialized score and scratch geometry across CPU, CUDA, ROCm, Metal, and Vulkan model routes. ROCm online attention derives min(value, 1024) MiB while retaining fixed qualified 2048-query/4096-key tiles. Runtime memory observations remain fail-closed admission and reservation checks; they never resize the geometry or switch to smaller tiles during a request. Restart required.
accelerator.vulkan_device_index no "auto" or unsigned integer; "auto" KILN_ACCELERATOR_VULKAN_DEVICE_INDEX (implemented) none none auto preserves automatic discrete-GPU preference and otherwise chooses the first enumerated Vulkan physical device. An integer strictly selects that zero-based Vulkan enumeration index. An unavailable index fails logical-device startup; it is never ignored or replaced with another device. The immutable selection is installed before Vulkan device creation and reported with source attribution. Restart required.
accelerator.vulkan_validation no boolean; false KILN_ACCELERATOR_VULKAN_VALIDATION (implemented) none none true enables VK_LAYER_KHRONOS_validation at startup and fails if the layer is unavailable. Restart required.
accelerator.cuda_kernel_profile no string enum; "native_default" KILN_ACCELERATOR_CUDA_KERNEL_PROFILE (implemented) none none native_default enables the device-neutral subset of twenty-four CUDA model/backend routes and declines the GDN full-chunk multiblock route whose performance evidence covers only one GPU configuration. portable_fallback declines every owned route. The complete twenty-five-route set is installed before CUDA backend construction, immutable for the process lifetime, and reported with source attribution. Restart required.
accelerator.cuda_marlin_profile no string enum; "disabled" KILN_ACCELERATOR_CUDA_MARLIN_PROFILE (implemented) none none disabled preserves BF16 projections; attention_mlp and attention_mlp_gdn select immutable Marlin W4A16 layouts. Restart required.
accelerator.cuda_flash_backward_mode no string enum; "fast" KILN_ACCELERATOR_CUDA_FLASH_BACKWARD_MODE (implemented) none none fast or deterministic, case-insensitive. fast preserves the established CUDA FlashAttention backward accumulation. deterministic selects split accumulation for exact replay and diagnosis. The mode is installed before model construction and cannot change between training jobs. Restart required.
accelerator.metal_kernel_profile no string enum; "native_default" KILN_ACCELERATOR_METAL_KERNEL_PROFILE (implemented) none none native_default or portable_fallback, case-insensitive. native_default preserves forty-five of the forty-six Metal backend routes active before consolidation; custom LM-head argmax remains disabled by default. portable_fallback declines every owned route. The complete route set is installed before Metal backend construction, immutable for the process lifetime, and reported with source attribution. Restart required.
accelerator.rocm_synchronization_mode no string enum; "legacy_host_barriers" KILN_ACCELERATOR_ROCM_SYNCHRONIZATION_MODE (implemented) none none legacy_host_barriers or stream_ordered, case-insensitive. Restart required.
accelerator.rocm_strided_batched_matmul_mode no string enum; "disabled" KILN_ACCELERATOR_ROCM_STRIDED_BATCHED_MATMUL_MODE (implemented) none none disabled uses one operation per logical row; enabled selects strided batching. The retired auto value is rejected. Restart required.
accelerator.rocm_bf16_matmul_output_mode no string enum; "f32_then_cast" KILN_ACCELERATOR_ROCM_BF16_MATMUL_OUTPUT_MODE (implemented) none none f32_then_cast is the portable default; native_bf16 explicitly requests native BF16 output. Restart required.
accelerator.rocm_kernel_profile no string enum; "native_default" KILN_ACCELERATOR_ROCM_KERNEL_PROFILE (implemented) none none native_default enables native single-row and batched dynamic-length paged attention. portable_fallback is the explicit diagnostic route. The retired qualified and experimental_multiblock values fail startup. Restart required.
accelerator.rocm_graph_mode no string enum; "profile" KILN_ACCELERATOR_ROCM_GRAPH_MODE (implemented) none none profile selects guarded lazy capture during serving and eager execution during maintenance. Explicit modes are startup-immutable. Restart required.
accelerator.rocm_graph_cache_entries no unsigned integer; 8 KILN_ACCELERATOR_ROCM_GRAPH_CACHE_ENTRIES (implemented) none none 1..=64. Bounds retained native graph entries in every product and embedding constructor. At saturation, admission reclaims idle owners first and then the minimum fair-LRU active entries while preserving one graph per active owner after the incoming candidate. Zero or unbounded capacities are rejected. Restart required.
accelerator.rocm_graph_cache_max_bytes no unsigned integer bytes; 1073741824 (1 GiB) KILN_ACCELERATOR_ROCM_GRAPH_CACHE_MAX_BYTES (implemented) none none 67108864..=17179869184 (64 MiB through 16 GiB). Independently bounds requested physical bytes retained by graph-owned stable tensors, capture arenas, private-stream hipBLASLt workspaces, and owner slot state. Opaque HIP graph/exec/stream/event overhead is counted as objects and remains subject to live driver-pressure policy. Restart required.
batchingProduction batching actor and direct-decode rendezvous policy.4 fields

Type: object. Constraints: default {}; closed object.

Field Required Type and default Canonical environment target Alternate environment spelling Profile gate Validation and semantics
batching.rowwise_decode no boolean; false KILN_BATCHING_ROWWISE_DECODE (implemented) none none false sends each ready cohort through one true batched forward. true issues one forward per row while retaining actor ownership; it is an emergency correctness comparison, normally reduces throughput, and does not increase the effective decode width. Restart required.
batching.prefix_aware_admission no boolean; true KILN_BATCHING_PREFIX_AWARE_ADMISSION (implemented) none none When true, a queued same-adapter strict descendant waits while its active shorter prefix can become reusable; independent rows may still be admitted. Disable only for a controlled admission A/B. Restart required.
batching.prefill_admission_quantum no "auto" or unsigned integer; "auto" KILN_BATCHING_PREFILL_ADMISSION_QUANTUM (implemented) none none An integer must be 1..=65536 and caps how many queued prompts the actor admits in one cycle before returning to decode. auto is case-insensitive and uses the backend policy below. The selected value is then clamped to 1..=effective max_decode_batch; the diagnostics name effective_decode_width as final authority when it performs that clamp. With non-burst admission, total active capacity is effective decode width plus this staging quantum, capped internally at four staging slots. Restart required.
batching.actor_cycle_idle_ms no unsigned integer milliseconds; 0 KILN_BATCHING_ACTOR_CYCLE_IDLE_MS (implemented) none none 0..=60000. Zero preserves the unpaced actor. A nonzero value inserts one intentional cooperative wait after an actor cycle that advanced prefill or decode, only after synchronous accelerator work has returned. The actor polls control commands at intervals no longer than 5 ms, so shutdown remains responsive, and the independent response-delivery worker and HTTP process remain live. This deliberately trades request throughput and inter-token latency for a lower sustained accelerator duty cycle; it is not a temperature controller and never changes itself from a live sensor. Config, health, debug, Prometheus, and serving-benchmark receipts expose the policy and observed waits. Restart required.
modelModel, tokenizer, snapshot, adapter, and served identity paths.10 fields

Type: object. Constraints: default {}; closed object.

Field Required Type and default Canonical environment target Alternate environment spelling Profile gate Validation and semantics
model.path no optional string; omitted (None) KILN_MODEL_PATH (implemented) none none Must be non-empty when set. Omitted starts the server in mock mode; a real model path enables real inference.
model.model_id no string; "Qwen/Qwen3.5-4B" KILN_MODEL_MODEL_ID (implemented) none none Must be non-empty. Used for model/tokenizer identity and as the source of the default served id. Kiln still applies its built-in Qwen3.5-4B runtime profile.
model.tokenizer_path no optional string; omitted (None) KILN_MODEL_TOKENIZER_PATH (implemented) none none Must be non-empty when set.
model.adapter_dir no optional string; omitted (None) KILN_MODEL_ADAPTER_DIR (implemented) none none Must be non-empty when set. For the Qwen3.5-4B profile, omission resolves to <model.path>/adapters.
model.snapshot_dir no optional string; omitted (None) KILN_MODEL_SNAPSHOT_DIR (implemented) none none Must be non-empty when set. An empty or whitespace-only canonical environment value clears a TOML value. Without a value, Kiln tries a location beside the model and then the system temporary directory.
model.checkpoint_read_mib_per_second no optional unsigned integer MiB/s; omitted (None) KILN_MODEL_CHECKPOINT_READ_MIB_PER_SECOND (implemented) none none 1..=16384 when set. Independently bounds the private snapshot copy, initial full content verification, and post-upload full verification. Reflinked bytes are not charged as reads. Shutdown is checked between bounded chunks and at most every 25 ms during waits. Omission removes rate limiting but preserves cancellation. Applies to real-model startup on every backend, requires restart, and is never active during inference. GET /v1/config.model_startup.checkpoint_read reports all three phase observations.
model.accelerator_weight_upload_mib_per_second no optional unsigned integer MiB/s; omitted (None) KILN_MODEL_ACCELERATOR_WEIGHT_UPLOAD_MIB_PER_SECOND (implemented) none none 1..=16384 when set. Reserves the cumulative eager base-model source-byte schedule before the base group and each layer, then checks it again after the unit. The base group adds shutdown boundaries after embedding upload, transpose, pack, final norm, and rotary initialization. Transforms can add device work, so this is not a bus-throughput cap. The current backend operation is not interruptible; reservation waits poll cancellation every 25 ms. Omission removes rate limiting but preserves boundary cancellation. Inapplicable to mock and CPU-only execution. Startup-only, restart required, and never active during inference. GET /v1/config.model_startup.accelerator_weight_upload reports reserved/completed bytes and layers.
model.vulkan_decode_weight_prewarm no boolean; true KILN_MODEL_VULKAN_DECODE_WEIGHT_PREWARM (implemented) none none Populates backend-private Vulkan decode-weight caches during startup. Disable only to trade first-request latency for lower startup work. Restart required.
model.vulkan_decode_weight_prewarm_mib_per_second no unsigned integer MiB/s; 256 KILN_MODEL_VULKAN_DECODE_WEIGHT_PREWARM_MIB_PER_SECOND (implemented) none none 1..=16384. Bounds the average Vulkan decode-weight cache materialization rate. Pacing checks shutdown at least every 25 ms between uploads. Restart required.
model.served_model_id no optional string; omitted (None) KILN_MODEL_SERVED_MODEL_ID (implemented) none none Must be non-empty when set. Otherwise the effective id is the final slash-separated component of model.model_id (Qwen3.5-4B by default). serve --served-model-id applies a typed, validated override after environment resolution.
pathsProcess-lifetime filesystem locations shared by model and accelerator caches.1 field

Type: object. Constraints: default {}; closed object.

Field Required Type and default Canonical environment target Alternate environment spelling Profile gate Validation and semantics
paths.cache_root no optional path string; omitted (platform account cache directory) KILN_PATHS_CACHE_ROOT (implemented) none none Must be a non-empty path when set. Relative paths are made absolute against the startup working directory. The resolved root is installed before cache consumers and cannot change during the process lifetime. GET /v1/config.paths reports the absolute effective path and source.
memoryAccelerator capacity, live-governor, KV-cache, and graph allocation policy.13 fields

Type: object. Constraints: default {}; closed object.

Field Required Type and default Canonical environment target Alternate environment spelling Profile gate Validation and semantics
memory.num_blocks no optional unsigned integer; omitted (None) KILN_MEMORY_NUM_BLOCKS (implemented) none none Must be greater than zero when set. Omission invokes backend-aware automatic KV-block sizing.
memory.gpu_memory_gb no optional finite number; omitted (None) KILN_MEMORY_GPU_MEMORY_GB (implemented) none none Must be finite, greater than zero, and representable as bytes. Units are GiB. This is a capacity cap, not a hardware override: it may reduce the detected safe capacity but never expands physical VRAM, host-backed unified memory, or a cgroup-bounded capacity. A request above the safe detected capacity is clamped down.
memory.inference_memory_fraction no finite number; 0.7 KILN_MEMORY_INFERENCE_MEMORY_FRACTION (implemented) none none Loader validation accepts 0.0..=1.0; real-state construction clamps the configured value to 0.1..=1.0 before KV sizing. The remainder is available to the training budget.
memory.training_memory_gb no optional finite number; omitted (None) KILN_MEMORY_TRAINING_MEMORY_GB (implemented) none none Must be finite, greater than zero, and representable as bytes when set. Optional training-budget cap in GiB; it can reduce but never expand the capacity remaining after resident model and KV allocations.
memory.vulkan_buffer_pool_gb no finite number; 3.0 KILN_MEMORY_VULKAN_BUFFER_POOL_GB (implemented) none none Vulkan-only process-wide cap, in GiB, on idle scratch buffers retained for reuse. Must be finite, non-negative, and representable as bytes; 0 disables retention. Active operations may allocate beyond the cap, but overflow buffers are freed when their final caller drops. A new cache entry evicts the oldest idle buffers before admission, and pressure reclaim releases idle entries under exclusive GPU coordination. /v1/config, /health, and Prometheus expose the cap, retained/free/borrowed bytes, hits/misses by allocation route, evictions, and uncached overflow. Health also exposes one bounded last-miss record with requested and bucket bytes plus the source callsite.
memory.floor_gb no finite number; 1.0 KILN_MEMORY_FLOOR_GB (implemented) none none Must be finite, non-negative, representable as bytes, and strictly smaller than the selected accelerator's effective capacity after memory.gpu_memory_gb is applied. Units are GiB. Accelerator startup rejects an equal or larger floor before model upload and reports both configured and effective byte values. The process-wide governor subtracts this additional floor, then outstanding soft reservations, from live free memory when computing allocation headroom. On unified-memory devices it is separate from the physical-memory reserve applied during safe-capacity detection.
memory.probe_ms no unsigned integer; 500 KILN_MEMORY_PROBE_MS (implemented) none none Must be greater than zero. Sets the background memory-sampler cadence. Request, inference, health, and metrics paths read only the published sample and never run a driver/OS probe synchronously. Cached admission fails closed when the sample is older than max(5000 ms, 4 * probe_ms), the latest probe failed, or a required sampler is not running. An explicit refresh after a material allocation or release bypasses the cadence.
memory.reclaim_mode no string enum; "off" KILN_MEMORY_RECLAIM_MODE (implemented) none none Exactly off, on-demand, or automatic, case-insensitive with surrounding whitespace ignored. off prevents execution of registered allocator reclaim hooks; on-demand permits explicit pressure and allocation-retry reclaim calls; automatic also permits the background pressure monitor. The immutable serving profile remains authoritative: a profile with allocator reclaim disabled keeps the effective mode off and does not start the monitor.
memory.kv_autoscale no boolean; true KILN_MEMORY_KV_AUTOSCALE (implemented) none none Requests the pressure-driven physical KV-cache control loop. Backends without device-resident KV pressure report the request as unavailable rather than silently enabling mutation. /health, /v1/config, and the trusted debug state expose the request, effective state, bounded reason, and source.
memory.kv_force_blocks no unsigned integer; 0 (disabled) KILN_MEMORY_KV_FORCE_BLOCKS (implemented) none maintenance when minimum 1 A positive value requests one exact startup resize before the normal autoscaler loop. It requires memory.kv_autoscale=true and server.serving_profile="maintenance"; every other combination fails configuration validation. Zero disables the one-shot operation. The resize still uses full replacement-pool reservation, exclusive GPU ownership, graph invalidation, transactional publication, and typed forced_configuration attribution. This is an offline maintenance/qualification control, not a per-request tuning knob.
memory.kv_cache_fp8 no boolean; false KILN_MEMORY_KV_CACHE_FP8 (implemented) none none Requests E4M3FN KV storage. Backend storage policy may reject or disable the request when unsupported.
memory.cuda_graphs no boolean; true KILN_MEMORY_CUDA_GRAPHS (implemented) none none CUDA-only request. Non-CUDA backends ignore it, and a serving profile with live graph capture disabled selects eager-only execution regardless of this value.
memory.cuda_graph_cache_entries no unsigned integer; 8 KILN_MEMORY_CUDA_GRAPH_CACHE_ENTRIES (implemented) none none 1..=64. Bounds retained single-row CUDA decode graphs and their graph-stable device buffers. Resolved once before device selection; decode never re-reads process environment. The unqualified batched CUDA graph route remains unavailable.
trainingNative training checkpoint, queue, retention, and webhook policy.12 fields

Type: object. Constraints: default {}; closed object.

Field Required Type and default Canonical environment target Alternate environment spelling Profile gate Validation and semantics
training.grad_checkpoint_segments no optional unsigned integer; omitted (None) KILN_TRAINING_GRAD_CHECKPOINT_SEGMENTS (implemented) none none Must be greater than zero when set. When present, selects an explicit process-lifetime gradient-checkpoint segment count for native training; omission leaves workload- and capacity-aware automatic planning enabled.
training.no_grad_checkpoint no boolean; false KILN_TRAINING_NO_GRAD_CHECKPOINT (implemented) none none Disables gradient checkpoint execution for native training. The disabled state and any explicit segment count are retained together in the immutable training policy and exact-resume identity. Disabling checkpointing can materially increase training memory.
training.recompute_checkpoint_boundaries no string enum; "auto" KILN_TRAINING_RECOMPUTE_CHECKPOINT_BOUNDARIES (implemented) none none auto, enabled, or disabled, case-insensitive with surrounding whitespace ignored. auto replays sparse SFT boundaries when sequence length is at least recompute_boundary_threshold_tokens; enabled always replays them and disabled always retains them. Every other TOML type, TOML value, or environment value fails startup.
training.recompute_boundary_threshold_tokens no positive unsigned integer; 8192 KILN_TRAINING_RECOMPUTE_BOUNDARY_THRESHOLD_TOKENS (implemented) none none Inclusive sequence-length threshold used only by automatic SFT boundary replay. Zero, negative, overflowing, malformed, and non-UTF-8 environment values stop startup.
training.checkpoint_boundary_anchor_stride no "auto" or positive unsigned integer; "auto" KILN_TRAINING_CHECKPOINT_BOUNDARY_ANCHOR_STRIDE (implemented) none none When sparse SFT replay is active, a concrete value retains every Nth segment boundary as an anchor. auto derives a shape-specific positive stride from sequence length, segment count, hidden width, boundary dtype, and the cache target. Zero and strings other than auto fail startup.
training.checkpoint_boundary_cache_gb no positive floating-point GiB value; 6.0 KILN_TRAINING_CHECKPOINT_BOUNDARY_CACHE_GB (implemented) none none Automatic anchor-stride memory target. Despite the historical _gb spelling, the unit is GiB (2^30 bytes). The value must be finite, positive, convert to at least one byte, and remain below the u64 byte limit. Startup converts it once to integral bytes using the historical truncating conversion.
training.checkpoint_interval no optional unsigned integer; omitted (None) KILN_TRAINING_CHECKPOINT_INTERVAL (implemented) none none Must be greater than zero when set. Number of committed optimizer steps between checkpoints; per-job configuration overrides it. Omission disables periodic checkpoints.
training.webhook_url no optional string; omitted (None) KILN_TRAINING_WEBHOOK_URL (implemented) none none Must be a non-empty valid HTTP(S) URL. An exactly empty environment value clears a TOML URL; whitespace is not a clearing value and fails validation. Delivery is fire-and-forget with a five-second timeout after terminal state is recorded.
training.logit_cache_dir no optional path string; omitted (beside the effective adapter directory) KILN_TRAINING_LOGIT_CACHE_DIR (implemented) none none Must be a non-empty path when set. Resolved once at startup; request handlers never reread the environment.
training.max_queued_jobs no unsigned integer; 32 KILN_TRAINING_MAX_QUEUED_JOBS (implemented) none none Must be greater than zero. At capacity, submissions return HTTP 503 with Retry-After: 30.
training.max_tracked_jobs no unsigned integer; 1024 KILN_TRAINING_MAX_TRACKED_JOBS (implemented) none none Must be greater than zero and at least max_queued_jobs. Counts queued, running, completed, and failed entries.
training.tracked_job_ttl_secs no unsigned integer; 604800 KILN_TRAINING_TRACKED_JOB_TTL_SECS (implemented) none none Must be greater than zero. Terminal entries older than the TTL are removed; active jobs are never age-evicted.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-dependent-order": [
    {
      "less-or-equal": "max_queued_jobs",
      "greater-or-equal": "max_tracked_jobs"
    }
  ]
}
openenvNative OpenEnv discovery, stateful rollout, artifact retention, and GRPO handoff policy for the server HTTP/dashboard control plane.6 fields

Type: object. Constraints: default {}; closed object.

Field Required Type and default Canonical environment target Alternate environment spelling Profile gate Validation and semantics
openenv.enabled no boolean; true KILN_OPENENV_ENABLED (implemented) none none Enables protocol discovery, bounded Task API catalogs, and asynchronous run lifecycle routes. Disabling it does not remove the local CLI.
openenv.max_active_runs no unsigned integer; 4 KILN_OPENENV_MAX_ACTIVE_RUNS (implemented) none none Must be greater than zero and no greater than max_tracked_runs. Bounds admitted complete workflows across collection, queued or running GRPO, static post-evaluation, and paired held-out environment evaluation. Additional accepted runs wait in a cancellable FIFO; underlying executors retain their own bounds.
openenv.max_tracked_runs no unsigned integer; 128 KILN_OPENENV_MAX_TRACKED_RUNS (implemented) none none Must be greater than zero and at least max_active_runs. This is the hard admission bound for active plus FIFO-queued work and retained terminal history. A retained record also owns its optional idempotency-key binding.
openenv.tracked_run_ttl_secs no unsigned integer; 604800 KILN_OPENENV_TRACKED_RUN_TTL_SECS (implemented) none none Must be greater than zero. Terminal status and idempotency bindings age out after this window; content-addressed rollout and paired-evaluation artifacts remain under <adapter_dir>/.openenv/runs/.
openenv.allow_remote_environments no boolean; false KILN_OPENENV_ALLOW_REMOTE_ENVIRONMENTS (implemented) none none When false, server-launched discovery and runs reject non-loopback origins before network access. Enable only for trusted operators and origins; Kiln's HTTP API is unauthenticated unless protected by your deployment.
openenv.credentials.<id> no map of origin-scoped credential objects; empty none none none Config-file-only handles. IDs use 1..=64 ASCII letters, digits, _ or -, except that - alone is reserved for a public CLI/dashboard slot; each object requires an exact canonical origin and bearer_token_env. Remote origins require HTTPS. The named secret must be set and non-empty at startup; its value and variable name are redacted from effective configuration.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-dependent-order": [
    {
      "less-or-equal": "max_active_runs",
      "greater-or-equal": "max_tracked_runs"
    }
  ]
}
loggingTracing filter and output format.2 fields

Type: object. Constraints: default {}; closed object.

Field Required Type and default Canonical environment target Alternate environment spelling Profile gate Validation and semantics
logging.level no string; "info" KILN_LOGGING_LEVEL (implemented) none none One of trace, debug, info, warn, error, or a valid tracing_subscriber::EnvFilter directive such as kiln=debug,tower_http=warn. RUST_LOG overrides the effective filter but does not make an invalid typed value valid.
logging.format no string; "auto" KILN_LOGGING_FORMAT (implemented) none none Exactly auto, json, pretty, text, or human. auto is pretty on a stderr TTY and JSON otherwise; text and human select pretty output.
prefix_cacheRequested shared-prefix KV and recurrent-state retention policy. Backend qualification determines the effective capability.3 fields

Type: object. Constraints: default {}; closed object.

Field Required Type and default Canonical environment target Alternate environment spelling Profile gate Validation and semantics
prefix_cache.enabled no boolean; true KILN_PREFIX_CACHE_ENABLED (implemented) none none Requests reuse of KV blocks and recurrent-state snapshots for shared prompt prefixes. CPU, CUDA, ROCm, and Metal honor the request. Vulkan currently forces the effective capability off because repeated production-model runs proved semantic corruption after cross-request restoration. This is a source-level correctness quarantine, not a second setting.
prefix_cache.max_blocks no optional unsigned integer; omitted (None) KILN_PREFIX_CACHE_MAX_BLOCKS (implemented) none none Must be greater than zero when set. On an admitted backend, None resolves to half of the allocated KV block pool. It has no runtime allocation effect while the effective capability is off.
prefix_cache.max_entries no optional unsigned integer; omitted (None) KILN_PREFIX_CACHE_MAX_ENTRIES (implemented) none none Must be greater than zero when set. On an admitted backend, None resolves from the relevant safe allocation tier and per-entry recurrent-state bytes, with at least one entry. It has no runtime allocation effect while the effective capability is off; quarantined Vulkan reserves no host-backed prefix state.
speculativeFail-closed speculative-decoding method and geometry.3 fields

Type: object. Constraints: default {}; closed object.

Field Required Type and default Canonical environment target Alternate environment spelling Profile gate Validation and semantics
speculative.method no string enum; "off" KILN_SPECULATIVE_METHOD (implemented) none none off, skip_layer, or mtp, case-insensitive with surrounding whitespace ignored. method is the single authority: off disables speculative decoding and either non-off value requests that qualification method. Non-off serving remains fail-closed until its accelerator lifecycle contract is qualified.
speculative.num_speculative_tokens no unsigned integer; 4 KILN_SPECULATIVE_NUM_SPECULATIVE_TOKENS (implemented) none none Draft proposal bound K. Must be in 1..=4; out-of-range values stop startup before accelerator allocation. This conservative ceiling matches the planned local K=1/2/4 qualification matrix and cannot be raised without new accelerator evidence.
speculative.draft_layers no unsigned integer; 8 KILN_SPECULATIVE_DRAFT_LAYERS (implemented) none none Must be greater than zero. When method is not off, model-dependent startup validation also requires this value to be less than the selected model transformer-layer count. Invalid geometry stops startup; it does not fall back at request time.
streaming_prefillBackend-aware streaming-prefill dispatch and tile policy.6 fields

Type: object. Constraints: default {}; closed object.

Field Required Type and default Canonical environment target Alternate environment spelling Profile gate Validation and semantics
streaming_prefill.mode no string enum; "auto" KILN_STREAMING_PREFILL_MODE (implemented) none none auto, enabled, or disabled, case-insensitive with surrounding whitespace ignored. auto delegates dispatch to backend policy, enabled selects every non-empty prompt, and disabled selects none. ROCm requires dispatch to cover the first effective actor tile, so disabled is rejected for that backend. Every other TOML type, TOML value, or environment value fails startup.
streaming_prefill.threshold_tokens no "auto" or positive unsigned integer; "auto" KILN_STREAMING_PREFILL_THRESHOLD_TOKENS (implemented) none none In auto mode, an integer replaces the backend crossover only when that backend already has a threshold-based automatic policy. It does not make CPU or Vulkan auto-dispatch streaming. With the ROCm batching actor effective, the crossover cannot be later than the effective tile. 0, negative values, and strings other than auto fail startup. enabled and disabled modes ignore this crossover for dispatch while retaining it in diagnostics.
streaming_prefill.tile_tokens no "auto" or positive unsigned integer; "auto" KILN_STREAMING_PREFILL_TILE_TOKENS (implemented) none none Base tile for ordinary tiled prefill and non-tape GDN segment execution. Concrete values must be positive multiples of 64. With the ROCm batching actor effective, this tile must equal server.max_prefill_tokens_per_cycle and fit beside effective decode width in server.max_batch_tokens. When this field is concrete and either specialized tile below is auto, that specialized route inherits this base value rather than its backend default.
streaming_prefill.tape_tile_tokens no "auto" or positive unsigned integer; "auto" KILN_STREAMING_PREFILL_TAPE_TILE_TOKENS (implemented) none none Tile used by tape-authoritative training forward paths. Concrete values must be positive multiples of 64. auto inherits an explicit tile_tokens; when both are auto, backend policy owns the value.
streaming_prefill.detached_full_attn_tile_tokens no "auto" or positive unsigned integer; "auto" KILN_STREAMING_PREFILL_DETACHED_FULL_ATTN_TILE_TOKENS (implemented) none none Tile for detached materialized full-attention training work. A concrete value also controls its derived boundary-forward and tape-replay variants. auto inherits an explicit tile_tokens; when both are auto, each variant keeps its backend default. Every concrete value must be a positive multiple of 64.
streaming_prefill.last_token_lm_head no boolean; true KILN_STREAMING_PREFILL_LAST_TOKEN_LM_HEAD (implemented) none none When true, the final inference streaming tile computes the LM head only for its last row. All centralized strict boolean spellings, including on and off, work identically.
adaptersFinalized adapter and composed-cache disk limits.4 fields

Type: object. Constraints: default {}; closed object.

Field Required Type and default Canonical environment target Alternate environment spelling Profile gate Validation and semantics
adapters.library_url no string URL; "https://library.kiln.run" KILN_ADAPTERS_LIBRARY_URL (implemented) none none Must be a non-empty valid HTTP(S) URL. Resolved once at startup.
adapters.max_disk_bytes no optional unsigned integer; 107374182400 (100 GiB) KILN_ADAPTERS_MAX_DISK_BYTES (implemented) none none Caps finalized adapter bytes under adapter_dir, excluding upload staging and the composed cache. For the canonical environment override, empty or 0 means None and disables the cap. TOML 0 is accepted as a literal zero cap, not as None.
adapters.composed_cache_max_bytes no optional unsigned integer; 10737418240 (10 GiB) KILN_ADAPTERS_COMPOSED_CACHE_MAX_BYTES (implemented) none none LRU byte cap for .composed. Environment empty or 0 disables this dimension; TOML 0 remains a zero cap.
adapters.composed_cache_max_entries no optional unsigned integer; 64 KILN_ADAPTERS_COMPOSED_CACHE_MAX_ENTRIES (implemented) none none LRU entry-count cap for .composed. Environment empty or 0 disables this dimension; TOML 0 remains a zero cap.
evalEvaluation registry, queue, retention, and webhook policy.4 fields

Type: object. Constraints: default {}; closed object.

Field Required Type and default Canonical environment target Alternate environment spelling Profile gate Validation and semantics
eval.eval_dir no optional path string; omitted (None) KILN_EVAL_EVAL_DIR (target only; not implemented) none none Must be non-empty when set. Despite the historical field name, runtime treats it as the shared eval root and creates the three registry subdirectories below it.
eval.max_queued_jobs no unsigned integer; 32 KILN_EVAL_MAX_QUEUED_JOBS (target only; not implemented) none none Must be greater than zero.
eval.max_tracked_jobs no unsigned integer; 1024 KILN_EVAL_MAX_TRACKED_JOBS (target only; not implemented) none none Must be greater than zero and at least max_queued_jobs.
eval.webhook_url no optional string; omitted (None) KILN_EVAL_WEBHOOK_URL (target only; not implemented) none none Must be a non-empty valid HTTP(S) URL. Terminal eval notifications are fire-and-forget.

Kiln contract annotations

These machine-readable annotations are copied exactly from this schema node.

{
  "x-kiln-dependent-order": [
    {
      "less-or-equal": "max_queued_jobs",
      "greater-or-equal": "max_tracked_jobs"
    }
  ]
}
request_logDurable bounded inference request/response logging.6 fields

Type: object. Constraints: default {}; closed object.

Field Required Type and default Canonical environment target Alternate environment spelling Profile gate Validation and semantics
request_log.enabled no boolean; true KILN_REQUEST_LOG_ENABLED (implemented) none none Master switch. Initialization failure logs a warning and disables logging rather than aborting an otherwise valid server startup.
request_log.dir no optional path string; omitted (None) KILN_REQUEST_LOG_DIR (implemented) none none Must be non-empty when set. None resolves to <adapter_dir>/.requests. The canonical environment override cannot clear a TOML directory; an empty value is fatal.
request_log.max_file_bytes no unsigned integer; 67108864 (64 MiB) KILN_REQUEST_LOG_MAX_FILE_BYTES (implemented) none none Must be at least 4096. The active JSONL file rotates after reaching the threshold.
request_log.max_total_bytes no unsigned integer; 2147483648 (2 GiB) KILN_REQUEST_LOG_MAX_TOTAL_BYTES (implemented) none none Must be greater than zero. Oldest rotated files are removed until retained bytes fit. There is no validation requiring this value to exceed max_file_bytes.
request_log.compress no boolean; true KILN_REQUEST_LOG_COMPRESS (implemented) none none Gzip rotated files when true.
request_log.max_capture_bytes no unsigned integer; 4194304 (4 MiB) KILN_REQUEST_LOG_MAX_CAPTURE_BYTES (implemented) none none Must be greater than zero. Per-request and per-response storage cap; truncation affects the log only, never the wire response.
agentSelf-improvement schedule, embedded agent-run limits, and immutable pi runtime policy.7 fields

Type: object. Constraints: default {}; closed object.

Field Required Type and default Canonical environment target Alternate environment spelling Profile gate Validation and semantics
agent.self_improve_interval_hours no optional unsigned integer; omitted (None) KILN_AGENT_SELF_IMPROVE_INTERVAL_HOURS (implemented) none none Omission disables scheduling. 0 is accepted and also results in no scheduler. The first run occurs one full interval after startup; cadence is persisted under the adapter directory.
agent.self_improve no optional structured value; omitted (None) KILN_AGENT_SELF_IMPROVE (target only; not implemented) none none Request template submitted to the same self-improvement path as the API. This value is intentionally open structured data; its inner request contract is validated by that subsystem rather than by KilnConfig.
agent.max_concurrent_runs no unsigned integer; 2 KILN_AGENT_MAX_CONCURRENT_RUNS (implemented) none none Must be greater than zero. Embedded pi runs above the limit queue FIFO.
agent.run_timeout_secs no unsigned integer; 900 KILN_AGENT_RUN_TIMEOUT_SECS (implemented) none none Must be at least 10. A per-run timeout can override the server default.
agent.runs_access no string enum; "loopback_only" KILN_AGENT_RUNS_ACCESS (implemented) none none loopback_only, enabled, or disabled. Embedded runs can execute arbitrary code; changing this requires restart.
agent.pi_bin no optional path string; omitted (search startup PATH) KILN_AGENT_PI_BIN (implemented) none none Must name a non-empty existing file when explicitly configured. The resolved executable is immutable for the process lifetime.
agent.pi_sessions_dir no optional path string; omitted (OS account .pi/agent/sessions) KILN_AGENT_PI_SESSIONS_DIR (implemented) none none Must be a non-empty path when set. Relative paths and the operating-system account fallback are resolved once at startup without consulting HOME.
teacher_credentialExact fields and constraints for this schema definition.2 fields

Type: object. Constraints: closed object.

Field Required Type and default Canonical environment target Alternate environment spelling Profile gate Validation and semantics
teachers.credentials.<id>.origin yes required string for each entry; no entries by default none; structured trust policy is TOML-only none none Must be the exact canonical scheme://host[:port] origin, with no path, query, fragment, or embedded credentials. HTTPS is required unless the host is loopback.
teachers.credentials.<id>.api_key_env yes required string for each entry none; this value names the secret variable none none Must match [A-Za-z_][A-Za-z0-9_]*, length 1..=128. The named variable must exist and contain a non-whitespace value at startup.
teachersServer-owned remote-teacher credential handles and authorized origins.1 field

Type: object. Constraints: default {}; closed object.

Field Required Type Constraints and default Description
credentials no object default {} Opaque credential handles mapped to one exact authorized origin and one secret environment-variable name.