Skip to content

Configuration basics

Ghostvault is configured entirely through environment variables prefixed with GHOSTVAULT_. Everything is optional with sensible defaults — you can run a fresh install without touching a single setting.

This page covers the basics you'll actually want to know about on day one. For the full list (humanize policy, ephemeral tuning, encryption, proxy, log rotation, ...), see All environment variables.

Where settings are read from

Ghostvault reads GHOSTVAULT_* variables from two places, in order:

  1. The env block of your client's MCP config (Claude Desktop's claude_desktop_config.json, Cursor's mcp.json, etc.). This is the easiest place — set it once and your client passes it to every Ghostvault launch.
  2. A .env file in the working directory where Ghostvault runs. The installer doesn't create one for you; drop one next to your project if you prefer file-based config.

You can also export the variables in your shell before launching the client — but the client's env block is more reliable, since clients don't always inherit your shell environment.

Client env wins for most users

Because Ghostvault runs as a subprocess of your AI client (see Connect your agent), the env block in that client's config is the canonical place to set variables. Set them there and restart the client to apply.

The basics

Variable Default What it does
GHOSTVAULT_DATA_DIR ~/.ghostvault Where profiles, the SQLite DB, and logs live.
GHOSTVAULT_HEADLESS false Whether the browser shows a visible window.
GHOSTVAULT_DEFAULT_OS auto Default fingerprint OS for new accounts.
GHOSTVAULT_LOGIN_TIMEOUT 300 Seconds to complete login + 2FA.
GHOSTVAULT_TRANSPORT stdio How your client talks to Ghostvault.
GHOSTVAULT_WINDOW_WIDTH 1280 Browser window width in pixels.
GHOSTVAULT_WINDOW_HEIGHT 800 Browser window height in pixels.
GHOSTVAULT_LOG_LEVEL INFO Console log level.

GHOSTVAULT_DATA_DIR

The root directory for everything Ghostvault persists: per-account profiles (which hold real Google session cookies), the SQLite metadata DB, and JSONL debug logs. Defaults to ~/.ghostvault (macOS/Linux) or %USERPROFILE%\.ghostvault (Windows).

GHOSTVAULT_DATA_DIR=~/.ghostvault

Keep it local and private

This directory holds your Google sessions. Never sync it to a shared drive, never commit it to git. Anyone with read access to it has full access to your accounts. Protect the directory's permissions — or enable encryption at rest.

GHOSTVAULT_HEADLESS

Controls whether the browser shows a visible window.

  • false (default) — opens a real window. Required for first-time login and 2FA so you can see and complete verification.
  • true — no visible window (pure automation). Switch to this only after all accounts are signed in and you're running unattended.
GHOSTVAULT_HEADLESS=false

Keep it false until you're signed in

Headless mode has no window for you to type credentials into. Leave GHOSTVAULT_HEADLESS=false through your first sign-in of every account. Once sessions are saved, you can flip it to true for unattended runs.

GHOSTVAULT_DEFAULT_OS

The default fingerprint OS for new accounts created via gv_create_account. Once an account is created, its OS is pinned and this setting no longer affects it.

  • auto (default) — matches your host OS (recommended).
  • windows / macos / linux — pin to a specific OS regardless of where you run.
GHOSTVAULT_DEFAULT_OS=auto

GHOSTVAULT_LOGIN_TIMEOUT

How many seconds you have to complete Google login (including 2FA) in the opened window before gv_sign_in gives up. Default is 300 (5 minutes).

GHOSTVAULT_LOGIN_TIMEOUT=300

If your 2FA is slow or you fumble for your phone, bump it to 600.

GHOSTVAULT_TRANSPORT

How your client connects to Ghostvault:

  • stdio (default) — Ghostvault runs as a subprocess of your client (Claude Desktop, Cursor, Cline). This is what you want for local use.
  • http — streamable HTTP server, for remote clients. See Remote (HTTP transport).
GHOSTVAULT_TRANSPORT=stdio

For the vast majority of users, leave this at stdio. You only need http if you're running Ghostvault on a separate machine from your client.

GHOSTVAULT_WINDOW_WIDTH / GHOSTVAULT_WINDOW_HEIGHT

Browser window size in pixels. 0 (default) = auto-detect screen resolution and open at ~85% of it. Set to a specific size if you want exact control. Users can resize/maximize the window after it opens.

GHOSTVAULT_WINDOW_WIDTH=0
GHOSTVAULT_WINDOW_HEIGHT=0

GHOSTVAULT_LOG_LEVEL

Console log level: DEBUG | INFO | WARNING | ERROR. Default INFO. Set to DEBUG when something isn't working — the agent can read structured logs back via gv_get_logs.

GHOSTVAULT_LOG_LEVEL=INFO

A minimal .env example

If you prefer a file, drop this as .env next to where Ghostvault runs. Everything below is the default, so you'd only change what you need:

# Data directory — profiles, DB, logs. Keep this local and private.
GHOSTVAULT_DATA_DIR=~/.ghostvault

# Show a real browser window (required for first-time login + 2FA).
GHOSTVAULT_HEADLESS=false

# Default fingerprint OS for new accounts: auto | windows | macos | linux.
GHOSTVAULT_DEFAULT_OS=auto

# Seconds to complete login + 2FA.
GHOSTVAULT_LOGIN_TIMEOUT=300

# Browser window size (0 = let the browser decide).
GHOSTVAULT_WINDOW_WIDTH=1280
GHOSTVAULT_WINDOW_HEIGHT=800

# Transport: stdio (local) | http (remote).
GHOSTVAULT_TRANSPORT=stdio

# Console log level.
GHOSTVAULT_LOG_LEVEL=INFO

Or, equivalently, in your client's env block (Claude Desktop example):

{
  "mcpServers": {
    "ghostvault": {
      "command": "/absolute/path/to/python",
      "args": ["-m", "ghostvault"],
      "env": {
        "GHOSTVAULT_HEADLESS": "false",
        "GHOSTVAULT_DEFAULT_OS": "macos",
        "GHOSTVAULT_LOGIN_TIMEOUT": "600"
      }
    }
  }
}

All values are strings in the client env block

Even though GHOSTVAULT_LOGIN_TIMEOUT is a number, JSON requires it as a string ("600"). Ghostvault parses the type on its end.

When defaults aren't enough

These basics cover local, single-machine use. When you outgrow them, the deeper guides have you covered:

Next steps

  • Tool reference — every gv_* tool, what it does, and its arguments.
  • Examples — runnable scripts and copy-paste agent prompts.