Metadata-Version: 2.4
Name: silicon-browser
Version: 1.0.7
Summary: Terminal-native cloud browser CLI for AI agents.
Keywords: browser,automation,cli,ai-agents,playwright
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Requires-Dist: httpx>=0.28.1
Requires-Dist: playwright>=1.61.0
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: rich>=15.0.0
Requires-Dist: typer>=0.26.8
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/teamofsilicons/silicon-browser
Project-URL: Repository, https://github.com/teamofsilicons/silicon-browser
Description-Content-Type: text/markdown

# Silicon Browser

A terminal-native browser CLI for AI agents — same command surface as the
original [silicon-browser](https://github.com/unlikefraction/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):

```bash
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:

```bash
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`):

```bash
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:

```bash
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

```bash
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:

```bash
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:

```bash
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:

```bash
silicon-browser share                      # current session 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 blank 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`): the Silicon Browser interface renders the
  Browserbase live view without pointer events.

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.

If there is no active local session, `share` fails instead of silently creating
an `about:blank` link. Open a page first, or pass `--new` when you explicitly
want a fresh blank shared browser.

## Glass session archives

On a Glass-managed Silicon, each Browserbase session is registered with Glass
when it starts. Closing, replacing, timing out, or completing the session queues
an asynchronous archive: Glass copies every recorded tab and HLS segment, the
provider session metadata, browser logs, and downloaded files into private S3
storage. Team operators can watch live sessions and replay completed sessions
from the team's Browser page in Glass. Standalone installations continue to use
Browserbase directly and do not attempt a Glass archive.

## Profiles

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

```bash
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.

```bash
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
```

If a configured proxy tunnel fails during browser startup or navigation,
Silicon Browser warns and retries the open once in a replacement session without
a proxy. That fallback session uses its direct IP.

## 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_INTERFACE_URL` | Override the branded share-link host (default `https://browser.teamofsilicons.com`) |
| `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
