Unchained Infra

Open infrastructure and control plane for Unchained, a browser automation system

built on raw Chrome DevTools Protocol.

Most browser agents break at authentication. Unchained avoids that by driving the

user's own Chrome session, with their existing cookies, extensions, IP, and 2FA

state, instead of replaying brittle logins in a sandbox.

This repository contains the public-facing pieces of that system: relay, web UI,

agent packaging, browser bridge, deployment assets, and server orchestration.

The proprietary extraction engine lives behind a documented runtime boundary in a

separate private repository.

What is in this repo

• `unchained/web.py`: chat UI, auth flows, scheduler UI, SSE chat transport
• `unchained/relay.py`: WebSocket relay for browser-agent tunnels and CDP clients
• `unchained/chrome_bridge.py`: local or headless bridge from Chrome CDP to relay
• `unchained/chat_agent_cli.py`: local agent lanes for Claude CLI, Codex CLI,

OpenCode CLI, and related model backends

• `unchained/chat_agent_openrouter.py`: hosted OpenRouter inference worker for

the hybrid trial lane (the browser still runs through the user's connector)

• `unchained/credit.py`: grant-based hosted-inference ledger and per-call holds
• `unchained/agent_package.py`: downloadable agent bundle generator
• `docker-compose.yml`: production deployment topology
• `deploy.sh` and `deploy_headless.sh`: EC2 deployment entrypoints

What stays private

The DDM, page-intelligence, and core CDP execution logic are not stored in this

repository. Public code talks to that layer through `private_core_client.py`.

That split is intentional:

• the relay, UI, auth, packaging, and deployment code are open for inspection
• the high-leverage browser extraction heuristics stay in the private core repo
• CI enforces the boundary with import guards and artifact checks

See docs/open-core-split-plan.md for the

current open-core model.

Why developers can evaluate this repo

• The browser tunnel is here. You can inspect how agent auth, relay routing, and

CDP proxying actually work.

• The deployment path is here. Docker Compose, Caddy routing, EC2 deploy scripts,

and headless worker definitions are part of the public repo.

• The trust boundary is explicit. Public services do not directly import private

browser-intelligence modules.

• The local dev path is real. You can run the relay and web app locally with

`./dev.sh`.

System shape

Phone / browser
    |
    | HTTPS + SSE
    v
Caddy -> web -> private_core_client -> private core service
   |       |
   |       +-> local chat-agent websocket
   |       +-> hosted trial-agent -> OpenRouter
   |
   +-> relay -> chrome_bridge -> user's Chrome DevTools endpoint

More detail: docs/architecture.md

Quick start

Local development

cd unchained-infra/unchained
uv sync
cd ..
./dev.sh

Then open `http://localhost:8080`.

If Google OAuth is not configured, the app falls back to dev auth:

curl -X POST http://localhost:8080/auth/dev \
  -H 'Content-Type: application/json' \
  -d '{"email":"dev@localhost"}'

`dev.sh` starts only the local web server and relay. To connect a local chat

client and controlled Chrome without sending test traffic to production, follow

docs/local-agent-testing.md. The browser

session, chat client, and Chrome bridge must use the same locally stored API

key.

The hosted trial worker is not started by `dev.sh`. Docker deployments that

enable it must set a dedicated `HOSTED_AGENT_SERVICE_TOKEN`; it must not reuse

`TRIAL_AGENT_KEY`, `PRIVATE_CORE_TOKEN`, or a user API key.

Production deploy

cd ~/Projects/unchainedsky_com/unchained-infra
git switch main
git pull --ff-only origin main

DEPLOY_REVISION="$(git rev-parse HEAD)" \
PRIVATE_CORE_SRC=../unchained-core-private/unchained \
KEY_PATH=~/.ssh/unchained-key.pem \
EC2_HOST= \
EC2_USER= \
./deploy.sh

`deploy.sh` rejects dirty worktrees and any revision other than the current

`origin/main`. It applies and restores the private-core overlay only after that

source check succeeds. The guard requires `origin` to be reachable and fails

closed if it cannot query the current `main` revision.

Verification

These are the quickest checks for the public repo boundary and local stack:

cd unchained-infra/unchained
uv run python test_open_core_boundary.py

cd ..
python3 tools/oss_guard/check_private_imports.py
python3 tools/oss_guard/check_agent_artifact_leaks.py

Repository layout

unchained-infra/
├── docs/                    # Architecture, setup, roadmap, and design notes
├── deploy/                  # Deployment helpers
├── tools/                   # Private-core overlay + OSS boundary guards
├── unchained/               # Python application code
├── docker-compose.yml       # Production stack
├── docker-compose.headless.yml
└── deploy.sh

Documentation

• docs/README.md: docs index
• docs/architecture.md: service layout and request flow
• docs/cloud-tools-execution-map.md: where

browser actions execute across the public/private boundary

• docs/debugging-map.md: trace events and incident triage
• docs/local-agent-testing.md: run the web UI,

chat client, relay, and controlled Chrome entirely on one development machine

• docs/mcp-local-browser-guide.md: run

production MCP against your local Chrome bridge

• docs/mcp-frontend-route-plan.md: plan for

a public `/mcp` onboarding route and positioning copy

• docs/unbrowser-mcp-route.md: hosted

unbrowser MCP route and deployment notes

• docs/fin-terminal-route.md: authenticated

financial terminal route and deployment notes

• docs/you-navigate-demo.md: local setup and

reward-critic framing for the "Unchained drives. You navigate." demo

• docs/split-repo-setup.md: CI and private-core overlay
• unchained/benchmark/README.md: local benchmark flow
• unchained/README.md: package-level developer notes

License

MIT