# Glass
Glass is a Rust browser control tool. It controls Chrome or Chromium through
the Chrome DevTools Protocol (CDP). It does not include a browser runtime.
Glass runs declared browser actions. It does not create an action plan or
change a target without an explicit request.
## Support status
| Linux x86-64 | Declared target; not verified on this machine |
| Linux arm64 | Locally verified target; use system Chromium or `--chrome-path` |
| macOS x86-64 | Declared target; not verified on this machine |
| macOS arm64 | Declared target; not verified on this machine |
| Windows | Unsupported |
| 0.2.1 | Current release |
| Chrome and Chromium | Supported browser families |
| Firefox, WebKit, and Safari | Unsupported browser families |
The command-line interface (CLI), terminal user interface (TUI), Model
Context Protocol (MCP) server, and Rust library use the same session runtime.
The support table distinguishes declared targets from the Linux ARM64 machine
that has been verified locally. See the [cross-platform feature parity
matrix](docs/feature-parity.md) for implementation inventory and the [release
evidence guide](docs/release-evidence.md) for the crates-only publication
boundary.
## Install the local checkout
Prerequisite: install stable Rust and a supported Chrome or Chromium browser.
Run:
```console
cargo install --path . --locked
glass --help
```
The command builds and installs the local `glass` executable.
The latest published package can be installed with:
```console
cargo install glass-browser --locked
```
Use `glass install-chromium` when no supported system browser is available.
Read [Installation and operations](docs/installation.md) for browser
discovery, profiles, attach mode, logging, policy, and deployment.
See [Experimental capabilities](docs/experimental-capabilities.md) before
enabling opt-in features.
## Run Glass
Start the TUI for a visible session:
```console
glass tui
```
Enter these commands in the TUI:
```text
navigate https://example.com
observe
```
Run one operation from the CLI:
```console
glass navigate https://example.com
glass --incognito --headed navigate https://example.com
```
Use `--profile NAME` for persistent cookies and storage. Use `--incognito`
for a disposable browser profile.
## Interfaces
| CLI | Scripts and one operation | `glass <command>` |
| TUI | An interactive session | `glass tui` |
| MCP | A long-lived stdio connection | `glass --mcp` |
| Rust library | An embedded session runtime | crate `glass-browser`, import `glass` |
Example MCP configuration:
```json
{
"mcpServers": {
"glass": {
"command": "/absolute/path/to/glass",
"args": ["--mcp"]
}
}
}
```
Use an absolute path when the MCP client does not inherit your shell path.
Keep stdout reserved for MCP frames. Read the [MCP guide](docs/mcp.md) for
frame limits, tools, lifecycle, and security.
## Main capabilities
Glass provides these browser operations:
- navigate, click, double-click, hover, drag, type, clear, check, uncheck, and
select;
- scroll, wait, inspect text, inspect the DOM, evaluate JavaScript, and capture
screenshots or PDFs;
- upload files, handle JavaScript dialogs, and dismiss recognized consent
controls;
- select page targets and frames;
- inspect and export cookies and web storage;
- run bounded batches and workflows; and
- use revision guards and bounded verification evidence.
Semantic observations provide bounded page and region data. Start with:
```console
glass observe --level summary
glass observe --level interactive
```
Read the [semantic observation guide](docs/semantic-observation.md) before
using observation references for actions.
Intent resolution compares semantic candidates before an action. Use:
```console
glass resolve-intent request.json
glass execute-intent execution.json
```
Read the [intent resolution guide](docs/intent-resolution.md) for evidence,
ambiguity, and revision rules.
Glass also includes workflow authoring and reliability checks. Read [Workflow
authoring](docs/workflow-authoring.md) and [Reliability laboratory](docs/reliability.md).
## Targets and revisions
An observation returns bounded accessibility data and revisioned target
references such as `r7:b42`. You can also use explicit locators:
```console
glass click 'name=Save'
glass click 'role=button;name=Save'
glass click 'css=button.primary'
```
Guard an action with the revision from the observation:
```console
glass click r7:b42 --expected-revision 7
glass type 'hello' --target r7:b43 --expected-revision 7
```
Glass rejects a stale revision before it sends the browser action. Read the
[action guide](docs/actions.md) for result fields and recovery.
## Rust library and clients
After publication, add the crate as `glass`:
```toml
[dependencies]
glass = { package = "glass-browser", version = "0.2" }
```
The library provides `BrowserSession`, session options, policies, observations,
revision-safe actions, target and frame management, storage, downloads,
screenshots, PDFs, semantic observations, and the MCP server.
The optional [TypeScript client](clients/typescript) and [Python
client](clients/python) start a local Glass binary. They do not include a
browser runtime.
## Safety and scope
Glass requires a local Chrome or Chromium process and a local CDP connection.
It does not provide a hosted browser service or Windows support.
Use a dedicated browser profile. Keep the CDP endpoint local. Treat profiles,
screenshots, DOM output, cookies, and logs as sensitive. Read the
[security policy](SECURITY.md) before using authenticated sessions or attach
mode.
## Documentation
Start with the [documentation index](docs/INDEX.md). It links to installation,
CLI, actions, workflows, MCP, daemon mode, policy, security, architecture,
and release guides.
## Development
Run the checks before you submit a change:
```console
cargo fmt --all -- --check
cargo test --all-targets --locked
cargo clippy --all-targets --all-features --locked -- -D warnings
```
Run the browser smoke test only when a supported browser is available:
```console
GLASS_E2E=1 cargo test --test browser_smoke -- --nocapture
```
## License
Glass is licensed under the [MIT License](LICENSE).