Getting started
Quickstart
A project API key, a first Agent run, and a first cloud browser — in Python, JavaScript or plain HTTP.
1. Create an API key
In the console, open Configuration → API keys and create a key with the read and execute scopes. The secret is shown once; store it outside source control.
export STEALTH_API_KEY="sk_…" # the one-time secretexport STEALTH_API_URL="https://…" # your deployment's origin, no trailing slashEvery request carries Authorization: Bearer $STEALTH_API_KEY. The key already selects its project. See Authentication for scopes and the permission matrix.
2. Install a client
The SDKs are workspace packages in the repository until the platform launch; publishing to npm and PyPI follows it.
# Put sdks/python on your path; standard library only, Python >= 3.10export PYTHONPATH="/path/to/stealth-browser/sdks/python:$PYTHONPATH"# From the repository checkout; no runtime dependency beyond fetch, Node >= 20npm install /path/to/stealth-browser/packages/cloud-sdk# Nothing to install: the API is plain HTTP + JSONcurl "$STEALTH_API_URL/health"3. Run your first Agent task
Create a run, wait for it, and read the result. judge: true asks a second model reading for a verdict once the agent reports done.
import osfrom stealth_browser import StealthBrowser client = StealthBrowser(os.environ["STEALTH_API_KEY"], base_url=os.environ["STEALTH_API_URL"]) run = client.run("Open https://example.com and report the page title.", judge=True, on_event=lambda event: print(event["type"]))print(run["status"], run["output"], run.get("judgment"), run["usage"])import { StealthBrowser } from '@stealth-browser/cloud-sdk'; const client = new StealthBrowser({ apiKey: process.env.STEALTH_API_KEY, baseUrl: process.env.STEALTH_API_URL }); const run = await client.run('Open https://example.com and report the page title.', { judge: true, onEvent: (event) => console.log(event.type),});console.log(run.status, run.output, run.judgment, run.usage);# Create the run (202 + Location), then read it until status is succeeded, failed or cancelled.curl -X POST "$STEALTH_API_URL/v1/runs" \ -H "Authorization: Bearer $STEALTH_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"task":"Open https://example.com and report the page title.","judge":true}' curl "$STEALTH_API_URL/v1/runs/$RUN_ID" -H "Authorization: Bearer $STEALTH_API_KEY"# Live progress as server-sent eventscurl -N "$STEALTH_API_URL/v1/runs/$RUN_ID/events?stream=1" -H "Authorization: Bearer $STEALTH_API_KEY"A run's output is the agent's own account; judgment.verdict is pass, fail or uncertain. See Results and verdicts.
4. Drive a browser yourself
Create a browser, wait for running, navigate, observe the page, act by ref, stop.
browser = client.browsers.create({"settings": {"locale": "en-US"}})browser.ready()browser.navigate("https://example.com")state = browser.observe() # tree with [ref=eN], targets, tabs, dialogs, downloadslink = next((t for t in state["targets"] if t["role"] == "link"), None)if link: browser.click(link["ref"]) # observation frames are handled insideprint(browser.text(format="markdown")["text"])browser.stop()const browser = await client.browsers.create({ settings: { locale: 'en-US' } });await browser.ready();await browser.navigate('https://example.com');const state = await browser.observe(); // tree with [ref=eN], targets, tabs, dialogs, downloadsconst link = state.targets.find((t) => t.role === 'link');if (link) await browser.click(link.ref); // observation frames are handled insideconsole.log((await browser.text({ format: 'markdown' })).text);await browser.stop();curl -X POST "$STEALTH_API_URL/v1/browsers" -H "Authorization: Bearer $STEALTH_API_KEY" \ -H "Content-Type: application/json" -d '{"settings":{"locale":"en-US"}}'# poll GET /v1/browsers/$BROWSER_ID until "status":"running"curl -X POST "$STEALTH_API_URL/v1/browsers/$BROWSER_ID/navigate" -H "Authorization: Bearer $STEALTH_API_KEY" \ -H "Content-Type: application/json" -d '{"url":"https://example.com"}'curl "$STEALTH_API_URL/v1/browsers/$BROWSER_ID/observe" -H "Authorization: Bearer $STEALTH_API_KEY"# act with the observation's frame_id and a ref from its treecurl -X POST "$STEALTH_API_URL/v1/browsers/$BROWSER_ID/action" -H "Authorization: Bearer $STEALTH_API_KEY" \ -H "Content-Type: application/json" -d '{"type":"click","frame_id":"<frame_id>","ref":"e3"}'curl -X POST "$STEALTH_API_URL/v1/browsers/$BROWSER_ID/stop" -H "Authorization: Bearer $STEALTH_API_KEY" \ -H "Content-Type: application/json" -d '{}'The observation, refs and actions are described in Observe and act.