Ghostlight

Ghostlight lets an AI agent use the Chromium profile where you are already signed in, inside a dedicated tab group that stays separate from your ordinary tabs. Actions happen in front of you. It works wide open for personal use or under inspectable policy when stronger boundaries are useful. Everything runs locally, and nothing phones home.

No account and no subscription trap. The local browser automation core is Apache-2.0 OR MIT and runs without a Ghostlight login, activation server, telemetry, or subscription. Organizational governance is a separately licensed source-available layer. Personal use, evaluation, development, small teams, and unrestricted all-open operation remain free under the exact terms linked in License.

Responsibility is part of the experience, not a brake on it. A good agent tool should be easy to start, obvious while it acts, clear when it stops, and honest about what it can and cannot control.

Is this your problem?

Ghostlight is worth trying when:

• your agent needs a site where you are already signed in, not a fresh browser profile;

• you want the same browser tools from Codex, Claude, Cursor, VS Code, Windsurf, Zed, OpenCode, Crush, or another MCP client;

• you want to watch the work, take the wheel, and understand failures without decoding logs; or

• you need policy and evidence that a developer and a security reviewer can both inspect.

It is probably not the right tool for a headless scraping farm, stealth automation, an isolated cloud browser, or a Claude-only setup already served by Anthropic's first-party integration. The interactive browser-control decision aid helps you choose by operating model. The comparison guide provides the detailed capability evidence behind those choices.

Related MCP server: Scout

What makes it feel different

• Your session, not a clean-room. Real cookies and real SSO, used only in Ghostlight-managed tabs. Nothing gets relocated to a cloud browser or a throwaway profile just to gain a technical property; the whole point is your authenticated context without opening your ordinary tabs.

• The agent gets a tool surface shaped for models. The trained schemas stay byte-stable; additive tools provide forms, files, multi-step composition, recording, and inspection. Results are compact, errors say how to recover, and a capable agent can begin without a Ghostlight lesson.

• The person watching can follow along. Every move is visible: sky-blue click ripples, a comet trail on drags, a shimmer as it types, captions that narrate each step. It runs in its own tab group, kept visually separate from your own tabs, and you can grab the wheel or hit the kill switch at any moment.

• Responsibility scales with the job. Personal use needs no policy. When boundaries matter, Ghostlight adds capability grants, sacred never-touch domains, dry-run preflight, and one structured record per call. The unrestricted engine remains a first-class product.

• The software stays yours. The Rust service and its thin relay have no runtime framework to maintain. The engine is open source, the governance code is readable, license state never changes behavior, and an installed copy keeps working offline.

Try it

Needs a Chromium browser (116+), an MCP client, and Node for the npx install path. The running service is native Rust; there is no Node service to keep alive and nothing to compile.

[1 Install service] -> [2 Add extension] -> [3 Restart MCP client] -> [4 Ask a first task]
      automatic           visible step             once                useful proof

1. Install the local service and register detected MCP clients:

   npx -y ghostlight install

   The installer is idempotent and opens the extension walkthrough on the first run. It recognizes Claude Code, Claude Desktop, Cursor, VS Code, Codex, Windsurf, Zed, OpenCode, and Crush. Use --client <id> to target one client, or --dry-run to inspect every planned change first.

2. Add the extension. Until the Chrome Web Store listing is public, download ghostlight-extension-v*.zip from the latest release and load it unpacked at chrome://extensions. The walkthrough opened by the installer shows the same current path.

3. Restart your MCP clients. The browser tools appear. Try:

   In my current browser, summarize the active page and tell me which tab you used. Do not click or change anything.

If anything looks off, npx ghostlight doctor tells you exactly what. Prebuilt archives, building from source, and every other path live in the installation guide and the manual steps below.

For an unsupported client, add { "command": "npx", "args": ["-y", "ghostlight"] } as a stdio MCP server, then run the installer for the browser side. If VS Code reports a manual client step, use its native installer:

Current platform state. Windows and Linux are verified end to end against live browsers. macOS builds and passes the full test suite in CI; its live-browser verification is still owed.

Extension state. The Chrome Web Store listing remains under compliance review; until it is public, the install guide provides the current release-extension path.

Other ways to get it. Homebrew: brew install sylin-org/tap/ghostlight. On the MCP registry as org.sylin/ghostlight. Every release also ships prebuilt binaries and checksums on the Releases page.

1. Get the binary. Download a prebuilt archive from the Releases page (each carries a SHA-256 checksum and a signed build-provenance attestation: gh attestation verify <archive> --repo sylin-org/ghostlight), or build from source with a stable Rust toolchain: cargo build --release. The build produces two executables: ghostlight (the CLI) and ghostlight-relay, the thin pass-through that your MCP client and Chrome launch.

2. Load the extension. chrome://extensions -> Developer mode -> Load unpacked -> the extension/ directory. The committed manifest key pins the extension ID, and the installer already allows it, so there is nothing to copy.

3. Register. ./target/release/ghostlight install. Useful flags: --dry-run (print the plan, write nothing), --browser <id> / --client <id> (limit scope; repeatable), --all-browsers / --all-clients, --no-open, --debug (observability on), and --system (machine-wide). The installer is an idempotent value-level merge; it never clobbers your config and never duplicates entries.

4. Restart the client, reload the extension, run ghostlight doctor. A healthy result reports registration, a live endpoint, and a connected extension; anything off gets a specific, actionable finding.

What the agent can do

A typical first request:

Open a new browser tab, go to example.com, and tell me what the page says.

The tool surface preserves the schemas Claude was trained on, byte for byte, then adds more on top, for 25 tools in five groups. (Everything behind those schemas is an original, clean-room Rust implementation.)

• See and act. Navigate, click, type, scroll, hover, drag; screenshots with exact coordinate mapping and an on-page cursor; semantic one-call actions with bounded outcome receipts.

• Forms and files. Fill forms by element ref or semantically by label (shadow DOM included); upload file bytes or captured screenshots straight into page inputs and drop targets.

• Compose. Multi-step scripts with inter-step data flow and dry_run pre-flight; one-call action batches; wait-for-condition with page settlement; timed narration at meaningful workflow phases for the person watching.

• Record. Animated-GIF session recording with click cues, action labels, a truthful REC badge, and real per-frame timing.

• Inspect. Accessibility tree (with diff mode), page text, actionable element search, console and network activity, JavaScript dialogs, and explicit owned-tab lifecycle controls.

Ask the agent to call explain at any time for the authoritative, in-session directory of every action and the capability it requires.

For computer, the read-only actions (screenshot, scroll, zoom, scroll_to, hover) require read, the input actions (left_click, right_click, type, key, left_click_drag, double_click, triple_click) require action, and wait requires none.

Governed, honestly

Governance is off by default and switches on when a policy manifest is present. A manifest grants capabilities (read, action, write, execute) to an identity on the hosts you name, with deny carve-outs, and every call resolves against it at a single chokepoint:

{
  "schema": 3,
  "name": "acme-dev",
  "version": "2026.07.0",
  "identity": { "resolved_by": "local_file", "principal": "dev@acme" },
  "grants": [
    { "id": "acme-apps",
      "hosts": { "allow": ["*.acme.com"], "deny": ["payroll.acme.com"] },
      "allowed": ["read", "action", "write"] }
  ],
  "config": [
    { "key": "content.security.sacred_domains", "value": ["*.mybank.com"], "level": "mandatory" }
  ]
}

(That exact file renders as plain English with ghostlight policy explain. Try it.)

• Capabilities, not tool lists. Every action carries an intrinsic classification. The vocabulary is published as an open, vendor-neutral spec: the RAWX capability model (rwx for agents).

• Observe before you enforce. observe mode dispatches everything and records what enforce would have denied; enforce blocks. Sacred never-touch domains always enforce.

• Evidence built in. Every call, whether permitted, denied, or shadow-denied, emits one structured JSON-Lines audit record: identity, host, capability, grant, decision, duration. The recorder is on by default even in all-open mode, so a session always leaves a trail. Stream it to a file, stderr, or syslog for your SIEM (guide).

• Live and layered. Manifests hot-reload without a restart (failing closed on a bad edit); configuration resolves through defaults, org policy, and user layers, with org locks.

A governed client only sees the tools its grants permit, plus explain. Start from a ready manifest in examples/, preview any file with ghostlight policy explain <file>, and see the governance configuration guide for the mechanics, with the solo-developer and compliance-team walkthroughs for the full journey.

Reviewing Ghostlight for procurement or a security assessment? The Trust Center is public and ungated: it answers the questions reviewers ask first, each with linked evidence, and ships a CAIQ-shaped questionnaire plus MSA and DPA templates you can read and file before you ever reach out.

How it works

MCP Client <--stdio--> Relay <--local IPC--> Service <--native messaging--> Relay
                                                                        |
                                                                     Extension <--CDP--> Browser

The persistent Rust service owns browser sessions, governance, and audit. The two roles that MCP clients and Chromium spawn are handled by one small ghostlight-relay executable. The extension is deliberately thin: it contains Chrome-API mechanism, not policy. All decisions and records stay in the local service. The separation lets clients, the extension worker, and the service restart without making the user rebuild their browser session.

• No subcommand: prints a short hint and exits. The MCP server role now lives in ghostlight-relay (your client launches ghostlight-relay --role agent; you never run it by hand).

• install / uninstall: register or remove everything (both support --dry-run).

• doctor [--verbose]: read-only diagnosis of the whole chain with a truthful exit code.

• status [--json]: a running server's live inner state (requires --debug / GHOSTLIGHT_DEBUG=1).

• config <list|get|set|schema|docs|preset>: the layered configuration, with sources and locks.

• policy <explain|simulate|init>: render a manifest as plain sentences, replay an audit log against a candidate policy, or write a starter manifest.

• demo-brief: run the short public launch-brief story used for the README hero recording.

• demo: run the longer Card Foundry QA and governance story.

If something is off, start with doctor. It pinpoints unregistered browsers or clients, a missing server, a stale endpoint, or an extension that never connected. Extension shows disconnected? Reload it at chrome://extensions. Developing on Windows? Use the isolated engine swap in docs/DEV-LOOP.md; live clients and the browser reconnect around it.

Documentation

Questions, requests, and contributing

GitHub Issues for bugs, GitHub Discussions for questions and ideas, and hello@sylin.org for anything that cannot be public. Every request gets a disposition with reasoning: accepted, deferred, or declined against the project's recorded vision. See CONTRIBUTING.md.

License

The Continuity Promise comes first: license state never affects behavior, and the binary never phones home. Ghostlight runs the same whether or not anyone ever pays.

Ghostlight is open-core. The engine (everything outside crates/core/src/governance/) is open source under Apache-2.0 OR MIT, at your option. The governance module (crates/core/src/governance/) is source-available under the Ghostlight Commercial License, and it is free for almost everyone: individuals and solo developers, teams of up to five, evaluation and development at any size, all-open operation at any size, and noncommercial nonprofit or open-source use. Exactly one situation needs a paid subscription: an organization of more than five people running the governance features operationally.

See LICENSING.md for the plain-language guide, and, when you want them, PRICING.md for editions, prices, and the founding program (12 months free for the first ten organizations).