Skip to content

Examples

Runnable example scripts and copy-pasteable MCP client configs. Everything below lives in the repo under examples/.

Prerequisites

Every Python script assumes Ghostvault is installed and Camoufox's binary is fetched:

pip install -e ".[sdk]"          # SDK is an optional extra
python -m camoufox fetch         # downloads the patched Firefox binary

Scripts that touch real accounts also need a display available — the first-time sign-in (gv_sign_in) opens a real browser window for you to complete login + 2FA.

Provider system

Scripts for the provider-agnostic login system. See Custom providers.

Script What it shows
custom_provider_demo.py Create a custom provider recipe for any website + list/delete providers.
detect_login_demo.py Scan a login page for SSO buttons, form fields, 2FA, captcha + get recommendation.
record_login_demo.py Level 3: record a login flow → replay automatically next time.
session_health_demo.py Check session health + API call + JS eval + cookie reading.

SDK usage

Scripts that drive Ghostvault programmatically via the ghostvault-sdk package — no LLM in the loop. See Programmatic SDK.

Script What it shows
check_gmail.py Minimal smoke test: create an account, sign in, read Gmail. Launches the server as a subprocess and drives it end-to-end.
sdk_all_tools.py Comprehensive walkthrough: every gv_* tool demonstrated via the SDK client.
sdk_private_public.py The private/public gate flow: set a password, mark an account private, list while locked, unlock, logout.

Security

Scripts that exercise Ghostvault's security features — encryption at rest, auto-close, auto-lock, the private/public gate. See Encryption at rest and Private/public profiles.

Script What it shows
mcp_security_test.py Phase-1 security test: encryption + auto-close + auto-lock + lock/open cycle. Does NOT sign out or delete — session is preserved throughout.

Human-like interaction

Scripts that defeat behavioral bot detection (reCAPTCHA v3, login-form heuristics) by typing and clicking like a real user. See Human-like typing & clicks and Humanize policy.

Script What it shows
human_like_login.py Human-like login (any provider): per-char typing with log-normal cadence, occasional typos, inter-action pauses, Enter to submit, pre-click hover.
fill_long_form.py Filling a long form with varied typing speed per field, Tab between fields, different mistake rates, Shift+Tab to go back and fix.
captcha_friendly_browsing.py The "warm-up" pattern for reCAPTCHA v3: scroll, move, read content, click a non-target link, take a screenshot — THEN perform the target action.

Scraping

Scripts that use ephemeral (gv_open_ephemeral) sessions to scrape public pages without an account or login. See Anonymous scraping.

Script What it shows
scrape_public_page.py Simplest scraping pattern: open an ephemeral session, read text + screenshot, collect links, close. Defaults to Hacker News.
scrape_with_pagination.py Multi-step scrape flow on an ephemeral session: navigate, extract, scroll, click "Next", repeat. Sessions stay open across calls.

Lower-level / MCP integration

Scripts that speak raw JSON-RPC to the MCP server (mimicking a real MCP client) rather than using the SDK. Useful for understanding the wire protocol or debugging a client integration.

Script What it shows
mcp_e2e_test.py Spawns the server as a subprocess, performs the initialize handshake, calls one tool, reads the result back.
mcp_gmail_test.py Runs the full open → read Gmail → close sequence inside ONE server process (so the browser context stays open across tool calls).
test_login_session.py End-to-end test of the core contract: create → sign in → verify session → close → reopen → check the session survived the restart.

MCP client configs

Copy-pasteable config snippets for connecting each AI agent to Ghostvault. See examples/README.md for where each file goes and how to find the absolute path to your Python.

File Client
claude_desktop_config.json Claude Desktop
cursor_config.json Cursor
cline_mcp_settings.json Cline (VS Code)
vscode_mcp.json VS Code (native Agent mode)
zcode_config.json ZCode
continue_dev_config.json Continue.dev
hermes_config.json Hermes Agent (Nous Research)
openclaw_config.json OpenClaw
agent_prompts.md Prompt snippets to paste into your agent

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