Skip to main content
The GSD Browser authentication vault stores credentials in an encrypted format on disk, separate from your automation scripts and prompts. Instead of embedding usernames, passwords, or tokens in agent instructions or environment variables, you store them once with a vault key and reference them by profile name in every subsequent run. The vault also integrates with session state — log in once, save the authenticated browser context, and restore it instantly in later runs without repeating the login flow.

​
Store Credentials

Add a credential entry to the vault using a logical profile name: 
gsd-browser vault-save \
  --profile myapp-login \
  --url https://app.example.com/login \
  --username user@example.com \
  --password secret
Credentials are encrypted at rest in the GSD Browser config directory using the key defined by GSD_BROWSER_VAULT_KEY. Never pass raw credentials in agent prompts or CLI history — store them once here and reference the profile name everywhere else.
Set GSD_BROWSER_VAULT_KEY to a strong, unique value before storing any credentials. If you lose the vault key, stored credentials cannot be recovered. For MCP clients, set the key in the "env" block of your MCP server configuration so the daemon always starts with the correct key.

​
Log In Automatically

Use a stored credential profile to navigate to the configured login page and complete the form automatically: 
gsd-browser vault-login --profile myapp-login
The vault-login command navigates to the URL stored in the profile, finds the login form, fills the username and password fields with the stored values, and submits the form. No credentials appear in your shell history or process list.
In MCP mode, use the browser_vault_login tool with the same profile parameter. The robust_login_flow built-in prompt also integrates with the vault automatically.

​
Save and Restore Session State

After a successful login, save the authenticated browser context so future runs can skip the login step entirely:
1

Log in

gsd-browser vault-login --profile myapp-login
2

Verify you are logged in

gsd-browser assert --checks '[{"kind": "url_contains", "text": "/dashboard"}]'
3

Save the session state

gsd-browser save-state --name myapp-authenticated
GSD Browser writes a session state file (cookies, local storage, session storage) to the config directory.
4

Restore in future runs (skip login)

gsd-browser restore-state --name myapp-authenticated
gsd-browser navigate https://app.example.com/dashboard
The browser context loads with the saved authentication state. The login page is bypassed entirely.
Combine named sessions with session state for maximum efficiency. Use --session myapp so the restored state, action cache, and browser context all share the same isolated namespace across multiple automation runs.

​
List Vault Profiles

List all stored credential profiles (values are never shown): 
gsd-browser vault-list

​
Full Authenticated Automation Workflow

1

Store credentials once

gsd-browser vault-save \
  --profile myapp-login \
  --url https://app.example.com/login \
  --username user@example.com \
  --password secret
2

Log in and save state

gsd-browser vault-login --profile myapp-login
gsd-browser wait-for --condition url_contains --value /dashboard
gsd-browser save-state --name myapp-authenticated
3

Restore state in every subsequent run

gsd-browser restore-state --name myapp-authenticated
gsd-browser navigate https://app.example.com/dashboard
# Continue automation from the authenticated state

​
Best Practices for AI Agents

Never pass credentials in prompts

Store credentials with vault-save during initial setup. In all agent prompts and MCP calls, reference the vault profile name — the agent never sees the actual password.

Use restore-state to skip login

For repeated automation runs, restore a saved session instead of logging in each time. This is faster and eliminates the risk of triggering bot-detection on the login page.

Re-login when sessions expire

Session state has a finite lifetime. When restore-state followed by a navigate lands on the login page, repeat the vault-login → save-state cycle to refresh the stored state.

Validate redaction before sharing

Run gsd-browser recording-validate on any evidence bundle that was captured in an authenticated session. The validator confirms that cookies and tokens were stripped before export.