Skip to content

All environment variables

Ghostvault is configured entirely through environment variables prefixed with GHOSTVAULT_. They're loaded by pydantic-settings from .env (or your shell / the env block of an MCP client config). Every value has a sensible default — you only need to set the ones you want to change.

This page is the authoritative reference. The source of truth is the Settings class in src/ghostvault/config.py; .env.example in the repo root is a copy-pasteable template with inline comments.

How to set them

Three places, in order of precedence (highest first):

  1. Real environment variables — export GHOSTVAULT_HEADLESS=true before launching.
  2. The env block of your MCP client config — see example client configs.
  3. A .env file in the working directory of the server process.

A bare python -m ghostvault reads .env from the current directory.

Paths

Variable Type Default Description
GHOSTVAULT_DATA_DIR path ~/.ghostvault Root for all data: per-account profiles, the SQLite metadata DB, and JSONL logs. Never sync or commit this directory.

Derived paths (read-only, you don't set these directly):

Path Resolves to
Profiles dir $DATA_DIR/profiles
Logs dir $DATA_DIR/logs
Log file $DATA_DIR/logs/ghostvault.jsonl
SQLite DB $DATA_DIR/ghostvault.sqlite
Auth state $DATA_DIR/auth.json
Providers config $DATA_DIR/providers.json
Per-account profile $DATA_DIR/profiles/<account_id>
Per-account fingerprint $DATA_DIR/profiles/<account_id>.fingerprint.json
Per-account encrypted archive $DATA_DIR/profiles/<account_id>.profile.enc

Browser launch

Variable Type Default Description
GHOSTVAULT_HEADLESS bool false false opens a real browser window (recommended for first-time login + 2FA so you can see and complete verification). true runs headless (automation only).
GHOSTVAULT_DEFAULT_OS str auto Default fingerprint OS for new accounts: auto (detect host), windows, macos, or linux. Pinned per-account at creation time via the os argument.
GHOSTVAULT_LOGIN_TIMEOUT int 300 Seconds the user has to finish login (including 2FA) before the flow times out.
GHOSTVAULT_WINDOW_WIDTH int 0 Browser window width in pixels. 0 = auto-detect screen resolution, open at ~65% of it (fits any screen). Users can resize after.
GHOSTVAULT_WINDOW_HEIGHT int 0 Browser window height in pixels. 0 = auto-detect. Users can resize after.

Advanced fingerprint defaults

These are the global fallback for accounts that don't pin a value in their own advanced config (gv_create_account / gv_update_account_config). Per-account overrides always win.

Variable Type Default Description
GHOSTVAULT_HUMANIZE bool true Human-like cursor movement (click jitter + bezier path with up to N seconds travel time). Strongly recommended for Google/SSO work.
GHOSTVAULT_BLOCK_WEBRTC_STRATEGY str auto WebRTC gate. auto = block only when a proxy is set (prevents IP leak). true = always block (some WebRTC A/V sites break). false = never block (leaks real IP via STUN when using a proxy).
GHOSTVAULT_DEFAULT_LOCALE str (empty) Default locale for new accounts (e.g. en-US). Empty = let geoip (with proxy) or the host OS decide.
GHOSTVAULT_DEFAULT_TIMEZONE str (empty) Default IANA timezone for new accounts (e.g. America/New_York). Empty = let geoip or host OS decide.

Humanize policy

Controls how the per-call humanize arg on gv_fill_input / gv_click_element is resolved against per-account config. See Humanize policy for the full 3-layer model.

Variable Type Default Description
GHOSTVAULT_HUMANIZE_POLICY str off off = agent decides every call (backward compat). recommended = humanize defaults on, agent can turn off per call. always = humanize forced on; agent cannot disable. Per-account humanize_policy wins over this.

Ephemeral sessions

gv_open_ephemeral opens a throwaway Camoufox session: no account row, no persistent profile, no encryption. Random identity per session; tempdir is removed on close. These settings tune that flow.

Variable Type Default Description
GHOSTVAULT_EPHEMERAL_HEADLESS bool true Run ephemeral sessions headless (scraping usually doesn't need a visible window).
GHOSTVAULT_EPHEMERAL_BLOCK_IMAGES bool true Block image loading for faster text scraping. Turn off if you screenshot-scrape.
GHOSTVAULT_EPHEMERAL_HUMANIZE bool false Cursor humanization for ephemeral sessions. Turn on for captcha-protected scrape targets.
GHOSTVAULT_EPHEMERAL_AUTO_CLOSE_MINUTES int 5 Idle timeout (minutes) for ephemeral sessions. Shorter than auto_lock_minutes because these multiply. 0 = disabled.
GHOSTVAULT_EPHEMERAL_MAX_CONCURRENT int 3 Cap on simultaneous ephemeral sessions. Each is a full Firefox process — too high exhausts memory.

Proxy

Optional global proxy (Playwright-style). Leave blank for local-first. When set, ALL traffic for ALL accounts goes through this proxy unless an account has its own override. With a proxy set, geoip=True auto-matches timezone/locale/geolocation to the proxy's exit IP.

Variable Type Default Description
GHOSTVAULT_PROXY_SERVER str (empty) Proxy URL, e.g. http://host:port or socks5://host:port.
GHOSTVAULT_PROXY_USERNAME str (empty) Proxy auth username.
GHOSTVAULT_PROXY_PASSWORD str (empty) Proxy auth password.

Logging

Variable Type Default Description
GHOSTVAULT_LOG_LEVEL str INFO Console log level: DEBUG / INFO / WARNING / ERROR.
GHOSTVAULT_LOG_MAX_MB int 10 Rotate the JSONL action log once it reaches this many megabytes.
GHOSTVAULT_LOG_BACKUPS int 5 How many rotated log files to keep.

MCP transport

Variable Type Default Description
GHOSTVAULT_TRANSPORT str stdio stdio (default; for Claude Desktop / Cursor / Cline / ZCode) or http (streamable HTTP server for remote clients).
GHOSTVAULT_HOST str 127.0.0.1 Bind address when TRANSPORT=http. Defaults to loopback — change to 0.0.0.0 only behind a reverse proxy.
GHOSTVAULT_PORT int 8765 Port when TRANSPORT=http.

See Remote (HTTP transport) for the full remote-access walkthrough.

Encryption at rest

When enabled, each account's persistent profile (which holds real Google session cookies) is stored on disk as an AES-256-GCM encrypted archive. The browser only sees a decrypted copy in a temp dir while running; on close it's re-encrypted and the temp is wiped. The master key lives in your OS keychain — never on disk.

Variable Type Default Description
GHOSTVAULT_ENCRYPTION_ENABLED bool false Enable AES-256-GCM profile encryption at rest. Requires a working keychain backend.
GHOSTVAULT_KEYRING_SERVICE str ghostvault Keychain service name under which the master key is stored.

Losing the keychain entry makes encrypted profiles unrecoverable

There is no recovery path. If the OS keychain entry is deleted (e.g. you wipe the keychain, or move profiles to another machine without exporting the key), the encrypted archives are gone for good.

Headless Linux

On headless Linux without D-Bus / Secret Service, encryption stays disabled even if you set GHOSTVAULT_ENCRYPTION_ENABLED=true — there's no keychain backend to hold the key.

Auto-close / auto-lock

Two independent safety nets for minimizing the window during which a decrypted profile exists on disk.

Variable Type Default Description
GHOSTVAULT_AUTO_CLOSE_AFTER_TASK bool false When true, the browser context is closed (and, if encryption is on, the profile re-encrypted) immediately after each MCP browser tool call returns. Costs ~1–2s to re-open per call. Ephemeral sessions are always skipped.
GHOSTVAULT_AUTO_LOCK_MINUTES int 0 When > 0, close any browser context that has been idle (no tool calls) for this many minutes. Belt-and-suspenders for when auto_close_after_task is off or a long task is in flight. 0 = disabled.

Combine for defense in depth

The most paranoid posture is GHOSTVAULT_ENCRYPTION_ENABLED=true + GHOSTVAULT_AUTO_CLOSE_AFTER_TASK=true + GHOSTVAULT_AUTO_LOCK_MINUTES=5. The decrypted profile then only exists on disk for the duration of each tool call.

Quick reference: common combos

Goal Set
First-time sign-in on a laptop defaults (headful, balanced preset)
Fully automated, post-login GHOSTVAULT_HEADLESS=true
Scrape public pages fast defaults + gv_open_ephemeral
Maximum security GHOSTVAULT_ENCRYPTION_ENABLED=true + GHOSTVAULT_AUTO_CLOSE_AFTER_TASK=true
Remote server, accessed from a laptop GHOSTVAULT_TRANSPORT=http + reverse proxy with TLS
Force humanize everywhere GHOSTVAULT_HUMANIZE_POLICY=always