Python SDK

pip install boxline-sdk playwright

export BOXLINE_API_KEY="your-api-key"export BOXLINE_API_URL="https://api.boxline.dev"

import osfrom boxline import Boxlinebx = Boxline()  # reads BOXLINE_API_KEY and BOXLINE_API_URL# Or set the options yourself. timeout is in seconds, for each request.custom = Boxline(    api_key=os.environ["BOXLINE_API_KEY"],    base_url="https://api.boxline.dev",    max_retries=3,    timeout=60,)# As a context manager, the client closes its connections at the end.with Boxline() as client:    print(client.me()["project"]["plan"])

from playwright.sync_api import sync_playwrightfrom boxline import Boxlinebx = Boxline()with bx.sessions.create(timeout=300) as session:  # leaving the block stops it    with sync_playwright() as p:        # A signed URL: treat it like a password.        browser = p.chromium.connect_over_cdp(session.connect_url)        page = browser.contexts[0].pages[0]        page.goto("https://example.com")        print(page.title())    # The actions API drives the same browser without Playwright.    print(session.content("markdown")["title"])

browser_only = bx.sessions.create()                              # the defaultshell_only = bx.sessions.create(browser=False, shell=True)both = bx.sessions.create(shell=True)

with bx.sessions.create(timeout=300, proxy={"type": "residential", "country": "DE"}) as session:    session.update(timeout=900)           # its length in seconds from its last start; expires_at moves    session.update(idle_timeout=120)      # end it after 2 minutes without activity    session.update(rotate_proxy=True)     # a new proxy IP now; open browser connections reconnect (400 without a proxy)    session.update(proxy=None)            # remove the proxy    session.update(block_ads=True, cookie_banners="reject", captcha="ask")    session.update(rotate_urls=True)      # every earlier signed URL stops working    print(session.live_url)               # the new one: share it only with people who may use it

import urllib.parsefrom boxline import Boxlinefrom playwright.sync_api import sync_playwrightbx = Boxline()with bx.sessions.create(shell=True, keep_alive=True) as session:    # Browser: download a report. Downloads land in /workspace/downloads.    # (A demo page; on your own site, page.goto() your report page instead.)    with sync_playwright() as p:        browser = p.chromium.connect_over_cdp(session.connect_url)        context = browser.contexts[0]        page = context.pages[0] if context.pages else context.new_page()        csv_url = "data:text/csv," + urllib.parse.quote("month,revenue\nJan,1200\nFeb,1850\nMar,2410")        page.set_content(f'<a download="report.csv" href="{csv_url}">Download report</a>')        page.get_by_role("link", name="Download report").click()        csv = session.files.wait_for("downloads/*.csv")        print("downloaded", csv["path"], csv["size"])    # Shell: add up the revenue column with Python, on the same machine.    run = session.exec("""mkdir -p output && python3 -c "import pandas as pd; print(pd.read_csv('downloads/report.csv')['revenue'].sum())" > output/total.txt""")    if run["exitCode"] != 0:        raise RuntimeError(run["stderr"])    # Files: read the result.    total = session.files.read_text("output/total.txt").strip()  # "5460"    # Actions: type it into the form and send it.    results = session.actions([        {"action": "goto", "url": "https://httpbin.org/forms/post"},        {"action": "fill", "selector": "input[name=custname]", "value": total},        {"action": "click", "selector": "form button"},        {"action": "content", "format": "text"},    ])    print(results[-1]["value"]["content"])  # what the form received

tar = session.files.archive("output")  # a folder as one .tar.gz (bytes)with open("output.tar.gz", "wb") as f:    f.write(tar)session.stop()print(session.files.read_text("output/total.txt"))  # still readable while stoppedentries = session.files.list("output")

page = bx.fetch("https://example.com", format="markdown", links=True)png = bx.screenshot("https://example.com", full_page=True)  # bytespdf = bx.pdf("https://example.com", paper="A4")result = bx.extract(url="https://example.com/pricing", prompt="The name and monthly price of every plan")print(result["data"])started = bx.crawl.start("https://example.com/docs", max_pages=20)crawl = bx.crawl.wait(started["id"])  # every page in crawl["data"]

found = bx.search("playwright connectOverCDP", limit=5, recency="year")for r in found["results"]:    print(r["title"], r["url"], r.get("publishedAt", ""))# fetch: also open the top pages (True = 3, or 0 to 5) and get them as Markdown.with_pages = bx.search("playwright connectOverCDP", limit=3, fetch=2)print((with_pages["results"][0].get("content") or "")[:200], with_pages["results"][0].get("error"))

with bx.sessions.create() as s:    s.goto("https://example.com")    s.mouse.move(400, 300, steps=10)    s.mouse.click(400, 300, button="right", count=2, modifiers=["Shift"])    s.mouse.drag("#card", "#done-column", steps=20)         # selectors: the element's centre    s.mouse.drag(path=[(100, 100), (200, 150), (300, 100)])  # or a path    s.mouse.down()    s.mouse.up()    s.hover("#menu")    s.keyboard.key("ControlOrMeta+A")    print(s.cursor())                                        # {"x", "y"}    png = s.screenshot(max_width=640, cursor=True)    # Every result says what happened; a bare string is a plain-English step.    results = s.actions([{"action": "goto", "url": "https://example.com"}, "click More information"])    print([r.get("text") for r in results])    # One action exactly as a computer-use model gave it, and the screen after it.    screen = s.computer({"action": "left_click", "coordinate": [512, 300]}, max_width=1024)

import osrun = bx.agent.run(    "Sign in to https://example.com with %email% and %password%, then open the billing page.",    variables={        "email": "ada@example.com",        "password": {"value": os.environ["SITE_PASSWORD"], "origins": ["https://example.com"]},    },)for event in bx.agent.stream(run["id"]):    if event["type"] == "thought":        print("…", event["text"])  # what it is about to do    elif event["type"] == "tool":        print(event["name"], event.get("input"))  # placeholders, never values    elif event["type"] == "done":        print(event["status"], event.get("result"))

# A shell-only run: no browser, so the AI gets the shell and the files only.run = bx.agent.run(    "Convert every video in /workspace to MP4 with ffmpeg and list the new files",    session={"browser": False, "shell": True},)done = bx.agent.wait(run["id"])print(done["status"], done["result"])

run = bx.agent.run("Download the latest invoice from https://example.com/billing")bx.agent.pause(run["id"], "I will sign in myself")      # the AI finishes its step, then waitssession = bx.sessions.get(run["sessionId"])print(session.live_url)                                 # a signed link: share it only with that personbx.agent.resume(run["id"], note="I signed in")          # the same run goes ondone = bx.agent.wait(run["id"])if done.get("resumable"):    # It stopped at a limit. Give it more steps; the work so far is kept.    bx.agent.resume(run["id"], max_steps=60, note="The invoice page is already open")

code = """useModel("claude-haiku-5-5");                               // every later step() and extract() uses itawait page.goto("https://example.com/signup");await step("type %email% into the email field");await step("click Continue", { model: "claude-sonnet-5-5" }); // this call onlyconsole.log(JSON.stringify(await extract("the plan names and prices")));"""with bx.sessions.create(shell=True) as s, s.run_script(code, env={"email": "ada@example.com"}) as proc:    for stream, text in proc:        print(text, end="")print(proc.result["exitCode"])

def tell_someone(change):    # The live URL is a signed link: share it only with the person who may solve it.    if change["state"] == "detected":        print(f'{change["kind"]} on {change["url"]}: solve it in the live view')with bx.sessions.create(captcha="ask") as s:    stop = s.on_captcha(tell_someone)  # runs on a background thread until the session stops, or stop()    s.goto("https://example.com/signup")    s.wait_for_human(timeout=300)      # raises CaptchaTimeoutError if nobody solves it    stop()

import asynciofrom boxline import AsyncBoxlineasync def main():    async with AsyncBoxline() as bx:        pages = await asyncio.gather(*(bx.fetch(u) for u in ["https://example.com", "https://example.org"]))        async with await bx.sessions.create() as s:            print((await s.goto("https://example.com"))["title"])        async for session in bx.sessions.list(status="RUNNING"):            print(session.id)asyncio.run(main())

s = bx.sessions.create(block_ads=True, cookie_banners="reject")  # "reject" is the defaults.goto("https://example.com")s.refresh()print(s.blocked_requests)  # refused inside the machine, before any proxys.update(block_ads=False, cookie_banners="off")bx.fetch("https://example.com", block_ads=True)  # screenshot, pdf, extract, crawl.start and agent.run too

ext = bx.extensions.upload("my-extension.zip")  # a path, or the zip's bytes; at most 10 MBwith_ext = bx.sessions.create(extensions=[ext["id"]])  # loaded before the session is returnedfor e in bx.extensions.list():    print(e["id"], e["name"], e["version"], e["permissions"])bx.extensions.delete(ext["id"])

import osfrom boxline import CredentialCodeTimeoutError, CredentialLoginFailedErrorbx.credentials.create(    "SHOP",    "password",    origins=["https://shop.example.com"],    username="ops@example.com",    password=os.environ["SHOP_PASSWORD"],    code_source="push",  # your system sends each code or sign-in link)session = bx.sessions.create()try:    # login waits as long as the server may (a code from your system included).    page = session.login("SHOP", url="https://shop.example.com/signin")    print(page["url"], page["title"], page["runId"])except CredentialLoginFailedError as err:  # also CredentialLoginTimeoutError    print("could not sign in; run", err.run_id)except CredentialCodeTimeoutError:    print("no code arrived in time")# In your webhook receiver, when credential.code_needed arrives (the run is waiting):bx.credentials.push_code("SHOP", code="123456")  # what the site just emailed or texted

import osfrom boxline import WebhookSignatureError, verify_webhookendpoint = bx.webhooks.create("https://example.com/webhooks/boxline", ["session.stopped"])# endpoint["secret"] ("whsec_…") is shown only now: store it with your other secrets.# In your receiver: the raw body, the Boxline-Signature header, and the secret (or [new, old] after a rotation).try:    event = verify_webhook(body, header, os.environ["BOXLINE_WEBHOOK_SECRET"])  # 5-minute window    # drop event["id"] if you have handled it already, then answer 200except WebhookSignatureError as e:    print(e.reason)  # answer 400for d in bx.webhooks.deliveries(endpoint["id"], status="failed"):    print(d["id"], d["errorCode"])bx.webhooks.test(endpoint["id"])

settings = bx.project.settings()  # {"captchaDefault", "captchaDefaultEffective", "trajectories", "updatedVia", …}print(settings["trajectories"])   # {"enabled", "noticeSeenAt", "decidedBy"}bx.project.set_settings(captcha_default="ignore")                # for new sessions and runs without captchabx.project.set_settings(trajectories={"enabled": False})         # the Trajectories program, for this project

u = bx.usage(from_="2026-10-01", to="2026-10-07")print(f'{u["running"]} of {u["concurrencyLimit"]} sessions running')print(u["sessions"], u["agentRuns"], u["modelCostUsd"], u["ownKeyModelCostUsd"], u["costUsd"])for day in u["byDay"]:    print(day["date"], day["sessions"], day["agentRuns"], day["costUsd"])

page = bx.sessions.list(status=["RUNNING", "STOPPED"], limit=50)print(len(page.data), page.total, page.next)for s in bx.sessions.list(status="RUNNING", kind="shell"):  # shell-only sessions    print(s.id)for e in bx.sessions.events("SESSION_ID", types=["console", "error"]):    print(e.get("text"))for p in page.iter_pages():    print(len(p.data))

from boxline import Boxline, BoxlineError, FeatureNotInPlanError, RateLimitErrorbx = Boxline()try:    with bx.sessions.create(shell=True) as session:  # stopped even when the code inside fails        print(session.exec("python3 --version")["stdout"])except RateLimitError as err:    print("busy, try again in", err.retry_after, "s")except FeatureNotInPlanError as err:    print("not on this plan:", err.message)except BoxlineError as err:    print(err.code, err.message, "request", err.request_id)    raise

session = bx.sessions.create(timeout=600, options={"idempotency_key": "nightly-report-2026-09-30"})

bx.sessions.get("SESSION_ID", options={"timeout": 5, "max_retries": 0, "client_request_id": "trace-42"})patient = bx.with_options(max_retries=6)  # a copy of the client with other defaults