Every session with a browser has a live view: a web page that shows the browser as it works. Open it to watch your code or your agent. Click and type in it to take control, for example to sign in or to solve a CAPTCHA.

Open the live view

The session’s liveUrl is the link. Open it in a browser tab, or send it to the person who should act.

curl -X POST https://api.boxline.dev/v1/sessions \  -H "x-api-key: $BOXLINE_API_KEY" \  -H "content-type: application/json" \  -d '{}'# {"id": "…", "liveUrl": "https://…/live/…?token=…", …}

const session = await bx.sessions.create();console.log("Watch it:", session.liveUrl);

session = bx.sessions.create()print("Watch it:", session.live_url)

A session needs a browser for this. One created with browser: false has liveUrl: null, and the live view page and its socket answer 409 browser_disabled. See Three kinds of session.

Get the links

Get a session returns a fresh liveUrl (and connectUrl and terminalUrl) every time. Each link is signed when you read the session, so ask again whenever you need one. The links are null unless the session is running.

curl https://api.boxline.dev/v1/sessions/$SESSION_ID \  -H "x-api-key: $BOXLINE_API_KEY"# {"id": "…", "liveUrl": "https://…/live/…?token=…", "terminalUrl": null, "connectUrl": "wss://…", …}

const session = await bx.sessions.get(sessionId);console.log("Watch it:", session.liveUrl);await session.refresh(); // later: read it again, with fresh links

session = bx.sessions.get(session_id)print("Watch it:", session.live_url)session.refresh()  # later: read it again, with fresh links

boxline sessions live $SESSION_ID   # a signed link: keep it private

What you can do in it

See every tab in a tab bar. Switch tabs, close them, or open a new one.
New tabs and pop-ups are followed. Chrome’s own pages are never picked by themselves.
Click, scroll and type. Your keyboard goes to the session’s browser.
Cmd or Ctrl+V pastes the text on your own clipboard. Cmd or Ctrl+A, C, X, Z and Y work as select all, copy, cut, undo and redo. Other Cmd shortcuts stay with your own browser.

The link carries a signed token and works without your API key. Anyone who has it can control the browser, including any site the session is signed in to. So:

Send it only to the person who should act, over a private channel.
Do not put it in logs, tickets or chat rooms that other people can read.
It stops working 5 minutes after the session’s expiresAt, and when the session stops. A resume gives the session fresh links, and the old ones never work again. For a shorter life, give the session a shorter timeout.
If a link leaks, rotate it at once (below).

Rotate the links

Send rotateUrls: true in Update a session. Every earlier connectUrl, liveUrl and terminalUrl of the session stops working, and the connections made with them are closed (within 15 seconds). The answer carries the fresh links. Your own code must reconnect with the new connectUrl.

curl -X PATCH https://api.boxline.dev/v1/sessions/$SESSION_ID \  -H "x-api-key: $BOXLINE_API_KEY" \  -H "content-type: application/json" \  -d '{"rotateUrls": true}'

await session.update({ rotateUrls: true });console.log(session.liveUrl); // the new link; the old one no longer works

session.update(rotate_urls=True)print(session.live_url)  # the new link; the old one no longer works

Take control of the browser

A person takes control by opening the liveUrl and clicking and typing. When the AI agent is working in the session, pause its run first, so you do not both use the page, and resume it when you are done:

Call	What happens
Pause a run: `POST /v1/agent/runs/:id/pause`	The agent finishes its current action, then waits. The run’s status is `paused`.
Resume a run: `POST /v1/agent/runs/:id/resume`	The agent is told a person had the browser (plus your `note`), looks at the page again and goes on.

The agent can also ask for you, for example to sign in. A paused run fails after 30 minutes without a resume. See Pause and resume a run.

Solve a CAPTCHA

When a CAPTCHA waits for a person, the session’s attention is set and agent runs and plain-English steps wait. Open the live view, solve it, and they carry on by themselves. See CAPTCHAs.

Embed it

Only Boxline’s own apps, such as the console, can show the live view inside a page. Embedding it in an <iframe> on your own site needs embed origins for your project, which are not available yet. Open it in a new tab or window instead.

These docs describe a beta API. Endpoints, fields and SDK methods may change before general availability; breaking changes will be listed in the changelog.