Usage

The standard automation pattern with Octo Browser has three steps:

1. Use the Cloud API to create a profile (or reuse an existing UUID from the dashboard).
2. Use the Local Client API to start that profile with debug_port: true, which returns a ws_endpoint.
3. Connect your automation library to that WebSocket endpoint via CDP.

---

Minimal example: Playwright (Python, sync)

This is the simplest working script. Reuse an existing profile UUID instead of creating one programmatically.

import httpx
from playwright.sync_api import sync_playwright

PROFILE_UUID = "2bbfd1dbaf3349cf979787f15a9e413d"  # replace with your real UUID

def main():
    with sync_playwright() as p:
        # Start the profile via the local API (no token needed)
        resp = httpx.post(
            "http://127.0.0.1:58888/api/profiles/start",
            json={"uuid": PROFILE_UUID, "headless": False, "debug_port": True},
        )
        resp.raise_for_status()
        ws_endpoint = resp.json()["ws_endpoint"]

        # Connect Playwright to the running Octo profile via CDP
        browser = p.chromium.connect_over_cdp(ws_endpoint)
        page = browser.contexts[0].pages[0]
        page.goto("https://google.com")

        # Stop the profile when done
        httpx.post(
            "http://127.0.0.1:58888/api/profiles/stop",
            json={"uuid": PROFILE_UUID},
        )
        browser.close()

if __name__ == "__main__":
    main()

---

Minimal example: Puppeteer (Node.js)

Creates a fresh profile via the cloud API, starts it, navigates, then stops it.

const puppeteer = require('puppeteer');
const axios = require('axios');

const REMOTE = axios.create({
  baseURL: 'https://app.octobrowser.net/api/v2/automation/',
  timeout: 5000,
  headers: { 'X-Octo-Api-Token': process.env.OCTO_TOKEN },
});

const LOCAL = axios.create({
  baseURL: 'http://127.0.0.1:58888/api/profiles/',
  timeout: 120000,
});

(async () => {
  // 1. Create a profile
  const { data: created } = await REMOTE.post('/profiles', {
    title: 'Automation run',
    fingerprint: { os: 'win' },
  });
  const uuid = created.data.uuid;

  // 2. Start the profile locally
  const { data: started } = await LOCAL.post('/start', {
    uuid,
    headless: true,
    debug_port: true,
  });

  // 3. Connect Puppeteer via CDP
  const browser = await puppeteer.connect({
    browserWSEndpoint: started.ws_endpoint,
    defaultViewport: null,
  });
  const page = await browser.newPage();
  await page.goto('https://google.com/');

  // 4. Stop the profile
  await LOCAL.post('/stop', { uuid });
})();

---

Key API reference

Local Client API (no auth required)

Base URL: http://localhost:58888

Method	Path	Purpose
GET	/api/profiles/active	List currently running profiles
POST	/api/profiles/start	Start a profile, returns ws_endpoint
POST	/api/profiles/stop	Gracefully stop a profile
POST	/api/profiles/force_stop	Force-kill a profile (requires v1.7+)

Cloud Automation API

Base URL: https://app.octobrowser.net/api/v2/automation

Header: X-Octo-Api-Token: <your_token>

Response envelope: { "success": bool, "msg": string, "data": ... }

Method	Path	Purpose
GET	/profiles	List all profiles
POST	/profiles	Create a profile
PATCH	/profiles/{uuid}	Update a profile
DELETE	/profiles/{uuid}	Delete a profile
GET	/tags	List tags
GET	/proxies	List saved proxies