Quickstart

The quickest way to try Surfsky is to open a single page in a cloud browser. Do it with a Surfsky SDK, with your existing automation framework, or through the API directly.

Before you start

In the Surfsky dashboard:

Copy your API token.
Pick the region closest to the machine that runs your code and copy the API base URL shown for it.

Replace YOUR_API_TOKEN and https://YOUR_API_HOST below with those values.

export SURFSKY_API_TOKEN="YOUR_API_TOKEN"
export SURFSKY_API_BASE_URL="https://YOUR_API_HOST"

SDK quickstart

The SDK is the recommended way to work with Surfsky. It controls the browser directly, without the extra scripts and bindings that Playwright, Puppeteer, and ChromeDriver inject into the page, and it does almost everything you need from an automation library.

Python
JavaScript / TypeScript

Requires Python 3.12 or newer.

pip install surfsky

uv init # For a new project
uv add surfsky

Save as first_browser.py:

import asyncio
from surfsky import AsyncSurfsky


async def main():
    # Or: AsyncSurfsky(api_token="YOUR_API_TOKEN", base_url="https://YOUR_API_HOST")
    async with AsyncSurfsky() as client:
        async with client.browser() as browser:
            await browser.goto("https://www.google.com")
            print(await browser.title())


asyncio.run(main())

Run it:

python first_browser.py

uv run first_browser.py

Requires Node.js 22+ or Bun.

npm install surfsky

bun add surfsky

Save as first-browser.mjs:

import { Surfsky } from "surfsky";

// Or: new Surfsky({ apiToken: "YOUR_API_TOKEN", baseUrl: "https://YOUR_API_HOST" });
const client = new Surfsky();
const browser = await client.browser();
try {
  await browser.goto("https://www.google.com");
  console.log(await browser.title());
} finally {
  await browser.close();
}

Run it:

node first-browser.mjs

bun first-browser.mjs

Both examples use a one-time profile, so the session is destroyed when the script finishes, together with its cookies and anything else the browser stored. If you want to keep a login and reuse it on the next run, use a persistent profile instead, as in the Python and TypeScript examples.

Connect your existing code

Follow the guide for your framework:

Using the API directly

1. Start a browser

One-time
Persistent

Start a browser on a one-time profile. It lives for a single session, and its state is discarded when the browser stops:

curl --fail-with-body "$SURFSKY_API_BASE_URL/profiles/one_time" \
  -H "X-Cloud-Api-Token: $SURFSKY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Create a persistent profile once and reuse it on every run:

curl --fail-with-body "$SURFSKY_API_BASE_URL/profiles" \
  -H "X-Cloud-Api-Token: $SURFSKY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "My profile", "fingerprint": {"os": "win"}, "storage_options": {"cookies": true, "localstorage": true}}' # os: win, mac, or android

Save data.uuid from the response and replace PROFILE_UUID below with it. Use this same UUID on every run; do not create a new profile each time.

curl --fail-with-body "$SURFSKY_API_BASE_URL/profiles/PROFILE_UUID/start" \
  -H "X-Cloud-Api-Token: $SURFSKY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

After each run, stop the session and wait for completion so Surfsky saves its state. On the next run, repeat only the start request above to restore it. See Sessions for login reuse.

Response:

{
  "success": true,
  "internal_uuid": "a8fb62f90611456aa75422b01c385a62",
  "ws_url": "wss://YOUR_API_HOST/proxy/a8fb62f90611456aa75422b01c385a62"
}

2. Connect

Pass the returned ws_url to your framework’s CDP connection method. Use the existing browser context to work with the profile’s state. The default inactivity timeout is 30 seconds. To allow more time, set inactive_kill_timeout in the start request. For example, "browser_settings": {"inactive_kill_timeout": 300} allows 300 seconds of inactivity. To interact with the browser through HTTP requests, use the Scraping API with the returned internal_uuid.

3. Stop it

A running browser occupies 1 browser slot until it stops.

You can stop the browser in 3 ways:

Call a method that closes the remote browser, such as Puppeteer’s browser.close().
Leave it idle until inactive_kill_timeout expires.
Send the stop request below.

Replace INTERNAL_UUID with the value from your start response:

curl --fail-with-body -X POST \
  "$SURFSKY_API_BASE_URL/profiles/INTERNAL_UUID/stop" \
  -H "X-Cloud-Api-Token: $SURFSKY_API_TOKEN"

Playwright’s browser.close() over CDP only disconnects. Use the stop request or close it through CDP to end the session immediately.

If the example fails

Error	Check
`not_authorized`	The token is set and has no leading or trailing whitespace.
`namespace_not_allowed`	The base URL matches the one assigned to your account.
`region_not_chosen`	A region is selected in the dashboard.
`proxy_required` or `proxy_pool_unavailable`	Your account has a proxy pool, or the start request supplies your own proxy.
`parallel_browsers_limit_reached`	An existing browser must stop before another can start.

See Errors for other API failures. Continue with Sessions to reuse browser state, or the Python and TypeScript SDK guides for browser actions and pooling.

Get started

Connect your tools

Browser sessions

Browser actions

CAPTCHA guides

Debugging

Performance and limits

About Surfsky

Before you start

SDK quickstart

Connect your existing code

Using the API directly

1. Start a browser

2. Connect

3. Stop it

If the example fails

​Before you start

​SDK quickstart

​Connect your existing code

​Using the API directly

​1. Start a browser

​2. Connect

​3. Stop it

​If the example fails

Before you start

SDK quickstart

Connect your existing code

Using the API directly

1. Start a browser

2. Connect

3. Stop it

If the example fails