Configuration

All configuration lives in ~/.sigil/config.json, chmod 600. Edit it through the dashboard (Settings) rather than by hand — the wizard validates and live-tests what it writes.

How the file works

• Sparse on disk. Only explicitly-set values are written. Defaults live in code and merge at read time, so defaults track the code instead of freezing into a stale file.
• Versioned. schemaVersion plus ordered migrations run on load. Unknown keys are dropped.
• Atomic. Written temp-then-rename, chmod 600.
• Live. The daemon’s in-memory cache updates on every patch, so most changes apply without a restart. The ones that don’t are marked below.

This replaced ~/.sigil/.env

An earlier design used a .env file. It was replaced because a stale env file broke upgrades, and because a stray global like LLM_PROVIDER=openai could silently override what onboarding saved. No environment variable is consulted for configuration any more.

---

database

Key	Default
mode	null	embedded · local · docker · url
url	null	Connection string. Takes precedence when set.
host	localhost
port	5432
name	sigil
user	sigil_app
password	null

Recognized providers — Neon, Supabase, RDS, Render, Railway, CockroachDB — get sensible SSL defaults automatically. Override with ?sslmode=… in the URL.

embedded runs PGlite in-process against ~/.sigil/db. Zero install, single machine only.

---

llm

Key	Default
provider	null	openrouter · openai · anthropic · ollama · claude-cli · codex
model	provider default
apiKey	null	Stored per chosen provider
host	null	Ollama host — defaults to http://localhost:11434
maxRetries	3
requestTimeout	60000	HTTP timeout (ms) for network providers
cliTimeout	120000	Timeout (ms) for CLI providers and local Ollama generation
maxClaudeProcs	4	Hard ceiling on concurrent claude processes
cliPath	''	Explicit path to the claude binary
codexPath	''	Explicit path to codex
codexExtraArgs	[]	e.g. ['-c', 'model_reasoning_effort="low"']

Per-task model overrides

Key	Called
extractionModel	Per chunk — high volume, cheap model
decisionModel	Per AUDM decision — judgement, worth a smarter model
entityModel	Entity extraction

Use provider:model syntax:

extractionModel = openrouter:qwen/qwen3.5-flash
decisionModel   = openrouter:anthropic/claude-sonnet-latest

Extraction is volume work; AUDM is judgement work. Splitting them is the highest-leverage tuning in Sigil. See Deduplication.

maxClaudeProcs

The cap exists because an unbounded ingest fan-out once produced 1600+ live claude sessions, pinning RAM and tokens. Every spawn routes through one semaphore, so excess calls queue rather than fork. Default 4 keeps throughput while making that failure impossible.

---

llm.managedSession

Warm claude CLI workers in tmux, amortizing agentic cold-start across many ingest calls. Opt-in — when disabled the provider transparently uses the one-shot path, so nothing breaks. Only meaningful on a host with both tmux and the claude CLI. All keys need a daemon restart.

Key	Default
enabled	false
poolSize	1	Workers per source type. 1 = strictly serial.
tokenBudget	60000	Recycle a worker after ~this many tokens — caps context bleed and memory creep
taskTimeoutMs	120000	Dead-man timeout per task → one-shot fallback + recycle
firstTaskTimeoutMs	45000	Boot handshake window. Must clear a cold claude TUI render (~10s) plus one agent turn.
healthProbeMs	15000	How often busy workers are swept for a wedged interactive dialog
clearBetweenTasks	true	/clear between tasks

---

embedding

Key	Default
provider	null	openai · voyage · openrouter · ollama
model	mxbai-embed-large
apiKey	null
host	null	Ollama host

Dimension is not configurable. Every embedding is 1024 dimensions, pinned in code and in the schema so the two can never drift. A model that can’t emit or truncate to 1024 is rejected at setup.

Changing provider invalidates existing vectors. Sigil reports how many rows are affected and makes you choose.

---

memory

AUDM thresholds and search floors. All in Settings → Advanced.

Key	Default
skipThreshold	0.88	Above this similarity, skip as a duplicate
ambiguousThreshold	0.78	Above this, hand the decision to the LLM
supersedeThreshold	0.72	Floor for considering a supersession
supersedeScanLimit	8	Existing candidates compared against
minFactSimilarity	0.45	Search relevance floor — below this, results are dropped
injectionFloor	0.6	Automatic injection floor. Higher than the search floor, deliberately.

These fail quietly

A wrong value here degrades recall rather than throwing an error. Change one at a time and check a week later with sigil facts —limit=100. See Deduplication → Tuning.

---

search

Key	Default
synthesize	true	Have an LLM write an answer from retrieved facts
synthesizeModel	''	Provider default when empty

---

ingest

Key	Default
eagerExtract	true	Extract facts at write time
extractRelations	false	Discover graph relations during ingest. Off — a coalesced background job handles cross-document edges more cheaply.
graphGleanRounds	0	Extra passes per chunk hunting for missed entities. Each round is another LLM call per chunk.
workerConcurrency	2	Background workers (restart required)
maxJobAttempts	3	Retries before a job is failed

---

hebbian.entity

Co-retrieval edge behaviour at the entity layer. See Ranking.

Key	Default
enabled	true
eta	1	How much one co-retrieval strengthens an edge
halfLifeDays	30	Edges decay; unused associations fade
cap	50	Strength ceiling
minEffective	0.5	Below this, an edge is ignored
rrfWeight	0.3	Influence on ranking
maxWriteEntities	12	Entities strengthened per search — bounds the O(n²)
expandPerSeed	3	Expansion breadth per seed

---

defaults

Key	Default
namespace	default	Where this install writes. Always exactly one.
searchNamespaces	[]	Where this install reads. Empty means “just my own”; * means everything.

searchNamespaces exists for one case: two installs sharing a database under different namespaces that should still see each other.

---

http

Key	Default
enabled	true	(restart required)
host	127.0.0.1	Loopback by default. Changing this exposes the dashboard and MCP HTTP transport to your network. (restart)
port	7777	(restart)

---

network

Key	Default
mode	solo	solo · master · follower · lite-follower
enabled	false
masterNodeId	null	Set by sigil join

---

identity and preferences

Key	Default
identity.name	null	Your name — used in prompts and stored as your first memory
preferences.noUpdateCheck	false	Skip the periodic update check

---

output

Artifact storage for exports and generated files.

Key	Default
storage	local	local · s3
dir	./output
s3.endpoint · s3.bucket · s3.region · s3.accessKey · s3.secretKey · s3.publicUrl		S3-compatible target

---

Environment variables

Only bootstrap, runtime, and process-identity values remain:

Variable	Purpose
HOME	Locates config.json itself
SIGIL_PGLITE_PATH	Redirect the embedded database path (tests, launch)
SIGIL_BRANCH	Release-lane selector, set by install.sh
SIGIL_DEBUG	Verbose diagnostics
SIGIL_AGENT · SIGIL_WORKER_ID · SIGIL_SOURCE · SIGIL_DAEMON_PROCESS · SIGIL_SUPERVISED	Per-process identity and IPC — set by Sigil

Per-invocation CLI flags still override transiently. Those are explicit one-shot intent, not a file.

---

Inspecting and validating

sigil doctor          # includes config validation — catches provider/model mismatches
cat ~/.sigil/config.json

The file is sparse, so anything you don’t see is at its code default. That’s expected, not a missing key.