Session creation
Attaching a browser opens a session. Creation is two-phase and orphan-safe: Vetta writes acreating row before asking the browser automation interface for an upstream session, then promotes it to active on success or marks it error on failure. If the process dies mid-create, the creating row makes the orphan recoverable rather than leaking a live session.
1
creating
A row is written first, before any upstream session exists.
2
active
The upstream session is up; the row is promoted and the agent can drive it.
3
error
Creation failed; the row records it so nothing is orphaned.
Attach a browser
Enable a browser when you create the computer.allowed_domains is required — it scopes every page the browser navigates to.
Actions
Domain re-validation on every action
Every action re-validates the current page URL againstallowed_domains at call time — not just at goto. A redirect or a link that lands off the allow-list is blocked. Regardless of the allow-list, the browser always blocks private, loopback, and metadata hosts (link-local, internal ranges, and cloud metadata endpoints), including hostnames that resolve into them.
Credentials & saved logins
Credentials are never entered throughtype. A guard blocks credential-shaped input, so the agent cannot type a password or token into a field via a normal action.
Instead, saved logins are entered through a dedicated login flow that injects values from the vault as opaque variables — the agent drives the flow but never sees the raw secret.
Coming soon. Vault-backed injection into the browser’s login flow is not wired yet: the login flow and the credential guard exist, and the vault API is live, but the substitution path between them — the egress boundary that resolves an opaque placeholder into the real value — does not exist yet.
Saved logins are default-deny
A saved login (“context”) is default-deny. An agent cannot reuse one just by naming it — it needs an explicit grant, by agent id or by role. Without a grant,context_name is refused.
Human-first login
Sethuman_login to run a human-first flow: a person completes the login once, then save_login persists the context for later reuse. During the flow a 15-minute lock is held on the context until save_login completes, so two flows can’t race the same login.
Session lifetime & what’s withheld
- Each session runs under
timeout_minutes— default 15 minutes, maximum 360 (6 hours). See Limits & billing. - Sessions carry no charge of their own, residential proxy egress included.
- Withheld from the agent: the raw connect URL and the live-view URL. The agent works only through actions and their results.
Configuration reference
string[]
required
The domains the browser may reach. Required.
"*" means unrestricted but is logged. Using a proxy requires a scoped list — "*" is not allowed with a proxy.integer
default:"15"
Per-session timeout. Range 1–360 minutes (up to 6 hours).
string
default:"us-west"
Geographic region the browser runs in:
us-west, us-east, eu-central, or ap-southeast. Pick the one closest to the target site.boolean
default:"false"
Keep the session alive across brief disconnects instead of closing it. Useful for long, resumable flows.
boolean
default:"false"
Persist cookies and local storage into the named
context_name when the session ends, so a later session can resume the same logged-in state.object
{ width, height } in pixels for the browser viewport.string
Emulated platform fingerprint:
windows, mac, linux, mobile, or tablet.boolean
default:"false"
Block ad and tracker requests.
boolean
default:"true"
Attempt automated CAPTCHA solving on supported challenges.
boolean
default:"false"
Enable advanced anti-bot evasion (stealth / verified fingerprint).
boolean
default:"false"
When
false, a heuristic blocks write-looking actions (submits, purchases, mutations). Set true to permit them.boolean
default:"false"
Gates
extract and screenshot on saved-login sessions. Off by default so a reused login can’t silently exfiltrate page content.string
Reopen a saved login (“context”) by name. Subject to the default-deny grant model below.
boolean
default:"false"
Start a human-first login flow. Takes a 15-minute lock on the context until
save_login completes.boolean | object
default:"false"
Route egress through a residential path. Requires a scoped
allowed_domains list (not "*").Next: snapshots & volumes
Checkpoint a running VM, fork from it, and keep state on a persistent volume.