Scripts

A script is Playwright code that runs inside the session’s own sandbox, next to its browser, so every browser call is local and fast. Inside it, step() and extract() bring in AI for the parts where exact selectors are hard. Watch the live view while it runs.

Run a script

POST /v1/sessions/:id/browser/script with { code, env?, timeoutMs?, ai?, credentials?, allowWithExtensions? }. The session needs a browser and a shell: the code runs with Node on the session’s machine, next to its Chrome. The output streams back as it happens.

A shell-only session has no browser and answers 409 browser_disabled. A session without a shell answers 409 shell_disabled. Create the session with {"shell": true} to get both. The script waits for the session’s setup commands to finish.

# In a session with a browser and a shell: the output streams back as JSON lines.curl -N -X POST https://api.boxline.dev/v1/sessions/$SESSION_ID/browser/script \  -H "x-api-key: $BOXLINE_API_KEY" \  -H "content-type: application/json" \  -d @- <<'JSON'{  "code": "await page.goto(env.START_URL);\nawait step(\"type %email% into the email field\");\nawait step(\"click Continue\");\nconst plans = await extract(\"the plan names and monthly prices\");\nreturn plans;",  "env": {    "START_URL": "https://example.com/signup",    "email": "ada@example.com"  }}JSON

const session = await bx.sessions.create({ shell: true, keepAlive: true });const result = await session.runScript(  `await page.goto(env.START_URL);await step("type %email% into the email field");await step("click Continue");const plans = await extract("the plan names and monthly prices");return plans;`,  {    env: { START_URL: "https://example.com/signup", email: "ada@example.com" },    onData: (_stream, text) => process.stdout.write(text),  },);console.log("exit code", result.exitCode);

session = bx.sessions.create(shell=True, keep_alive=True)code = """await page.goto(env.START_URL);await step("type %email% into the email field");await step("click Continue");const plans = await extract("the plan names and monthly prices");return plans;"""with session.run_script(code, env={"START_URL": "https://example.com/signup", "email": "ada@example.com"}) as script:    for stream, text in script:        print(text, end="")print("exit code", script.result["exitCode"])

The script controls the browser, so it can read what a step typed into a page. Its output is shown with the session’s exported credentials and these credentials’ values hidden.

What the code can use

• page, context and browser: Playwright, already connected to the session’s browser.
• env: your variables.
• console: what you log is streamed back.
• step(), extract() and useModel(): the AI helpers below.

Top-level await works, and a value you return is printed. Do not call browser.close(): it would close the session’s browser.

Output

The response is newline-delimited JSON, like a streaming shell command: output lines, then one exit line.

{"type":"stdout","data":"[{\"name\":\"Pro\",\"price\":\"$20\"}]\n"}{"type":"exit","exitCode":0,"timedOut":false,"durationMs":6120}

The run is also an exec event in the session’s events, with data.by: "script". Its output stays in this response.

AI helpers

step() needs a plan with plain-English steps, like step actions. Model use counts toward your monthly spend cap.

Which model a step or extract uses

The first of these that is set wins:

1. the call’s own provider and model;
2. the last useModel();
3. the request’s ai;
4. the platform default: the first configured provider and its fast step model.

useModel("gpt-6-sol");                                   // OpenAI, found from the model idawait step("click Sign in");                             // gpt-6-solawait step("type %email% into the email field", { model: "claude-haiku-5-5" }); // this call onlyuseModel("anthropic", "claude-sonnet-5-5");const prices = await extract("the plan prices");         // claude-sonnet-5-5

• With a model id alone, the provider is the one whose model list has it. An unknown id (or one two providers list) throws, with the valid ids in the message.
• A call that names only another provider gets that provider’s fast model.
• useModel() only picks the model. It is checked (model list, plan, spend cap) when a step or extract uses it.
• ai is checked when the script starts: 400 invalid_request for an unknown provider or model, 503 provider_unavailable when that provider is not set up, and 402 feature_not_in_plan without plain-English steps.

Every field is in the API reference: Run a Playwright script. Over MCP, browser_act runs plain-English steps and shell_exec runs commands.