Auth States

Give the agent browser login states so it can access authenticated sites during sessions.

Auth states let you provide the agent with saved browser cookies for sites that require login — your deployed app, Vercel, GitHub, or any third-party service. When a session starts, these cookies are injected into the sandbox browser so the agent can access authenticated pages without needing to log in manually.

Adding Auth States

You can add auth states from the Agent Environment settings panel. There are two methods:

Record in Browser

The easiest way to capture login cookies. This opens a real browser on the server that you control through your dashboard.

1. Click Record in browser
2. Enter the login URL (e.g. https://vercel.com/login)
3. Give it a label (auto-detected from the URL if left blank)
4. A browser window opens in the dashboard — log in normally
5. Once signed in, click Done to capture all cookies
6. Click Save to apply

The recording session captures all cookies including HttpOnly session cookies that browser extensions can't access. Sessions auto-expire after 10 minutes if left idle.

Paste from CLI

For sites where you already have cookies exported, or when you prefer to capture them locally:

1. Click Paste from CLI
2. Run the Playwright command in your terminal:

npx playwright codegen --save-storage=auth.json https://your-site.com

3. A browser opens. Navigate to your login page and sign in.
4. Close the browser. Playwright writes auth.json with all cookies.
5. Copy the contents of auth.json and paste into the dashboard
6. Add a label (e.g. "Vercel", "My App") and click Add
7. Click Save to apply

Managing Auth States

Each auth state shows its label, cookie count, and capture date. You can add multiple auth states for different sites — the agent gets all of them injected into its browser at session start.

Auth states are encrypted at rest and scoped to the environment they're configured on.

How It Works During Sessions

When a session starts with auth states configured:

1. The saved cookies are decrypted and injected into the sandbox Chromium browser
2. The agent can navigate to authenticated pages immediately — no login flow needed
3. If the agent needs to access credentials during the session, the desktop stream is temporarily blacked out to protect sensitive data on screen
4. The blackout auto-releases after 60 seconds as a safety measure

Credential Vault

During a session, the agent also has access to a built-in credential vault with four tools:

When the agent calls get-auth, the desktop stream blacks out automatically to prevent credentials from being visible on screen. The agent can handle full login flows including 2FA — it generates TOTP codes from stored secrets and reads verification emails.

When to Use Auth States

Tips

• Cookies expire. If the agent starts getting 401s or redirect loops, recapture the auth state with a fresh login.
• One per site. Each label should be unique. To update cookies for a site, remove the old entry and add a new one.
• General chat too. Auth states work for both repo-scoped sessions and general chat sessions — any session where the agent uses a desktop sandbox.

Next Steps