Rabbithole

Configuration

Rabbithole can be configured via command-line flags or a TOML configuration file. Command-line flags always take precedence over values set in the config file. The config file is optional; Rabbithole will run with defaults if none is provided.

The source of truth is always the binary. Run rabbithole --help to see the current list of flags and their defaults.

CLI Reference

TOML Configuration File

All CLI flags (except --config itself) may be expressed in a TOML file. Keys use the long flag name without the leading dashes, with hyphens replaced by underscores.

Full example: rabbithole.toml

# Rabbithole configuration file
# All fields are optional; shown values are defaults unless marked.

# Path to the seed prompt file (required if not passed on CLI)
seed = "seed.txt"

# TCP port to listen on
port = 8080

# SQLite database path (created if missing)
db = "rabbithole.db"

# LLM model name (required)
model = "claude-sonnet-4-5"

# API key — prefer environment variables instead of hardcoding here
# api_key = "sk-..."

# Maximum crawl depth from the seed page (0 = seed page only)
depth = 5

# Enable web search and web fetch tools
web_tools = false

# Override the built-in system prompt (path to a .txt file)
# system_prompt = "my_system_prompt.txt"

Environment Variables

Depth Limit (--depth)

Every URL in Rabbithole has an associated depth: the seed page (/) is at depth 0. Links generated by the seed page are at depth 1. Links generated by depth-1 pages are at depth 2, and so on.

The --depth flag sets a ceiling. When a page is being generated and its depth equals or exceeds the limit:

• The page itself is still generated and served normally. The depth limit does not prevent a URL from being visited by a human browser.
• The ---MAPPINGS--- block produced by the LLM for that page is ignored. No new URLs are registered from it. This means that any <a href="..."> links pointing to local paths on that page will return a 404 if followed, because no prompt was ever stored for them.

This prevents unbounded, infinite graph growth. Without a depth limit, a sufficiently creative LLM could generate links indefinitely, consuming API credits and disk space.

Choosing a depth value

Cache Invalidation

Generated pages are cached permanently in the SQLite database. Once a URL has been generated and stored, Rabbithole will always serve the cached version without calling the LLM again. There is currently no automatic TTL or expiry mechanism.

To invalidate cached content, you have two options:

Option 1 — Delete the entire database

This clears all cached pages and all URL-to-prompt mappings. The next request to any URL will regenerate from scratch, beginning with the seed.

rm rabbithole.db

Option 2 — Delete a specific row

Use the SQLite CLI (or any SQLite client) to remove a single cached page. Rabbithole will regenerate it on next request, using the stored prompt.

sqlite3 rabbithole.db

-- See what's cached:
SELECT url, length(html), created_at FROM pages ORDER BY created_at DESC;

-- Delete a single page so it will be regenerated:
DELETE FROM pages WHERE url = '/some-page.html';

-- Remove a URL from the mapping entirely
-- (prevents it from being served or re-registered):
DELETE FROM mappings WHERE url = '/some-page.html';

.quit

Example CLI Invocations

Minimal (required flags only)

rabbithole --seed seed.txt --model gpt-4o

Custom port and database path

rabbithole \
  --seed seed.txt \
  --model claude-sonnet-4-5 \
  --port 3000 \
  --db /var/lib/rabbithole/site.db

With web tools enabled and increased depth

rabbithole \
  --seed seed.txt \
  --model gpt-4o \
  --depth 8 \
  --web-tools

Using a config file with an API key override

ANTHROPIC_API_KEY=sk-ant-... rabbithole --config rabbithole.toml

Using a TOML config file, overriding port on CLI

rabbithole --config rabbithole.toml --port 9000

Verbose logging for debugging

RUST_LOG=rabbithole=debug rabbithole --seed seed.txt --model gpt-4o

Precedence Order

When the same option is set in multiple places, Rabbithole resolves it in this order (highest wins):

1. Command-line flag
2. TOML config file value
3. Environment variable (for API keys)
4. Built-in default

See Also

• Getting Started — install and run your first site
• Architecture — how pages, mappings, and the cache work internally
• Web Tools — details on the web search and fetch tool integration
• Deployment — running Rabbithole behind nginx, with systemd, or in Docker
• Examples — sample seed prompts and the sites they produce
• GitHub: ajbt200128/rabbithole — source code and issue tracker