silicon-browser 1.0.0

Terminal-native cloud browser CLI for AI agents.

Silicon Browser

A terminal-native browser CLI for AI agents — same command surface as the original silicon-browser, but every browser runs through Browserbase. No local Chromium, no stealth-patch maintenance: Silicon Browser gives you a fast, scriptable CLI with a stable @ref element model and shareable remote-access links.

How it works

• Each named session is a cloud browser, driven over CDP via Playwright.
• The browser lives remotely and persists between commands; Silicon Browser keeps a small local state file per session (~/.silicon-browser/sessions/<name>.json) recording the session id, active tab, and the last snapshot's @ref → element map.
• Every command opens a short-lived CDP connection, does its work, and disconnects. Disconnecting does not end the cloud browser — only close (or the session timeout) does.

Install

Install directly from GitHub (no clone needed):

uv tool install git+https://github.com/teamofsilicons/silicon-browser.git
# or:  pipx install git+https://github.com/teamofsilicons/silicon-browser.git

Or from a local clone:

git clone https://github.com/teamofsilicons/silicon-browser.git
cd silicon-browser
uv tool install .          # or: pipx install .

Then save your key — the easiest way is the login command, which prompts for the key (hidden input), verifies it, and stores it persistently in ~/.silicon-browser/config.env (owner-only 0600):

silicon-browser login          # prompts for your key, verifies & saves it
# or non-interactively:
silicon-browser login --key <browserbase-api-key>

Once saved, every command picks it up automatically — no need to re-export it. Prefer environment variables? Those still work and take precedence:

export SILICON_BROWSER_API_KEY=<browserbase-api-key>   # or put it in a project-local .env file
# or:
export BROWSERBASE_API_KEY=<browserbase-api-key>
silicon-browser install        # verifies your key + connectivity

Resolution order (first wins): SILICON_BROWSER_API_KEY env var → BROWSERBASE_API_KEY env var → project-local ./.env → saved ~/.silicon-browser/config.env.

Browserbase caps session/link lifetimes at 6 hours; Silicon Browser clamps higher requested values automatically and tells you when it does.

Usage

silicon-browser open example.com         # start a 180-minute session and navigate
silicon-browser open example.com --timeout 60
silicon-browser snapshot -i              # list interactive elements with @refs
silicon-browser click @e1                # click by ref
silicon-browser fill @e2 "hello"         # fill an input
silicon-browser type "search query"      # keystroke-level typing
silicon-browser get text @e3             # extract text / html / value
silicon-browser screenshot               # saved under ~/.silicon-browser/screenshots
silicon-browser evaluate "document.title"
silicon-browser file session upload ./data.csv
silicon-browser file input @e4 /tmp/uploads/data.csv
silicon-browser file session archive
silicon-browser tabs                     # list tabs
silicon-browser tab new example.org      # open / switch tabs
silicon-browser tab select 0
silicon-browser close                    # release the cloud browser

Commands

Command	Description
open <url> [--timeout min]	Navigate (starts a session if none active; default 180 min)
snapshot [-i] [--json]	Accessibility tree with @refs; -i = interactive only
click @ref	Click an element
fill @ref "text"	Fill an input
type "text" [--delay ms]	Type at the keyboard level
select @ref "value"	Select a dropdown option
hover @ref	Hover an element
scroll [down|up|top|bottom] [--amount px]	Scroll the page
get text|html|value @ref	Extract from an element
screenshot [path] [--full-page]	Capture a screenshot
evaluate "js"	Run JavaScript, print the result
file session list|upload|download|archive|delete|clear	Manage files in the active browser session
file global list|upload|download|delete	Not supported on Browserbase
file input @ref /tmp/uploads/name	Set a file input to one or more session files
tabs / tab new [url] / tab select <n>	Manage tabs
share [--expiry min] [--view-only] [--new]	Remote access link (see below)
status / sessions	Inspect sessions
profile list|save <name>|delete <name>	Persistent identities
proxy current|status|connect|disconnect	Inspect or change proxy routing
close	Release the cloud browser
login [--key ...]	Enter & save your provider API key (prompts if no --key)
install	Verify credentials

Files

Uploaded session files live inside the remote Browserbase VM under /tmp/uploads. Upload a local file into the current session, then bind it to a web page file input:

silicon-browser snapshot -i
silicon-browser file session upload ./invoice.pdf
silicon-browser file input @e7 /tmp/uploads/invoice.pdf

Browserbase downloads can be listed, downloaded by filename/id, or bundled into a local archive:

silicon-browser file session list
silicon-browser file session download report.csv ./report.csv
silicon-browser file session archive ./session-files.zip

Provider-global file storage is not available on Browserbase.

Global options

--session/-s <name> (parallel sessions) · --profile <name> · --incognito · --proxy <url> · --location <country[-state][-city]> · --user-agent <ua> · --solve-captcha

Remote access links

Generate a shareable link to watch — or take control of — the live cloud browser:

silicon-browser share                      # interactive link, expires in 120 min
silicon-browser share --expiry 30          # custom expiry (minutes)
silicon-browser share --view-only          # watch only, no control
silicon-browser share --new --expiry 120   # fresh session dedicated to the link

The link's lifetime is the remote session timeout, so the expiry is enforced server-side: when it elapses, Browserbase tears the browser down and the link stops working. The default is 120 minutes (clamped to Browserbase's maximum if higher).

• Interactive (default): recipients can click and type in the live browser.
• View-only (--view-only): Silicon Browser adds interactive=false; Browserbase live views are interactive by default, so enforcement depends on Browserbase URL support.

Because the provider fixes a session's timeout at creation, share on an existing session reports that session's real expiry; use --new to mint a fresh session with exactly the expiry you ask for.

Profiles

A profile maps a local name to a Browserbase Context, so cookies, storage, and login state persist across sessions:

silicon-browser --profile work open github.com   # reuse saved context
silicon-browser --profile work close             # context is saved on close
silicon-browser profile list

Proxies

On Glass-managed silicons, proxy locations are resolved from Glass: assigned browser profile location first, then team default. A session-scoped location override is vpn-style and leaves the profile/default unchanged.

silicon-browser proxy status              # configured default/profile + session use
silicon-browser proxy current             # just the current session's proxy
silicon-browser proxy connect in-mumbai   # this session only
silicon-browser proxy disconnect          # back to profile/default routing
silicon-browser proxy set-location us-ny  # assigned profile, shared by its silicons
silicon-browser proxy set-default de      # profile-less fallback

Configuration

Variable	Purpose
SILICON_BROWSER_API_KEY / BROWSERBASE_API_KEY	Browserbase API key (required)
SILICON_BROWSER_PROJECT_ID / BROWSERBASE_PROJECT_ID	Optional Browserbase project id
SILICON_BROWSER_BASE_URL / BROWSERBASE_BASE_URL	Override the Browserbase API base URL
SILICON_BROWSER_CONNECT_URL	Legacy CDP connect-host override for old sessions
SILICON_BROWSER_HOME	State directory (default ~/.silicon-browser)

silicon-browser login writes SILICON_BROWSER_API_KEY to $SILICON_BROWSER_HOME/config.env (default ~/.silicon-browser/config.env, 0600). Delete that file to "log out".

License

Apache-2.0