See what your agent sees.
Work in real browser tabs. Inspect the same page, requests and console errors while your agent works.
Explore the developer workflowASTRAL / THE AGENTIC BROWSER
Build, debug and test alongside your AI agent. Connect your coding tools to Astral, watch every action, and keep the tests worth running again.
Free · Pre-alpha · macOS, Windows & Linux
Developer tools are verified on macOS and Linux; Windows is not verified yet.
YOUR LOCAL APP
↖ Agent checks this step
AGENT ACTIVITY
“Check the checkout flow and save a test.”
checkout.test.tsLESS HANDOFF. MORE BUILDING.
A browser built for the loop between you, your app and your coding agent.
Work in real browser tabs. Inspect the same page, requests and console errors while your agent works.
Explore the developer workflowSave reproducible tests in your repo, with screenshots and step reports. Replay them without a model call for each run.
Explore saved testsTests reference a credential by name. Astral types it on the project’s origins without passing the secret to your agent.
See what makes Astral differentYOUR DEVELOPMENT LOOP
Start with the workflow you need. Open the details when you’re ready.
Astral is an MCP server for testing the pages you build. Your coding agent drives the tab in front of you, and you see exactly what it does.
Connect Claude Code, Cursor, VS Code or any MCP client in one click. Agents read compact page snapshots and click, type and navigate in the real tabs you see, as trusted native input.
astral.test, step and expect produce a report per step: screenshots with the click drawn on them, network and console evidence, page performance and an optional video of the run.
Tests live in .astral/tests in your repo, linked to the ticket they verify. The agent opens one in Astral; you press ▶ Play and watch it in slow motion, pause or go step by step.
Scripts refer to a credential by name. Astral types the secret itself, only on the project's own origins, and masks it in every result, report and log. The agent never sees it.
Network, console, an Error Inbox that groups failures and links them to the click that caused them, and page performance with web vitals. It persists across reloads, and agents read the same data.
Choose which panels an agent may see, switch tool groups on and off, and follow every call in a live activity feed and an audit log.
Turn on Developer mode, then use the one-click setup in Settings → Developer, or paste the command it shows into your terminal.
claude mcp add --scope user astral -- "/Applications/Astral.app/Contents/MacOS/astral-mcp" The path is where macOS installs Astral; Settings shows the exact command for your install. Developer mode is verified on macOS and Linux, and implemented but not yet verified on Windows. Cursor, VS Code, Claude Desktop and Windsurf get the same one-click setup.
// .astral/tests/checkout.astral.js — linked to a ticket, replayable with ▶ Play
return await astral.test('Sign in and pay', async () => {
await astral.step('Sign in', async () => {
await astral.navigate({url: astral.url('/login')});
await astral.fill({locator: {role: 'textbox', name: 'Email'}, credential: 'shop.demo', field: 'username'});
await astral.fill({locator: {role: 'textbox', name: 'Password'}, credential: 'shop.demo', field: 'password'});
await astral.click({locator: {role: 'button', name: 'Sign in'}});
await astral.expect.url('/account');
});
await astral.step('Pay', async () => {
await astral.click({locator: {role: 'button', name: 'Pay'}});
await astral.expect.request({urlContains: '/api/checkout', method: 'POST', status: '2xx'});
await astral.expect.noErrors();
});
}, {record: 'video'}); credential: 'shop.demo' is a name from
.astral/config.json; the password itself comes from the OS keychain and
shows as ••••••.
One command registers Astral's MCP server with the client you already use, and your agent gets a short guide on how to test with it.
astral-mcp setup --client <x> astral-mcp setup --client claude-code --project .Writes .mcp.json in the project. Without --project it prints the official claude mcp add --scope user command instead of editing Claude Code's own state file.
astral-mcp setup --list shows every client and whether it is installed;
--client all-detected sets up all of them.
Visual Studio Marketplace and Open VSX: Cursor, Windsurf, Antigravity, VSCodium
In VS Code 1.101 and later it also registers the Astral MCP server for you.
The astral-testing skill
When to reach for Astral, how to save, run and read tests, and the credential rules: never ask for or print a secret.
Not published yet. Once it is, two commands install it:
/plugin marketplace add Perseusoft/astral
/plugin install astral@astral
The plugin brings the skill; astral-mcp setup --client claude-code connects the server.
Codex, Cursor, Antigravity · GEMINI.md for Gemini CLI
--instructions adds the same guide, shorter, between
astral:begin and astral:end markers.
Running it again replaces the block instead of duplicating it.
JetBrains plugin coming
Today: --client jetbrains --print gives you the JSON for AI Assistant's MCP settings.
When an agent says a flow works, it hands you the run: what it did at every step, what the page answered, and a test you can replay yourself.
Every run writes report.html and report.json: a screenshot per step with the click drawn on it, the network requests, console errors and Error Inbox groups of that step, performance per navigation, and an optional video.
A saved test is a script in .astral/tests, versioned with your repo and linked to its ticket. ▶ Play, test_run and the CI runner execute that script, not the model, so a replay spends no tokens and runs the same steps every time.
Group tests into ordered collections and run them against local, staging or prod from .astral/config.json. Collections run in order, in one visible tab, and write a summary report with a link to each test.
Mark an environment protected and only tests saved as readOnly may run there. Agents get a clear refusal, collections skip the rest with the reason, and the app asks before it runs anything on it.
Each replay is added to a local run history, kept on this machine and never in the repo. The Tests panel shows the latest runs per environment as green and red dots; agents read the same history with test_history.
By default the agent opens the test paused and you press ▶ Play: slow motion, pause, step by step. For demos it can start Play itself and open DevTools on the view it wants to show you. The run is labelled with the agent's name and you keep Pause, Step and Stop.
Environments, collections and credentials live in .astral/config.json.
A secret is never written there: it is a reference to the OS keychain, an
ASTRAL_TEST_* variable or a git-ignored local file, and Astral refuses a password
in plain text.
{
"project": "shop",
"envs": {
"local": { "baseUrl": "http://127.0.0.1:4555" },
"staging": { "baseUrl": "https://staging.shop.test" },
"prod": { "baseUrl": "https://shop.test", "protected": true }
},
"defaultEnv": "local",
"collections": {
"smoke": { "name": "Smoke", "tests": ["login-demo", "home-loads"] }
},
"credentials": {
"shop.demo": {
"username": "[email protected]",
"password": { "keychain": "shop.demo.password" }
}
}
} astral-test runs the same saved tests without opening Astral: in GitHub
Actions, in GitLab, or inside your agent's loop. Same collections, same protected-environment rules.
Measured on macOS with Chrome against a demo app. The browser's own memory is not included.
name: e2e
on: [push, pull_request]
jobs:
astral-test:
runs-on: ubuntu-latest # ships with Google Chrome
steps:
- uses: actions/checkout@v4
# Put astral-test on the PATH (binaries: see Downloads)
- name: Start the app under test
run: npm start & # your app
- name: Run saved tests
run: |
astral-test run . --collection smoke --engine cdp \
--reporter pretty --reporter junit --out astral-test-results
env:
ASTRAL_TEST_SHOP_DEMO_PASSWORD: ${{ secrets.SHOP_DEMO_PASSWORD }}
- if: always()
uses: actions/upload-artifact@v4
with: { name: astral-test-results, path: astral-test-results }
- if: always()
uses: mikepenz/action-junit-report@v4
with: { report_paths: astral-test-results/junit.xml } report.html per test as an artifact.
In CI, credentials come from ASTRAL_TEST_* secrets; the keychain stays in
the app, and every resolved secret is masked in the output.
With --reporter json, one JSON event per line: which step failed, what was
expected, what the page showed, the URL, an excerpt of the page tree around the target, failing requests and
console errors.
{"schemaVersion":1,"type":"step_end","testId":"wrong-greeting","step":2,"name":"Greeting","status":"failed","durationMs":5134,"error":"expect.text heading nth 0 contains \"Hi, Nobody\" — got \"Hi, Demo User\", \"Preferences\", \"Session\""}{"schemaVersion":1,"type":"test_end","testId":"wrong-greeting","status":"failed","durationMs":6964,"failure":{"kind":"assertion","step":2,"stepName":"Greeting","expected":"Hi, Nobody","actual":"\"Hi, Demo User\", \"Preferences\", \"Session\"","url":"http://127.0.0.1:4555/account","domExcerpt":"…"},"reportHtml":"/out/wrong-greeting/report.html"}{"schemaVersion":1,"type":"run_end","status":"failed","exitCode":1,"totals":{"tests":6,"passed":4,"failed":2,"skipped":0,"errors":0},"durationMs":18896} type and
schemaVersion; run_end is always last.
--engine cdp
Google Chrome, Chromium or Microsoft Edge already on the machine, or any browser you started with DevTools
(--cdp-url). Full rendering, screenshots and video. Nothing is downloaded.
--engine lite experimental
Lightpanda (opens in a new tab), if you installed it: DOM and JavaScript without rendering, page trees instead of screenshots. Not verified or measured yet. Lightpanda is AGPL-3.0; astral-test only starts it as a separate process.
How Astral compares with classic headless automation.
| Aspect | Astral | Classic headless automation |
|---|---|---|
| Where it runs | In the tab you are looking at, with a separate profile per project | In a separate browser, usually headless, started for each run |
| Seeing what happened | Watch it live, or press ▶ Play to replay in slow motion, step by step | Traces, logs and videos you open after the run |
| Credentials | OS keychain; Astral types them and the agent never sees them | Often environment variables or .env files the test process can read |
| Debugging context | Network, console, Error Inbox and performance, shared with the agent | Whatever the test collects, read after the fact |
| Best at | The daily loop: you and your agent building and checking a flow together | Large suites in CI, run in parallel across several browser engines |
Astral doesn't replace your CI suite. Use it where you build and review flows with your agent; the same saved tests can then run headless in CI with astral-test, next to the suites you already have.
From the first install to a test running in CI: how to connect your agent, what it can call, and how to keep what it tests.
Both are good tools, and you can use them alongside Astral. Here is what each is built around.
A mature way to let an agent drive Chromium, Firefox or WebKit through Playwright. It can save traces and video and generate Playwright code, and Playwright scales to large parallel suites.
Puts an agent inside the browser you already use, with your everyday profile and the sites you are signed in to. Nothing new to install beyond the extension.
BEYOND THE DEVELOPMENT LOOP
Chat with pages, keep your bookmarks close, and bring local apps into your workspace.
No coding agent needed. Ask Astral's chat to look something up or try a flow on a site, and it works in a real tab while you watch.
The Performance tab of the DevTools drawer rates every load green, amber or red, explains the slow part in a sentence, and draws the load timeline.
| Metric | Good | Poor |
|---|---|---|
| TTFB | ≤ 0.8 s | > 1.8 s |
| FCP | ≤ 1.8 s | > 3 s |
| LCP | ≤ 2.5 s | > 4 s |
| INP | ≤ 200 ms | > 500 ms |
| CLS | ≤ 0.1 | > 0.25 |
The web-vitals thresholds. On macOS and Linux the WebKit engines do not report CLS, long tasks or JavaScript memory, so those read "not available".
The collector runs in an isolated world, so the page cannot see or fake it. Load phases, FCP, LCP and its element, INP, and resources by type and weight, for every document a tab shows.
What the engine cannot measure says not available, and what has not happened yet says waiting. Never a 0.
The last loads of each page are kept while Astral is open, with every metric compared against their median: better, same or worse.
Agents call page_performance; test reports include a performance table for every navigation of the run.
With devtools_show, an agent opens the DevTools drawer on Issues, Network, Console or Performance, or on one request's timings, while it explains what it found.
Bring your bookmarks with you in one click. They are stored in a local database on your machine: no account, no server, nothing leaves the device.
Complete on macOS, where some browsers' data needs Full Disk Access (or an HTML export); best effort on Windows and Linux.
Plugins let the apps already running on your computer — a music player, a task list, your notes — show up in Astral while they're open.
A plugin declares what it is. A music player gets a now-playing pill and a player panel with its queue and library; other types work today through generic action panels.
Play, pause, skip or pick from the queue in Astral while the audio keeps playing in your app. Each plugin only gets the scopes you approved when pairing.
Plugins talk to Astral on 127.0.0.1 only. You pair each app with a 6-digit code, its token lives in the OS keychain, and every action lands in an audit log.
The contract is HTTP, JSON and server-sent events. The Plugin SDK guide walks through it, with a mock plugin and a conformance suite to test against.
Native desktop builds for macOS, Windows, and Linux. Free download, runs locally — credentials stay in your OS keychain.
Pick your platform:
Pre-alpha builds ship unsigned: macOS Gatekeeper and Windows SmartScreen will warn you the first time you open Astral. Pick a platform below and this note shows the exact command for it.
Why it is unsigned, and the notes for every platform ↓Astral is in pre-alpha and ships without code-signing certificates from Apple or Microsoft. macOS Gatekeeper and Windows SmartScreen will warn you when you try to open the installer. By downloading, you accept that you are installing software that has not been notarized by an OS vendor. We will introduce signing once the project exits pre-alpha.
macOS
macOS attaches a com.apple.quarantine flag
to every file your browser downloads. Gatekeeper blocks the app until the flag
is removed — even if you allowed apps from anywhere in System Settings.
If you already moved Astral to Applications and it refuses to open ("damaged" / "cannot be verified"), run:
sudo xattr -cr /Applications/Astral.app
Then double-click Astral. Alternative: clean the .dmg before mounting it:
xattr -d com.apple.quarantine ~/Downloads/Astral_*.dmg Windows
When SmartScreen says "Windows protected your PC", click More info → Run anyway.
Linux
Make the AppImage executable and run it:
chmod +x Astral_*.AppImage
./Astral_*.AppImage
Or install the .deb on Debian/Ubuntu:
sudo dpkg -i Astral_*.deb The CI runner is published. The MCP bridge has no download of its own: it ships inside each desktop installer. The editor extension and the Claude Code plugin are not published yet and are listed so you know what is coming; nothing below is a dead link.
astral-test · CI runner
astral-test · macOS Apple Silicon
Single binary. Uses a Chrome, Chromium or Edge you already have.
astral-test · CI runner
astral-test · macOS Intel
Single binary. Uses a Chrome, Chromium or Edge you already have.
astral-test · CI runner
astral-test · Linux x64
For CI runners such as GitHub Actions ubuntu-latest, which ship Chrome.
astral-test · CI runner
astral-test · Windows x64
Single binary. Uses a Chrome, Chromium or Edge you already have.
MCP bridge
astral-mcp
No separate download: it ships inside every Astral desktop installer.
Editor extension
VS Code extension · Visual Studio Marketplace
Astral Tests (perseusoft.astral-tests) for VS Code.
Editor extension
VS Code extension · Open VSX
The same extension for Cursor, Windsurf, Antigravity and VSCodium.
Agent plugin
Claude Code plugin
The astral-testing skill: when to use Astral and how to save, run and read tests.
Once it is published
/plugin marketplace add Perseusoft/astral
/plugin install astral@astral Optional engine
Lightpanda (optional engine)
Experimental lite engine for astral-test: DOM and JavaScript without rendering. AGPL-3.0, installed by you; Astral never bundles or downloads it.
A FEW MORE THINGS
Astral is the agentic browser for the agentic era: AI agents and you work in the same real browser tabs. Coding agents connect over MCP to drive and test the pages you build while you watch, and Astral's own agents use UADP (Universal Agentic Data Protocol) to reach services through structured data instead of HTML.
UADP is an open protocol that lets AI agents access structured data from services — email, banking, shopping, social media — via signed JSON responses instead of HTML. It replaces web scraping with a consent-based, agent-native API layer.
Yes, verified on macOS and Linux (implemented but not yet verified on Windows). Astral is an MCP server: connect Claude Code, Cursor, VS Code or any MCP client with one-click setup in Settings > Developer. Agents drive real tabs, run tests with step reports, screenshots and, on macOS, video, save reproducible tests in .astral/tests linked to tickets, and read network, console, errors and performance. Credentials come from the OS keychain and are never shown to the agent.
Yes. Astral is a free download. It runs locally on Windows, macOS, and Linux using Tauri. Credentials stay in the OS keychain. Connected services and AI providers process the requests you send to them.
Comet and Dia add an AI assistant to a traditional browser. Astral is built around agents: external coding agents connect over MCP and work in the same tabs you see, with permissions, consent and an audit log, and services that speak UADP return structured data that Astral renders as adaptive UI components instead of HTML.