# Boxline

> Give your AI agents the infrastructure they need: browsers, shells, storage and isolated machines. Each session is Chrome you drive with Playwright, Puppeteer or CDP, an optional bash shell and a shared disk, on one isolated machine. Billed per second.

Boxline is cloud infrastructure for AI agents. Each session is an isolated machine with a real Chrome browser (driven with Playwright, Puppeteer or CDP, with live view, proxies and CAPTCHA handling), an optional bash shell with Python and Node, and a disk that is kept when the session stops and resumes; a shell sandbox can also run on its own, without a browser. On top of sessions, Boxline runs AI agents that complete a goal in the browser, and offers one-call APIs to fetch, crawl and search the web. It is used through a REST API, TypeScript and Python SDKs, a CLI and an MCP server, and billed per second.

The API is at https://api.boxline.dev. Every page below is Markdown; https://docs.boxline.dev/llms-full.txt has all of them in one file.

## Guides: Get started

- [Introduction](https://docs.boxline.dev/index.md): Give your AI agents the infrastructure they need: browsers, shells, storage and isolated machines. Start with a quickstart, or pick a topic.
- [Quickstart](https://docs.boxline.dev/quickstart.md): Three short walk-throughs: drive a cloud browser with Playwright, turn a URL into Markdown, and hand a task to the AI agent.

## Guides: Sessions

- [Configuring sessions](https://docs.boxline.dev/sessions.md): What a session is, the three kinds (a browser, a shell or both), every option you can create it with, the session object it returns, and your plan's limits.
- [Lifecycle](https://docs.boxline.dev/lifecycle.md): How long a session lives, why it stops, how long a stopped session is kept, and how to find, update, stop, resume and delete sessions, one at a time or in bulk.
- [How runs and sessions end](https://docs.boxline.dev/runs-and-sessions-end.md): Every way an agent run or a session ends, what to do about each, and the habits that keep sessions from running longer than you want: stop in finally, timeouts, keepAlive, idleTimeout, cancelling, reconnecting.
- [Connect with Playwright](https://docs.boxline.dev/playwright.md): Drive a session's Chrome with Playwright over the Chrome DevTools Protocol, in Node or Python.
- [Connect with Puppeteer](https://docs.boxline.dev/puppeteer.md): Drive a session's Chrome with Puppeteer, or with any other client that speaks the Chrome DevTools Protocol.
- [Live view](https://docs.boxline.dev/live-view.md): Watch a session's browser as it works, get its link, take control of it, and keep the signed links safe.
- [Recordings](https://docs.boxline.dev/recordings.md): A frame-by-frame recording of every session's screen, its log of events (console, network, pages, actions and every shell command, whoever ran it), a live stream, and how long both are kept.
- [Proxies](https://docs.boxline.dev/proxies.md): Send a session's or a request's traffic through a residential, datacenter or your own proxy, from the country, US state or city you choose, with a different proxy per site if you need one.
- [Browser mode](https://docs.boxline.dev/browser-mode.md): Match a session's clock, language and Accept-Language to the country its proxy comes out in, or set the locale and time zone yourself.
- [CAPTCHAs](https://docs.boxline.dev/captchas.md): The platform notices a CAPTCHA that is waiting for a person, tells you, and pauses its own automation until someone solves it. On paid plans a session can opt in to automatic solving first.
- [Ad and cookie-banner blocking](https://docs.boxline.dev/ad-blocking.md): Block ad and tracker sites in a session or a page request, and answer cookie banners with Reject all (the default), free on every plan.
- [Browser profiles](https://docs.boxline.dev/profiles.md): Keep cookies and local storage between sessions, so your agent stays signed in, and link a password credential so it can sign in again when the cookies expire.
- [Credentials](https://docs.boxline.dev/credentials.md): Write-only, encrypted website passwords (with 2FA codes from an authenticator key or your own system) and secrets: the AI types them as placeholders on their own sites, one call signs a session in, and shells get them as environment variables, hidden in output and audited.
- [Extensions](https://docs.boxline.dev/extensions.md): Upload a Manifest V3 Chrome extension once and load it into the sessions that need it.
- [File uploads and downloads](https://docs.boxline.dev/files.md): The shared /workspace disk: browser downloads, files you upload for the browser, reading, writing and downloading files and whole folders, also after the session has stopped.
- [Stop and resume](https://docs.boxline.dev/stop-resume.md): Stop a session to save the whole browser and its files and stop billing, then resume it as it was. What is saved, how long it is kept, and what happens when a machine is lost.
- [Shell](https://docs.boxline.dev/shell.md): A bash shell next to the browser, or on its own: run a command, environment variables, a persistent shell, streaming, background jobs, installs, and best practices.

## Guides: Web

- [Overview](https://docs.boxline.dev/web.md): One request per page, no session to manage: fetch, screenshot, PDF, extract and crawl.
- [Fetch](https://docs.boxline.dev/fetch.md): Turn a URL into Markdown, HTML or plain text with one request.
- [Screenshot](https://docs.boxline.dev/screenshot.md): A PNG or JPEG of any page, the visible part, the whole page or one element.
- [PDF](https://docs.boxline.dev/pdf.md): Print any page to a PDF, the way Chrome's Save as PDF does.
- [Extract](https://docs.boxline.dev/extract.md): Turn one or more pages into JSON that matches your schema, or answer a question about them.
- [Crawl](https://docs.boxline.dev/crawl.md): Follow links from a start page in the background and collect up to 200 pages on Free, 1,000 on paid plans, as Markdown, text or HTML.
- [Search](https://docs.boxline.dev/search.md): Search the web in one request, with the top pages as Markdown if you want them.

## Guides: AI

- [AI agent](https://docs.boxline.dev/agent.md): Hand a task to an AI agent that works in a session you describe, browser only, shell only or both: limits and how a run stops, pausing and resuming a run, messages while it works, answers as JSON, and variables and credentials.
- [Tasks](https://docs.boxline.dev/tasks.md): Save an agent run as a task with variables, an output schema and the session each run starts in, run it again with new values, get its results as JSON, and put it on a cron schedule in your time zone.
- [Computer use](https://docs.boxline.dev/computer-use.md): Run a computer-use model's clicks and key presses on a session, in Anthropic's or OpenAI's shape, with a loop for each provider, or let the agent work in computer mode.
- [Steps](https://docs.boxline.dev/steps.md): Drive the browser one step at a time: exact actions like click and fill, or a plain-English step that a fast model turns into one action.
- [Mouse and keyboard](https://docs.boxline.dev/mouse-keyboard.md): Move, hover, click with any button, drag, scroll at a point, press key combinations, and take screenshots scaled for a model, in CSS pixels of the page.
- [Plain-English and exact steps together](https://docs.boxline.dev/steps-together.md): Mix exact actions and plain-English sentences in one list of actions, and read what each one did.
- [Scripts](https://docs.boxline.dev/scripts.md): Run Playwright code inside the session's own sandbox, with step(), extract() and useModel() for the parts that need AI.

## Guides: Account

- [Organizations, projects and team members](https://docs.boxline.dev/organizations.md): Your personal organization, projects, the five roles and what each can do, access per project, invitations, leaving and transferring, the audit list, and how limits are shared by an organization's projects.
- [Plans and features](https://docs.boxline.dev/plans.md): What your plan controls: limits and feature switches, which features are paid, the 402 feature_not_in_plan error, how to check your plan from code, and suspended projects.
- [Credit and spending limits](https://docs.boxline.dev/credit-and-spending-limits.md): How included and granted credit are used, the balance, monthly spending limits for an organization and each project, what happens at a limit, alerts by email and webhook, and how to use limits safely. Buying credit is coming.
- [Trajectories](https://docs.boxline.dev/trajectories.md): A project setting, on by default, that decides whether your sessions are eligible for trajectory datasets. See which sessions are eligible, and turn it off at any time with the project settings.
- [Webhooks](https://docs.boxline.dev/webhooks.md): Signed HTTPS callbacks for every kind of event (sessions, agent runs, CAPTCHAs, tasks, usage limits, keys and credentials), with sample payloads, typed receivers, retries, the delivery log and local development.
- [Your own model keys](https://docs.boxline.dev/model-keys.md): Save your own Claude, OpenAI, Grok or Gemini key, choose whose key a provider uses, set the project's default model, and see how it is billed. The Free plan runs AI on your own keys.
- [Project settings](https://docs.boxline.dev/project-settings.md): Settings for your whole project: the CAPTCHA default and the default model that new sessions and agent runs get when they do not choose, and your choice about the Trajectories program.
- [Pricing](https://docs.boxline.dev/pricing.md): How usage is billed: per-second sessions, proxy data, CAPTCHA solving, web search and AI models, the monthly spend cap, and how to watch your usage.

## API reference: Basics

- [Start here](https://docs.boxline.dev/api-reference/start-here.md): The eight calls most things start with, each as the smallest request that works: fetch a page, search, start a session, drive its browser, run a command, read a file, stop it, or hand the job to an AI.
- [Overview](https://docs.boxline.dev/api-reference.md): The base URL, authentication, the WebSocket URLs and every endpoint of the API.
- [Errors and request ids](https://docs.boxline.dev/api-reference/errors.md): What an error looks like, the error codes you will meet, and the request id to quote when you ask for help.
- [Rate limits](https://docs.boxline.dev/api-reference/rate-limits.md): How many requests each route takes per minute or hour, the RateLimit headers, and how to back off.
- [Idempotency keys](https://docs.boxline.dev/api-reference/idempotency.md): Retry a request that creates something without creating it twice.
- [Pagination](https://docs.boxline.dev/api-reference/pagination.md): Page through any list with limit and after, until next is null.

## API reference: Web

- [Search the web](https://docs.boxline.dev/api-reference/search.md): Results from a web search provider (Brave Search API): title, URL, snippet, and the page's date and site name when known. With fetch, the top pages also come back as Markdown, opened like /v1/fetch in a real browser inside a sandbox; one page failing never fails the search. The same search by the same project within an hour is answered from the cache (cached: true) and not counted. Each other search counts against the plan's searchesPerMonth; beyond it the plan's extraSearchesPer1000Usd applies, and a plan without one (Free) answers 402 plan_limit until the 1st (UTC). The query text and options are sent to Brave with the platform's own key, nothing about the caller; the query text is kept 30 days. 60 per minute per project; every page fetch opens also counts against the fetch/screenshot/pdf limit.
- [Fetch a page](https://docs.boxline.dev/api-reference/fetch-page.md): Renders the page in a real browser inside a sandbox. 120 per minute per project (shared with screenshot and pdf).
- [Screenshot a page](https://docs.boxline.dev/api-reference/screenshot.md): Screenshot a page.
- [Print a page to PDF](https://docs.boxline.dev/api-reference/pdf.md): Print a page to PDF.
- [Extract data from pages](https://docs.boxline.dev/api-reference/extract.md): Renders each page in a real browser, then a model fills your schema or answers your prompt (page text is treated as data). Defaults to a fast model. 30 per minute per project; model use counts against the monthly spend cap (402 spend_limit).

## API reference: Crawls

- [Start a crawl](https://docs.boxline.dev/api-reference/start-crawl.md): Follows links breadth-first from a start URL in the background, 3 pages at a time, respecting robots.txt (fetched through the sandboxed browser) and crawl-delay; there is no option to ignore them. maxPages may not exceed the plan's maxCrawlPages (Free 200, paid plans 1000; 402 plan_limit). 10 per minute per project.
- [List crawls](https://docs.boxline.dev/api-reference/list-crawls.md): Jobs newest first, without their pages.
- [Get a crawl](https://docs.boxline.dev/api-reference/get-crawl.md): Pages by index. limit=0 returns the job only (for polling its progress).
- [Cancel a crawl](https://docs.boxline.dev/api-reference/cancel-crawl.md): Cancel a crawl.

## API reference: Sessions

- [Create a session](https://docs.boxline.dev/api-reference/create-session.md): Claims a warm machine with a browser and/or a shell. Limited to 120 per minute per project, and to the plan's concurrent sessions (429 concurrency_limit). 503 no_capacity when no machine is free in time. browser (default true) and shell (default false) choose the kind: browser only, shell only ({browser: false, shell: true}) or both. Without a browser connectUrl and liveUrl are null; without a shell terminalUrl is.
- [List sessions](https://docs.boxline.dev/api-reference/list-sessions.md): List sessions.
- [Get a session](https://docs.boxline.dev/api-reference/get-session.md): The session with freshly signed connectUrl, liveUrl and terminalUrl (null as for Create a session; all null unless it is running).
- [Update a session](https://docs.boxline.dev/api-reference/update-session.md): The one call that changes a running session, with the field names and shapes of Create a session. Checks first, then the changes, so a bad value leaves the session as it was. A new proxy applies at once (the browser's open connections are closed); null removes it. Browser settings apply to every tab within a second or two. blockAds and cookieBanners apply at once. timeout changes its length, rotateProxy gives a new proxy IP, rotateUrls makes new signed URLs. What is fixed when the session starts (browser and shell on or off, viewport, profile, recordSession, setup, extensions, env, credentials) is 400 not_updatable. A stopped session takes the changes too; they apply when it resumes. 409 session_not_running for a deleted session.
- [Delete a session](https://docs.boxline.dev/api-reference/delete-session.md): Ends the session for good: a running one is stopped without saving, then what it saved, its recording, events, pages and agent-run steps are deleted now. The record (usage, cost) stays. Cannot be undone.
- [Stop a session](https://docs.boxline.dev/api-reference/stop-session.md): Saves the session exactly as it is (the whole browser and /workspace), frees the machine and stops billing. The recording, events, pages and agent-run steps stay. A stopped session is kept for its plan's retentionDays (see deletesAt), then deleted; resume it any time before. If its state cannot be saved the call fails and the session keeps running. 409 session_not_running for a deleted session.
- [Resume a session](https://docs.boxline.dev/api-reference/resume-session.md): The same session on a fresh machine, as it was when it stopped (tabs with their history, cookies, storage, files, each shell's directory and exported variables; not running processes or page memory). 409 nothing_saved when nothing was saved (a machine lost before its first checkpoint, a session from before stop and resume existed); 409 session_not_stopped for a deleted session; 409 conflict while another running session holds its browser profile; 429 concurrency_limit; 402 spend_limit or out_of_credit.
- [Stop, resume or delete many sessions](https://docs.boxline.dev/api-reference/bulk-sessions.md): 30 calls per minute per project. Every id must be a session id (a UUID). Each id is one single action with its own result.

## API reference: Browser

- [Run browser actions](https://docs.boxline.dev/api-reference/run-actions.md): Runs a list of actions next to the session's browser, in order, and stops at the first failure. A stopped session is not woken by a call (409 session_not_running): resume it first. 409 browser_disabled on a session created with browser: false. A bare string in the list is a plain-English step. step needs the plan's plain-English steps (402 feature_not_in_plan), and model calls count against the monthly model spend cap (402 spend_limit). Mouse and keyboard actions are checked before anything runs: a point outside the viewport is 400 out_of_viewport, a bad shape 400 invalid_request. Coordinates are CSS pixels of the viewport. Screenshots count against 300 per minute per session (shared with /computer).
- [Run a computer-use action](https://docs.boxline.dev/api-reference/computer-action.md): Runs ONE action exactly as a computer-use model's tool gives it, on the session's browser page (never the machine's desktop), then returns the screen: a screenshot, the pointer, URL and title. Two shapes: one action of Claude's computer toolset (computer_toolset_20260801) as {action: <member name>, ...input}, e.g. {action:"left_click", coordinate:[x, y]}, and one item of an OpenAI computer_call's actions (GA computer tool: {type:"click", x, y, button}). Coordinates are pixels of the screenshot: with maxWidth the screenshot is scaled down and coordinates are divided by scale. A failure in the page is 200 with ok:false (and still a screenshot); input that cannot be mapped, or a point outside the screenshot, is 400 (invalid_request, out_of_viewport). 300 calls per minute per session; screenshots also count against the session's 300 per minute. 409 browser_disabled on a session created with browser: false.
- [Run a Playwright script](https://docs.boxline.dev/api-reference/run-script.md): Runs JavaScript with Node inside the session's own sandbox, next to its Chrome (the session needs a browser, else 409 browser_disabled, and a shell, else 409 shell_disabled). In scope: page, context, browser (Playwright, already connected), env and console; top-level await works; do not call browser.close(). The reply streams NDJSON exactly like a streaming exec. Never replayed by Idempotency-Key.
- [Export cookies to a file](https://docs.boxline.dev/api-reference/export-cookies.md): A Netscape cookie file in the workspace, for curl or wget in the shell. 409 browser_disabled on a session created with browser: false.
- [Open the live view](https://docs.boxline.dev/api-reference/live-page.md): An HTML page showing the session's browser, with tabs and input (a person can click and type in it). Open the session's liveUrl; framing is allowed only on the platform's own front ends. A session created with browser: false has no live view (liveUrl is null; the page answers 409 browser_disabled, and so does its socket).

## API reference: Shell

- [Run a command](https://docs.boxline.dev/api-reference/exec.md): Runs in the session's persistent shell (or a named one, or a fresh process with shell: false), after the session's setup commands finish. cd and export in a command carry to the next one (and across a stop and resume); cwd, env and credentials apply to this command only. Commands on one shell run one at a time. A command that times out is stopped with everything it started; the shell keeps its directory and exports, and background jobs keep running. Without stream, each of stdout and stderr keeps its first 64 KiB and last 448 KiB, with [… N characters not shown …] between them (truncated: true). With stream: true the reply is NDJSON as the command runs (nothing is cut); leaving stops the command. The session's exported credentials and the command's credentials are hidden in the output. 409 shell_disabled without a shell.
- [Restart the shell](https://docs.boxline.dev/api-reference/restart-shell.md): Restart the shell.

## API reference: Files

- [Read a file or list a folder](https://docs.boxline.dev/api-reference/get-file.md): A file comes back as an inert download (application/octet-stream, attachment). A folder, or list=1, gives a listing. Also works on a stopped session, read-only, from the workspace it saved (its stop archive, or the last checkpoint after a lost machine) without starting a machine; .boxline/ is left out and links are never followed. 409 nothing_saved when it saved no workspace. One request scans at most 1 GiB of the saved archive, and a stopped session's folder lists at most 10,000 entries (413 payload_too_large for both), and at most 8 such reads of a project run at once (429 archive_busy). Listing a file is 400 not_a_directory.
- [Upload a file](https://docs.boxline.dev/api-reference/put-file.md): The request body is the file's bytes, streamed into the workspace (any content type).
- [Delete a file or folder](https://docs.boxline.dev/api-reference/delete-file.md): Delete a file or folder.
- [Download a folder](https://docs.boxline.dev/api-reference/archive-files.md): One .tar.gz with the folder and everything in it (an inert download; .boxline/ is left out and links are stored as links, not followed). Also works on a stopped session, from the workspace it saved, without starting a machine (read-only; 409 nothing_saved when it saved none). The folder is path (default the whole workspace). At most 1 GiB and 100,000 entries (413 archive_too_large, before any byte is sent); 400 not_a_directory; 403 or 400 invalid_path for a path outside the workspace or through a link; 429 archive_busy (two at once per session, or per project for stopped sessions). The folder is under its own name in the archive (<name>/…; the whole workspace: workspace/…).
- [Wait for a file](https://docs.boxline.dev/api-reference/wait-for-file.md): Returns the newest file matching a glob once its size stops changing (e.g. a finished download).

## API reference: Logs and recording

- [List session events](https://docs.boxline.dev/api-reference/list-session-events.md): Oldest first. Pass nextAfter back as after to page forward and to poll for new events.
- [Stream session events](https://docs.boxline.dev/api-reference/stream-session-events.md): Server-sent events, one Event per data: line; first the backlog after after, then live.
- [List visited pages](https://docs.boxline.dev/api-reference/list-session-pages.md): Main-frame navigations grouped by tab and URL, in the order they were first visited.
- [Get the recording](https://docs.boxline.dev/api-reference/get-recording.md): A JPEG frame is kept whenever the screen changed (checked every 2 s), on plans with recordings.
- [Get a recording frame](https://docs.boxline.dev/api-reference/get-recording-frame.md): Works with the console cookie, so <img src> can show it.

## API reference: Agent

- [Start a run](https://docs.boxline.dev/api-reference/start-agent-run.md): The agent works on the task in a session (its own, stopped at the end unless keepSession, or sessionId). A run stops at its step limit (errorCode: max_steps, then resumable for a while: see Resume a run), at its session's time limit (session_timeout) or when canceled. timeout sets the run's own session's time (default 1800 s, or the plan's maximum when shorter; 402 plan_limit above it, 400 with sessionId). 30 per minute per project. 503 provider_unavailable when no key exists for that provider (add one in project settings); 402 feature_not_in_plan on a plan without platformModels (Free) and no own key; a rejected own key ends the run with model_key_rejected; 402 spend_limit once the monthly model spend cap is reached; 409 session_not_running for a sessionId whose session was deleted (a stopped one is resumed by the run). With an Idempotency-Key, variable values are not compared (they are never stored in any form): a retry with the same key and other values gets the first run.
- [List runs](https://docs.boxline.dev/api-reference/list-agent-runs.md): List runs.
- [Get a run](https://docs.boxline.dev/api-reference/get-agent-run.md): Get a run.
- [Stream a run](https://docs.boxline.dev/api-reference/stream-agent-run.md): Server-sent events: one per step (a user's message is a message step, sent when the model receives it), {type:"thought", text, at} as soon as the model's reply arrives (before its tool runs; the same text is that step's thought), {type:"status", status, by?, reason?} on pause and resume, {type:"exec", command, at} when a shell command starts and {type:"output", stream, data} while it runs, and a final {type:"done", status, result, resultText, error, errorCode, resumable}. Stays open while the run is paused.
- [Send a message to a run](https://docs.boxline.dev/api-reference/send-agent-run-message.md): The agent reads it at its next step boundary (before its next model call; a call or tool under way is not interrupted), as a user turn of its own (never inside page or tool text), and it then shows as a message step. A run paused because it asked for help takes the message as the answer and goes on; runs paused by a person (Pause a run), for a CAPTCHA, or for the model provider's safety checks get it after the resume (only a resume acknowledges safety checks). Values of the run's variables and secrets in it are replaced by their %name%. 409 invalid_state once the run has finished (use Resume a run for a run that stopped at its step limit), 409 run_not_live (or session_ended) when the server running it stopped, 409 too_many_messages after 50 to one run. 10 per minute per run, 60 per minute per project.
- [Pause a run](https://docs.boxline.dev/api-reference/pause-agent-run.md): The agent finishes its current step, then waits (status paused), so a person can act in the live view or the terminal: a CAPTCHA, a 2FA code, a choice. Works on every kind of run. 409 invalid_state unless running; 409 run_not_live (or session_ended) when the server running it stopped.
- [Resume a run](https://docs.boxline.dev/api-reference/resume-agent-run.md): Keeps the SAME run going: one job, one run id, steps and usage add up. A paused run: the agent is told a person had the browser (plus the optional note) and looks at the page again. A run that stopped early (resumable: it used its steps, reached its cost limit, hit too many errors or repeated itself, or its server restarted): it goes on in its session with optional new maxSteps, maxCostUsd and its variables again, and the optional note (shown to the agent as a message). 409 not_resumable for any other run; 409 session_not_running when its session was deleted; 409 run_not_live (or session_ended) when the server running it stopped; the usual plan, spend and rate checks for a run that stopped early.
- [Cancel a run](https://docs.boxline.dev/api-reference/cancel-agent-run.md): Interrupts a model call in progress and stops the run's own session. 409 once finished.
- [List models](https://docs.boxline.dev/api-reference/list-agent-models.md): List models.

## API reference: Tasks

- [Create a task](https://docs.boxline.dev/api-reference/create-task.md): Needs the plan's agentRuns. The plan limits tasks (Free 1) and schedules switched on (Free 0, Hobby 5, Startup 50, Scale no limit): 402 plan_limit beyond. A secret variable has no default (its value is never stored), and a task with one cannot have a schedule. 60 changes per minute per project.
- [List tasks](https://docs.boxline.dev/api-reference/list-tasks.md): List tasks.
- [Get a task](https://docs.boxline.dev/api-reference/get-task.md): Get a task.
- [Update a task](https://docs.boxline.dev/api-reference/update-task.md): Any TaskInput fields; null removes output, session, model, maxCostUsd, notifyOnFailure or schedule (maxSteps null: no step limit). schedule fields are merged into the current schedule (e.g. {"schedule": {"enabled": false}} pauses it); switching it on, or changing cron or timezone, counts the next run from now. session merges the same way: each top-level field sent replaces that field (browser and env as a whole), a field sent as null goes back to its default, fields not sent keep their saved value (a custom proxy keeps its stored password), session: null removes them all, and the merged session is checked as a whole.
- [Delete a task](https://docs.boxline.dev/api-reference/delete-task.md): Its run history goes with it; its agent runs stay, and runs in progress go on.
- [Run a task](https://docs.boxline.dev/api-reference/start-task-run.md): Starts an agent run with the task's settings: non-secret values are written into the instruction, secret ones go in as agent variables (the model sees only %name%). 400 missing_variables when a variable without a default has no value. Counts as an agent run (30 per minute per project, the plan's agentRuns, the spend cap). With an Idempotency-Key, variable values are not compared (they are never stored in any form).
- [List a task's runs](https://docs.boxline.dev/api-reference/list-task-runs.md): Runs by hand and on the schedule, with skipped and missed scheduled times (kept 30 days).

## API reference: Profiles

- [Create a profile](https://docs.boxline.dev/api-reference/create-profile.md): Empty: start a session with profile:{id, persist:true} to fill it. With fromSession: holds that working session's cookies and the site storage of its open tabs right now; with attach: true the session also saves to it from now on (at its checkpoints and when it stops; 409 conflict when it already has a profile). 400 for a session without a browser, 404 for another project's session, 409 session_not_running once it has stopped, 413 profile_too_large over 16 MB; 30 saves from sessions per minute per project. 402 plan_limit past the plan's maxProfiles (profiles per project) or maxProfileBytes (what they hold together).
- [List profiles](https://docs.boxline.dev/api-reference/list-profiles.md): List profiles.
- [Get a profile](https://docs.boxline.dev/api-reference/get-profile.md): Get a profile.
- [Update a profile](https://docs.boxline.dev/api-reference/update-profile.md): credential links a password credential (null unlinks it): sessions with this profile, and agent runs, task runs and steps in them, get it as if listed in their credentials (same scope rules), so the AI can sign in again when the cookies have expired. 404 credential_not_found, 400 for a secret, 402 without loginDetails.
- [Delete a profile](https://docs.boxline.dev/api-reference/delete-profile.md): Delete a profile.

## API reference: Credentials

- [Create a credential](https://docs.boxline.dev/api-reference/create-credential.md): A website password (type: "password": sites, user name, password and an optional code source: totp with a 2FA key, push or url; needs the plan's loginDetails) or a secret (type: "secret": one value). Each field is sealed (AES-256-GCM under the platform's secrets key) and never returned. 409 credential_exists for a name the project has (change it with PATCH), 402 plan_limit beyond the plan's maxCredentials (200 by default), 400 code_url_not_allowed for a codeUrl that is not a public HTTPS address (503 code_url_unavailable when this platform cannot send codeUrl requests). Setting codeUrl answers with codeUrlSecret once. 60 writes per minute per project.
- [List credentials](https://docs.boxline.dev/api-reference/list-credentials.md): Everything about each credential except its values, in name order.
- [Get a credential](https://docs.boxline.dev/api-reference/get-credential.md): Get a credential.
- [Update a credential](https://docs.boxline.dev/api-reference/update-credential.md): Changes what is sent and keeps the rest; type cannot change. A change of origins that adds a site (or, for a secret, removes the limit), and a scope/shell that makes an AI-only credential readable by shells, needs the sensitive values in the same request (a secret's value; a password's password, and totpSecret when it has 2FA), and so does a change of codeSource or codeUrl (the password), and applies only if the sites, scope, shell, codeSource and codeUrl did not change meanwhile (409 conflict). A new codeUrl answers with a new codeUrlSecret once, and so does rotateCodeUrlSecret: true (any time; the old one stops at once). Sessions that export the credential get the new values on their next machine (resume or recovery); runs already working keep the ones they started with.
- [Delete a credential](https://docs.boxline.dev/api-reference/delete-credential.md): Profiles that link it are unlinked.
- [Push a 2FA code or sign-in link](https://docs.boxline.dev/api-reference/push-credential-code.md): For a password with codeSource "push": the code (or sign-in link) the site sent by email or SMS. Used once, by a wait that began before it arrived (a run typing %NAME.otp%, opening %NAME.link%, a type action, a login action or boxline-otp); kept sealed at most 10 minutes (at most 10 per credential). A link must be on one of the credential's sites (400 credential_link_wrong_site). Audited (action "code", never the value); counts as a credential write (60 per minute per project).
- [List the audit log](https://docs.boxline.dev/api-reference/credentials-audit.md): Changes to credentials (who: user:<email>, key:<id> or support), and each use once per session, command, agent run, step session, script, task run, type action session or boxline-otp session (by what). Newest first. Never values.

## API reference: Extensions

- [Upload an extension](https://docs.boxline.dev/api-reference/upload-extension.md): An unpacked Manifest V3 extension as a zip, at most 10 MB: the raw body, or multipart/form-data with the zip in a file field. It is checked before it is stored (400 invalid_extension says why): Manifest V3 only; no nativeMessaging, debugger, proxy, vpnProvider or enterprise.* permissions; no native programs or libraries, symbolic links or unsafe paths; at most 32 MB and 5000 files unpacked. Needs the plan feature extensions. 30 per hour per project; at most 100 extensions per project (409 limit_reached). The plan and the rate limit are checked before the body is read. On the operator's deny list: 403 extension_denied. With a console login, only from the platform's own sites (403 cross_site_request). An extension sees every page and every typed value in the sessions that use it. Start sessions with extensions: [id].
- [List extensions](https://docs.boxline.dev/api-reference/list-extensions.md): List extensions.
- [Get an extension](https://docs.boxline.dev/api-reference/get-extension.md): Get an extension.
- [Delete an extension](https://docs.boxline.dev/api-reference/delete-extension.md): Removes the stored zip. Sessions already running with it keep it in their current browser; when such a session resumes or recovers, it is skipped (a lifecycle warning "extension missing").

## API reference: Webhooks

- [Create a webhook endpoint](https://docs.boxline.dev/api-reference/create-webhook.md): The response holds the endpoint's signing secret (whsec_…): the only time it is shown. Public HTTPS addresses only (400 webhook_url_not_allowed for http, private or reserved addresses, names that resolve to one, mail ports, or a user name or password in the URL). The plan limits how many endpoints a project has (402 plan_limit). 60 changes per minute per project.
- [List webhook endpoints](https://docs.boxline.dev/api-reference/list-webhooks.md): Oldest first. Signing secrets are never shown again after they are made.
- [Get a webhook endpoint](https://docs.boxline.dev/api-reference/get-webhook.md): Get a webhook endpoint.
- [Update a webhook endpoint](https://docs.boxline.dev/api-reference/update-webhook.md): enabled: false switches it off (deliveries not yet made then fail); enabled: true switches it back on, also after the platform switched it off, and forgets its earlier failures. rotateSecret: true makes a new signing secret, answered once as secret; the old one keeps signing for 24 hours.
- [Delete a webhook endpoint](https://docs.boxline.dev/api-reference/delete-webhook.md): Its queued deliveries and its delivery log go with it.
- [Send a test event](https://docs.boxline.dev/api-reference/test-webhook.md): Sends a webhook.test event to this endpoint only (also while it is switched off), signed like every delivery, and waits up to 12 seconds for the answer. With type, it sends a made-up sample of that event type instead (sample ids, no real data), so a receiver can be tried with every shape. Either way the body carries test: true. One attempt, no retries, and it never counts toward switching the endpoint off (a 410 answer still does). 10 per minute per project.
- [List deliveries](https://docs.boxline.dev/api-reference/list-webhook-deliveries.md): Newest first: each delivery's status, attempts (with a short history), the last answer's status, time and first 1 KB, and the error. The body that was sent is kept 7 days (then payload is null); log entries are kept 30 days.
- [Retry a delivery](https://docs.boxline.dev/api-reference/retry-webhook-delivery.md): Sends a finished delivery (delivered or failed) again now, with the same event id and body, and waits up to 12 seconds for the answer. 409 invalid_state while it is still queued, payload_expired after 7 days, webhook_disabled while the endpoint is switched off. Shares the limit of test events (10 per minute).
- [List event types](https://docs.boxline.dev/api-reference/list-webhook-event-types.md): Every event type an endpoint can subscribe to, in the order a picker shows them, with a group and what it says. Subscribe to "*" for all of them, those added later too. New types may be added at any time, so receivers ignore types they do not know.

## API reference: Project

- [Get project settings](https://docs.boxline.dev/api-reference/get-project-settings.md): captchaDefault is what new sessions and agent runs do about CAPTCHAs when they do not set captcha themselves ("Solve CAPTCHAs automatically" in the console is solve). captchaDefaultEffective is what they get now: ask when the setting is solve but the plan no longer includes automatic solving.
- [Update project settings](https://docs.boxline.dev/api-reference/set-project-settings.md): Only the fields you send change. solve needs a plan with automatic CAPTCHA solving (402 feature_not_in_plan). An explicit captcha on a session or agent run always wins. Changes apply to sessions started afterwards. A change made by an admin acting as you is recorded in the admin audit log.
- [List model keys](https://docs.boxline.dev/api-reference/list-model-keys.md): The four providers (anthropic, openai, xai, google) with the project's own-key state. A key is never returned: preview is its last 4 characters. use is the stored choice of whose key calls use; useEffective what they use now (a plan without platformModels, Free, always uses the project's own key). Model keys belong to the project, like everything an API key reaches. Without one, Boxline's keys are used where the plan includes them; each run says which in keySource.
- [Set a model key](https://docs.boxline.dev/api-reference/set-model-key.md): Send key, use, or both. Saving a key without use sets use: project. The provider is asked one read-only question (list models) first: a refusal is 400 invalid_model_key; if the provider cannot be reached the key is saved with verified: false. use: project needs a saved key (400); use: platform needs the plan feature platformModels (402 feature_not_in_plan) and keeps the saved key. Runs on the project's own key have no model charge from Boxline. 10 writes a minute per project (429). Every change is logged, never with a value.
- [Delete a model key](https://docs.boxline.dev/api-reference/delete-model-key.md): Removes the key and sets use back to platform (on Free calls then need a new key). Also 204 when there was none.
- [Create an API key](https://docs.boxline.dev/api-reference/create-api-key.md): The key is in the response only (it is stored hashed). 20 per hour per project. With an Idempotency-Key, the response is replayed only to the same caller (the same API key or console login; anyone else gets 422), and revoking the key forgets it. 403 email_unconfirmed while every owner of the project's organization is a sign-up still held back until it enters its confirmation code.
- [List API keys](https://docs.boxline.dev/api-reference/list-api-keys.md): Active keys, oldest first. Keys themselves are never shown again; prefix identifies them.
- [Revoke an API key](https://docs.boxline.dev/api-reference/revoke-api-key.md): Revoke an API key.
- [Get usage and cost](https://docs.boxline.dev/api-reference/get-usage.md): What the project used and spent in the period, and what the overview page shows (running sessions, the plan's concurrency limit, agent runs and their model cost, per day too).

## API reference: Account

- [Sign up](https://docs.boxline.dev/api-reference/signup.md): Creates a user, their personal organization on the Free plan with a first project and API key, and logs in (cookie bx_session). Needs acceptTerms: true (400 terms_not_accepted otherwise); the acceptance is recorded with the terms version. With inviteToken (from an invitation link; the email must be the invited one) the invitation is accepted too and the login starts in that organization. Where mail is delivered, signup also emails a 6-digit confirmation code, and the new account is held back until it enters it (POST /v1/auth/confirm-email; see emailConfirmationRequired in /v1/auth/me); signing in later never asks for a code.
- [Log in](https://docs.boxline.dev/api-reference/login.md): Starts a console login (cookie bx_session, 14 days). Limited per IP and per email; the RateLimit-* headers show the IP limit only.
- [Log out](https://docs.boxline.dev/api-reference/logout.md): Ends the console login and clears the cookie.
- [Get who is calling](https://docs.boxline.dev/api-reference/me.md): Also answered for a suspended project, so the console can say why. With an API key: its project and its organization's summary (role null), and organizations is null. With a console login: also every organization the user belongs to, with their role and the projects they reach.

## API reference: Platform

- [Get prices and plans](https://docs.boxline.dev/api-reference/get-pricing.md): Get prices and plans.
- [Get the OpenAPI description](https://docs.boxline.dev/api-reference/get-open-api.md): Get the OpenAPI description.
- [Check health](https://docs.boxline.dev/api-reference/health.md): Nothing about capacity or load.

## SDKs

- [Node SDK](https://docs.boxline.dev/node-sdk.md): The TypeScript SDK for Node 18 and later: install it, create a client, and every method it has.
- [Python SDK](https://docs.boxline.dev/python-sdk.md): The Python SDK: install it, create a client, and every method it has.
- [CLI](https://docs.boxline.dev/cli.md): The boxline command line: run the AI agent from your terminal, search the web, fetch pages, and work with sessions, shells and files.

## SDKs: MCP server

- [Setup](https://docs.boxline.dev/mcp-reference.md): Add the hosted or the local MCP server to Claude Desktop, Claude Code, Cursor or any other MCP client, what it checks over HTTP, and how a client signs people in with OAuth.
- [session_create](https://docs.boxline.dev/mcp-reference/session-create.md): Start a new session and get its sessionId.
- [session_list](https://docs.boxline.dev/mcp-reference/session-list.md): Find your sessions again.
- [session_stop](https://docs.boxline.dev/mcp-reference/session-stop.md): Stop a session and keep it.
- [session_resume](https://docs.boxline.dev/mcp-reference/session-resume.md): Bring a stopped session back.
- [session_delete](https://docs.boxline.dev/mcp-reference/session-delete.md): Delete a session for good.
- [browser_login](https://docs.boxline.dev/mcp-reference/browser-login.md): Sign in with a saved password, in one call.
- [browser_navigate](https://docs.boxline.dev/mcp-reference/browser-navigate.md): Open a URL in the session's browser.
- [browser_click](https://docs.boxline.dev/mcp-reference/browser-click.md): Click an element or a point on the page.
- [browser_type](https://docs.boxline.dev/mcp-reference/browser-type.md): Type text, or a saved credential.
- [browser_press](https://docs.boxline.dev/mcp-reference/browser-press.md): Press a key, a key combination, or several in a row.
- [browser_computer](https://docs.boxline.dev/mcp-reference/browser-computer.md): Run one computer-use action from a model, and see the screen.
- [browser_act](https://docs.boxline.dev/mcp-reference/browser-act.md): Do one or more steps in the browser, in plain English or as exact actions.
- [browser_screenshot](https://docs.boxline.dev/mcp-reference/browser-screenshot.md): Take a screenshot of the current tab.
- [browser_read](https://docs.boxline.dev/mcp-reference/browser-read.md): Read the current page as text.
- [shell_exec](https://docs.boxline.dev/mcp-reference/shell-exec.md): Run a bash command in the session's shell.
- [files_list](https://docs.boxline.dev/mcp-reference/files-list.md): List files in the workspace.
- [files_read](https://docs.boxline.dev/mcp-reference/files-read.md): Read a text file from the workspace.
- [files_write](https://docs.boxline.dev/mcp-reference/files-write.md): Write a text file into the workspace.
- [files_delete](https://docs.boxline.dev/mcp-reference/files-delete.md): Delete a file from the workspace.
- [credentials_list](https://docs.boxline.dev/mcp-reference/credentials-list.md): List the saved credentials (never their values).
- [web_fetch](https://docs.boxline.dev/mcp-reference/web-fetch.md): Fetch a page without a session.
- [web_search](https://docs.boxline.dev/mcp-reference/web-search.md): Search the web, with no session.
- [web_screenshot](https://docs.boxline.dev/mcp-reference/web-screenshot.md): Screenshot a web page, with no session.
- [web_extract](https://docs.boxline.dev/mcp-reference/web-extract.md): Get JSON from up to 10 pages, with no session.
- [web_crawl_start](https://docs.boxline.dev/mcp-reference/web-crawl-start.md): Crawl a site from a start URL, with no session.
- [web_crawl_get](https://docs.boxline.dev/mcp-reference/web-crawl-get.md): Get a crawl's state and its next pages.

## Integrations

- [Connect Boxline to ChatGPT, Claude and Claude Code](https://docs.boxline.dev/connect-chatgpt-claude.md): Connect Boxline to ChatGPT, Claude or Claude Code with a Boxline sign-in and no API key. What a connected app can and cannot do, how to disconnect it, and the Boxline plugin.
- [MCP](https://docs.boxline.dev/mcp.md): Give ChatGPT, Claude, Cursor and other MCP clients a cloud browser, a shell and files as tools: sign in with one click, use an API key, run it over stdio, or host it yourself.
- [LangChain](https://docs.boxline.dev/langchain.md): Two LangChain tools backed by the platform, a page fetch and a whole browser task, given to a LangChain agent, in Node and Python. Tested code.
- [CrewAI](https://docs.boxline.dev/crewai.md): A CrewAI tool that reads pages in a sandboxed browser, used by a one-agent crew. Tested code, in Python.
- [Vercel AI SDK](https://docs.boxline.dev/vercel-ai-sdk.md): Web search and page fetch as AI SDK tools: the model decides when to search and which pages to read. Tested code.
- [Stagehand](https://docs.boxline.dev/stagehand.md): Stagehand's act() and extract() on a session's browser, with Stagehand 3.7.x and zod 3 (and why not v4). Tested code.
- [Browser Use](https://docs.boxline.dev/browser-use.md): A Browser Use agent on your own OpenAI key drives a session's browser. Tested code, in Python.
- [OpenAI computer use](https://docs.boxline.dev/openai-computer-use.md): Your own loop with OpenAI's computer tool: each computer_call's actions run on a session, and the screen goes back to the model. Tested code, Node and Python.
- [Claude computer use](https://docs.boxline.dev/claude-computer-use.md): Your own loop with Claude's computer tool: each tool_use runs on a session, and the screen goes back as the tool result. Tested code, Node and Python.

## Examples

- [All examples](https://docs.boxline.dev/examples.md): Runnable examples in Node and Python, each with a result check that proves it worked: data out, logins, forms, monitoring, AI agents, research, site quality, data for AI and integrations. Open source on GitHub.

## Examples: Get started

- [Sessions and Playwright](https://docs.boxline.dev/examples/sessions-and-playwright.md): Start a session, connect Playwright to its browser over CDP, read a page, and stop the session. The same page is then read through the actions API, which drives the browser without Playwright.
- [Update a session](https://docs.boxline.dev/examples/update-a-session.md): One call changes a running session: session.update({ timeout: 600, rotateUrls: true }) gives it a longer life and fresh signed URLs, and the session keeps running. This example creates a session for 5 minutes, updates it to 10, and shows what changed: expiresAt moved by the extra five minutes, the old connectUrl and liveUrl stopped working, and the new ones work.
- [Get a page, or a browser?](https://docs.boxline.dev/examples/fetch-or-browser.md): The same site two ways. fetch is one call that returns the page as Markdown (rendered in a real browser in a sandbox): use it to read. A session is a browser that stays open between calls, so it can click through pages, fill forms and sign in: here it clicks on to page 3.
- [Search, read, answer](https://docs.boxline.dev/examples/search-read-answer.md): Search the web, open the top results in a sandboxed browser, and answer the question from those pages with their addresses as sources.

## Examples: Data out

- [Product page to JSON](https://docs.boxline.dev/examples/product-to-json.md): Pull a product's name, price, stock and specs from its page into a fixed shape given as a JSON Schema.
- [Site to Markdown](https://docs.boxline.dev/examples/site-to-markdown.md): Crawl a site into clean Markdown files, one per page, with each page's address and title at the top: ready for AI search. The crawler respects robots.txt and crawl-delay.
- [Link checker](https://docs.boxline.dev/examples/link-checker.md): Crawl the pages a page links to (on the same site) and report the broken ones (HTTP 400 and up, or not loading) and the slow ones (timed with fetch, one at a time). Its links to other sites are opened too and sorted into working, broken and blocked: a site that answers 401, 403 or 429, or shows a CAPTCHA, refuses automated visitors, so check those links by hand.
- [SEO and metadata audit](https://docs.boxline.dev/examples/seo-audit.md): Check each page's title, meta description, headings, Open Graph tags (title, description, image), Twitter/X card, canonical link, noindex, page language and image alt texts, list what to fix, and have a model suggest a description for pages that have none.
- [Prices by country](https://docs.boxline.dev/examples/prices-by-country.md): Open the same product page through residential proxies in three countries and compare the prices side by side, with the country each request really came from.
- [Download all images](https://docs.boxline.dev/examples/download-all-images.md): The browser finds every image on a page, the shell downloads them into the workspace with the browser's cookies (so images behind a sign-in work too) and zips them, and the files API brings the zip back.

## Examples: Documents

- [Financial report to data](https://docs.boxline.dev/examples/financial-report-to-data.md): Find a company's latest quarterly report on its investor page, download the PDF in the shell, turn it into text with pdftotext, and have a model read the key figures into JSON.

## Examples: Logins

- [Save a login once](https://docs.boxline.dev/examples/save-a-login.md): Sign in by hand in the live view once. The session saves its cookies and local storage into a profile when it ends, and later sessions start from it already signed in.
- [My invoices](https://docs.boxline.dev/examples/my-invoices.md): Open your billing page signed in with a profile and download the invoices of the last 3 months through the browser; the files API copies them to your computer.
- [Hand over for a code](https://docs.boxline.dev/examples/hand-over-for-a-code.md): The AI signs in with your username and a password kept as a credential; when the site asks for a code sent by SMS or an app, it pauses and asks you, then types the code and carries on. The run names the credential (credentials: ["SIGNIN_PASSWORD"]) and the model only ever sees %SIGNIN_PASSWORD%.
- [Two-factor sign-in](https://docs.boxline.dev/examples/two-factor-sign-in.md): Keep a site's sign-in details as a password credential once (user name, password and the 2FA setup key) and link it to a profile, then an agent run signs in with %NAME.username%, %NAME.password% and %NAME.otp%: the platform makes the current 6-digit code at the moment it is typed. The model never sees any of them, and they are typed only on that site.
- [Email-code sign-in](https://docs.boxline.dev/examples/email-code-sign-in.md): Some sites email a one-time code (or a sign-in link) after the password. Save the password as a credential whose codes you send yourself (codeSource: "push"). An agent run signs in with %NAME.username%, %NAME.password% and %NAME.otp%; when it reaches the code field it **waits**. You hear of it (a code step in the run, and the webhook credential.code_needed), read the email, and send the code with credentials.pushCode. The platform types it. The model never sees the password or the code, and a code is used once, by the wait it was sent for.

## Examples: Forms

- [Fill a form from a spreadsheet](https://docs.boxline.dev/examples/form-from-spreadsheet.md): Read rows from a CSV with Python in the shell, and fill one form per row with plain-English steps, pausing before the first submit so you can check it in the live view. The row values reach the steps as %name%-style variables: the model picks the fields but never sees the values.
- [Public registry lookup](https://docs.boxline.dev/examples/public-registry-lookup.md): An agent finds a company in the UK's public company register (Companies House) and opens its page; extract then reads the record into JSON with a schema.
- [Company details from its legal pages](https://docs.boxline.dev/examples/company-details-from-legal-pages.md): Crawl a site's pages, pick its terms, privacy and imprint pages, and have a model read the organisation's legal name and postal address from them.

## Examples: Monitoring

- [Watch a price](https://docs.boxline.dev/examples/watch-a-price.md): A task reads a product's price and stock into a fixed shape (an output schema), a schedule runs it every hour, and each finished run goes to your webhook receiver (task_run.finished), which verifies the signature and compares the price with the last one it saw.
- [Visual uptime check](https://docs.boxline.dev/examples/visual-uptime-check.md): Two checks of your key pages:
- [Changelog watcher](https://docs.boxline.dev/examples/changelog-watcher.md): A task reads the newest released entry of a product's changelog into JSON (version, date, title, the changes and a one-sentence summary) every morning, and the example says whether it is new since the last time it looked. A new entry is posted to your team's chat.
- [Security headers check](https://docs.boxline.dev/examples/security-headers-check.md): Which security headers a site sends, which are missing, and how its cookies are flagged; the redirect chain hop by hop; HSTS in detail (how many days, subdomains, preload); and how the site answers a request from another site (CORS), flagging an origin echoed back with credentials. fetch opens the page in a real browser; curl in the session's shell reads the raw headers.

## Examples: AI agents

- [Research a question](https://docs.boxline.dev/examples/research-a-question.md): An agent searches the web, reads several sources in its browser, and answers with citations.
- [Agent with a human in the loop](https://docs.boxline.dev/examples/agent-with-human-in-the-loop.md): An agent that asks you when it is unsure (here: which of several books to pick), waits for your answer, then carries on.
- [Computer use](https://docs.boxline.dev/examples/computer-use.md): The agent drives the browser the way a person does, from screenshots with the mouse and keyboard (the model provider's own computer-use tool), instead of reading the page's structure.
- [Compare models](https://docs.boxline.dev/examples/compare-models.md): A small benchmark: the same browser tasks, each with its right answer written down beforehand (tasks.json), run by two or more models side by side. The example scores every run itself (no model judges) and prints each model's pass rate, time, steps and cost.
- [Wiki race](https://docs.boxline.dev/examples/wiki-race.md): The old game: get from one Wikipedia article to another by clicking links only. An agent plays it in a real browser. The example then judges the game without trusting the agent: it reads the pages the browser really visited from the session's log, checks every hop against Wikipedia's API in the session's shell, and works out whether a shorter route existed.
- [Shell-only agent](https://docs.boxline.dev/examples/shell-only-agent.md): An agent run with no browser at all: session: { browser: false, shell: true } gives it a machine with only a shell and a /workspace disk. The agent generates a CSV by a rule, computes statistics from it with Python and writes a report. Then the example reads the files back through the API (files.readText) and recomputes every number itself, so the result does not rest on what the agent says.

## Examples: Browser + shell

- [Download and add up](https://docs.boxline.dev/examples/download-and-add-up.md): The browser downloads a CSV report, Python in the shell adds up its revenue column and saves the total, and the browser types the total into a form. Browser, shell and files share one /workspace.
- [PDF to summary](https://docs.boxline.dev/examples/pdf-to-summary.md): Download a PDF in the shell, turn it into text with pdftotext, and have a model sum it up in 5 bullet points from the session's browser.
- [Screenshots to a PDF report](https://docs.boxline.dev/examples/screenshots-to-pdf.md): Screenshot several pages in the session's browser, then combine them into one PDF with Python (Pillow) in the session's shell.
- [Video clip](https://docs.boxline.dev/examples/video-clip.md): Download a video you are allowed to download with yt-dlp in the session's shell, and cut its first 30 seconds with ffmpeg. Only the first part is fetched. If the site refuses the download, the example stops: it never disguises the downloader.
- [Test my staging site](https://docs.boxline.dev/examples/test-my-staging-site.md): Clone your repository in the session's shell, run its tests against your staging site, and open every page that failed in the session's browser for a screenshot.
- [Tables to CSV](https://docs.boxline.dev/examples/tables-to-csv.md): Every data table on a page, read in a real browser, written as CSV, with the numbers in each column worked out in the session's shell. No model reads the data: what is in the CSV is what is on the page.
- [Session replay as a GIF](https://docs.boxline.dev/examples/session-replay-gif.md): Every session keeps a recording: one frame each time the screen changes, with the time and the page. This example browses a shop for a few seconds, then turns that session's recording into an MP4 and a GIF with ffmpeg in a second, shell-only session. Use it to show what an agent did in a pull request, a bug report or a demo.
- [Results after stop](https://docs.boxline.dev/examples/results-after-stop.md): A session's files outlive its machine. This example writes a folder of files in a shell session, stops the session, and then lists the folder, reads two of its files and downloads the whole folder as one .tar.gz, all **without resuming the session**: files.list, files.readText and files.archive answer from the workspace the session saved when it stopped, so no machine runs and no machine time is billed.
- [Solve and test](https://docs.boxline.dev/examples/solve-and-test.md): An agent gets a programming exercise and a machine with a shell. It reads the instructions, writes solution.py, runs the exercise's tests, reads what failed, fixes, and runs them again until they pass. Then the example runs the tests itself, from a fresh download in another folder, so the result does not rest on what the agent says.
- [Docs to working code](https://docs.boxline.dev/examples/docs-to-working-code.md): Give an agent an API's documentation and a goal. In one session it reads the docs in the browser, writes a Python client in the shell, runs it, reads the errors and fixes it until the output is right. Then the example runs the script again itself: what you get is code that has run against the real API, with its output beside it.
- [Earnings from EDGAR](https://docs.boxline.dev/examples/earnings-from-edgar.md): Yearly revenue, net income and diluted EPS of a few public companies, straight from the filings: SEC EDGAR's official companyfacts API, read in a session's shell with Python. Growth and margins are worked out there too, with a CSV, a chart and a short summary. No model reads or writes a number, so every figure is one a company filed.

## Examples: Quality

- [Accessibility check](https://docs.boxline.dev/examples/accessibility-check.md): Run the axe-core accessibility scan on a page in the session's browser and list the issues, worst first. The shell fetches axe-core inside the machine; Playwright runs it in the page.
- [Dark pattern review](https://docs.boxline.dev/examples/dark-pattern-review.md): Two parts:

## Examples: Chat and research

- [Chat with a page](https://docs.boxline.dev/examples/chat-with-a-page.md): Open a page once in a cloud browser, then ask questions about it in the terminal. Each answer is read from the page that is open in the session, takes the chat so far into account, and quotes the words on the page it is based on. When the page does not say, the answer says so instead of guessing.
- [Company research](https://docs.boxline.dev/examples/company-research.md): Research a company on one topic: search the web, read the top pages in a cloud browser, and get structured findings (an overview, the findings, key points and what is still open) where every key point names the page it comes from.
- [Compare two sites](https://docs.boxline.dev/examples/compare-two-sites.md): Read two product sites side by side: each one's headline, features, pricing and what it says makes it different, which features they share or not, which is cheaper, and a two-sentence summary. A screenshot of each landing page goes into the report.
- [Watch competitor pages](https://docs.boxline.dev/examples/watch-competitor-pages.md): Check a few pages now and then, tell **real** changes (a price, a plan, a feature, an announcement) from noise (a date, a counter, a rotating banner), and post the real ones to your chat.
- [Daily tech digest](https://docs.boxline.dev/examples/daily-tech-digest.md): Collect today's stories from Hacker News and a few blogs, keep the ones on your topics, rank them, read the top ones in a cloud browser and summarise them, then make a Markdown digest and a PDF slide deck and post the digest to your chat. Run it every morning from cron or a CI schedule.
- [Tech signals](https://docs.boxline.dev/examples/tech-signals.md): Find the themes that many Hacker News stories of the last days share, read each theme's stories, and make one grounded prediction per theme: a short claim, why, how confident, and the facts from the pages it rests on.
- [GitHub profile summary](https://docs.boxline.dev/examples/github-profile-summary.md): What a developer works with, measured instead of guessed: their public GitHub profile and repository list are read in a cloud browser, then their top repositories are cloned in a session's shell and measured there (lines of code per language, frameworks and libraries from the manifest files, CI, containers and infrastructure).
- [Ask a repository](https://docs.boxline.dev/examples/ask-a-repo.md): Clone a git repository into a session's shell and let an agent answer your questions about it by reading the code (ls, grep, cat, git log), not a web page about it. Every answer names the files it rests on, and the example checks that those files exist.
- [Top story discussion](https://docs.boxline.dev/examples/top-story-discussion.md): Take today's most-voted Hacker News story, read the article and its discussion in a cloud browser, and sum up both: what the article says, the viewpoints in the comments (each with a short quote and how many hold it), where people agree and disagree, and what is still open.
- [Bring your own model](https://docs.boxline.dev/examples/bring-your-own-model.md): Boxline gets the page (rendered in a real browser, scripts run, as clean Markdown); your own model turns it into JSON, with your own key. Any OpenAI-compatible endpoint works: OpenAI, Fireworks, Together, Groq, or a model on your machine with Ollama or vLLM. One HTTP request, no vendor SDK.
- [Changelog between refs](https://docs.boxline.dev/examples/changelog-between-refs.md): Clone a repository into a session's shell, list the commits between two tags (or any two refs), and let an agent in that session write the changelog from the history itself, grouped for readers, every line citing its commits.
- [Chat with a video](https://docs.boxline.dev/examples/chat-with-a-video.md): Ask questions about a video and get answers from what is said in it, each with the moments (mm:ss) to jump to.
- [Article to speech](https://docs.boxline.dev/examples/article-to-speech.md): Turn a web article into an MP3 you can listen to, with no speech API key: the article's own paragraphs are taken from the page and spoken offline in a session's shell.

## Examples: Monitoring and drafts

- [Status page watch](https://docs.boxline.dev/examples/status-page-watch.md): Watch the official status pages of the services you depend on, and get a chat message when something changes: a component degraded or back to normal, an incident opened or resolved. Every page is read into the same shape whatever its format (overall state, components, open incidents), and each alert comes with a screenshot of the page.
- [News to drafts](https://docs.boxline.dev/examples/news-to-drafts.md): Follow a few blogs or news pages and, each run, turn what is new since the last run into drafts for a person to review: a newsletter (Markdown and HTML) and one short social post per item, each with its source link. Nothing is sent and nothing is posted.
- [Store trust check](https://docs.boxline.dev/examples/store-trust-check.md): Before buying from an online store you do not know, gather the signals that tell a real shop from a scam and score them, with every reason shown.

## Examples: Shopping and places

- [Product alternatives](https://docs.boxline.dev/examples/product-alternatives.md): Read a product page, find comparable products, rank them by how close they are (with a reason each) and show the price difference. Prices are remembered, so the next run says which went up or down.
- [Local businesses](https://docs.boxline.dev/examples/local-businesses.md): List the businesses of one kind in a place (cafés in Bath, bike shops in Utrecht, printers in Lyon) from OpenStreetMap's open data, then read the websites they list to say what each offers. For finding a place to go, a supplier or a venue.
- [Gift ideas](https://docs.boxline.dev/examples/gift-ideas.md): Describe the person and a budget, and get gift ideas found on real gift guides and reviews, each with why it suits them, a price range when the page gives one, and the page it came from. Ideas over the budget are left out.

## Examples: Site quality

- [UI review](https://docs.boxline.dev/examples/ui-review.md): A design check of a page from what the browser actually renders, at desktop width and at phone width, with screenshots and the top fixes in plain words.
- [Data collection map](https://docs.boxline.dev/examples/data-collection-map.md): What personal data a site's pages ask for, and where it goes: a starting point for a privacy review of your own site.
- [Form anatomy](https://docs.boxline.dev/examples/form-anatomy.md): Take a web form apart without submitting it: every field with its label, type and rules, the messages the browser itself shows for an empty and for a wrong value, the hidden fields (and whether one is a CSRF token), where and how it posts, and warnings. For testing and documenting your own forms.
- [Hero CTA review](https://docs.boxline.dev/examples/hero-cta-review.md): Does your landing page's main call to action work? A computer-use agent looks at the page the way a visitor does and picks the hero's main button; then that button is measured in the page, its link is checked, and a short critique says what to change.

## Examples: Data for AI

- [Site map](https://docs.boxline.dev/examples/site-map.md): Crawl a site and see its shape: the page tree, the heaviest pages, the broken links (and which pages link to them), and the **orphans**: pages the site's sitemap.xml lists that no crawled page links to. A crawler alone can never find orphans, since it only reaches pages that are linked; the sitemap is what shows them.
- [Site to RAG chunks](https://docs.boxline.dev/examples/site-to-rag-chunks.md): Turn a site (or one page) into chunks ready for an embedding pipeline or a vector store: boilerplate removed, each page cut at its headings and then into chunks within a token budget, every chunk with its source address, its heading path and a ready-to-embed text that starts with that path.
- [Crawl and extract](https://docs.boxline.dev/examples/crawl-and-extract.md): Find every page of one kind on a site, then pull the same fields from each into JSONL and CSV. The crawl follows only links that match a pattern (product pages, say, not categories), and extract reads 10 pages per call with one schema. Each price is then checked against the page's own crawled text: a row whose price is not written on its page is marked verified: false, so a model slip does not go unnoticed.
- [Page resources](https://docs.boxline.dev/examples/page-resources.md): Open a page in a cloud browser and list everything it loads, taken from the session's own network log: requests and bytes by type and by domain, the third parties, what failed, and the slowest and heaviest requests, with a picture of the page.
- [Pages to dataset](https://docs.boxline.dev/examples/pages-to-dataset.md): Turn web pages into a dataset for fine-tuning or evaluation: clean text passages and question-answer pairs, split into train and eval sets in JSONL. The pages come from your list of addresses, or from a web search.
- [Context pack](https://docs.boxline.dev/examples/context-pack.md): Squeeze a few pages into a small, cited context for a model's prompt. Each source gets a tag ([S1], [S2], …), a summary, its key facts (each carrying its tag) and its main links, and the pack is cut to a token budget.

## Examples: Proxies and CAPTCHAs

- [Weather in 3 cities](https://docs.boxline.dev/examples/weather-in-3-cities.md): Open the same weather page through residential proxies in New York, London and Tokyo, with the browser in "realistic" mode (its clock and language follow the proxy), and compare the local weather and time.
- [CAPTCHA hand-over](https://docs.boxline.dev/examples/captcha-hand-over.md): Open a form behind a CAPTCHA, see the platform detect it, have a person solve it in the live view, then carry on and submit the form. With captcha: "ask" (the default) nothing is solved automatically. Only on sites you own or may automate.

## Examples: More

- [Browser, shell and files together](https://docs.boxline.dev/examples/browser-shell-files.md): Download a file in the browser, work on it in the shell, and use the result back in the browser, all in one session: from your code, by the AI agent, and as a script.
- [Playground examples](https://docs.boxline.dev/examples/playground.md): The ready-made tasks and scripts of the console's Try an example list, with the same thing as an API call.
- [Claude Code skills](https://docs.boxline.dev/examples/skills.md): Five Claude Code skills that use the platform to read the web: /web (a site map for agents), /design (a design system, measured), /learn, /skill-tree and /harness. Open source.