Configuration Reference

Complete reference for all CLI flags and environment variables accepted by the rabbithole binary. Source: github.com/ajbt200128/rabbithole. Live demo: isarabbithole.com.

Quick Start

# Minimum viable invocation
export ANTHROPIC_API_KEY="sk-ant-..."
rabbithole --seed "A wiki about the Rust programming language"

# With a file-based seed and budget cap
rabbithole --seed-file ./seed.txt --max-cost 2.00 --db ./site.db

# Full example
rabbithole \
  --seed-file ./prompts/seed.txt \
  --port 3000 \
  --model claude-haiku-4-5 \
  --max-tokens 8192 \
  --depth-limit 4 \
  --db ./rabbithole.sqlite \
  --max-cost 5.00 \
  --four-oh-four ./static/404.html

CLI Flags

All flags are parsed by clap. Run rabbithole --help for a summary.

Environment Variables

These variables are read at startup. CLI flags take precedence over environment variables where both apply.

Setting Environment Variables

# Shell (temporary, current session)
export ANTHROPIC_API_KEY="sk-ant-api03-..."
export RABBITHOLE_MAX_COST="3.00"
export RABBITHOLE_DEPTH_LIMIT="4"
rabbithole --seed "A recipe site"

# Using a .env file (with a tool like direnv or dotenv)
# .env
ANTHROPIC_API_KEY=sk-ant-api03-...
RABBITHOLE_MAX_COST=3.00
RABBITHOLE_DEPTH_LIMIT=4

# Docker / docker-compose
environment:
  - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
  - RABBITHOLE_MAX_COST=10.00
  - RABBITHOLE_DEPTH_LIMIT=5

Model Pricing

Rabbithole calls the Anthropic Messages API on each uncached page request. Each page generation costs approximately 1,000–4,000 input tokens (system prompt + mappings context) plus up to --max-tokens output tokens. Choose your model based on cost tolerance and quality requirements.

Estimating Cost Per Page

# Rough cost model (Sonnet 4.5, default settings):
#
#   Input:  ~2,000 tokens  (system prompt + context)  @ $3.00/MTok  = $0.000006
#   Output: ~8,192 tokens  (full HTML page)            @ $15.00/MTok = $0.000123
#   Total per page:  ~$0.000129  (~$0.13 per 1,000 pages)
#
# With Haiku 4.5:
#   Input:  ~2,000 tokens                              @ $1.00/MTok  = $0.000002
#   Output: ~8,192 tokens                              @ $5.00/MTok  = $0.000041
#   Total per page:  ~$0.000043  (~$0.043 per 1,000 pages)
#
# --max-cost 1.00 buys roughly:
#   Sonnet 4.5:  ~7,750 uncached pages
#   Haiku 4.5:   ~23,200 uncached pages

Persistence and the SQLite Database

When --db is provided, Rabbithole stores all generated pages and their URL-to-prompt mappings in a SQLite file. On subsequent startups with the same --db path, previously generated pages are served from the database without any API calls — so cached pages are effectively free.

The database also stores the accumulated cost counter used by --max-cost. If you hit the cost cap and want to continue generating new pages, you can either raise --max-cost or clear the cost counter manually.

# Inspect the database with sqlite3:
sqlite3 ./rabbithole.sqlite ".tables"
# pages   mappings   meta

sqlite3 ./rabbithole.sqlite "SELECT url, length(html) FROM pages ORDER BY rowid DESC LIMIT 10;"
sqlite3 ./rabbithole.sqlite "SELECT value FROM meta WHERE key='total_cost';"

Depth Limit Behavior

The --depth-limit flag controls how deep the link graph can grow. Depth is tracked per URL in the mapping:

• The seed/homepage is depth 0.
• Pages linked from the homepage are depth 1.
• Pages linked from depth-1 pages are depth 2, and so on.
• At the configured limit, pages are generated normally but their ---MAPPINGS--- output is ignored — no new child pages are registered, preventing further graph growth.
• Pages are never regenerated once cached, regardless of depth.

# Example: prevent any sub-pages (homepage only)
rabbithole --seed "A single-page site" --depth-limit 0

# Example: allow two levels deep from homepage
rabbithole --seed-file seed.txt --depth-limit 2

Custom 404 Page

By default, budget-exceeded and unknown-path requests return a minimal built-in 404 page. Use --four-oh-four to serve a branded page instead. The file must be valid HTML and is read once at startup.

# custom-404.html example
cat > ./static/404.html << 'EOF'
<!DOCTYPE html>
<html>
<head><title>Not Found</title></head>
<body>
  <h1>404 — Page Not Found</h1>
  <p>This page has not been generated yet (or the budget cap was reached).</p>
  <p><a href="/">Return to homepage</a></p>
</body>
</html>
EOF

rabbithole --seed "My site" --four-oh-four ./static/404.html

Flag Reference Summary

rabbithole [OPTIONS]

OPTIONS:
    --seed <STRING>          Seed prompt string (mutually exclusive with --seed-file)
    --seed-file <PATH>       Read seed prompt from file (mutually exclusive with --seed)
    --port <NUMBER>          HTTP port [default: 8080]
    --model <STRING>         Anthropic model [default: claude-sonnet-4-5]
    --max-tokens <NUMBER>    Max output tokens per response [default: 8192]
    --depth-limit <NUMBER>   Max link graph depth [default: 5]
    --db <PATH>              SQLite database path [default: in-memory]
    --no-web-tools           Disable web_search / web_fetch tools
    --max-cost <DOLLARS>     Budget cap in USD (strongly recommended)
    --four-oh-four <PATH>    Custom 404 HTML file path
    -h, --help               Print help information
    -V, --version            Print version information

See Also

• Getting Started — Installation and first run
• Architecture — How Rabbithole generates pages and manages state
• Web Tools — Details on web_search and web_fetch
• Deployment — Running in production with Docker, systemd, or a reverse proxy
• Examples — Example seed prompts and live sites
• GitHub Repository — Source code and issue tracker
• clap documentation — CLI argument parsing library used by Rabbithole
• Anthropic API Pricing — Official, up-to-date pricing page