Configuration Reference#

Configuration schema for Antfly distributed key-value store and vector search engine.

Antfly is configured using a YAML configuration file. This reference documents all available configuration options.

Minimal Configuration#

The minimum required configuration for running Antfly:

Complete Example#

A comprehensive configuration showing all available options:

# Logging configuration for Antfly inference services
log:
  # Logging verbosity level
  level: info
  # Logging output format style. 'terminal' for colorized console, 'json' for structured JSON, 'logfmt' for token-efficient key=value pairs, 'noop' for silent.
  style: terminal
# Enables the health/metrics server. Defaults to true.
health_enabled: true
# Port for the health/metrics server. Defaults to 4200.
health_port: 4200
# Node-local foreground database request admission settings.
admission:
  query:
    # Maximum concurrent query, search, and retrieval requests in this
    # process. The default is 32. The budget is shared by REST, MCP,
    # retrieval-agent, A2A, and direct API-kernel execution. Full-text,
    # vector, hybrid, graph, aggregation, federated searches, and document
    # scans consume it. Point lookups and operational/control-plane reads
    # remain outside it. Excess HTTP work is rejected immediately with
    # HTTP 429 and Retry-After: 1; asynchronous protocols use their native failure
    # response. Excess work is not queued. Set to 0 to disable query
    # admission. This budget is independent of transport safeguards,
    # write admission, and
    # admission.inference.max_concurrent_requests.
    #
    max_concurrent_requests: 32
  write:
    # Maximum concurrent foreground data mutations in this process. The
    # default is 16. Table batch writes, cross-table batches, linear merges,
    # and transaction commits consume this budget. Schema, index, backup,
    # restore, repair, and other administrative operations use dedicated
    # control or background-maintenance paths. Set to 0 to disable write
    # admission.
    #
    # Excess HTTP work in either foreground class is rejected immediately
    # with HTTP 429 and Retry-After: 1; asynchronous protocols use their
    # native failure response. Excess work is not queued. Both budgets are
    # independent of transport safeguards and
    # admission.inference.max_concurrent_requests.
    #
    max_concurrent_requests: 16
  inference:
    # Maximum concurrent inference requests admitted by this process.
    # The budget covers embedded inference routes, direct providers, and
    # public connection inference forwarding. Remote forwarding holds a
    # slot for the full upstream request. The runtime-reserved
    # `local-inference` connection dispatches in process and is admitted
    # once by the destination inference route; configured URLs remain
    # remote boundaries even when they alias the local listener.
    # Embedded standalone uses one shared coordinator for all of those
    # surfaces; API-only runtimes use the same setting as a local forwarding
    # gate. For embedded inference, this value also sizes the weighted work
    # budget: each request consumes one request slot and at least one unit,
    # while request body size, generation workload, and image byte/count
    # reservations can consume more than one unit. The request count can
    # therefore never exceed this value, while expensive requests may
    # exhaust weighted capacity sooner. Read and
    # image-extraction admission reserves the effective downloaded-byte ceiling at 16 MiB
    # per unit and at least one unit per two images. A positive capacity also
    # clamps each such request's downloaded-image ceiling to 16 MiB times
    # this value. When a request or weighted-work ceiling is exhausted, new HTTP requests are
    # rejected immediately with 503 Service Unavailable and Retry-After: 1;
    # they are not retained
    # in an in-process queue. Set to 0 to disable request admission and,
    # for embedded inference, weighted-unit accounting and the
    # capacity-derived clamp. The default is 32.
    #
    max_concurrent_requests: 32
# Operator-owned ceilings shared by all named graph operations in one admitted query. Public requests cannot raise these values. Explored work, scanned anchors, and exact-distinct capacity are request-consumptive; intermediate and retained-state ceilings bound simultaneously live state.
graph_execution:
  # Cumulative node expansions across every named operation and path spur in one request.
  max_explored_nodes: 100000
  # Cumulative edge expansions across every named operation and path spur in one request.
  max_explored_edges: 1000000
  # Cumulative owned bytes of materialized edges read while executing one request.
  max_explored_edge_bytes: 67108864
  # Cumulative source anchors scanned by exact MATCH operations in one request.
  max_scanned_anchors: 1000000
  # Maximum simultaneously live traversal, pathfinding, or MATCH frontier states.
  max_intermediate_states: 100000
  # Maximum simultaneously retained bytes of admitted graph execution state.
  max_retained_state_bytes: 67108864
  # Cumulative exact-distinct identities admitted across all named aggregates in one request.
  max_distinct_identities: 100000
  # Request-consumptive bytes for exact-distinct identities, indexes, and ownership transfer.
  max_distinct_state_bytes: 16777216
# Model Context Protocol transport compatibility settings.
mcp:
  # Maximum serialized MCP `tools/call` result size, including both
  # TextContent and structuredContent. Results above the limit are
  # replaced with an actionable MCP tool error. The default is 96 KiB,
  # leaving envelope headroom beneath common 100 KiB connector limits.
  # Nonzero values must be at least 512 bytes so the replacement error
  # itself fits. Set to 0 to disable the compatibility guard.
  #
  max_tool_result_bytes: 98304
# Operator-owned limits for backup execution.
backup:
  # End-to-end ceiling for one table or cluster backup. Increase this for exceptionally large datasets; cleanup fencing remains independent.
  operation_timeout_seconds: 3600
# Tagged storage-engine configuration. Engine is required and exactly the matching engine member must be present.
storage:
  # Durable storage representation, independent of deployment topology.
  engine: local
  lite:
    # Path to the single writable Antfly Lite database file.
    path: ./data.antfly.aflite
    # Synchronize committed Lite state before acknowledging it.
    fsync: true
  object:
    # ID of a connections entry with kind external_io, protocol s3, and the storage.primary capability. Storage credentials are resolved from that connection independently of remote-content credentials.
    connection: string
    bucket: string
    prefix: string
    # Optional placement overrides for independently managed serverless durability lanes. Unspecified fields inherit from the object-level connection, bucket, and prefix.
    lanes:
      artifacts:
        # Optional external_io connection override for this lane.
        connection: string
        bucket: string
        prefix: string
      manifests:
        # Optional external_io connection override for this lane.
        connection: string
        bucket: string
        prefix: string
      wal:
        # Optional external_io connection override for this lane.
        connection: string
        bucket: string
        prefix: string
      progress:
        # Optional external_io connection override for this lane.
        connection: string
        bucket: string
        prefix: string
      catalog:
        # Optional external_io connection override for this lane.
        connection: string
        bucket: string
        prefix: string
  local:
    # Root directory for all antfly data storage. Defaults to 'antflydb'.
    base_dir: antflydb
# Resource and retention limits for multi-request transaction sessions.
transaction_sessions:
  ttl_seconds: 3600
  cleanup_interval_seconds: 60
  max_count: 1024
  max_record_bytes: 16777216
  max_savepoints: 64
metadata:
  # Mapping from Metadata Node ID (hex string) to its URL used by store nodes for enrolling into the cluster
  orchestration_urls:
    "1": "http://localhost:5001"
    "2": "http://localhost:5002"
    "3": "http://localhost:5003"
inference:
  # Deprecated compatibility alias for
  # `admission.inference.max_concurrent_requests`. New configurations
  # should use the process-level admission setting. If both spellings
  # are supplied, they must have the same value.
  #
  max_concurrent_requests: 32
  # URL of the Antfly inference embedding/chunking service
  api_url: "http://localhost:8080"
  # API key used when calling an authenticated shared Antfly inference API.
  api_key: string
  # Base directory containing model subdirectories. Antfly inference auto-discovers models from:
  # - `{models_dir}/embedders/` - Embedding models (ONNX)
  # - `{models_dir}/chunkers/` - Chunking models (ONNX)
  # - `{models_dir}/rerankers/` - Reranking models (ONNX)
  # - `{models_dir}/extractors/` - Entity, relation, and structured extraction models
  # - `{models_dir}/rewriters/` - Seq2Seq rewriter models (ONNX)
  #
  # Defaults to ~/.antfly/inference/models (set via viper). If not set, only built-in fixed chunking is available.
  #
  models_dir: ~/.antfly/inference/models
  # Base directory containing Traditional ML predictor subdirectories. The `/ml/v1/*`
  # API auto-discovers predictors from `{ml_dir}/{name}/tabular_model.json`.
  #
  # Defaults to ~/.antfly/inference/ml.
  #
  ml_dir: ~/.antfly/inference/ml
  # Low-level content download policy. In the generic scraper, omitted
  # `allowed_hosts` and `allowed_paths` fields do not restrict those sources;
  # explicit empty lists deny them. Consumers may merge this object over a
  # stricter baseline before downloading. Antfly inference does so: omitted
  # or empty inference policies, and omitted inference allowlists, deny
  # HTTP(S), file, and S3 content until explicit allowlists are configured.
  # Do not assume omission has identical policy semantics across consumers.
  #
  content_security:
    # Whitelist for HTTP(S) downloads. With block_private_ips enabled (the default), IP literals and every address resolved from an allowlisted DNS hostname must be globally routable; the connection is pinned to a vetted address. Set block_private_ips to false only to opt into private or special destinations. The generic scraper treats omission as unrestricted subject to that policy and an explicit empty list as deny-all; Antfly inference requires an explicit allowlist.
    allowed_hosts:
      - 93.184.216.34
    # Reject loopback, private, link-local, carrier-grade NAT, reserved, and multicast destinations. Allowlisted DNS hostnames are resolved, every result is filtered by this policy, and the connection is pinned to a vetted address. Set false only as an explicit opt-out that permits private and special destinations.
    block_private_ips: true
    # RFC 6052 network-specific NAT64 prefixes used by this deployment. Resolved IPv6 addresses under these prefixes are decoded and checked against the private IPv4 policy. Prefix length must be 32, 40, 48, 56, 64, or 96.
    nat64_prefixes:
      - "2001:db8:64::/96"
    # Maximum size of downloaded content in bytes
    max_download_size_bytes: 104857600
    # Maximum HTTP(S) and S3 download duration in seconds. Defaults to 30. Zero disables this configured ceiling, but a caller-supplied request deadline still applies. A deadline-bound file:// fetch fails closed because portable filesystem I/O does not expose a preemptive timeout.
    download_timeout_seconds: 30
    # Maximum source-image width or height enforced for accepted inference image inputs, including generate/chat, dense embed, multimodal rerank, `/read`, image `/extract`, and their embedded direct APIs. Images are rejected rather than resized. Batch generation rejects multimodal content before fetch; non-inference scraping consumers do not enforce this setting.
    max_image_dimension: 1
    # Whitelist of allowed path prefixes for file:// and s3:// URLs. The generic scraper treats omission as unrestricted and an explicit empty list as deny-all. Consumers may impose stricter defaults; Antfly inference requires explicit path allowlists. For file:// use absolute paths (e.g., /Users/data/). For s3:// use bucket/prefix (e.g., my-bucket/uploads/).
    allowed_paths:
      - /Users/data/
      - my-bucket/uploads/
    # User-Agent header for HTTP downloads. Defaults to 'AntflyDB/1.0' if not set. Some servers (e.g., Wikipedia) reject requests without a User-Agent.
    user_agent: AntflyDB/1.0
  s3_credentials:
    # S3-compatible endpoint (e.g., 's3.amazonaws.com' or 'localhost:9000' for MinIO)
    endpoint: s3.amazonaws.com
    # Enable SSL/TLS for S3 connections (default: true for AWS, false for local MinIO)
    use_ssl: true
    # AWS access key ID. Supports secret-store references. Falls back to AWS_ACCESS_KEY_ID when not set.
    access_key_id: your-access-key-id
    # AWS secret access key. Supports secret-store references. Falls back to AWS_SECRET_ACCESS_KEY when not set.
    secret_access_key: your-secret-access-key
    # Optional AWS session token for temporary credentials. Supports secret-store references.
    session_token: your-session-token
  # How long to keep models loaded in memory after last use (Ollama-compatible).
  # Models are automatically unloaded after this duration of inactivity.
  # Use Go duration format: "5m" (5 minutes), "1h" (1 hour), or "0".
  # Defaults to "5m". Set to "0" to disable idle-time eviction; models can
  # still be evicted under resource pressure or to enforce max_loaded_models.
  #
  keep_alive: 5m
  # Maximum total models loaded across all registry types (embedders, rerankers,
  # generators, chunkers, etc.). When the limit is reached, the least-recently-used
  # idle model from any registry is evicted to make room. Set to 0 for unlimited.
  # Defaults to 10.
  #
  max_loaded_models: 3
  # Legacy compatibility field. The current Zig inference runtime does not
  # create per-model pipeline pools from this setting; configuring it has no effect.
  #
  pool_size: 0
  # Native generator prompt KV cache configuration.
  prompt_cache:
    # Enable inference-native prompt KV cache reuse for generator requests.
    enabled: false
    # Prompt KV cache implementation. `block_hash` (default) uses hash-addressed
    # full KV blocks under prompt_cache_key with O(1) block lookup. `radix` is an
    # opt-in page-aligned compressed radix tree with shared-prefix ownership and
    # leaf-only LRU eviction; it is currently qualified for native and Metal
    # backends. Eligible Metal requests use eager paged attention; explicit compiled
    # generation is incompatible with prompt caching. `simple` keeps the linear-scan
    # retained-prefix cache and is only suitable for small caches or debugging.
    #
    mode: block_hash
    # Node-wide target for live prompt-cache entries. The runtime divides it
    # across participating model caches and evicts using estimated metadata
    # and logical host/device KV bytes. Backend allocators may retain reusable
    # capacity, so this is not a hard cap on process or accelerator memory.
    #
    max_bytes_mb: 512
    # Minimum prompt length eligible for prompt KV caching.
    min_tokens: 64
    # Idle time-to-live for prompt KV cache entries. Refreshed on every cache
    # hit, so only entries left unused for this duration expire.
    #
    ttl_ms: 300000
  # Runtime Metal and CUDA kernel JIT configuration. Live compilation and
  # GPU qualification run only for models in the configured startup
  # `preload` list, before serving begins. A cold dynamic model load never
  # benchmarks against an in-use GPU: `on` and `shadow` retain bundled
  # kernels, while `required` rejects the load. When runtime JIT is enabled,
  # startup also materializes every vision, audio, and projection session
  # declared by each preloaded model without running media inference.
  # Preload every model that must use runtime-JIT kernels; `required`
  # rejects an empty preload list.
  #
  kernel_jit:
    # Runtime kernel JIT operating mode. `off` disables compilation. `shadow`
    # compiles and validates without dispatching JIT kernels. `on` may activate
    # qualified kernels while preserving the production fallback. `required`
    # fails model loading when there are no eligible routes or any scoped
    # route cannot qualify, rejects sessions that are not direct Metal or
    # CUDA sessions, and requires at least one configured startup preload.
    # Backend preference remains separately configured; this mode neither
    # enables nor selects a backend. Runtime JIT is currently supported on
    # Linux and macOS; other platforms reject non-`off` modes rather than
    # silently degrading.
    #
    mode: off
    # Persistent artifact cache directory on Linux and macOS. Omit to use ~/.antfly/inference/jit when HOME is available.
    cache_dir: string
    # Persistent cache size limit in MiB. Set to 0 to disable disk persistence.
    max_cache_bytes_mb: 1024
    # Per direct model session pre-publication start budget for
    # best-effort `on` and `shadow` JIT work. A compiler or qualification
    # operation already started may overrun the budget. Multimodal model
    # preloads may create several direct sessions, each with this budget.
    # `required` completes or fails all required routes and may exceed
    # this value.
    #
    preload_budget_ms: 300000
  # Legacy compatibility field. The current Zig inference runtime selects a
  # backend from model metadata, explicit preload settings, and compiled capabilities;
  # configuring this list has no effect.
  #
  backend_priority:
    - string
  # Legacy Go-runtime queue setting. The current Zig runtime does not retain
  # excess inference requests in memory and ignores this field.
  #
  max_queue_size: 0
  # Legacy Go-runtime queue/request timeout. The current Zig runtime ignores
  # this field; its HTTP listener applies a separate fixed transport timeout.
  #
  request_timeout: string
  # Models to preload and warm at startup. Generators run a tiny generation
  # request so native/Metal weights, KV setup, and kernels use the same
  # budgeted path as request-time generation. Other model kinds use the
  # best available warm path for that kind. When runtime kernel JIT is
  # enabled, every vision, audio, and projection session declared by a
  # preloaded model is also loaded without running media inference.
  # Runtime kernel JIT `required` mode rejects an empty preload list.
  #
  preload:
    - {"kind":"generator","name":"antflydb/gemma-e2b","backend":"metal","format":"gguf","quantization":"q4_k"}
  # Legacy compatibility field. The current Zig runtime uses explicit host,
  # backend, combined, KV, and scratch budgets instead and ignores this field.
  #
  max_memory_mb: 0
  # Per-model loading strategy overrides. Maps model names to their loading strategy.
  # Models not in this map load on demand. keep_alive controls their idle
  # eviction; setting it to "0" disables idle eviction but does not preload or pin them.
  #
  # When a model has strategy "eager" in this map:
  # - It is loaded at startup through the same startup warmup path
  # - It is never unloaded, even when keep_alive>0 (pinned in memory)
  #
  # This allows mixing eager and lazy models in the same pool.
  #
  model_strategies:
    "BAAI/bge-small-en-v1.5": eager
    "mirth/chonky-mmbert-small-multilingual-1": lazy
  # Legacy compatibility field controlling whether dashboards show model
  # download commands. It defaults to true for standalone deployments;
  # managed deployments historically set it to false. Download-command
  # availability is a build-time setting in the current Zig runtime, so
  # configuring this field has no effect.
  #
  allow_downloads: true
  # Legacy inference-local logging field. The current unified Zig runtime
  # ignores it; configure the top-level `log` object instead.
  #
  log: null
# Unsupported by the built-in Zig server. Any non-null `tls` object causes
# startup to fail closed. Terminate TLS at a trusted reverse proxy or load balancer.
#
tls:
  # Legacy certificate path; rejected by the current Zig server.
  cert: /path/to/cert.pem
  # Legacy private-key path; rejected by the current Zig server.
  key: /path/to/key.pem
# Configuration for remote content fetching (`remoteMedia`, `remoteText`, and the deprecated
# `remotePDF` compatibility helper). Durable PDF ingestion uses a `document_extraction` asset producer.
# Consolidates S3 credentials and security settings separate from backup storage.
#
# **Credential Resolution Order:**
# 1. Explicit `credentials="name"` parameter in template
# 2. First credential where `buckets` glob pattern matches URL's bucket
# 3. `default_s3` credential
#
remote_content:
  # Low-level content download policy. In the generic scraper, omitted
  # `allowed_hosts` and `allowed_paths` fields do not restrict those sources;
  # explicit empty lists deny them. Consumers may merge this object over a
  # stricter baseline before downloading. Antfly inference does so: omitted
  # or empty inference policies, and omitted inference allowlists, deny
  # HTTP(S), file, and S3 content until explicit allowlists are configured.
  # Do not assume omission has identical policy semantics across consumers.
  #
  security:
    # Whitelist for HTTP(S) downloads. With block_private_ips enabled (the default), IP literals and every address resolved from an allowlisted DNS hostname must be globally routable; the connection is pinned to a vetted address. Set block_private_ips to false only to opt into private or special destinations. The generic scraper treats omission as unrestricted subject to that policy and an explicit empty list as deny-all; Antfly inference requires an explicit allowlist.
    allowed_hosts:
      - 93.184.216.34
    # Reject loopback, private, link-local, carrier-grade NAT, reserved, and multicast destinations. Allowlisted DNS hostnames are resolved, every result is filtered by this policy, and the connection is pinned to a vetted address. Set false only as an explicit opt-out that permits private and special destinations.
    block_private_ips: true
    # RFC 6052 network-specific NAT64 prefixes used by this deployment. Resolved IPv6 addresses under these prefixes are decoded and checked against the private IPv4 policy. Prefix length must be 32, 40, 48, 56, 64, or 96.
    nat64_prefixes:
      - "2001:db8:64::/96"
    # Maximum size of downloaded content in bytes
    max_download_size_bytes: 104857600
    # Maximum HTTP(S) and S3 download duration in seconds. Defaults to 30. Zero disables this configured ceiling, but a caller-supplied request deadline still applies. A deadline-bound file:// fetch fails closed because portable filesystem I/O does not expose a preemptive timeout.
    download_timeout_seconds: 30
    # Maximum source-image width or height enforced for accepted inference image inputs, including generate/chat, dense embed, multimodal rerank, `/read`, image `/extract`, and their embedded direct APIs. Images are rejected rather than resized. Batch generation rejects multimodal content before fetch; non-inference scraping consumers do not enforce this setting.
    max_image_dimension: 1
    # Whitelist of allowed path prefixes for file:// and s3:// URLs. The generic scraper treats omission as unrestricted and an explicit empty list as deny-all. Consumers may impose stricter defaults; Antfly inference requires explicit path allowlists. For file:// use absolute paths (e.g., /Users/data/). For s3:// use bucket/prefix (e.g., my-bucket/uploads/).
    allowed_paths:
      - /Users/data/
      - my-bucket/uploads/
    # User-Agent header for HTTP downloads. Defaults to 'AntflyDB/1.0' if not set. Some servers (e.g., Wikipedia) reject requests without a User-Agent.
    user_agent: AntflyDB/1.0
  # Default S3 credential name when no bucket pattern matches.
  default_s3: primary
  # Named S3 credentials for remote content fetching.
  s3:
    "primary":
      endpoint: s3.amazonaws.com
      access_key_id: "${secret:aws.key}"
      secret_access_key: "${secret:aws.secret}"
    "untrusted":
      endpoint: s3.amazonaws.com
      buckets:
        - user-uploads-*
        - public-*
      access_key_id: "${secret:uploads.key}"
      secret_access_key: "${secret:uploads.secret}"
      security:
        max_download_size_bytes: 10485760
  # Named HTTP credentials for authenticated endpoints.
  http:
    "internal-api":
      base_url: "https://docs.internal.com"
      headers:
        Authorization: "Bearer ${secret:token}"
# Public connection resources keyed by stable connection ID. These
# are the external systems Antfly can use for inference, external IO,
# CDC, backups, indexing, agents, and related workflows.
#
connections:
  "agent-web":
    kind: web_search
    provider: exa
    capabilities:
      - web.search
      - web.fetch
      - agents.use
    web_search:
      max_results: 10
      include_content: true
      api_key: "${secret:exa.api_key}"
# Named speech-to-text provider configurations.
#
# Define named STT providers that can be referenced by templates and API calls.
# The first provider defined becomes the default when no provider name is specified.
#
# **Example:**
# ```json
# {
#   "speech_to_text": {
#     "antfly-whisper": { "provider": "antfly", "api_url": "http://localhost:8080", "model": "openai/whisper-base" },
#     "openai-whisper": { "provider": "openai", "model": "whisper-1" }
#   }
# }
# ```
#
# Then in templates: `{{transcribeAudio url="..." provider="whisper-local"}}`
#
speech_to_text:
  "antfly-whisper":
    provider: antfly
    api_url: "http://localhost:8080"
    model: openai/whisper-base
  "openai-whisper":
    provider: openai
    model: whisper-1
cors:
  # Controls whether CORS is enabled
  enabled: true
  # List of allowed origins for CORS requests. Use ['*'] to allow all origins. Defaults to ['*'] if empty and enabled is true. Credentialed CORS rejects both '*' and the opaque 'null' origin.
  allowed_origins:
    - "https://example.com"
    - "https://app.example.com"
  # HTTP methods allowed for CORS requests
  allowed_methods:
    - GET
    - POST
    - PUT
    - DELETE
  # Headers that can be used in CORS requests. ['*'] allows any valid requested header; when credentials are enabled, the server reflects the validated requested header names because browsers treat '*' as a literal name in credentialed CORS.
  allowed_headers:
    - Content-Type
    - Authorization
  # Headers exposed to the client. Supplying this field replaces the defaults, so include `Deprecation` if browser clients must observe legacy API migration signals. ['*'] is rejected when credentials are enabled because browsers treat it as a literal header name.
  exposed_headers:
    - X-Total-Count
  # Indicates whether credentials (cookies, auth headers) are allowed. Note: If true, allowed_origins cannot be ['*'].
  allow_credentials: false
  # How long (in seconds) the results of a preflight request can be cached
  max_age: 3600
# How many replicas of each shard should be maintained.
replication_factor: 3
# Enables authentication for the unified API and authorization on routes with defined RBAC policies. Inference routes require a valid principal when enabled, but do not currently enforce per-model or per-operation inference RBAC.
enable_auth: false
# Disables automatic shard reallocation (splitting/merging).
disable_shard_alloc: true
# Cooldown period after shard operations (start/stop/split). Format: duration string like '1m', '30s'. Default: '1m' (one minute).
shard_cooldown_period: 1m
# Maximum duration for a shard split operation before triggering rollback. Format: duration string like '5m', '30s'. Default: '5m' (five minutes).
split_timeout: 5m
# Minimum continuous readiness duration required before finalizing a split. Format: duration string like '15s', '1m'. Default: '15s'.
split_finalize_grace_period: 15s
# Maximum size of a shard in bytes. Used to determine when to split shards.
max_shard_size_bytes: 1073741824
# Minimum size of a shard in bytes before it becomes eligible for automatic merge consideration. If unset, defaults to one quarter of max_shard_size_bytes.
min_shard_size_bytes: 268435456
# Minimum number of shards to keep for a table. Automatic merges will not reduce a table below this count.
min_shards_per_table: 1
# Maximum number of shards that can be created for a single table.
max_shards_per_table: 100
# Default number of shards to create for a new table.
default_shards_per_table: 4
# Runtime deployment topology. Standalone runs metadata, data, APIs, and inference in one process.
deployment_mode: distributed
# Named embedder configurations for embedding operations.
#
# Define named embedders that can be referenced by indexes, templates, and API calls.
# The first embedder defined becomes the default when no embedder name is specified.
#
# **API Key Configuration:**
#
# API keys can be provided through a protected secret-store file or environment variables:
#
# 1. **Secret store** (recommended for production): mount a platform-managed
#    secret file and pass `--secret-store-path /run/secrets/antfly/secrets.json`.
#    Reference its values in JSON config as
#    `"api_key": "${secret:openai.api_key}"`.
#
# 2. **Environment variable** (simpler for development):
#    Omit `api_key` from config and set the appropriate env var:
#    - OpenAI: `OPENAI_API_KEY`
#    - Gemini: `GEMINI_API_KEY`
#    - Anthropic: `ANTHROPIC_API_KEY`
#    - Cohere: `COHERE_API_KEY`
#
# See [Secrets Management](/docs/v0.1.1/secrets) for complete documentation.
#
# **Example:**
# ```json
# {
#   "embedders": {
#     "openai-small": { "provider": "openai", "model": "text-embedding-3-small" },
#     "antfly-local": { "provider": "antfly", "model": "bge-base-en-v1.5", "api_url": "http://localhost:8082" }
#   }
# }
# ```
#
embedders:
  "openai-small":
    provider: openai
    model: text-embedding-3-small
  "antfly-local":
    provider: antfly
    model: bge-base-en-v1.5
    api_url: "http://localhost:8082"
# Named generator configurations for AI operations.
#
# Define named generators that can be referenced by chains, templates, and API calls.
# The first generator defined becomes the default when no generator name is specified.
#
# **API Key Configuration:**
#
# API keys can be provided through a protected secret-store file or environment variables:
#
# 1. **Secret store** (recommended for production): mount a platform-managed
#    secret file and pass `--secret-store-path /run/secrets/antfly/secrets.json`.
#    Reference its values in JSON config as
#    `"api_key": "${secret:gemini.api_key}"`.
#
# 2. **Environment variable** (simpler for development):
#    Omit `api_key` from config and set the appropriate env var:
#    - Gemini: `GEMINI_API_KEY`
#    - OpenAI: `OPENAI_API_KEY`
#
# See [Secrets Management](/docs/v0.1.1/secrets) for complete documentation.
#
# **Example:**
# ```json
# {
#   "generators": {
#     "gemini-flash": { "provider": "gemini", "model": "gemini-2.5-flash" },
#     "ollama-local": { "provider": "ollama", "model": "llama3" },
#     "openai-gpt4": { "provider": "openai", "model": "gpt-4.1" }
#   }
# }
# ```
#
generators:
  "gemini-flash":
    provider: gemini
    model: gemini-2.5-flash
  "ollama-local":
    provider: ollama
    model: llama3
  "openai-gpt4":
    provider: openai
    model: gpt-4.1
# Named chain configurations for fallback/retry logic.
#
# Chains are ordered lists of generators with retry and fallback logic.
# Each link references a generator by name from the `generators` map.
# The first chain defined becomes the default when no chain name is specified.
#
# **Chain Conditions:**
# - `on_error`: Try next generator on any error (default)
# - `on_rate_limit`: Try next only on rate limit (429) errors
# - `on_timeout`: Try next only on timeout errors
# - `always`: Always try the next generator
#
# **Example:**
# ```json
# {
#   "chains": {
#     "default": [
#       { "generator": "gemini-flash", "retry": { "max_attempts": 3 }, "condition": "on_rate_limit" },
#       { "generator": "ollama-local" }
#     ],
#     "with-inline": [
#       { "generator": "gemini-flash" },
#       { "generator_config": { "provider": "openai", "model": "gpt-4.1" } }
#     ]
#   }
# }
# ```
#
# Then in API calls: `chain: "default"` or `chain: "with-inline"`
#
chains:
  "default": [{"generator":"gemini-flash","retry":{"max_attempts":3},"condition":"on_rate_limit"},{"generator":"ollama-local"}]
  "with-inline": [{"generator":"gemini-flash"},{"generator_config":{"provider":"openai","model":"gpt-4.1"}}]
# Named reranker configurations for search result reranking.
#
# Define named rerankers that can be referenced by indexes, search queries, and API calls.
# The first reranker defined becomes the default when no reranker name is specified.
#
# **Example:**
# ```json
# {
#   "rerankers": {
#     "cohere-english": { "provider": "cohere", "model": "rerank-english-v3.0" },
#     "antfly-local": { "provider": "antfly", "model": "mxbai-rerank-base-v1", "url": "http://localhost:8080" }
#   }
# }
# ```
#
rerankers:
  "cohere-english":
    provider: cohere
    model: rerank-english-v3.0
  "antfly-local":
    provider: antfly
    model: mxbai-rerank-base-v1
    url: "http://localhost:8080"
# Named chunker configurations for text chunking.
#
# Define named chunkers that can be referenced by indexes and API calls.
# The first chunker defined becomes the default when no chunker name is specified.
#
# **Example:**
# ```json
# {
#   "chunkers": {
#     "fixed-500": { "provider": "antfly", "model": "fixed", "target_tokens": 500, "overlap_tokens": 50 },
#     "semantic": { "provider": "antfly", "model": "semantic-chunker", "api_url": "http://localhost:8080" }
#   }
# }
# ```
#
chunkers:
  "fixed-500":
    provider: antfly
    model: fixed
    target_tokens: 500
    overlap_tokens: 50
  "semantic":
    provider: antfly
    model: semantic-chunker
    api_url: "http://localhost:8080"

Configuration Properties#

Core Settings#

Essential configuration for running Antfly

Storage Configuration#

Configure local and remote storage backends

StorageConfig Properties:

LocalStorageConfig Properties:

Metadata Configuration#

Metadata orchestration cluster settings

MetadataInfo Properties:

Shard Management#

Control automatic shard allocation and sizing

Security & CORS#

TLS and cross-origin settings

TLSInfo Properties:

CORSConfig Properties:

External Services#

Optional Antfly inference, remote content, and model-provider integration

Connections#

External systems Antfly can use for inference, web search, external IO, CDC, backups, indexing, and agents

ConnectionConfig Properties:

InferenceConnectionConfig Properties:

WebSearchConnectionConfig Properties:

ExternalIoConnectionConfig Properties:

CdcConnectionConfig Properties: