Skip to content

Remote browser

The remote browser is available for eligible active rentals. The customer SDK creates the session, waits for readiness, connects to it, and stops it when finished.

Lifecycle

  1. Obtain a device from GET /v1/devices.
  2. Create a session with POST /v1/devices/{id}/browser.
  3. Poll GET /v1/devices/{id}/browser until the session is ready.
  4. Connect with the returned connect_url and one-time connect_token.
  5. Stop the session with DELETE /v1/devices/{id}/browser.

A browser session requires an eligible active rental and cannot outlive that rental.

SDK example

from aimlib import Aimlib

async with Aimlib() as ai:
    device = (await ai.devices.list())[0]

    async with await device.browser(ttl="10m", idle_timeout="2m") as session:
        page = await session.new_page()
        await page.goto("https://example.com", wait_until="domcontentloaded")
        print(await page.title())

The browser extra supplies the supported client integration. No separate browser installation step is required.

Connection credentials

The create response includes a connect_url and connect_token. Both values are session secrets. Do not log them, persist them beyond the session, or share them between customers. The Python SDK handles connection authentication for you.

Session timing

  • Requested TTL is capped at 30 minutes and never extends beyond the rental.
  • Default idle timeout is 120 seconds.
  • Readiness can take tens of seconds; the SDK waits up to 180 seconds by default.
  • A device normally has one active remote-browser session.

Reuse a live session for related work. If a replacement session returns capacity_unavailable, wait a few seconds and retry with bounded backoff.

Pages and tabs

Use await session.new_page() to obtain the initial page and create later tabs. The response exposes max_tabs; exceeding it raises TabLimitError in the SDK.

Footprints

await device.list_footprints() returns options available for that device. Pass a returned slug at creation time:

async with await device.browser(footprint="pixel-9", ttl="10m") as session:
    page = await session.new_page()

Use await session.set_footprint(slug) to change the active selection. An empty string restores the device's default presentation. Do not assume a slug is available on every device.

Stop a session

The SDK context manager requests a stop on both normal exit and exceptions. Without a context manager:

session = await device.browser(ttl="10m")
try:
    await session.connect()
    page = await session.new_page()
finally:
    await session.stop()

The service can also stop sessions at TTL, idle timeout, rental end, or an applicable account limit. A stop request can return status: "stopping"; poll until no active session is returned when your workflow needs confirmation.

Supported browser interface

Use the methods documented by the aimlib SDK. Capabilities outside the published customer interface are not part of the service contract and can return BrowserPolicyError. Contact support if a documented workflow is unavailable for an eligible session.

See Account security and acceptable use for credential and account guidance.