Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/StarTrail-org/PixelRAG/llms.txt

Use this file to discover all available pages before exploring further.

PixelRAG reads several environment variables for runtime configuration — from the Chrome binary path to FAISS index loading strategy to the search API’s articles database. Variables are optional unless stated otherwise; each one sets the default for the corresponding CLI flag and can be overridden on the command line at any time.

​
Rendering (pixelshot)

​
CHROME_PATH
string
Path to a Chrome or Chromium binary. When set, pixelshot uses this binary instead of its auto-detection logic. Useful when you have a custom or non-standard Chrome installation. If unset, pixelshot searches a platform-specific list of locations (Playwright cache → system Chrome) and auto-installs the bundled patched headless_shell on linux-x64 if nothing else is found.Used by: pixelshot / pixelrag_render
​
PIXELSHOT_CDP_URL
string
Attach to an already-running Chrome DevTools Protocol endpoint (e.g. http://127.0.0.1:9222) instead of launching a new browser process. pixelshot renders each input in a fresh tab using that browser’s existing session — so authenticated pages and existing cookies work — then closes only that tab. No local Chrome binary is required when this is set. Can also be passed as --cdp-url on the CLI.Used by: pixelshot / pixelrag_render
export PIXELSHOT_CDP_URL=http://127.0.0.1:9222
pixelshot https://example.com --output ./tiles

​
Server (pixelrag serve)

​
PIXELRAG_INDEX_DIR
string
default:"./index"
Default value for --index-dir when not passed on the CLI. Points to the directory produced by pixelrag index build (contains index.faiss, metadata.npz, and summary.json).Used by: pixelrag serve
​
PIXELRAG_TILES_DIR
string
default:"./tiles"
Default value for --tiles-dir when not passed on the CLI. The directory holding per-article tile subdirectories ({article_id}.png.tiles/). Used by the /tile endpoints to serve tile images to clients.Used by: pixelrag serve
​
PIXELRAG_ARTICLES_JSON
string
default:"./articles.json"
Default value for --articles-json when not passed on the CLI. Path to the articles.json file generated by pixelrag index build. Contains per-article title, URL, and department metadata used to populate search results.Used by: pixelrag serve
​
PIXELRAG_INDEX_MMAP
string
Set to 1 to memory-map the FAISS index file instead of loading it fully into RAM. With mmap enabled, server startup is near-instant because the OS pages in inverted lists on demand rather than reading the whole file upfront. Hot lists stay resident in the OS page cache. This is especially useful for multi-100 GB indexes stored on NFS.Used by: pixelrag serve → FaissBackend
export PIXELRAG_INDEX_MMAP=1
Leave PIXELRAG_INDEX_MMAP unset for smaller indexes (≤ a few GB) on local SSDs — a full read into RAM gives lower query latency since every inverted list access is an in-process memory access rather than a page-fault.
​
PIXELRAG_QUERY_LOG_DIR
string
default:"logs/"
Directory where query log JSONL files are written. Each incoming /search request is appended as a line to {PIXELRAG_QUERY_LOG_DIR}/queries.jsonl. Log records include the timestamp, request ID, query text, whether an image was provided, n_docs, and department. The directory is created automatically if it does not exist.Used by: pixelrag serve
​
PIXELRAG_KIWIX_URL
string
default:"http://localhost:30900"
Base URL of a running kiwix-serve instance, used with --render-on-demand. When on-demand rendering is enabled, the server fetches article HTML from this URL and renders it to tiles on the fly instead of reading a materialized tiles/ directory. Can also be passed as --kiwix-url.Used by: pixelrag serve (with --render-on-demand)
​
PIXELRAG_ZIM_BOOK
string
The kiwix book ID used in /content/<book>/ URLs, e.g. wikipedia_en_simple_all_nopic_2026-05. When unset, the server auto-derives it by reading the kiwix-serve catalog at {PIXELRAG_KIWIX_URL}/catalog/v2/entries. Set it explicitly when auto-detection is unavailable or unreliable. Can also be passed as --zim-book.Used by: pixelrag serve (with --render-on-demand)

​
Qdrant

​
QDRANT_API_KEY
string
API key for authenticating with Qdrant Cloud. Passed automatically to the QdrantClient constructor. Use this instead of embedding the key in pixelrag.yaml or on the CLI. Can also be passed as --qdrant-api-key.Used by: pixelrag index build (when index.backend: qdrant), pixelrag serve (when --backend qdrant)
export QDRANT_API_KEY=your-qdrant-cloud-key

​
Example: setting up for production

The snippet below shows a typical production launch that combines several environment variables to avoid repeating long paths on every CLI invocation: 
export PIXELRAG_INDEX_DIR=/data/search_index_normed_v2
export PIXELRAG_TILES_DIR=/data/tiles
export PIXELRAG_ARTICLES_JSON=/data/articles.json
export PIXELRAG_INDEX_MMAP=1
pixelrag serve --port 30001
CLI flags always take precedence over environment variables. For example, pixelrag serve --index-dir /tmp/test_index will use /tmp/test_index regardless of what PIXELRAG_INDEX_DIR is set to.

Build docs developers (and LLMs) love

Get started for freeTalk to us