<div align="center">

👻 Ghostvault

Open-source MCP server for managing multiple Google accounts through your AI agent — powered by Camoufox.

Let Claude Desktop, Cursor, Cline, or any MCP-compatible agent sign in to Google accounts, switch between them, read Gmail, and drive any website that uses Sign in with Google — with persistent sessions and locked anti-detect fingerprints.

Quick start · How it works · Tools · FAQ · Contributing

</div>

---

Why Ghostvault

Managing several Google accounts from automation is painful:

• 🔒 Google's bot detection flags headless browsers and datacenter IPs
• 🔁 Account hopping requires re-authentication every time
• 🌐 Third-party sites that use "Sign in with Google" don't expose API access

Ghostvault solves this by giving your AI agent a real, anti-detect browser per account — with sessions that persist between restarts and fingerprints that don't drift.

Features

• 🎭 Locked fingerprints — each account always looks like the same device to Google (Camoufox C-level spoofing + persisted noise seeds)
• 🔐 Persistent sessions — sign in once per account, then reuse forever (cookies + localStorage survive restarts)
• 🔄 Multi-account — create, sign in, and switch between unlimited Google accounts from one agent
• 🌍 Any Google-SSO site — once signed in, the agent can drive Notion, Canva, ChatGPT, or any site that uses Google login
• 🔌 Multi-provider ready — gv_create_account({provider: "google"}) defaults to Google; the architecture supports GitHub, Facebook, or any OAuth provider in the future
• 👁️ Vision support — tools return PNG screenshots so the LLM can see the page when text isn't enough
• 📋 Self-debugging — structured JSONL logs of every action; the agent can read them via gv_get_logs
• 🏠 Local-first — sessions, cookies, and fingerprints live on your machine under ~/.ghostvault; nothing is ever sent anywhere
• 🔒 Optional encryption at rest — AES-256-GCM encrypted profile archives with the key in your OS keychain (off by default)
• ⏱️ Auto-close & auto-lock — optionally close + re-encrypt after each task or after N idle minutes (off by default)
• 🔑 Private/public profiles — optional password gate separating sensitive profiles (hidden until unlocked) from public ones; 5 wrong passwords wipes private profiles
• 🤖 LLM-agnostic — works with Claude, GPT, Gemini, or any model your MCP client supports
• 🪶 Zero-dependency agent loop — you bring the LLM client, Ghostvault provides the browser tools

How it works

Your AI agent (Claude Desktop / Cursor / Cline)
        │  MCP protocol (stdio or HTTP)
        ▼
┌─────────────────────────────────────────────────┐
│ Ghostvault MCP Server                           │
│                                                 │
│  24 tools:                                      │
│   gv_sign_in, gv_open_account,          │
│   gv_switch_account, gv_lock_account,   │
│   gv_sign_out, gv_delete_account,       │
│   gv_open_url, gv_read_gmail,           │
│   gv_get_page_content (+ screenshot),       │
│   gv_click_element, gv_fill_input,      │
│   gv_setup_password, gv_unlock,         │
│   gv_make_private, gv_get_logs, ...     │
│                                                 │
│  Per-account persistent Camoufox profiles:      │
│   profile_A/  ── + locked fingerprint A         │
│   profile_B/  ── + locked fingerprint B         │
│   profile_C/  ── + locked fingerprint C         │
└─────────────────────────────────────────────────┘
        │  traffic exits via your home IP (local-first)
        ▼
   google.com  +  any Google-SSO site

The agent decides what to do; Ghostvault provides the hands. Because the agent loop lives client-side, you can use whichever LLM you like.

Why fingerprints are locked (critical)

Camoufox generates a fresh random fingerprint on every launch — it does not persist one to the profile directory. Without locking, each launch would look like a brand-new device and Google would flag the account.

Ghostvault generates one fingerprint per account at creation, serializes it (BrowserForge fingerprint + the canvas/audio/fonts noise seeds + OS) to a sidecar JSON, and passes it back on every launch. Result: an account always presents the same identity.

---

Quick start (one command)

No Python experience needed. Run the one-line installer for your platform. It installs everything and configures Claude Desktop / Cursor for you.

macOS / Linux (in a terminal):

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

Windows (in PowerShell):

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

The installer automatically:

1. 📥 Clones Ghostvault into ~/.ghostvault-app (or %USERPROFILE%\.ghostvault-app on Windows)
2. 🐍 Creates an isolated Python virtualenv (doesn't touch your system Python)
3. 📦 Installs Ghostvault + all dependencies
4. 🦊 Downloads the Camoufox browser binary (~120 MB, one-time)
5. ⚙️ Writes the MCP config for Claude Desktop and/or Cursor if they're installed

Then restart Claude Desktop / Cursor — Ghostvault's tools appear. That's it. 🎉

Requirements: Python 3.11+ (download) and git. On macOS, run xcode-select --install first if git isn't installed. On Windows, check "Add Python to PATH" during the Python installer.

Update

# macOS / Linux
~/.ghostvault-app/update.sh

# Windows (PowerShell)
powershell -File "$env:USERPROFILE\.ghostvault-app\update.ps1"

Ghostvault also checks automatically on startup and prints a notice if a new version is available — so you'll never be silently out of date.

Uninstall

# macOS / Linux
bash ~/.ghostvault-app/uninstall.sh

On Windows, just delete the install dir and the data dir manually:

Remove-Item -Recurse -Force "$env:USERPROFILE\.ghostvault-app"
Remove-Item -Recurse -Force "$env:USERPROFILE\.ghostvault"   # sessions (optional)

Then remove the ghostvault entry from your Claude Desktop / Cursor config by hand.

Removes the install dir + the Ghostvault entry from your client configs. (On macOS/Linux the script asks before deleting session data, since ~/.ghostvault contains your Google sessions.)

---

Connect your agent

💡 If you ran the one-line installer above, it already wrote the config for Claude Desktop and Cursor. Just restart those apps and you're done — skip to Usage. The steps below are only needed if you installed manually, or want to connect a different agent.

Ghostvault is an MCP server, so any MCP-compatible client can connect. Ready-to-copy config files for each client live in examples/ — see examples/README.md for the full cheat-sheet of where each file goes and the JSON shape each client expects.

⚠️ Use an absolute path to your Python. Clients run the server as a subprocess and don't inherit your shell PATH, so a bare python won't be found. After installing, find the right interpreter:

• One-line installer: ~/.ghostvault-app/.venv/bin/python
• Manual install: run which python in the venv where you installed Ghostvault, or use /usr/bin/python3, /opt/homebrew/bin/python3, etc.

Supported clients

Client	Example file	Config location
Claude Desktop	claude_desktop_config.json	~/Library/Application Support/Claude/ (macOS), %APPDATA%\Claude\ (Windows), ~/.config/Claude/ (Linux)
Cursor	cursor_config.json	~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project)
Cline (VS Code)	cline_mcp_settings.json	~/.cline/data/settings/cline_mcp_settings.json (note extra disabled/autoApprove fields)
VS Code (Agent mode)	vscode_mcp.json	.vscode/mcp.json (note shape is {"servers": {...}} with type: "stdio")
ZCode	zcode_config.json	<repo>/.zcode/config.json (workspace) or ~/.zcode/cli/config.json (note nested mcp.servers)
Continue.dev	continue_dev_config.json	~/.continue/config.json under mcpServers
Claude Code (CLI)	(CLI — see below)	claude mcp add ...

Claude Code (CLI)

Claude Code is configured via the claude CLI rather than a JSON file:

claude mcp add --transport stdio -s user \
  -e GHOSTVAULT_HEADLESS=false \
  ghostvault -- /absolute/path/to/python -m ghostvault

Verify: claude mcp list. Scopes: -s user (all projects), -s project (shared via .mcp.json), -s local (default).

Other clients

Any MCP-compatible client works. The universal recipe:

1. Point command at an absolute Python path that has Ghostvault installed
2. Set args to ["-m", "ghostvault"]
3. Optionally set env for any GHOSTVAULT_* variables (see Configuration)

The clients disagree on JSON shape — see the shape cheat-sheet in examples/README.md.

Remote / HTTP transport (advanced)

To serve Ghostvault over HTTP instead of stdio (e.g. for a remote client):

GHOSTVAULT_TRANSPORT=http GHOSTVAULT_PORT=8765 python -m ghostvault

Then point your client at http://127.0.0.1:8765/mcp (use the machine's IP for remote access — ensure you secure it).

---

Verify the connection

After connecting any agent, test it with a simple prompt:

"List my Ghostvault accounts."

The agent should call gv_list_accounts and return an empty list on a fresh install. If you get an error instead, check:

• The Python path in the config is absolute and correct (ls /that/path)
• Ghostvault is importable from that Python: /that/path/python -c "import ghostvault"
• The Camoufox browser binary is downloaded: /that/path/python -m camoufox path
• For stdio clients: check the client's MCP/logs panel — startup errors appear there

Just talk to your agent naturally. Example prompts:

• "Sign in to my Work Google account, then read my latest 5 emails and tell me if any need an urgent reply."
• "Switch to my Personal account and open Drive — list my recent files."
• "Open Notion using my Work Google login and create a new page called 'Weekly review'."
• "Take a screenshot of the current page so I can see what's happening."

The agent calls the right tools. On the first sign-in of a new account, a browser window opens for you to complete login (Google will likely ask for 2FA — this is normal).

Typical first-time flow

1. You:   "Create a Google account called Work"
   Agent: calls gv_create_account → "Done. Now sign in."

2. You:   "Sign in to Work"
   Agent: calls gv_sign_in → a browser window opens
   You:   complete Google login + 2FA in that window
   Agent: "Signed in as you@gmail.com."

3. You:   "Read my latest emails"
   Agent: calls gv_read_gmail → returns inbox summary

4. You:   "Now switch to Personal and open Drive"
   Agent: calls gv_switch_account + gv_open_url

---

Tool reference

Accounts & lifecycle (16 tools)

Tool	Description
gv_list_accounts	List accounts + which is active + statuses (private hidden when locked)
gv_create_account	Create a slot with a locked fingerprint (name, os?, proxy?)
gv_sign_in	Open a login window for the user (handles 2FA)
gv_open_account	Open the browser reusing a saved session (no login window)
gv_switch_account	Change the active account
gv_get_session_status	Check if a session is running/authenticated
gv_close_account	Close a browser context (session saved)
gv_lock_account	Close + re-encrypt (session kept)
gv_sign_out	Sign out of Google (session invalidated; re-login required)
gv_delete_account	Delete account + profile + session + DB row permanently
gv_setup_password	Set a password to enable the private/public gate (browser window)
gv_unlock	Unlock the gate to access private profiles (password or browser window)
gv_logout	Lock the gate + close private contexts + switch to public
gv_get_auth_status	Check whether the gate is active and unlocked
gv_make_private	Mark a profile as private (hidden when locked)
gv_make_public	Mark a profile as public (always accessible)

Browser (7 tools)

Tool	Description
gv_open_url	Open any URL in the active account (incl. Google-SSO sites)
gv_get_page_content	Read page text (+ optional screenshot via include_screenshot)
gv_screenshot	Capture a PNG (vision) — full_page option
gv_get_page_links	List visible links
gv_click_element	Click by visible text or CSS selector
gv_fill_input	Fill a form field by label or selector
gv_read_gmail	Read the Gmail inbox (convenience tool)

Debug (1 tool)

Tool	Description
gv_get_logs	Read recent JSONL action log entries

Full tool docstrings (what the agent sees) are in SKILL.md.

---

Configuration

All settings are env vars (prefix GHOSTVAULT_), loadable from a .env file. See .env.example for the full list. Highlights:

Var	Default	Purpose
GHOSTVAULT_DATA_DIR	~/.ghostvault	Profiles, DB, logs
GHOSTVAULT_HEADLESS	false	Open a visible window (recommended for login + 2FA)
GHOSTVAULT_DEFAULT_OS	auto	Default fingerprint OS (auto = host OS, or windows/macos/linux)
GHOSTVAULT_LOGIN_TIMEOUT	300	Seconds to complete login + 2FA
GHOSTVAULT_TRANSPORT	stdio	stdio | http | sse
GHOSTVAULT_PROXY_*	(empty)	Optional global proxy (local-first otherwise)
GHOSTVAULT_LOG_LEVEL	INFO	Console log level
GHOSTVAULT_ENCRYPTION_ENABLED	false	Encrypt profile dirs at rest (see Encryption)
GHOSTVAULT_AUTO_CLOSE_AFTER_TASK	false	Close browser + re-encrypt after each tool call (minimizes exposure window)
GHOSTVAULT_AUTO_LOCK_MINUTES	0	Auto-close idle contexts after N minutes (0 = disabled)
GHOSTVAULT_WINDOW_WIDTH	1280	Browser window width in pixels (0 = let browser decide)
GHOSTVAULT_WINDOW_HEIGHT	800	Browser window height in pixels (0 = let browser decide)

Encryption at rest (optional)

By default, each account's persistent profile (which holds real Google session cookies) lives on disk as plaintext Firefox profile files. Anyone with read access to ~/.ghostvault/profiles/ can steal your sessions.

Enable encryption to store profiles as AES-256-GCM archives instead:

export GHOSTVAULT_ENCRYPTION_ENABLED=true

Or set it in your client's env block:

"env": { "GHOSTVAULT_ENCRYPTION_ENABLED": "true" }

How it works:

• The master key is stored in your OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) — never on disk. It's auto-generated on first use.
• When the browser opens, the profile is decrypted to a temp dir (wiped on close).
• When the browser closes, the profile is re-encrypted to <account_id>.profile.enc.
• Existing plaintext profiles are auto-migrated on first open after enabling.

Requirements & caveats:

• Keychain backend required. On headless Linux without D-Bus / Secret Service (e.g. a bare Docker container), encryption can't store the key securely and stays disabled. Run gnome-keyring or kwallet first.
• Losing the keychain entry = losing the profiles. The key is not derivable from anything else. There is no recovery path by design — that's what makes it secure.
• The browser still sees plaintext while running. Encryption protects data at rest, not against an attacker who compromises the running session.
• Fingerprint files stay plaintext. They describe the spoofed identity (UA, screen, etc.) but don't contain session secrets, so encrypting them isn't worth the complexity.

Private/public profiles (optional)

Ghostvault can separate profiles into public (accessible without unlocking) and private (hidden behind a password). This is an app-level visibility gate on top of encryption-at-rest.

How it works:

1. Call gv_setup_password — a browser window opens for you to set a password
2. Mark sensitive profiles as private: gv_make_private({account_id})
3. When locked, gv_list_accounts hides private profiles; browser tools refuse to open them
4. Call gv_unlock({password}) to access private profiles (stays unlocked until gv_logout or server restart)

Brute-force protection:

• 3 wrong passwords → warning with remaining attempts
• 5 wrong passwords → all private profiles permanently deleted + password reset
• Public profiles are never affected by failed attempts

This is different from encryption-at-rest: encryption protects the disk (someone steals the laptop); the private/public gate protects access (someone sits at your unlocked machine and tries to use private Google accounts via the agent).

Remote (HTTP transport)

For remote access instead of the default stdio transport:

GHOSTVAULT_TRANSPORT=http GHOSTVAULT_PORT=8765 python -m ghostvault

Point your client at http://127.0.0.1:8765/mcp.

---

Manual install (alternative)

<details> <summary>Click to expand — for users who prefer a manual setup or want to develop Ghostvault</summary>

Ghostvault is not yet on PyPI — install it from the GitHub source. 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]"

Then add Ghostvault to your client config manually. Use the Python from your environment as the command — for example, the venv python if you installed into one.

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or ~/.config/Claude/claude_desktop_config.json (Linux):

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

Cursor — edit .cursor/mcp.json:

{
  "mcpServers": {
    "ghostvault": {
      "command": "/absolute/path/to/your/python",
      "args": ["-m", "ghostvault"]
    }
  }
}

Restart your client after editing.

</details>

---

Programmatic use (SDK)

For scripts that want to call Ghostvault without an LLM in the loop (run inside the cloned repo, after pip install -e . above):

pip install -e ".[sdk]"

import asyncio
from ghostvault_sdk import GhostvaultClient

async def main():
    async with GhostvaultClient() as gv:
        await gv.create_account(name="Work", os="macos")
        accounts = await gv.list_accounts()
        print(accounts)

asyncio.run(main())

See the examples/ directory for comprehensive examples:

Example	What it demonstrates
scripts/sdk_all_tools.py	Every gv_* tool called via SDK (24 tools)
scripts/sdk_private_public.py	Private/public gate flow via SDK (setup, lock, unlock, logout)
scripts/test_login_session.py	End-to-end: login Google + verify session persists across restart
scripts/mcp_e2e_test.py	MCP protocol test: create + sign in + read Gmail
scripts/mcp_security_test.py	Encryption + auto-close + auto-lock + sign_out + delete
agent_prompts.md	Copy-paste prompts for Claude Desktop / Cursor / ZCode (all 24 tools)

---

FAQ

<details> <summary><b>Will Google ban my accounts?</b></summary>

Ghostvault uses Camoufox, a Firefox fork with C-level fingerprint spoofing — the same technology used by professional anti-detect tools. With locked fingerprints and your home IP, each account looks like a genuine, consistent device. That said:

• First-time login always triggers 2FA — Google sees a new device. This is expected and one-time per account.
• Don't share IPs across many accounts — Google clusters accounts by IP. One account per proxy/IP is the safe ratio.
• Don't automate at inhuman speed — the agent should pace actions like a real user.

Ghostvault gives you the tools to be safe; how you use them is your responsibility. </details>

<details> <summary><b>Can I run this on a server instead of my laptop?</b></summary>

Yes, but with caveats:

• You'll need a residential/mobile proxy per account (datacenter IPs get flagged immediately).
• Login requires a visible window — on a headless server, use headless='virtual' (Xvfb) or forward via VNC/noVNC so you can complete 2FA.
• The session won't survive a fingerprint+IP change, so configure the proxy before the first login.

For most users, running locally is simpler and safer. The remote HTTP transport (GHOSTVAULT_TRANSPORT=http) is there if you need it. </details>

<details> <summary><b>Does this work with non-Google sites?</b></summary>

Yes — that's a major use case. Once an account is signed in, call gv_open_url with any URL. Sites that use "Sign in with Google" will auto-SSO using the account's session. The agent can then navigate them like any other page. </details>

<details> <summary><b>How is this different from browser-use / Stagehand / AgentQL?</b></summary>

Those are agent frameworks (they provide the LLM↔browser reasoning loop). Ghostvault is a tool provider — it exposes browser tools via MCP that any agent framework (or plain Claude Desktop) can call. You can even combine them: use Ghostvault for the stealth Google sessions and let your favorite agent framework drive the pages.

Ghostvault uses Camoufox (Firefox/Juggler), while browser-use 0.13+ requires CDP (Chromium-only) — so they don't directly interoperate, but they solve different problems. </details>

<details> <summary><b>Where is my data stored? Is it sent anywhere?</b></summary>

Everything stays local under ~/.ghostvault/:

• profiles/ — per-account Camoufox profiles (cookies, localStorage, fingerprint lock)
• logs/ghostvault.jsonl — structured debug log
• browserver.sqlite — account metadata only (no sessions)

Nothing is ever sent to a remote server except the browser traffic itself (which exits via your home IP, or your configured proxy). Ghostvault has no telemetry, no analytics, no phone-home. </details>

<details> <summary><b>The agent says "No active account" — what do I do?</b></summary>

You need to sign in first. Tell the agent: "Sign in to [account name]". A browser window opens; complete Google login there. After that, the account is active and the browser tools work. See Typical first-time flow. </details>

---

Troubleshooting

Symptom	Fix
Login window doesn't appear	Set GHOSTVAULT_HEADLESS=false in .env or your client config env block
gv_read_gmail returns empty	Gmail's DOM changes often — fall back to gv_open_url to mail.google.com + gv_get_page_content with include_screenshot=true
"Session not authenticated"	The session expired — re-run gv_sign_in for that account
Agent action had no effect	Call gv_get_logs and/or gv_screenshot to see what the browser shows
Install fails on camoufox fetch	Network issue — retry with python -m camoufox fetch, or skip and run it later
Two windows for same account	Not possible — Ghostvault enforces one context per account. Switch accounts instead.

---

Important notes

• First-time login = new device. Google sees a new fingerprint/IP, so expect a 2FA challenge. This is one-time per account.
• Local-first by default. Traffic exits via your home IP. If you move Ghostvault to a server, add a residential proxy and re-login.
• One context per account. Ghostvault refuses to open two windows for the same profile (would corrupt it). Switch accounts instead.
• Gmail scraping is best-effort. Gmail's DOM changes often; if gv_read_gmail returns empty, fall back to gv_open_url + gv_get_page_content with a screenshot.
• Sessions are sensitive. Anyone with read access to ~/.ghostvault/ has full access to your Google accounts. Protect that directory — or enable encryption at rest.
• Camoufox ≠ Firefox. Ghostvault downloads its own patched Camoufox browser (~120 MB) during install. You don't need to install Firefox separately; the two don't conflict.

---

Roadmap

Legend: 🟢 done · 🔵 in progress · ⚪ planned · 🏁 good first issue · 💛 help wanted · 💰 needs funding

v0.1 — MVP (current release)

• 🟢 Core: per-account persistent Camoufox profiles + locked fingerprints
• 🟢 24 MCP tools (accounts, lifecycle, browser, Gmail, debug, private/public gate)
• 🟢 Vision support (gv_screenshot, include_screenshot)
• 🟢 Structured JSONL debug logs + gv_get_logs
• 🟢 One-click installer (install.sh) with auto-config for Claude Desktop / Cursor
• 🟢 Auto-update check on startup
• 🟢 CI: lint + test (3.11/3.12) + build

v0.2 — Solidify (in progress)

Make what exists reliable enough for daily use.

• 🟢 Auto-detect host OS — GHOSTVAULT_DEFAULT_OS=auto resolves to the machine's OS
• 🟢 Real browser integration tests in CI — runs against a real Camoufox browser in GitHub Actions, validating the persistent-context contract and the fingerprint-lock stability invariant across relaunches
• 🟢 Windows installer (install.ps1) — PowerShell one-click installer
• 🟢 Encryption at rest (optional) — AES-256-GCM + OS keychain
• 🟢 Auto-close / auto-lock (optional) — close + re-encrypt after each task or after N idle minutes
• 🟢 Lock / sign-out / delete tools — gv_lock_account, gv_sign_out, gv_delete_account
• 🟢 Configurable window size — GHOSTVAULT_WINDOW_WIDTH / GHOSTVAULT_WINDOW_HEIGHT
• 🟢 24 MCP tools (renamed google_* → gv_* for multi-provider support)
• 🟢 Private/public profiles (optional) — password gate + 5-attempt wipe
• 🟢 SDK client (ghostvault_sdk) — programmatic access without an LLM
• ⚪ Publish to PyPI — pip install ghostvault (currently source-only)
• ⚪ Robust Gmail reader — graceful fallbacks when Gmail's DOM changes + structured output
• ⚪ Session health check — auto-detect expired sessions and tell the agent to re-login
• ⚪ gv_get_account_cookies / gv_export_session — backup/restore sessions
• 🏁 Replace ad-hoc CSS selectors in pages.py with a tested selector strategy
• 🏁 Add more languages to the README (TH, ES, ZH) — translations welcome

v0.3 — More Google services

Cover the main Google use cases.

• ⚪ Google Drive — list, download, upload files 🏁
• ⚪ Google Calendar — upcoming events, create events
• ⚪ Google Photos — list, download 🏁
• ⚪ Google Contacts — search, export
• ⚪ Generic "fill + submit form" helper with better recovery
• ⚪ gv_wait_for_element + gv_wait_for_navigation tools

v1.0 — Production-ready (multi-user / server)

Safe to run as a shared service.

• 🔵 Encrypt profiles at rest — AES-256-GCM + OS keychain (implemented, in testing)
• 🟢 Private/public profiles + password gate — done in v0.2 (moved from v1.0)
• ⚪ Per-account proxy lock enforcement in the API 💛
• ⚪ Docker image + docker-compose 💛
• ⚪ Audit log (who did what, when)
• ⚪ Rate limiting + concurrent account limits
• ⚪ Independent security review 💰

v1.x+ — Ecosystem

Grow beyond Google.

• ⚪ Plugin system for per-site action packs (Notion, GitHub, Stripe, ...)
• ⚪ MCP marketplace listing
• ⚪ Vision-based action suggestion (LLM looks at screenshot → proposes next action)
• ⚪ Cloud-hosted option (managed Ghostvault as a service) 💰

Contributing to the roadmap

• Pick anything marked 🏁 (good first issue) or 💛 (help wanted) — open a PR.
• For 💰 items (security review, hosting), we'd need sponsorship; reach out via Discussions.
• Have a use case we're missing? Open a discussion.

---

Contributing

Contributions welcome! See CONTRIBUTING.md for setup, conventions, and how to add a new tool.

pip install -e ".[dev]"
pytest -q
ruff check .

Adding a tool

1. Add the input model to src/ghostvault/inputs.py
2. Add the logic to src/ghostvault/tools.py (raise ToolError for expected failures)
3. Register it in src/ghostvault/server.py with @mcp.tool(name=..., annotations=...) and a thorough docstring
4. Add a test under tests/

The fingerprint lock is an invariant — any change that breaks it causes every account to look like a new device. tests/test_fingerprint.py guards it; keep it green.

---

Development

git clone https://github.com/mienetic/Ghostvault.git
cd Ghostvault
pip install -e ".[dev]"
python -m camoufox fetch   # one-time browser download
pytest -q                  # 17 unit tests
ruff check .               # lint

---

License

MIT © Ghostvault Contributors

---

<div align="center">

⚠️ Use responsibly. Ghostvault is a tool for managing your own accounts. Don't use it to access accounts you don't own, violate terms of service, or do anything illegal. You are responsible for how you use it.

</div>