Auth Vault

The Auth Vault provides secure credential storage for authentication workflows. Credentials are always encrypted at rest using AES-256-GCM, and the LLM never sees passwords - only profile names.

Quick Start

# Save credentials (password via stdin for security)
echo "mypassword" | agent-browser auth save github \
  --url https://github.com/login \
  --username myuser \
  --password-stdin

# Login using saved profile
agent-browser auth login github

Commands

Save Auth Profile

Store credentials for later use:

# Interactive (prompts for password)
agent-browser auth save <profile-name> \
  --url <login-url> \
  --username <username>

# Non-interactive (password via stdin)
echo "password" | agent-browser auth save <profile-name> \
  --url <login-url> \
  --username <username> \
  --password-stdin

# With custom selectors
agent-browser auth save myapp \
  --url https://myapp.com/login \
  --username user@example.com \
  --username-selector "#email" \
  --password-selector "#pwd" \
  --submit-selector "button[type=submit]" \
  --password-stdin

Navigate to login page and automatically fill credentials:

agent-browser auth login <profile-name>

This command:

Navigates to the profile’s URL
Fills username and password fields
Clicks the submit button
Updates lastLoginAt timestamp

List Profiles

View all saved auth profiles:

agent-browser auth list

Output:

Auth profiles:
  github
    URL: https://github.com/login
    Username: myuser
    Created: 2026-03-01T10:30:00.000Z
    Last login: 2026-03-02T08:15:00.000Z

Show Profile Details

View details for a specific profile (without password):

agent-browser auth show <profile-name>

Delete Profile

Remove a stored auth profile:

agent-browser auth delete <profile-name>

Storage Location

Auth profiles are stored at:

~/.agent-browser/auth/<profile-name>.json

Each profile file:

Has 0600 permissions (owner read/write only)
Is encrypted with AES-256-GCM
Contains username, password, URL, and selectors

Encryption

Automatic Encryption Key

If no encryption key is configured, agent-browser automatically generates one on first use:

~/.agent-browser/.encryption-key

This file:

Contains a 256-bit random key (64 hex characters)
Has 0600 permissions (owner read/write only)
Is used for all encryption operations

Manual Encryption Key

For production deployments, set an explicit encryption key:

# Generate a key
openssl rand -hex 32

# Set as environment variable
export AGENT_BROWSER_ENCRYPTION_KEY=<64-char-hex-key>

# Now save profiles
echo "password" | agent-browser auth save myapp \
  --url https://myapp.com/login \
  --username user \
  --password-stdin

Encryption Algorithm

Algorithm: AES-256-GCM
Key size: 256 bits (32 bytes)
IV size: 96 bits (12 bytes)
Authentication: AEAD with GCM auth tag

Auth profiles are stored as JSON with this structure:

{
  "version": 1,
  "encrypted": true,
  "iv": "base64-encoded-iv",
  "authTag": "base64-encoded-auth-tag",
  "data": "base64-encoded-ciphertext"
}

Decrypted Data Structure

The decrypted data contains:

interface AuthProfile {
  name: string;
  url: string;
  username: string;
  password: string;
  usernameSelector?: string;  // CSS selector for username field
  passwordSelector?: string;  // CSS selector for password field
  submitSelector?: string;    // CSS selector for submit button
  createdAt: string;          // ISO 8601 timestamp
  lastLoginAt?: string;       // ISO 8601 timestamp
}

Custom Selectors

By default, auth profiles use standard selectors:

Username: input[type="text"], input[type="email"]
Password: input[type="password"]
Submit: button[type="submit"], input[type="submit"]

For non-standard login forms, specify custom selectors:

agent-browser auth save myapp \
  --url https://myapp.com/login \
  --username user@example.com \
  --username-selector "#email-field" \
  --password-selector "input[name='pwd']" \
  --submit-selector ".login-btn" \
  --password-stdin

Profile Naming

Profile names must contain only:

Alphanumeric characters (a-z, A-Z, 0-9)
Hyphens (-)
Underscores (_)

Invalid characters are rejected to prevent directory traversal attacks.

Security Best Practices

1. Always Use stdin for Passwords

Never pass passwords as command-line arguments (they appear in shell history):

# Good: password via stdin
echo "password" | agent-browser auth save profile --password-stdin

# Bad: password in command line
agent-browser auth save profile --password "password"  # DON'T DO THIS

2. Backup Your Encryption Key

If you lose the encryption key, encrypted profiles cannot be recovered:

# Backup the auto-generated key
cp ~/.agent-browser/.encryption-key ~/secure-backup/

# Or use an environment variable and store it securely
export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)
echo $AGENT_BROWSER_ENCRYPTION_KEY >> ~/secure-backup/agent-browser-key.txt

3. Use Unique Keys Per Environment

Don’t share encryption keys between development, staging, and production:

# Development
export AGENT_BROWSER_ENCRYPTION_KEY=<dev-key>

# Production
export AGENT_BROWSER_ENCRYPTION_KEY=<prod-key>

4. Rotate Keys Periodically

To rotate keys:

# 1. List current profiles
agent-browser auth list > profiles-backup.txt

# 2. Export profiles (note: requires manual re-creation)
# 3. Delete old profiles
agent-browser auth delete profile1
agent-browser auth delete profile2

# 4. Set new key
export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)

# 5. Re-create profiles with new key
echo "password1" | agent-browser auth save profile1 --password-stdin ...

Programmatic API

Auth profiles can also be managed via the Node.js API:

import {
  saveAuthProfile,
  getAuthProfile,
  listAuthProfiles,
  deleteAuthProfile,
  updateLastLogin
} from 'agent-browser/auth-vault';

// Save profile
const result = saveAuthProfile({
  name: 'github',
  url: 'https://github.com/login',
  username: 'myuser',
  password: 'mypassword',
  usernameSelector: '#login_field',
  passwordSelector: '#password',
  submitSelector: 'input[type="submit"]'
});

console.log(result);
// {
//   name: 'github',
//   url: 'https://github.com/login',
//   username: 'myuser',
//   createdAt: '2026-03-02T10:00:00.000Z',
//   updated: false
// }

// Get profile (with password)
const profile = getAuthProfile('github');
if (profile) {
  console.log(profile.password); // Decrypted password
}

// List all profiles (without passwords)
const profiles = listAuthProfiles();
console.log(profiles);
// [
//   {
//     name: 'github',
//     url: 'https://github.com/login',
//     username: 'myuser',
//     createdAt: '2026-03-02T10:00:00.000Z',
//     lastLoginAt: '2026-03-02T12:00:00.000Z'
//   }
// ]

// Delete profile
const deleted = deleteAuthProfile('github');
console.log(deleted); // true if existed, false otherwise

// Update last login timestamp
updateLastLogin('github');

Environment Variables

Variable	Description	Example
`AGENT_BROWSER_ENCRYPTION_KEY`	64-character hex encryption key for AES-256-GCM	`openssl rand -hex 32`

If not set, a key is auto-generated at ~/.agent-browser/.encryption-key.

Troubleshooting

Encryption key required error

Encryption key required to read encrypted auth profiles.
Set AGENT_BROWSER_ENCRYPTION_KEY or ensure ~/.agent-browser/.encryption-key exists.

Solution: The profile was encrypted with a key that’s no longer available. Either:

Restore the original key file or environment variable
Delete the profile and re-create it

Invalid auth profile name error

Invalid auth profile name 'my/profile': only alphanumeric characters, hyphens, and underscores are allowed

Solution: Use only alphanumeric characters, hyphens, and underscores in profile names. If auth login fails to find elements:

Open the login page in headed mode:

agent-browser --headed open https://myapp.com/login

Inspect the page and identify correct selectors:
```
agent-browser snapshot
```

Update the profile with correct selectors:

echo "password" | agent-browser auth save myapp \
  --url https://myapp.com/login \
  --username user \
  --username-selector "#correct-selector" \
  --password-stdin

Get Started

Core Concepts

Commands

Security

Advanced

Integrations

Guides

Auth Vault

Auth Vault

Quick Start

Commands

Save Auth Profile

List Profiles

Show Profile Details

Delete Profile

Storage Location

Encryption

Automatic Encryption Key

Manual Encryption Key

Encryption Algorithm

Decrypted Data Structure

Custom Selectors

Profile Naming

Security Best Practices

1. Always Use stdin for Passwords

2. Backup Your Encryption Key

3. Use Unique Keys Per Environment

4. Rotate Keys Periodically

Programmatic API

Environment Variables

Troubleshooting

Encryption key required error

Invalid auth profile name error

See Also

Build docs developers (and LLMs) love

Get Started

Core Concepts

Commands

Security

Advanced

Integrations

Guides

​Auth Vault

​Quick Start

​Commands

​Save Auth Profile

​Login with Profile

​List Profiles

​Show Profile Details

​Delete Profile

​Storage Location

​Encryption

​Automatic Encryption Key

​Manual Encryption Key

​Encryption Algorithm

​Decrypted Data Structure

​Custom Selectors

​Profile Naming

​Security Best Practices

​1. Always Use stdin for Passwords

​2. Backup Your Encryption Key

​3. Use Unique Keys Per Environment

​4. Rotate Keys Periodically

​Programmatic API

​Environment Variables

​Troubleshooting

​Encryption key required error

​Invalid auth profile name error

​Login fails with custom selectors

​See Also

Build docs developers (and LLMs) love

Auth Vault

Quick Start

Commands

Save Auth Profile

Login with Profile

List Profiles

Show Profile Details

Delete Profile

Storage Location

Encryption

Automatic Encryption Key

Manual Encryption Key

Encryption Algorithm

Decrypted Data Structure

Custom Selectors

Profile Naming

Security Best Practices

1. Always Use stdin for Passwords

2. Backup Your Encryption Key

3. Use Unique Keys Per Environment

4. Rotate Keys Periodically

Programmatic API

Environment Variables

Troubleshooting

Encryption key required error

Invalid auth profile name error

Login fails with custom selectors

See Also