FAQ

General

Do I need to login to Google before using other providers?

No. Each profile is a container that holds sessions for any website equally. Use gv_create_account(provider="github") + gv_sign_in to login GitHub directly. Or create a custom provider for any website via gv_create_provider. Google is just one of the built-in providers — it's not a "parent" that other providers depend on. See Custom providers.

Can Ghostvault create new accounts automatically?

No, and intentionally so. Signup flows use phone verification, IP reputation, behavioral ML (reCAPTCHA v3), and cross-account correlation — automating them reliably is not feasible and risks getting accounts banned. Ghostvault is a session manager, not an account creator. Create accounts manually, then use Ghostvault to manage their sessions.

Can Ghostvault change my IP address?

No browser can change the TCP source IP — that's set by the OS kernel, not the browser. Camoufox (and Ghostvault) can spoof everything except the source IP: locale, timezone, fonts, WebGL, WebRTC leak gate, etc. For IP rotation, use a proxy or VPN. See Anonymous scraping for the proxy setup.

Is this legal?

Ghostvault is a tool for managing browser sessions you already have. It does not bypass authentication, scrape paywalled content, or create fake accounts. Using it to manage your own accounts is fine. Using it to evade anti-bot systems on sites where you're violating terms of service is your responsibility. See the Apache 2.0 + Commons Clause License — which includes a full liability disclaimer.

Does it work with Chromium / Chrome?

No. Ghostvault is built on Camoufox, which is a Firefox fork. Camoufox patches Firefox at the C++ level — the same approach is not portable to Chromium without a complete rewrite.

What's the license?

Apache 2.0 + Commons Clause — free to use, modify, and distribute for personal, research, educational, and internal use. Selling the software as a product or paid service (SaaS, paid hosting) requires a commercial license. The authors are not liable for misuse. See LICENSE for the full terms + liability disclaimer.

Setup

The installer failed — what do I do?

See Installation → Troubleshooting. Common issues: Python version too old (< 3.11), missing build tools, camoufox fetch timeout (re-run it). The manual install path is always available as a fallback.

My agent can't see the Ghostvault tools

Make sure the MCP config JSON is valid and points to the right Python. See Connect your agent. The most common issue is the command path — use the absolute path to your Python (which python3).

Do I need to run camoufox fetch separately?

The installer does it for you. If you installed manually, run python -m camoufox fetch once to download the Camoufox binary (~300MB).

Security

If someone steals my laptop, are my Google sessions safe?

Only if you enabled encryption at rest. Without it, the persistent profiles under ~/.ghostvault/profiles/ contain plaintext session cookies — anyone with disk access can steal them. With encryption, the profiles are AES-256-GCM archives and the key is in your OS keychain.

What happens if I forget my private/public gate password?

After 5 wrong attempts, all private profiles are permanently deleted (this is the brute-force protection). There is no recovery path — that's what makes it secure. Public profiles are unaffected. If you lose the password, you'll need to re-create the private accounts and re-sign-in.

Does Ghostvault send my data anywhere?

No. Ghostvault is local-first. Sessions, cookies, fingerprints, and logs all live under ~/.ghostvault on your machine. The only network traffic is: (1) the browser itself visiting the URLs you tell it to, (2) the update check on startup (GitHub API, no telemetry).

Anti-detect

Will Google detect that I'm using an automated browser?

Camoufox is one of the most effective anti-detect browsers available — it patches Firefox at the C++ level, so spoofed values appear native (no JS to detect). However, no tool is undetectable. The main remaining tells are:

1. Behavioral — instant paste typing, no mouse movement, no scroll. Use humanize=True on fill/click tools and the reCAPTCHA warm-up pattern.
2. IP reputation — datacenter IPs, known VPN exits. Use a residential proxy.
3. Cross-account correlation — same phone number, same IP, same fingerprint across accounts. Use separate identities per account.

What's the difference between humanize=True (Camoufox) and humanize=True (Ghostvault fill/click)?

Camoufox's humanize covers mouse movement (bezier curves + jitter) at the C++ level. Ghostvault's per-call humanize on gv_fill_input / gv_click_element covers typing cadence (log-normal distribution), typo+correction, and pre-click hover — things Camoufox doesn't do. You want both. See Human-like interaction.

Can I use the same fingerprint for multiple accounts?

No. Each account gets its own locked fingerprint (generated once, persisted in the bundle JSON). Reusing the same fingerprint across accounts would let Google correlate them — defeating the purpose.

Scraping

Can I scrape without creating an account?

Yes — use gv_open_ephemeral. It opens a throwaway Camoufox session with a random identity, no profile, no login. All browser tools work on it. See Anonymous scraping.

How many concurrent ephemeral sessions can I run?

Default is 3 (GHOSTVAULT_EPHEMERAL_MAX_CONCURRENT). Each session is a full Firefox process (~200-400MB RAM). Raise the limit if you have the resources, but watch your memory.

Do ephemeral sessions auto-close?

Yes — after 5 minutes idle (GHOSTVAULT_EPHEMERAL_AUTO_CLOSE_MINUTES). They also close on server shutdown. Call gv_close_ephemeral explicitly for immediate cleanup.