Skip to main content

​
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.

No Local Chrome

Run tasks from any server or script without a desktop browser

Scalable

Spin up multiple cloud browsers in parallel for high-throughput automation

Persistent Sessions

Sessions stay alive after your script exits. Reconnect later to check results

​
Getting Started with the SDK

​
Opening a Cloud Browser

Use open_and_initialize_cloud_browser_window() to create a cloud browser session: 
import asyncio
from narada import Narada

async def main() -> None:
    async with Narada() as narada:
        # Open a cloud browser (no local Chrome needed)
        window = await narada.open_and_initialize_cloud_browser_window(
            session_name="my-research-session",  # Optional: label for the session
            session_timeout=3600,                 # Optional: timeout in seconds (default varies)
        )

        # Run tasks just like a local browser
        response = await window.agent(
            prompt='Search for "LLM Compiler" on Google and tell me who the authors are'
        )

        print("Response:", response.text)

if __name__ == "__main__":
    asyncio.run(main())
The agent() method works identically on cloud browser windows as on local browser windows. All SDK features (structured output, GIF recording, MCP servers, variables) work the same way.

​
Session Lifecycle

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

Create

Call open_and_initialize_cloud_browser_window() to spin up a new cloud browser.
2

Run tasks

Use agent(), go_to_url(), get_screenshot(), and all other SDK methods as usual.
3

Session persists

When your script exits the async with Narada() context manager, the cloud session keeps running. It doesn’t shut down when your code exits.
4

Reconnect (optional)

You can reconnect to a running session from another script using RemoteBrowserWindow:
from narada import RemoteBrowserWindow

# Reconnect using saved IDs
window = RemoteBrowserWindow(
    browser_window_id="saved-window-id",
    cloud_browser_session_id="saved-session-id",
)

# Continue running tasks
response = await window.agent(prompt="What page am I on?")
5

Close

Explicitly close the session when you’re done, or let it auto-expire after the configured timeout.
await window.close()  # Stops the cloud session
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.

​
Saving Session IDs for Later

After creating a cloud browser, save the session identifiers so you can reconnect later: 
async with Narada() as narada:
    window = await narada.open_and_initialize_cloud_browser_window(
        session_name="data-extraction"
    )

    # Save these for later reconnection
    session_id = window.cloud_browser_session_id
    window_id = window.browser_window_id
    print(f"Session: {session_id}, Window: {window_id}")

    # Run your task...
    await window.agent(prompt="Navigate to example.com and extract the main heading")

# Session is still running after exiting the context manager!
# Reconnect later with RemoteBrowserWindow using saved IDs.

​
Using Cloud Browsers via the REST API

You can also use cloud browsers through the Remote Dispatch API by setting executionMode to "cloud_browser": 
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"
  }'
When using executionMode: "cloud_browser", you do not need to provide a browserWindowId. A fresh cloud browser session is created automatically.

​
Execution Modes Compared

The Remote Dispatch API supports three execution modes:
ModeDescriptionRequires Extension?Requires browserWindowId?
"client"Runs in a local browser with the Narada extensionYesYes
"cloud"Runs server-side without a browser (limited to non-browser tasks)NoNo
"cloud_browser"Creates a cloud-hosted browser sessionNoNo

​
Managing Sessions in the Dashboard

You can view and manage your cloud browser sessions from the Narada web dashboard:
Cloud Browser Sessions dashboard showing active sessions
  • 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

Always Close Sessions

Call await window.close() when done to stop billing. Don’t rely solely on timeout.

Set Reasonable Timeouts

Use session_timeout to auto-expire sessions you might forget to close manually.

Name Your Sessions

Use session_name to label sessions so you can identify them in the dashboard.

Use for CI/CD

Cloud browsers are perfect for automated pipelines, no desktop or extension needed.

​
Troubleshooting

  • Verify your API key is valid and has sufficient credits
  • Check your internet connection
  • Contact support if the issue persists
  • Increase session_timeout when creating the session
  • Ensure your tasks complete within the timeout window
  • For long-running tasks, consider breaking them into smaller steps
  • Verify the session hasn’t 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

​
Next Steps

Remote Dispatch API

Use cloud browsers via the REST API with executionMode: "cloud_browser"

Parallel Execution

Run multiple cloud browser sessions in parallel for high-throughput automation

Remote Browser Control

Control remote browsers on other machines using RemoteBrowserWindow