Skip to content

First sign-in

This page walks you through the first end-to-end task in Ghostvault: creating an account slot, signing in, and reading your inbox. The examples below use Google (provider='google') since it's a common built-in provider, but the same flow works for any website. By the end you'll have a persistent session you can reuse forever.

You'll need Ghostvault installed and connected to an agent first.

How sign-in works

You complete the login yourself

When you sign in, Ghostvault opens a real browser window on your machine. You type your password and complete 2FA in that window — Ghostvault never sees, touches, or stores your password. Only the resulting session cookies are saved to the account's persistent profile.

Because the site sees a brand-new device fingerprint on first login, expect a 2FA challenge. This is one-time per account — after the session is saved, reopening reuses it without re-authenticating.

The flow has three steps:

  1. Create an account slot — gv_create_account generates a locked fingerprint + empty profile. No sign-in yet.
  2. Sign in — gv_sign_in opens a browser window; you complete login + 2FA there.
  3. Verify — gv_read_gmail (for Google accounts) confirms the session works.

You don't call these tools directly — you just talk to your agent in plain language and it calls them for you.

Step 1 — Create an account slot

Tell your agent to create an account. Give it a human-friendly label:

You: Create an account called Work (e.g. provider='google').

The agent calls gv_create_account:

gv_create_account(name="Work")

It returns something like:

{
  "id": "acc_abc123",
  "name": "Work",
  "status": "created",
  "message": "Account created. Call gv_sign_in to open a login window."
}

The account now exists in Ghostvault with a locked fingerprint (OS, screen size, noise seeds) that will follow it across every launch. But it's not signed in yet.

Picking the OS

gv_create_account pins a fingerprint OS (windows / macos / linux). If you omit it, Ghostvault uses GHOSTVAULT_DEFAULT_OS (which defaults to auto = your host OS). For most users auto is fine. See Configuration basics.

Step 2 — Sign in

Tell the agent to sign in:

You: Sign in to Work.

The agent calls gv_sign_in with the account id from step 1:

gv_sign_in(account_id="acc_abc123")

A real browser window opens on your machine. The tool blocks — the agent waits while you complete login.

A visible window is required for sign-in

gv_sign_in needs a visible browser window so you can type your credentials and complete 2FA. Make sure GHOSTVAULT_HEADLESS=false is set (it's the default). If no window appears, see troubleshooting.

In that window:

  1. Enter your email and password yourself (e.g. your Google credentials, or any other provider's).
  2. Complete 2FA — the provider will almost always challenge a new device. Approve the prompt, enter the SMS code, or use your authenticator app. This is expected and one-time.
  3. Wait for the window to settle on a logged-in page (e.g. the account chooser or your provider's home).

Ghostvault detects the successful login, saves the session to the account's persistent profile, and returns:

{
  "status": "signed_in",
  "email": "you@gmail.com",
  "message": "Signed in as you@gmail.com."
}

From now on, this account is active — all browser tools target it until you switch accounts.

Timeout

You have GHOSTVAULT_LOGIN_TIMEOUT seconds (default 300 = 5 minutes) to finish login + 2FA. If you need longer (slow 2FA, fumbling for your phone), bump it in your client's env block.

Step 3 — Verify with Gmail

Confirm the session works by reading your inbox:

You: Read my latest 5 emails.

The agent calls gv_read_gmail:

gv_read_gmail(limit=5)

You'll get back a summary like:

[
  {"id": "...", "subject": "Your weekly digest", "sender": "news@x.com", "snippet": "...", "date": "..."},
  {"id": "...", "subject": "Re: project update", "sender": "colleague@y.com", "snippet": "...", "date": "..."}
]

If you see your real messages, the session is live and you're done.

If Gmail comes back empty

Gmail's DOM changes often and gv_read_gmail is best-effort. If it returns nothing, fall back to:

"Open mail.google.com and take a screenshot." The agent will call gv_open_url + gv_get_page_content(include_screenshot=true) so it (and you) can see the inbox directly.

The full conversation

Here's the complete first-time flow, end to end:

1. You:   "Create an account called Work (e.g. provider='google')"
   Agent: calls gv_create_account
   Agent: "Done — account acc_abc123 created. Call gv_sign_in to sign in."

2. You:   "Sign in to Work"
   Agent: calls gv_sign_in
   [a browser window opens on your machine]
   You:   complete login + 2FA in that window
   Agent: "Signed in as you@gmail.com."

3. You:   "Read my latest 5 emails"
   Agent: calls gv_read_gmail(limit=5)
   Agent: returns the inbox summary

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

After the first sign-in

Once an account is signed in, you rarely need gv_sign_in again. To reopen the account in a later session (after the browser was closed), the agent uses gv_open_account instead — it reuses the saved session with no login window and no 2FA:

You: Open my Work account.

gv_open_account(account_id="acc_abc123")

The session persists across Ghostvault restarts and machine reboots, because it lives in the account's profile directory on disk.

Reusing the session on SSO-enabled sites

The saved session isn't just for the provider's own sites — any SSO-enabled site will auto-SSO. For example, with a Google account, try:

You: Open notion.so using my Work Google login.

The agent calls gv_open_url("https://notion.so"), and Notion's "Continue with Google" button picks up the active account's session automatically. The same applies to any provider's SSO (GitHub, etc.) or any login-gated site. From there the agent can navigate the site like any other page.

Troubleshooting

No browser window appears on gv_sign_in.

The most common cause is GHOSTVAULT_HEADLESS=true. Set it to false in your client's env block (see Configuration basics) and restart the client. Headless mode has no window to type into — sign-in can't work there.

"Login timed out" before I finished 2FA.

Raise the timeout. In your client config's env block:

"env": { "GHOSTVAULT_LOGIN_TIMEOUT": "600" }

That gives you 10 minutes. Restart the client and try again.

"Session not authenticated" later on.

Sessions can expire or get invalidated (e.g. if you revoke access from the provider's security page). Re-run gv_sign_in for that account to refresh it.

The agent says "No active account".

You need to sign in (or open) an account first. Tell the agent: "Sign in to [account name]" or "Open my [account name] account."

Two windows for the same account.

Not possible — Ghostvault enforces one browser context per account to avoid corrupting the profile. Switch accounts instead of opening the same one twice.

Next steps