Configuration

Hanflow is configured through hanflow.yaml. Configuration is resolved with this priority: HANFLOW_* environment variables > explicit dict > ./hanflow.yaml

~/.hanflow/config.yaml > defaults. ${VAR} placeholders are expanded from the environment.

Top-level keys

Key	Purpose
workspace_root	Base directory for runtime workspaces
models	Named model references used by routing
routing	Default model, roles, tasks, fallback, budget, privacy
mcp_servers	MCP tool servers (stdio / sse / http / websocket / inprocess)
search embeddings rerankers	RAG retrieval providers
memory skills	Long-term memory and skill registries
persistence	Checkpoint, session, and artifact stores
observability	Tracing and metrics backends
workflows	Workflow storage (file) and root directory
server	Host, port, and inline worker toggle

Models

Each model entry is a ModelRef with provider, model, api_key, and an optional base_url.

models:
  strong:
    provider: openai
    model: gpt-4o
    api_key: "${OPENAI_KEY}"
  local:
    provider: ollama
    model: llama3
    base_url: http://localhost:11434

Providers: openai, anthropic, glm (ZhipuAI), deepseek, ollama, vllm. Ollama and vLLM are flagged is_local: true so privacy routing can target them.

Routing

routing:
  default: strong
  fallback_chain: [strong, fast]
  budget:
    daily_usd: 50
  privacy:
    enforce: hard
    local_providers: [local]

Strategies run in priority order privacy > role > task > cost > static. Privacy candidates are a hard veto: when sensitivity is confidential or higher, or PII is detected, only local providers are eligible.

Persistence

persistence:
  checkpoint: { backend: sqlite, config: { path: ./data/checkpoints.db } }
  session:    { backend: sqlite, config: { path: ./data/sessions.db } }
  artifact:   { backend: local_fs, config: { root: ./workspace/artifacts } }

Three stores: checkpoint (resume), session (state), and artifact (outputs). Backends in 1.0.1 are SQLite and local filesystem.

MCP tool servers

mcp_servers:
  web_search: { transport: inprocess }
  filesystem:
    transport: stdio
    command: node
    args: ["./mcp/fs-server.js"]

Five transports are supported: stdio, sse, http, websocket, inprocess.