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

# Cloud Browser Sessions

> Run browser automation tasks in serverless cloud browsers without a local Chrome installation

## What are Cloud Browser Sessions?

Cloud Browser Sessions let you run Narada automation tasks in **serverless, cloud-hosted browsers** without a local Chrome installation or Narada extension. This is ideal for server-side automation, CI/CD pipelines, and running tasks at scale.

<CardGroup cols={3}>
  <Card title="No Local Chrome" icon="cloud">
    Run tasks from any server or script without a desktop browser
  </Card>

  <Card title="Scalable" icon="layer-group">
    Spin up multiple cloud browsers in parallel for high-throughput automation
  </Card>

  <Card title="Persistent Sessions" icon="clock">
    Sessions stay alive until you close them or they time out
  </Card>
</CardGroup>

## Getting Started with the SDK

Use `CloudBrowserEnvironment` to create a hosted browser session, then bind an `Agent` to that environment:

```python theme={null}
import asyncio

from narada import Agent, CloudBrowserEnvironment


async def main() -> None:
    env = CloudBrowserEnvironment(
        session_name="my-research-session",
        session_timeout=3600,
    )
    agent = Agent(environment=env)

    try:
        response = await agent.run(
            prompt=(
                'Search for "LLM Compiler" on Google and open the first arXiv paper '
                "on the results page, then tell me who the authors are."
            )
        )

        print("Response:", response.text)
        print("Session ID:", env.cloud_browser_session_id)
        print("Window ID:", env.browser_window_id)
    finally:
        await env.close()


if __name__ == "__main__":
    asyncio.run(main())
```

<Note>
  `Agent.run()`, `go_to_url()`, `get_screenshot()`, structured output, GIF recording, MCP servers, and input variables work the same way on cloud browser environments as they do on local browser environments.
</Note>

## Session Lifecycle

Cloud browser sessions have a different lifecycle than local browser windows:

<Steps>
  <Step title="Create an environment">
    Construct `CloudBrowserEnvironment(session_name=..., session_timeout=...)`.
  </Step>

  <Step title="Run tasks">
    Create `Agent(environment=env)` and call `agent.run()`, `agent.go_to_url()`, `agent.get_screenshot()`, or other agent methods.
  </Step>

  <Step title="Save IDs when needed">
    After the environment initializes, read `env.cloud_browser_session_id` and `env.browser_window_id` if you need to reconnect later.
  </Step>

  <Step title="Reconnect">
    Use `RemoteBrowserEnvironment` with the saved IDs to reconnect to a running cloud browser session.
  </Step>

  <Step title="Close">
    Call `await env.close()` when you're done. If you reconnect with `RemoteBrowserEnvironment`, calling `close()` on that environment stops the cloud session.
  </Step>
</Steps>

<Warning>
  **Cost Warning**: Cloud browser sessions accrue costs until they are stopped or time out. Always close sessions when you're done to avoid unexpected charges.
</Warning>

## Reconnect to a Cloud Session

Save the session identifiers after creating a cloud browser:

```python theme={null}
env = CloudBrowserEnvironment(session_name="data-extraction")
agent = Agent(environment=env)

await env.start()

session_id = env.cloud_browser_session_id
window_id = env.browser_window_id
print(f"Session: {session_id}, Window: {window_id}")

await agent.run(prompt="Navigate to example.com and extract the main heading")

# Intentionally leave the cloud session running so you can reconnect later.
# Call env.close() after the final reconnecting script is done.
```

Reconnect later with `RemoteBrowserEnvironment`:

```python theme={null}
import asyncio

from narada import Agent, RemoteBrowserEnvironment


async def main() -> None:
    env = RemoteBrowserEnvironment(
        browser_window_id="saved-browser-window-id",
        cloud_browser_session_id="saved-cloud-session-id",
    )
    agent = Agent(environment=env)

    try:
        response = await agent.run(prompt="What page am I currently on?")
        print(response.text)
    finally:
        await env.close()


if __name__ == "__main__":
    asyncio.run(main())
```

<Note>
  Closing a `RemoteBrowserEnvironment` with `cloud_browser_session_id` stops the backing cloud session.
</Note>

## Download Files from a Session

Use `get_downloaded_files()` on a cloud-backed environment:

```python theme={null}
downloaded_files = await env.get_downloaded_files()

for item in downloaded_files:
    print(item.file_name, item.size, item.download_url)
```

## Using Cloud Browsers via the REST API

You can also use cloud browsers through the [Remote Dispatch API](/api-reference/remote-dispatch) by setting `executionMode` to `"cloud_browser"`:

```bash theme={null}
curl -X POST 'https://api.narada.ai/fast/v2/remote-dispatch' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "prompt": "/Operator navigate to example.com and extract the heading",
    "executionMode": "cloud_browser",
    "cloudBrowserSessionName": "my-api-session"
  }'
```

<Note>
  When using `executionMode: "cloud_browser"`, you do **not** need to provide a `browserWindowId`. A fresh cloud browser session is created automatically.
</Note>

## Execution Modes Compared

The Remote Dispatch API supports three execution modes:

| Mode              | Description                                       | Requires Extension? | Requires browserWindowId? |
| ----------------- | ------------------------------------------------- | ------------------- | ------------------------- |
| `"client"`        | Runs in a local browser with the Narada extension | Yes                 | Yes                       |
| `"cloud"`         | Runs server-side without a browser                | No                  | No                        |
| `"cloud_browser"` | Creates a cloud-hosted browser session            | No                  | No                        |

## Managing Sessions in the Dashboard

You can view and manage your cloud browser sessions from the Narada web dashboard:

<Frame>
  <img src="https://mintcdn.com/naradaai/pruXFeeEFZta0axq/images/cloud-browser-sessions.png?fit=max&auto=format&n=pruXFeeEFZta0axq&q=85&s=7afd2771a4707132cf37d2188d677ce7" alt="Cloud Browser Sessions dashboard showing active sessions" width="2490" height="1394" data-path="images/cloud-browser-sessions.png" />
</Frame>

* **View active sessions** with their status, name, and creation time
* **Watch live sessions** via the session player
* **Replay completed sessions** to review what the agent did
* **Download action traces** as JSON for debugging
* **Download files** that were saved during the session
* **Stop sessions** that are no longer needed

## Best Practices

<CardGroup cols={2}>
  <Card title="Always Close Sessions" icon="circle-xmark">
    Call `await env.close()` when done to stop billing. Do not rely only on timeout.
  </Card>

  <Card title="Set Reasonable Timeouts" icon="hourglass">
    Use `session_timeout` to auto-expire sessions you might forget to close manually.
  </Card>

  <Card title="Name Your Sessions" icon="tag">
    Use `session_name` to label sessions so you can identify them in the dashboard.
  </Card>

  <Card title="Use for CI/CD" icon="gears">
    Cloud browsers are suited for automated pipelines with no desktop browser or extension.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Session creation fails">
    * Verify your API key is valid and has sufficient credits
    * Check your internet connection
    * Contact support if the issue persists
  </Accordion>

  <Accordion title="Session times out unexpectedly">
    * Increase `session_timeout` when creating the session
    * Ensure your tasks complete within the timeout window
    * For long-running tasks, break them into smaller steps
  </Accordion>

  <Accordion title="Cannot reconnect to a session">
    * Verify the session has not been stopped or timed out
    * Check that you're using the correct `cloud_browser_session_id` and `browser_window_id`
    * Sessions that have expired cannot be reconnected
  </Accordion>
</AccordionGroup>