Skip to main content

Getting started with Morph Browsers

Morph Browsers lets you create on-demand, remotely accessible Chromium sessions in the cloud and connect over the Chrome DevTools Protocol (CDP) from Playwright or Puppeteer. You can get started via CLI, the web dashboard, or the Python SDK.

Useful links:

Prerequisites​

  • An API key from the Morph Cloud dashboard: https://cloud.morph.so
  • Optionally set the base URL (defaults to the hosted service)
export MORPH_API_KEY="<your-api-key>"
# Optional. Defaults to https://browsers.svc.cloud.morph.so
export BROWSERS_BASE_URL=${BROWSERS_BASE_URL:-"https://browsers.svc.cloud.morph.so"}

Use the CLI​

You can use standard command-line tools to call the Browsers API. The examples below use curl to create a session, fetch the connection URL, and stop the session when done.

# 1) Create a session (returns JSON with id and connect_url)
curl -sS -H "Authorization: Bearer $MORPH_API_KEY" \
  -X POST "$BROWSERS_BASE_URL/session?name=demo&viewport_width=1280&viewport_height=800"

# Example jq extraction
SESSION_ID=$(curl -sS -H "Authorization: Bearer $MORPH_API_KEY" \
  -X POST "$BROWSERS_BASE_URL/session?name=demo" | jq -r '.id')

# 2) Get a fresh connection URL (useful if you didn't store it from create)
CONNECT_URL=$(curl -sS -H "Authorization: Bearer $MORPH_API_KEY" \
  "$BROWSERS_BASE_URL/session/$SESSION_ID/connect" | jq -r '.')
echo "$CONNECT_URL"

# 3) Connect from your CDP client (e.g., Playwright/Puppeteer) using the URL
# See the Python SDK example below for a Playwright snippet.

# 4) Stop the session when finished
curl -sS -H "Authorization: Bearer $MORPH_API_KEY" \
  -X DELETE "$BROWSERS_BASE_URL/session/$SESSION_ID"

Notes:

  • The create endpoint accepts optional name, viewport_width, and viewport_height query parameters.
  • connect_url is compatible with Playwright’s connect_over_cdp and Puppeteer’s connect.
  • See the full endpoint list in the OpenAPI docs linked above.

Use the web dashboard​

If you prefer a graphical workflow:

  1. Sign in at https://cloud.morph.so
  2. Open the Browsers section in the left navigation
  3. Create a new browser session
  4. Copy the “Connection URL” (CDP WebSocket) and connect from Playwright or Puppeteer
  5. Stop the session when you’re done

Use the Python SDK​

The Python SDK is generated from the Browsers OpenAPI and also ships as a Morph Cloud plugin. You can use it in two ways:

# Install SDK (until published to PyPI, install from Git)
uv add "browsers-sdk @ git+https://github.com/morph-labs/browsers-sdk.git@main#subdirectory=sdks/python"

# Ensure your Morph API key is set
export MORPH_API_KEY="<your-api-key>"
import os
from morphcloud.api import MorphCloudClient
from playwright.sync_api import sync_playwright

# Optional override; defaults to https://browsers.svc.cloud.morph.so
os.environ.setdefault("BROWSERS_BASE_URL", "https://browsers.svc.cloud.morph.so")

client = MorphCloudClient()  # loads the Browsers plugin from browsers-sdk

sess = client.browsers.create_session(name="demo")
with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(sess.connect_url)
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.title())
    browser.close()

client.browsers.stop_session(sess.id)

For additional endpoints (pause/resume, metadata, recordings, branch sessions, etc.), see the OpenAPI docs: https://browsers.svc.cloud.morph.so/docs