An Open Standard for Autonomous Browser Automation
Quick Start • Specification • Book • Roadmap
The Starlight Protocol decouples intent from environment. Your test scripts describe goals; autonomous Sentinels handle the chaos.
// Traditional: Handle EVERYTHING yourself
if (await page.$('.cookie-banner')) await page.click('.dismiss');
if (await page.$('.popup')) await page.click('.close');
await page.click('#submit');
// Starlight: Express INTENT only
await hub.send({ goal: 'Submit Form' });
// Sentinels automatically clear obstacles
| Component | Role |
|---|---|
| Hub | Central orchestrator, manages Playwright browser |
| JWT Handler | Authentication & authorization system |
| Schema Validator | Input validation & message verification |
| PII Redactor | Data protection & privacy compliance |
| Pulse Sentinel | Monitors DOM/Network stability |
| Janitor Sentinel | Clears popups, modals, banners |
| Vision Sentinel | AI-powered obstacle detection (Moondream) |
| Data Sentinel | Context extraction & injection |
- Node.js 18+ & Python 3.9+
- Ollama (optional, for Vision)
git clone https://github.com/starlight-protocol/starlight.git
cd cba
npm install
pip install -r requirements.txt
npx playwright install chromium# One command launches everything
node bin/starlight.js test/intent_portfolio_v2.js --headlessnode launcher/server.js
# Open http://localhost:3000# Run with Firefox
HUB_BROWSER_ENGINE=firefox node bin/starlight.js test/intent_portfolio_v2.js
# Run with WebKit (Safari engine)
HUB_BROWSER_ENGINE=webkit node bin/starlight.js test/intent_portfolio_v2.js
# Or configure in config.json:
{
"hub": {
"browser": { "engine": "firefox" }
}
}Supported Browsers:
- Chromium (default) - Full CDP access, shadow DOM piercing
- Firefox - Mozilla engine, standard DOM APIs
- WebKit - Safari engine, iOS compatibility testing
Install all browsers:
npx playwright install chromium firefox webkit# Run on iPhone 14 Pro Max
HUB_DEVICE="iPhone 14 Pro Max" node bin/starlight.js test/intent_saucedemo.js
# Run on Pixel 7
HUB_DEVICE="Pixel 7" node bin/starlight.js test/intent_saucedemo.js
# Or configure in config.json:
{
"hub": {
"device": "iPhone 14 Pro Max"
}
}Verified: Full 12-step SauceDemo checkout flow passes autonomously. See test/intent_saucedemo.js.
All communication uses JSON-RPC 2.0:
| Method | Purpose |
|---|---|
starlight.intent |
Issue a goal or command |
starlight.pre_check |
Hub → Sentinels handshake |
starlight.clear |
Sentinel approves action |
starlight.wait |
Sentinel vetoes (retry later) |
starlight.hijack |
Sentinel takes browser control |
starlight.resume |
Sentinel releases control |
| Feature | Description |
|---|---|
| JWT Authentication | Secure token-based authentication with timing-safe verification |
| Input Validation | Comprehensive JSON schema validation for all protocol messages |
| PII Protection | Automatic detection and redaction of sensitive data (emails, passwords, credit cards) |
| Self-Healing Selectors | Learns alternatives when selectors fail |
| Animation Tolerance | Handles CSS animations without blocking |
| No-Code Recorder | Record tests by clicking through your site |
| Visual Sentinel Editor | Create custom Sentinels without code |
| Shadow DOM Support | Pierces web component boundaries |
| Webhook Alerts | Slack/Teams notifications |
| Upload Automation | Native file upload support (selector & semantic) |
| ROI Dashboard | Quantifies time saved |
from sdk.starlight_sdk import SentinelBase
class MySentinel(SentinelBase):
def __init__(self):
super().__init__("MySentinel", priority=5)
self.selectors = [".my-obstacle"]
async def on_pre_check(self, params, msg_id):
# Your detection logic
await self.send_clear()
if __name__ == "__main__":
import asyncio
asyncio.run(MySentinel().start())Install community Sentinels or create your own:
# List installed & available
python cli/main.py list --available
# Install from registry or GitHub
python cli/main.py install cookie-consent
python cli/main.py install captcha-detector
python cli/main.py install https://github.com/user/my-sentinel
# Create new Sentinel
python cli/main.py create "Cookie Blocker"
# Use Visual Editor (no-code)
# Open Mission Control → Click "Create Sentinel"Available Plugins:
| Plugin | Description |
|---|---|
cookie-consent |
Auto-dismiss cookie banners and GDPR popups |
captcha-detector |
Detect CAPTCHA and pause for manual intervention |
login-session |
Persist login sessions across test runs |
# Run all unit tests (100% coverage)
node test/run_all_tests.js| Component | Test File | Status |
|---|---|---|
| IntentRunner | test_intent_runner.js | ✅ |
| SentinelSDK | test_sentinel_sdk.js | ✅ |
| HubCore | test_hub_core.js | ✅ |
| BrowserAdapter | test_browser_adapter.js | ✅ |
| ShadowUtils | test_shadow_utils.js | ✅ |
| Warp | test_warp.js | ✅ |
| Telemetry | test_telemetry.js | ✅ |
| CLI | test_cli.js | ✅ |
| + 4 more | ... | ✅ |
| Document | Description |
|---|---|
| 🔒 Security Guide | Security architecture & best practices |
| 📖 Book | Comprehensive guide |
| 📄 Specification | Formal protocol standard |
| 📋 User Guide | Getting started |
| ⚙️ Technical Guide | SDK & configuration |
| 🛡️ Security Configuration | Security settings reference |
| 📊 Compliance Guide | GDPR/HIPAA compliance |
| 🧪 Security Testing | Security testing procedures |
| 🗺️ Roadmap | Future plans |
| 📝 Changelog | Version history |
Starlight Protocol includes enterprise-grade security features:
- ✅ JWT-based authentication with HS256 signing
- ✅ Configurable token expiration (default: 3600s)
- ✅ Timing-safe signature verification
- ✅ Token refresh mechanism
- ✅ Comprehensive JSON schema validation for all protocol messages
- ✅ Field type checking, pattern matching, and length limits
- ✅ CSS selector injection prevention
- ✅ XSS protection with HTML escaping
- ✅ Automatic PII detection and redaction
- ✅ AES-256-GCM encryption for sensitive data
- ✅ Secure logging with automatic PII redaction
- ✅ Compliance modes: alert, block, or redact
{
"security": {
"jwtSecret": "your-secret-key",
"tokenExpiry": 3600,
"piiRedaction": true,
"ssl": {
"enabled": false,
"keyPath": null,
"certPath": null
}
}
}📄 Security Guide - Complete security documentation
docker-compose up --buildMIT License - LICENSE
"Don't look at the ground; look at the Starlight."
Built with ❤️ by Dhiraj Das