> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vercel-labs/agent-browser/llms.txt
> Use this file to discover all available pages before exploring further.

# Auth Vault

> Secure credential storage with AES-256-GCM encryption

# 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

```bash theme={null}
# 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:

```bash theme={null}
# 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
```

### Login with Profile

Navigate to login page and automatically fill credentials:

```bash theme={null}
agent-browser auth login <profile-name>
```

This command:

1. Navigates to the profile's URL
2. Fills username and password fields
3. Clicks the submit button
4. Updates `lastLoginAt` timestamp

### List Profiles

View all saved auth profiles:

```bash theme={null}
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):

```bash theme={null}
agent-browser auth show <profile-name>
```

### Delete Profile

Remove a stored auth profile:

```bash theme={null}
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:

```bash theme={null}
# 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:

```json theme={null}
{
  "version": 1,
  "encrypted": true,
  "iv": "base64-encoded-iv",
  "authTag": "base64-encoded-auth-tag",
  "data": "base64-encoded-ciphertext"
}
```

### Decrypted Data Structure

The decrypted data contains:

```typescript theme={null}
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:

```bash theme={null}
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):

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# Development
export AGENT_BROWSER_ENCRYPTION_KEY=<dev-key>

# Production
export AGENT_BROWSER_ENCRYPTION_KEY=<prod-key>
```

### 4. Rotate Keys Periodically

To rotate keys:

```bash theme={null}
# 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:

```typescript theme={null}
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

<table>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Description</th>
      <th>Example</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>AGENT\_BROWSER\_ENCRYPTION\_KEY</code></td>
      <td>64-character hex encryption key for AES-256-GCM</td>
      <td><code>openssl rand -hex 32</code></td>
    </tr>
  </tbody>
</table>

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:

1. Restore the original key file or environment variable
2. 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.

### Login fails with custom selectors

If `auth login` fails to find elements:

1. Open the login page in headed mode:
   ```bash theme={null}
   agent-browser --headed open https://myapp.com/login
   ```

2. Inspect the page and identify correct selectors:
   ```bash theme={null}
   agent-browser snapshot
   ```

3. Update the profile with correct selectors:
   ```bash theme={null}
   echo "password" | agent-browser auth save myapp \
     --url https://myapp.com/login \
     --username user \
     --username-selector "#correct-selector" \
     --password-stdin
   ```

## See Also

* [Security Overview](/security/overview) - All security features
* [Domain Allowlist](/security/domain-allowlist) - Network restriction
* [Action Policies](/security/action-policies) - Action gating