axon.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "axon.schema.json",
  "title": "axon.json",
  "description": "Non-secret configuration for Axon workers and web frontend. Secrets and credentials belong in .env only.",
  "type": "object",
  "additionalProperties": true,
  "properties": {
    "services": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "qdrant_url":        { "type": "string", "description": "Qdrant HTTP endpoint" },
        "tei_url":           { "type": "string", "description": "TEI embeddings HTTP endpoint" },
        "chrome_remote_url": { "type": "string", "description": "Chrome management API endpoint" },
        "chrome_url":        { "type": "string", "description": "Chrome CDP endpoint (alias)" },
        "neo4j_url":         { "type": "string", "description": "Neo4j HTTP endpoint (empty = disabled)" },
        "neo4j_user":        { "type": "string", "description": "Neo4j username" },
        "backend_url":       { "type": "string", "description": "axon-workers HTTP endpoint (used by Next.js)" },
        "workers_ws_url":    { "type": "string", "description": "axon-workers WebSocket endpoint" },
        "backend_hostname":  { "type": "string", "description": "Override Host header for backend proxy" }
      }
    },
    "llm": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "base_url": { "type": "string", "description": "OpenAI-compatible LLM base URL" },
        "model":    { "type": "string", "description": "Default LLM model name" }
      }
    },
    "tei": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "max_retries":             { "type": "integer", "minimum": 0, "description": "Retries on TEI errors (429/5xx)" },
        "request_timeout_ms":      { "type": "integer", "minimum": 0, "description": "Per-request timeout in milliseconds" },
        "max_client_batch_size":   { "type": "integer", "minimum": 1, "description": "Max embedding batch size sent to TEI" },
        "http_port":               { "type": "integer", "minimum": 1, "maximum": 65535, "description": "TEI HTTP port" },
        "embedding_model":         { "type": "string", "description": "HuggingFace model ID for TEI" },
        "max_concurrent_requests": { "type": "integer", "minimum": 1, "description": "TEI server concurrency limit" },
        "max_batch_tokens":        { "type": "integer", "minimum": 1, "description": "Max tokens per TEI batch" },
        "max_batch_requests":      { "type": "integer", "minimum": 1, "description": "Max requests per TEI batch" },
        "pooling":                 { "type": "string", "description": "TEI pooling strategy (e.g. last-token, mean)" },
        "tokenization_workers":    { "type": "integer", "minimum": 1, "description": "Tokenization thread count" }
      }
    },
    "search": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "hybrid_enabled":      { "type": "boolean", "description": "Enable RRF hybrid search (dense + BM42)" },
        "hybrid_candidates":   { "type": "integer", "minimum": 1, "description": "Candidate pool size for hybrid search" },
        "ask_hybrid_candidates": { "type": "integer", "minimum": 1, "description": "Candidate pool size for ask hybrid search" },
        "hnsw_ef":             { "type": "integer", "minimum": 1, "description": "HNSW ef parameter (named-mode collections)" },
        "hnsw_ef_legacy":      { "type": "integer", "minimum": 1, "description": "HNSW ef parameter (legacy unnamed collections)" }
      }
    },
    "ask": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "max_context_chars":         { "type": "integer", "minimum": 1, "description": "Max characters of context passed to LLM" },
        "candidate_limit":           { "type": "integer", "minimum": 1, "description": "Max Qdrant candidates retrieved before reranking" },
        "chunk_limit":               { "type": "integer", "minimum": 1, "description": "Max chunks included in LLM context" },
        "full_docs":                 { "type": "integer", "minimum": 0, "description": "Number of top-scoring documents to fetch in full" },
        "backfill_chunks":           { "type": "integer", "minimum": 0, "description": "Extra chunks backfilled from top docs" },
        "doc_fetch_concurrency":     { "type": "integer", "minimum": 1, "description": "Concurrent full-document fetches" },
        "doc_chunk_limit":           { "type": "integer", "minimum": 1, "description": "Max chunks per full-document fetch" },
        "min_relevance_score":       { "type": "number", "minimum": 0, "maximum": 1, "description": "Minimum score threshold for including a chunk" },
        "authoritative_domains":     { "type": "array", "items": { "type": "string" }, "description": "Domains that receive a relevance boost" },
        "authoritative_boost":       { "type": "number", "minimum": 0, "description": "Score boost applied to authoritative domains" },
        "authoritative_allowlist":   { "type": "array", "items": { "type": "string" }, "description": "Allowlist for authoritative domain matching" },
        "min_citations_nontrivial":  { "type": "integer", "minimum": 0, "description": "Min citations required before answer is considered non-trivial" }
      }
    },
    "embed": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "collection":        { "type": "string", "description": "Default Qdrant collection name" },
        "doc_concurrency":   { "type": ["integer", "null"], "minimum": 1, "description": "Concurrent document embed jobs (null = CPU count)" },
        "doc_timeout_secs":  { "type": "integer", "minimum": 1, "description": "Per-document embed timeout in seconds" },
        "strict_predelete":  { "type": "boolean", "description": "Delete existing points before re-embedding a URL" }
      }
    },
    "queues": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "crawl":   { "type": "string", "description": "AMQP queue name for crawl jobs" },
        "extract": { "type": "string", "description": "AMQP queue name for extract jobs" },
        "embed":   { "type": "string", "description": "AMQP queue name for embed jobs" },
        "ingest":  { "type": "string", "description": "AMQP queue name for ingest jobs" },
        "refresh": { "type": "string", "description": "AMQP queue name for refresh jobs" },
        "graph":   { "type": "string", "description": "AMQP queue name for graph jobs" }
      }
    },
    "workers": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "ingest_lanes":              { "type": "integer", "minimum": 1, "description": "Parallel ingest worker lanes" },
        "max_pending_crawl_jobs":    { "type": "integer", "minimum": 0, "description": "Max pending crawl jobs (0 = unlimited)" },
        "crawl_size_warn_threshold": { "type": "integer", "minimum": 0, "description": "Warn when uncapped crawl exceeds this page count (0 = disabled)" },
        "job_stale_timeout_secs":    { "type": "integer", "minimum": 1, "description": "Seconds before a running job is considered stale" },
        "job_stale_confirm_secs":    { "type": "integer", "minimum": 1, "description": "Grace period after stale timeout before reclaim" },
        "pg_pool_size":              { "type": ["integer", "null"], "minimum": 1, "description": "Postgres connection pool size (null = default)" },
        "max_ws_connections":        { "type": ["integer", "null"], "minimum": 1, "description": "Max concurrent WebSocket connections (null = unlimited)" },
        "max_shell_connections":     { "type": ["integer", "null"], "minimum": 1, "description": "Max concurrent shell WebSocket connections (null = unlimited)" },
        "max_sync_concurrent":       { "type": ["integer", "null"], "minimum": 1, "description": "Max concurrent synchronous operations (null = default)" }
      }
    },
    "graph": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "concurrency":          { "type": "integer", "minimum": 1, "description": "Graph extraction concurrency" },
        "llm_model":            { "type": "string", "description": "LLM model for graph entity/relation extraction" },
        "similarity_threshold": { "type": "number", "minimum": 0, "maximum": 1, "description": "Minimum cosine similarity for graph edges" },
        "similarity_limit":     { "type": "integer", "minimum": 1, "description": "Max similar nodes to consider per entity" },
        "context_max_chars":    { "type": "integer", "minimum": 1, "description": "Max chars of context passed per graph extraction call" },
        "taxonomy_path":        { "type": "string", "description": "Path to custom entity taxonomy JSON file (empty = built-in)" }
      }
    },
    "acp": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "adapter_cmd":             { "type": "string", "description": "ACP adapter executable (e.g. claude, codex, gemini)" },
        "adapter_args":            { "type": "string", "description": "Extra args passed to the ACP adapter" },
        "prewarm":                 { "type": "boolean", "description": "Pre-warm ACP sessions on worker startup" },
        "auto_approve":            { "type": "boolean", "description": "Auto-approve ACP tool calls without user confirmation" },
        "max_concurrent_sessions": { "type": "integer", "minimum": 1, "description": "Max simultaneous ACP sessions" },
        "turn_timeout_ms":         { "type": "integer", "minimum": 1, "description": "Per-turn timeout in milliseconds" },
        "allowed_claude_betas":    { "type": "string", "description": "Comma-separated Claude beta features to enable" },
        "agents": {
          "type": "object",
          "additionalProperties": true,
          "description": "Per-agent cmd/args overrides",
          "properties": {
            "claude": {
              "type": "object",
              "additionalProperties": true,
              "properties": {
                "cmd":  { "type": "string" },
                "args": { "type": "string" }
              }
            },
            "codex": {
              "type": "object",
              "additionalProperties": true,
              "properties": {
                "cmd":  { "type": "string" },
                "args": { "type": "string" }
              }
            },
            "gemini": {
              "type": "object",
              "additionalProperties": true,
              "properties": {
                "cmd":  { "type": "string" },
                "args": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "web": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "allowed_origins":            { "type": "array", "items": { "type": "string" }, "description": "CORS allowed origins for the web API" },
        "allow_insecure_dev":         { "type": "boolean", "description": "Disable TLS/auth checks for local development" },
        "allow_query_token":          { "type": "boolean", "description": "Allow API token via ?token= query param (WS requires this)" },
        "trust_proxy":                { "type": "boolean", "description": "Trust X-Forwarded-For / X-Real-IP headers" },
        "pulse_chat_timeout_ms":      { "type": "integer", "minimum": 1, "description": "Idle timeout for Pulse chat sessions in milliseconds" },
        "shell_allowed_origins":      { "type": "array", "items": { "type": "string" }, "description": "CORS allowed origins for the shell WebSocket" },
        "shell_server_host":          { "type": "string", "description": "Bind host for the shell WebSocket server" },
        "shell_server_port":          { "type": ["integer", "null"], "minimum": 1, "maximum": 65535, "description": "Bind port for the shell WebSocket server (null = disabled)" },
        "docker_socket_path":         { "type": "string", "description": "Path to Docker socket for container stats (empty = disabled)" },
        "enable_docker_socket_logs":  { "type": "boolean", "description": "Stream Docker container logs via WebSocket" }
      }
    },
    "mcp": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "transport":               { "type": "string", "enum": ["http", "stdio"], "description": "MCP transport mode" },
        "http_host":               { "type": "string", "description": "MCP HTTP server bind host" },
        "http_port":               { "type": "integer", "minimum": 1, "maximum": 65535, "description": "MCP HTTP server port" },
        "artifact_dir":            { "type": "string", "description": "Directory for MCP artifact output files (empty = temp dir)" },
        "inline_bytes_threshold":  { "type": "integer", "minimum": 0, "description": "Artifact size below which content is inlined in the response" }
      }
    },
    "serve": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "host": { "type": "string", "description": "axon serve bind host (empty = 0.0.0.0)" },
        "port": { "type": "integer", "minimum": 1, "maximum": 65535, "description": "axon serve bind port" }
      }
    },
    "chrome": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "diagnostics":            { "type": "boolean", "description": "Enable Chrome diagnostics output" },
        "diagnostics_dir":        { "type": "string", "description": "Directory for Chrome diagnostic files" },
        "diagnostics_events":     { "type": "boolean", "description": "Log Chrome CDP events to diagnostics" },
        "diagnostics_screenshot": { "type": "boolean", "description": "Save screenshot on Chrome error" },
        "proxy":                  { "type": "string", "description": "HTTP proxy for Chrome requests (empty = none)" },
        "user_agent":             { "type": "string", "description": "Custom User-Agent string for Chrome (empty = default)" }
      }
    },
    "logging": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "file":       { "type": "string", "description": "Log file path (empty = stderr only)" },
        "max_bytes":  { "type": "integer", "minimum": 1, "description": "Max log file size in bytes before rotation" },
        "max_files":  { "type": "integer", "minimum": 1, "description": "Max rotated log files to keep" },
        "no_color":   { "type": "boolean", "description": "Disable ANSI color codes in log output" }
      }
    },
    "output": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "dir":                           { "type": "string", "description": "Default output directory for saved files" },
        "extract_est_cost_per_1k_tokens": { "type": ["number", "null"], "minimum": 0, "description": "Estimated LLM cost per 1k tokens for extract cost reporting (null = disabled)" }
      }
    },
    "ingest": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "github_max_issues":   { "type": "integer", "minimum": 0, "description": "Max GitHub issues to ingest per repo" },
        "github_max_prs":      { "type": "integer", "minimum": 0, "description": "Max GitHub PRs to ingest per repo" },
        "download_max_bytes":  { "type": ["integer", "null"], "minimum": 1, "description": "Max bytes per downloaded file (null = unlimited)" },
        "download_max_files":  { "type": ["integer", "null"], "minimum": 1, "description": "Max files per ingest job (null = unlimited)" },
        "domains_detailed":    { "type": "boolean", "description": "Enable detailed per-URL stats in domains output (slow on large collections)" },
        "domains_facet_limit": { "type": ["integer", "null"], "minimum": 1, "description": "Max domain facets returned (null = 100k default)" }
      }
    },
    "oauth": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "auth_url":        { "type": "string", "description": "OAuth2 authorization endpoint URL" },
        "token_url":       { "type": "string", "description": "OAuth2 token endpoint URL" },
        "redirect_uri":    { "type": "string", "description": "OAuth2 redirect URI" },
        "redirect_host":   { "type": "string", "description": "Redirect host override" },
        "redirect_path":   { "type": "string", "description": "Redirect path override" },
        "redirect_policy": { "type": "string", "description": "Redirect policy (e.g. strict)" },
        "scopes":          { "type": "string", "description": "Space-separated OAuth2 scopes to request" },
        "required_scopes": { "type": "string", "description": "Space-separated scopes required for access" },
        "redis_prefix":    { "type": "string", "description": "Redis key prefix for OAuth session storage" },
        "broker_issuer":   { "type": "string", "description": "Token broker issuer URL for validation" }
      }
    }
  }
}