Configuration

Complete reference for every setting in ctx.toml.

--config selects one explicit configuration file. Without it, Context Harness checks CTX_CONFIG, then the workspace’s .ctx/config.toml or legacy config/ctx.toml, then the global configuration and built-in defaults. Explicit --config or CTX_CONFIG bypasses merging; discovered workspace configuration is merged over global defaults. See the configuration resolution contract.

The annotated configuration below is an example of available settings; it does not enable every feature by default.

Full reference

[db]
path = "./data/ctx.sqlite"            # SQLite database file path

[chunking]
max_tokens = 700                      # Max tokens per chunk (~4 chars/token)
overlap_tokens = 80                    # Overlap between consecutive chunks

[embedding]
provider = "disabled"                  # "disabled" | "openai" | "ollama" | "local"
# model = "text-embedding-3-small"    # Model name (required for openai/ollama)
# dims = 1536                         # Vector dimensions (required for openai/ollama)
# batch_size = 64                     # Texts per batch
# max_retries = 5                     # Retry count for transient failures
# timeout_secs = 30                   # Per-request timeout
# url = "http://localhost:11434"      # Ollama API base URL (ollama provider only)

Requirements and platform support for local embeddings

The local provider has no system dependencies; models are downloaded on first use. Primary platforms use fastembed (bundled ORT); Linux musl and macOS Intel use a pure-Rust (tract) backend.

Pre-built release binaries are built for six targets. Local embeddings are included on all targets:

Build features (from source): Default build uses local-embeddings-fastembed (fastembed with bundled ORT). For musl or Intel Mac use cargo build --no-default-features --features local-embeddings-tract. To omit local embeddings entirely use --no-default-features.

[retrieval]
final_limit = 12                       # Max results returned to caller
hybrid_alpha = 0.6                     # 0.0 = keyword only, 1.0 = semantic only
candidate_k_keyword = 80               # FTS5 candidates to fetch before re-ranking
candidate_k_vector = 80                # Vector candidates to fetch before re-ranking
group_by = "document"                  # Group chunks by parent document
doc_agg = "max"                        # Aggregation: use max chunk score
max_chunks_per_doc = 3                 # Max chunks per document in results

[vector_index]
backend = "auto"                       # zvec when available, SQLite fallback otherwise
path = "auto"                          # .ctx/data/vector-index/zvec beside the SQLite DB
metric = "cosine"
index = "hnsw"
fallback = "sqlite"

[server]
bind = "127.0.0.1:7331"               # HTTP server bind address

# ── Local agent model aliases ─────────────────────────────

[models.default]
provider = "openai"                    # built-in local runtime adapter
model = "gpt-5-mini"                   # use a model available to your account
api_key_env = "OPENAI_API_KEY"         # environment-variable name, never the key

# ── Connectors (all types are named instances) ───────────

[connectors.filesystem.local]
root = "./docs"
include_globs = ["**/*.md", "**/*.rs", "**/*.pdf", "**/*.docx"]
exclude_globs = ["**/target/**"]
max_extract_bytes = 50_000_000          # Skip binary files larger than this (bytes)

[connectors.git.platform]
url = "https://github.com/acme/platform.git"
branch = "main"
root = "docs/"
include_globs = ["**/*.md"]
shallow = true

[connectors.git.auth-service]
url = "https://github.com/acme/auth-service.git"
branch = "main"

[connectors.s3.runbooks]
bucket = "acme-docs"
prefix = "engineering/"
region = "us-east-1"

# ── Lua scripted connectors ───────────────────────────────

[connectors.script.jira]
path = "connectors/jira.lua"
timeout = 30
url = "https://mycompany.atlassian.net"
project = "ENG"
api_token = "${JIRA_API_TOKEN}"        # ${VAR} expands env vars

# ── Lua scripted tools ────────────────────────────────────

[tools.script.create_jira_ticket]
path = "tools/create-jira-ticket.lua"
timeout = 30
jira_url = "https://mycompany.atlassian.net"
jira_project = "ENG"
jira_token = "${JIRA_API_TOKEN}"

# ── Inline profiles (static prompts) ────────────

[profiles.inline.code-reviewer]
description = "Reviews code changes against project conventions"
tools = ["search", "get"]
system_prompt = """
You are a senior code reviewer. Use search to find coding conventions.
Be specific — cite which convention a suggestion relates to.
"""

[profiles.inline.architect]
description = "Answers architecture questions using indexed docs"
tools = ["search", "get", "sources"]
system_prompt = """
You are a software architect. Search for ADRs and design documents.
When recommending changes, explain tradeoffs and cite sources.
"""

# ── Lua scripted profiles (dynamic prompts) ──────

[profiles.script.incident-responder]
path = "profiles/incident-responder.lua"
timeout = 30
search_limit = 5

# ── Extension registries ─────────────────────────────────

[registries.community]
url = "https://github.com/parallax-labs/ctx-registry.git"
branch = "main"
path = "~/.ctx/registries/community"
readonly = true                        # Don't write to this registry
auto_update = true                     # Pull on startup

Local agent generation with Ollama

[models.local]
provider = "ollama"
model = "qwen3" # Example ID; use a compatible model already installed locally.
base_url = "http://127.0.0.1:11434"
timeout_seconds = 120

Set an agent’s model field to "local" to select this alias. Run the Ollama service and provision a compatible model separately. This generation adapter requires a literal loopback HTTP address; localhost and remote hosts are not accepted. It does not download models or fall back to a cloud provider. Generation configuration under [models.*] is separate from retrieval embeddings under [embedding]. Model suitability for a task still needs to be evaluated. See the complete native adapter contract.

Standalone local resources

Standalone local agents and declarative tool bindings live beside the effective config rather than inside it:

.ctx/
├── config.toml
├── agents/
│   └── project-researcher.toml
└── tools/
    ├── project-search.toml
    └── project-get.toml

When --config or CTX_CONFIG selects a config, only its sibling agents and tools directories are used. Otherwise Context Harness layers the global config directory below the current workspace’s .ctx directories. Workspace collisions require explicit whole-resource overrides; individual fields are never merged.

Agent resources select a model alias from [models.*], execution limits, permissions, a system prompt, and public tool names. Tool resources select a trusted implementation, fixed arguments, and enforceable restrictions. See Build Local Agents for complete schemas and a runnable example.

Environment variable expansion

String values in [connectors.script.*] and [tools.script.*] configs support ${VAR_NAME} expansion. This keeps secrets out of your config file:

[connectors.script.slack]
path = "connectors/slack.lua"
token = "${SLACK_BOT_TOKEN}"           # Expanded at runtime
workspace = "acme"                      # Plain string, no expansion

Section reference

The deprecated [agents.inline.*] and [agents.script.*] spellings are still accepted as aliases for existing configurations.