aimlib / documentation

Build with real mobile connections¶

Use an active rental for HTTP or SOCKS5 proxy traffic, or start a managed remote browser—all through one customer API.

Mobile proxy

One credentialed endpoint accepts HTTP and SOCKS5 for an active mobile rental.

Read the proxy guide →
Remote browser

Create a managed browser session for an eligible active rental, connect with the SDK, and stop it when finished.

Follow the browser lifecycle →
API and SDK

Automate rentals, browser sessions, network operations, and support with a documented REST API and async Python client.

Browse the API reference →

How the pieces fit together¶

Use an active rental. The customer API returns only devices in your account's active rentals.
Choose the service. Use the provisioned proxy immediately, or create a browser session on the eligible rental.
Connect securely. Keep API keys, proxy credentials, and browser connection tokens out of code and logs.
Clean up. Stop browser sessions when work completes; rentals and service limits still apply.

One proxy port

The proxy hostname, port, username, and password are shared by HTTP and SOCKS5. Select the URL form your client expects; no protocol-specific session setup is required.

What you need¶

A customer API key with an active device rental.
The regional API URL assigned to the rental. Examples here use https://uswest1.aimlib.com.
Python 3.10 or newer for the SDK examples.

Treat the API key, proxy URLs, and browser connection token as secrets. Do not put them in source control, screenshots, analytics, or application logs.

Install the Python SDK¶

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

python -m pip install --upgrade "aimlib[browser]"

Set credentials in the environment:

export AIMLIB_API_KEY="<api-key>"
export AIMLIB_BASE_URL="https://uswest1.aimlib.com"

List your leased devices¶

from aimlib import Aimlib

async with Aimlib() as ai:
    devices = await ai.devices.list()
    for device in devices:
        print(device.id, device.region, device.carrier)

Only devices in your account's active rentals are returned. A device object includes its current proxy endpoint when provisioning is complete.

Use the mobile proxy¶

The same proxy host and port accept HTTP and SOCKS5. Choose the URL that matches your client:

async with Aimlib() as ai:
    device = (await ai.devices.list())[0]
    http_proxy = device.proxy.http_url
    socks_proxy_with_remote_dns = device.proxy.socks5h_url

See Mobile proxy for client examples, DNS behavior, IP rotation, and carrier selection.

Start a remote browser¶

A remote browser belongs to an existing active rental. The normal sequence is: select a leased device, create its browser session, wait for readiness, then connect.

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

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

The context manager requests a stop when the block exits. Explicitly call await session.stop() when you are not using a context manager.

See Remote browser for lifecycle, connection, timing, and stop behavior.

Use the REST API directly¶

Every customer request uses bearer authentication:

curl --fail-with-body \
  -H "Authorization: Bearer $AIMLIB_API_KEY" \
  "$AIMLIB_BASE_URL/v1/devices"

The REST API reference documents every customer endpoint, scope, request, response, and public error code.