> ## Documentation Index
> Fetch the complete documentation index at: https://docs.webrun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser Profiles

> Persist cookies, local storage, and browser state across sessions using an environment's browser profile

Every environment includes a browser profile that stores persistent Chrome data — cookies, local storage, extensions, IndexedDB, cached credentials. When you attach an environment to a session, the browser starts with that saved state already loaded.

**Without a profile:** every session opens a blank browser. You log in each time, re-accept cookie banners, and lose any site-specific data.

**With a profile:** sessions pick up where you left off. Login cookies persist, preferences carry over, and previously saved data is available immediately.

***

## Use Cases

### Skip Repeated Logins

Log in once, then reuse that session state across future tasks:

1. Create an environment and run a session with it attached
2. Log in to the target site during the session
3. The profile saves your login cookies automatically when the session ends
4. Future sessions on the same environment start already authenticated

### Preserve Site Preferences

Cookie consent choices, language settings, dark mode preferences, and other site-specific configuration carry over between sessions without any extra setup.

### Maintain Application State

For e-commerce or SaaS workflows, keep cart contents, workspace configurations, or application state intact between sessions.

***

## Profile Status

Each environment tracks the state of its browser profile:

| Status      | Meaning                                                                                    |
| ----------- | ------------------------------------------------------------------------------------------ |
| `empty`     | No browser data yet — sessions start with a clean browser and populate the profile on exit |
| `uploading` | A profile upload is in progress                                                            |
| `ready`     | Has browser data — sessions load the saved state before executing tasks                    |

<Tip>
  You can attach an environment with status `empty` to a session. The session starts with a clean browser, and the profile is populated automatically when the session ends.
</Tip>

***

## Populating a Profile

There are three ways to get browser data into an environment's profile:

| Method                                                                                       | When to use                                                                                             |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Run a session**                                                                            | Easiest — just run a session with the environment attached, log in, and the profile saves automatically |
| **[Sync from local Chrome](#sync-from-local-chrome)**                                        | You're already logged into sites locally and want to transfer that state                                |
| **[Upload a `.tar.gz` archive](/environments/environments-api#upload-browser-profile-data)** | You have an exported Chrome profile archive to restore                                                  |

***

## Using a Profile in a Session

Pass `environmentId` when starting a session or task. The browser loads the profile's saved data before executing anything:

```bash theme={null}
curl -X POST https://connect.webrun.ai/start/run-task \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environmentId": "<ENV_ID>",
    "prompt": "Go to amazon.com and check my order status"
  }'
```

After the session ends, any changes to the browser state (new cookies, updated local storage) are saved back to the profile automatically.

***

## Sync from Local Chrome

The sync command packages your local Chrome browser data and uploads it directly to an environment. This is the fastest way to populate a profile if you're already logged into sites locally.

### Sync to an Existing Environment

If you've already [created an environment](/environments/environments-api#create-an-environment), sync your local browser data to it:

```bash theme={null}
bash <(curl -fsSL https://webrun.ai/sync/sync.sh) --environmentId <environmentId> --key <apiKey>
```

| Parameter         | Description                          |
| ----------------- | ------------------------------------ |
| `--environmentId` | The ID of the environment to sync to |
| `--key`           | Your WebRun API key                  |

This replaces any existing profile data in the environment. The status changes to `ready` once the upload completes.

### Create and Sync in One Step

To create a new environment and upload your local data in a single command, omit `--environmentId`:

```bash theme={null}
bash <(curl -fsSL https://webrun.ai/sync/sync.sh) --key <apiKey>
```

This creates a new environment, uploads your Chrome profile, and returns the new environment ID.

<Tip>
  Save the environment ID returned by the command — you'll need it to pass as `environmentId` when starting sessions.
</Tip>

***

## Limits

| Resource              | Limit             |
| --------------------- | ----------------- |
| Environments per user | 20                |
| Profile upload size   | 500 MB            |
| Accepted format       | `.tar.gz`, `.tgz` |

***

<CardGroup cols={2}>
  <Card title="Environments Overview" icon="box" href="/environments/overview">
    What environments are and when to use them
  </Card>

  <Card title="Environments API" icon="code" href="/environments/environments-api">
    Create environments and upload profile data via the API
  </Card>
</CardGroup>