Skip to content

Installation

Ghostvault is available on PyPI (beta). You can install it with pip in two commands, or use the one-command installer which also configures your AI agent automatically.

Prerequisites

Before you start, make sure you have:

  • Python 3.11 or newer — download from python.org.
  • ~2 GB free disk space — the Camoufox browser binary is ~120 MB (one-time), plus Python dependencies and per-account profile data.
  • An MCP-compatible client you want to drive Ghostvault from — Claude Desktop, Cursor, ZCode, Cline, VS Code, etc. (See Connect your agent.)

Add Python to PATH

On Windows, check "Add Python to PATH" in the Python installer. On macOS, the official installer from python.org handles this for you.

Two commands — that's it:

# 1. Install Ghostvault from PyPI
pip install --pre ghostvault

# 2. Download the Camoufox browser binary (~120 MB, one-time)
python -m camoufox fetch

Then skip ahead to Connect your agent to set up the MCP config.

Why --pre?

Ghostvault is at v0.1-beta. The --pre flag tells pip to include pre-release versions. Once we reach v1.0, you'll be able to pip install ghostvault without it.

Option B — one-command installer

The installer does everything for you: installs Ghostvault, downloads the Camoufox binary, and writes the MCP config for Claude Desktop / Cursor if they're installed — no Python experience needed.

Run this in a terminal:

curl -fsSL https://raw.githubusercontent.com/mienetic/Ghostvault/main/install.sh | bash

That's it. The installer takes a minute or two — most of it is the one-time Camoufox download.

Run this in PowerShell (not the legacy cmd.exe):

irm https://raw.githubusercontent.com/mienetic/Ghostvault/main/install.ps1 | iex

If PowerShell complains about execution policy, the irm | iex pipe bypasses it — no need to change your system policy.

What the installer does

The installer is fully automated. Step by step, it:

  1. Checks prerequisites — verifies git and Python 3.11+ are on your PATH.
  2. Clones Ghostvault into ~/.ghostvault-app (macOS/Linux) or %USERPROFILE%\.ghostvault-app (Windows). If a previous install exists there, it updates in place instead of reinstalling.
  3. Creates an isolated Python virtualenv at .venv inside the install dir — Ghostvault and its dependencies never touch your system Python.
  4. Installs Ghostvault and its Python dependencies into that virtualenv (pip install -e .).
  5. Downloads the Camoufox browser binary (~120 MB, one-time). Camoufox is the patched, anti-detect Firefox that Ghostvault drives — you don't need to install Firefox separately.
  6. Writes the MCP config for Claude Desktop and/or Cursor if they're detected. Other clients (ZCode, Cline, VS Code) you wire up yourself — see Connect your agent.
  7. Drops an update.sh / update.ps1 helper next to the install for easy upgrades.

When it finishes you'll see a summary listing the install dir, data dir, and update command.

Verify the install

Check that Ghostvault is importable from the installer's virtualenv:

~/.ghostvault-app/.venv/bin/python -c "import ghostvault; print('OK')"

Confirm the Camoufox browser binary downloaded successfully:

~/.ghostvault-app/.venv/bin/python -m camoufox path

This prints the path to the Camoufox executable. If it errors, the download didn't finish — see troubleshooting below.

Check that Ghostvault is importable from the installer's virtualenv:

& "$env:USERPROFILE\.ghostvault-app\.venv\Scripts\python.exe" -c "import ghostvault; print('OK')"

Confirm the Camoufox browser binary downloaded successfully:

& "$env:USERPROFILE\.ghostvault-app\.venv\Scripts\python.exe" -m camoufox path

This prints the path to the Camoufox executable. If it errors, the download didn't finish — see troubleshooting below.

There's no ghostvault --version CLI flag yet

Ghostvault is an MCP server, not a standalone CLI, so it doesn't expose --version. The import + camoufox path checks above are the reliable way to confirm a healthy install. Ghostvault also checks for new releases on startup and prints a notice in your client's MCP logs if one is available.

If the installer wrote a config for Claude Desktop or Cursor, restart that app and Ghostvault's gv_* tools will appear. Then jump to Connect your agent (or First sign-in if you're already connected).

Keeping Ghostvault up to date

~/.ghostvault-app/update.sh

powershell -File "$env:USERPROFILE\.ghostvault-app\update.ps1"

The updater pulls the latest from main, refreshes dependencies, and re-checks the Camoufox binary. Ghostvault also checks automatically on startup and prints a notice in the MCP logs if a new version is available, so you'll never be silently out of date.

Troubleshooting

The installer failed at "Downloading Camoufox browser binary".

This is almost always a transient network issue. The Camoufox download is ~120 MB and the installer won't abort the whole install on it. Just retry it later:

~/.ghostvault-app/.venv/bin/python -m camoufox fetch

& "$env:USERPROFILE\.ghostvault-app\.venv\Scripts\python.exe" -m camoufox fetch

"Python 3.11+ required (found 3.x)"

Your system Python is too old. Install 3.11+ from python.org and re-run the installer. On macOS with Homebrew, brew install python@3.12 works too.

The installer said "No MCP client config was written".

This just means Claude Desktop and Cursor weren't detected on your machine — the install itself succeeded. Pick your client in Connect your agent and add the config snippet by hand. Other clients (ZCode, Cline, VS Code) always need manual config regardless.

command not found: git (macOS).

Run xcode-select --install to install the Xcode Command Line Tools, which include git, then re-run the installer.

Install dir already exists and I want a clean reinstall.

rm -rf ~/.ghostvault-app
curl -fsSL https://raw.githubusercontent.com/mienetic/Ghostvault/main/install.sh | bash

Remove-Item -Recurse -Force "$env:USERPROFILE\.ghostvault-app"
irm https://raw.githubusercontent.com/mienetic/Ghostvault/main/install.ps1 | iex

Don't delete ~/.ghostvault

That's your data dir — it holds per-account profiles (real session cookies), the SQLite metadata DB, and logs. Deleting it signs you out of every account. Only delete it if you actually want to wipe all sessions.

Manual install (alternative)

Prefer to set things up yourself, or want to develop Ghostvault? Ghostvault is on PyPI (beta) — pip install --pre ghostvault. Requires Python 3.11+.

git clone https://github.com/mienetic/Ghostvault.git
cd Ghostvault
pip install -e .

# Download the Camoufox browser binary (~120 MB, one-time)
python -m camoufox fetch

For development (includes test + lint tooling):

pip install -e ".[dev]"

You'll then need to connect your agent manually — point command at the absolute path of the Python you just installed into.

Next steps