Browser
This page shows you how to start the browser template, drive it from
Playwright, watch it live, and set its profile, proxy, timezone, and platform.
The browser template gives an agent its own Chromium to drive. It is a real
browser running headful on its own display, not a headless build, and you
connect to it over the Chrome DevTools Protocol (CDP) from Playwright,
Puppeteer, or anything else that speaks CDP. Port 9222 is CDP, and port 6080
is a live view of the screen in noVNC.
The browser is fingerprint-chromium, an open-source build of ungoogled-chromium (BSD-3-Clause), pinned to version 150. Each profile gets a fingerprint of its own: canvas, audio and fonts come from a seed that the profile keeps for its whole life. The core count and memory a page reads are the sandbox's real ones, so they agree with how fast the page sees it run.
Start a browser
Create a sandbox from browser and connect to port 9222. Chromium starts on
the first CDP request, so the first connection takes about 5 to 10 seconds
longer than the ones after it. Connections after the first one take under a
second. The example opens a page, prints its title, and kills the sandbox.
import { Sandbox } from '@impello/sdk'
import { chromium } from 'playwright'
const sandbox = await Sandbox.create('browser', { timeoutMs: 1_800_000 })
const browser = await chromium.connectOverCDP(
`https://${sandbox.getHost(9222)}`
)
const context = browser.contexts()[0]
const page = context.pages()[0] ?? (await context.newPage())
await page.goto('https://example.com')
console.log(await page.title())
await sandbox.kill()Use the browser's existing context, browser.contexts()[0]. It is the
profile on disk, with its fingerprint, cookies and logins. A context you make
with newContext() is a fresh incognito-style context that keeps nothing.
Connect, never launch. chromium.launch() starts a second, local browser with
automation switches turned on, and a page can see them; connectOverCDP
attaches to the one already running in the sandbox.
The URL is the HTTPS address of port 9222. Its /json/version answers with a
wss:// WebSocket address on the same host, which is what Playwright reads.
A client that wants the WebSocket address directly can use
wss://<host>/ with no path; it reaches the browser target.
Connect to a private sandbox
With network: { allowPublicTraffic: false } the CDP and live-view ports stop
answering callers without the sandbox's traffic access token. Send the token
in the impello-traffic-access-token header. Playwright sends the headers you give
connectOverCDP on both the HTTP request and the WebSocket. Without the
header, the port answers 403. The older e2b-traffic-access-token name is
still accepted, so code that sends it keeps working.
import { Sandbox } from '@impello/sdk'
import { chromium } from 'playwright'
const sandbox = await Sandbox.create('browser', {
network: { allowPublicTraffic: false },
})
const token = sandbox.trafficAccessToken
if (!token) throw new Error('no traffic access token')
const browser = await chromium.connectOverCDP(
`https://${sandbox.getHost(9222)}`,
{ headers: { 'impello-traffic-access-token': token } }
)Watch it live
The screen is served by noVNC at /vnc.html on port 6080. Open it in a
browser tab to watch the agent, or click into it to take over: the keyboard
and mouse are shared with the agent. This line prints the URL.
console.log(`https://${sandbox.getHost(6080)}/vnc.html?autoconnect=true&resize=scale`)
The live view takes the token as a header too, so a browser tab cannot open the live view of a private sandbox on its own. Put a proxy you control in front of it that adds the header, or keep the sandbox public only while you watch.
The browser command
Inside the sandbox, browser starts, stops and configures Chromium. Run it
with commands.run before you connect, and your settings apply from the first
page. The settings are saved, so if Chromium exits, the next CDP request starts
it again the same way. Each browser start or browser restart replaces the
saved settings: a flag you leave out goes back to its default.
The command takes these forms.
browser start [--profile NAME] [--proxy URL] [--seed N] [--timezone TZ]
[--lang LANG] [--platform linux|windows|macos] [-- CHROME FLAGS]
browser restart [the same flags]
browser stop
browser status
Every flag has an environment variable: BROWSER_PROFILE, BROWSER_PROXY,
BROWSER_SEED, BROWSER_TIMEZONE, BROWSER_LANG, BROWSER_PLATFORM and
BROWSER_ARGS. Chromium's log is ~/.browser/chrome.log.
Profiles
A profile is a directory under ~/.browser/profiles/, default unless you
name another. It holds the cookies, local storage, history and logins, and the
fingerprint seed. The seed is drawn at random the first time a profile starts
and read back every time after, so one profile is one identity, and two
sandboxes never share one by accident. To switch profiles, restart the browser
with --profile.
await sandbox.commands.run('browser restart --profile shop-account')The disk survives pause and resume, so a
paused sandbox comes back with every profile, signed in where you left it. To
carry an identity to another sandbox, copy the profile directory with the
filesystem API, or pass --seed to give a new
profile a seed you chose (an integer from 0 to 2147483647).
Proxy
--proxy sends every request through an HTTP or SOCKS proxy, for example
--proxy socks5://203.0.113.7:1080. The proxy URL cannot carry a username and
password; use a proxy that allows your sandbox's address instead. The
example sets the proxy through its environment variable.
await sandbox.commands.run('browser restart', {
envs: { BROWSER_PROXY: 'http://203.0.113.7:3128' },
})Timezone and language
On every start the browser looks up the timezone of the IP it will browse from
— through the proxy when there is one — and uses it, so the clock a page reads
agrees with where the request comes from. The lookup asks ipwho.is and gives
up after 4 seconds; then the timezone is UTC, and ~/.browser/chrome.log gets
a timezone lookup failed line with the reason. Each start also logs the
timezone it chose and where it came from. Set it yourself with
--timezone Europe/Paris. The timezone is read when the browser starts, so a
sandbox that resumes behind a different IP keeps the old one until
browser restart.
The language is en-US unless you pass --lang, for example --lang de-DE;
Accept-Language follows it.
Platform
The fingerprint describes a Linux computer by default, which is what the
sandbox is. --platform windows or --platform macos changes the user agent,
the platform and the reported graphics card to match; the fonts and the
network stack underneath are still Linux.
Size and price
The template is 2 vCPU and 4 GB, billed like every other sandbox; see Limits and pricing. The browser renders on the CPU, with no GPU, so pages heavy on WebGL or video are slower than on a desktop.
What it is not
The browser does not solve CAPTCHAs and is not a way around a site's terms. A fingerprint per profile, a matching timezone and a headful display remove the differences that make an automated browser look unlike a person's; they do not change what the agent does on the page. Sites that check behaviour, IP reputation or account history judge those as they would for anyone.
Next steps
- Network and public URLs: make a sandbox private and read its traffic access token.
- Pause, resume and snapshots: keep a signed-in profile between sessions.
- Templates: the other default templates.