Browser automation appliance with a real visible desktop inside Docker, Arch + Selkies + Niri + Noctalia, local CDP access for agents, full desktop control, Markdown extraction, and secure Bitwarden-assisted login flows.
License: Source-Available, Non-Commercial — Free for personal/educational use. Commercial use and SaaS deployment require a license.
Languages: 🇬🇧 English · 🇪🇸 Español
- GIF preview:
assets/demo.gif - Video demo:
assets/demo.mp4 - Static cover:
assets/demo-cover.jpg
Most browser automation stacks force you to choose between:
- a real visible browser for manual inspection
- deterministic agent control
- full desktop automation beyond the browser
- safe handling of credentials
- remote access from a server without a local GUI
AgentBrowser combines those pieces into one appliance:
- real visible browser, not headless-only
- full remote desktop streamed over Selkies/WebRTC
- local CDP for Playwright/agent control
- HTTP/MCP tools for browser and desktop actions
- Bitwarden-backed secure login without exposing secrets to the agent
- Arch-based Selkies image as the desktop streaming base
- Niri as the primary compositor
- Noctalia as the desktop shell
- Chromium and Google Chrome inside the container
- Persistent browser profile in a Docker volume
- CDP exposed only on localhost
- Go MCP server (~104 tools) for browser, desktop, Bitwarden, and Niri control
- Markdown extraction from rendered pages
- Desktop control for keyboard, mouse, windows, screenshots, apps, and Niri actions
- Secure login flow with auto-TOTP that reuses Bitwarden state without returning credentials
Open the streamed desktop in your browser and watch or interact with the running desktop session in real time.
Attach Playwright or any CDP-compatible client to the running browser without exposing it publicly.
Use the local MCP/API surface to drive navigation, clicks, screenshots, evaluation, app launching, keyboard typing, and window management.
~104 tools across browser, desktop, Niri, Thunar, Bitwarden, WebAuthn, and more. See docs/MCP_TOOLS.md.
Control workspaces, windows, screenshots, app spawning, and desktop actions through endpoints that understand the active Niri session.
Fetch a page and convert its rendered content into cleaner Markdown for downstream agent use.
Authenticate to Bitwarden once, then let the service perform site logins with auto-TOTP without returning usernames, passwords, or TOTP codes to the agent.
Agent / Playwright / MCP client (Claude, Codex, OpenCode)
|
v
127.0.0.1:18787 Go MCP server (agentbrowser-go)
|
+--------+-------------------+
| |
v v
CDP / browser control desktop + auth helpers
| |
+-------------+--------------+
v
Chromium / Chrome inside Docker
|
v
Arch Selkies base + Niri + Noctalia
|
v
http://localhost:18080
cp .env.example .env
docker compose up -d --buildThen:
- Edit
.env - Change at least
SELKIES_BASIC_AUTH_PASSWORD - Set a strong
BW_STATE_KEYif you want persistent Bitwarden sessions - Open
http://localhost:18080
claude mcp add agentbrowser http://127.0.0.1:18787/mcp/codex mcp add agentbrowser http://127.0.0.1:18787/mcp/Auto-discovery via .mcp.json in the project root, or add manually:
{
"mcp": {
"agentbrowser": {
"type": "remote",
"url": "http://127.0.0.1:18787/mcp/"
}
}
}Endpoint: http://127.0.0.1:18787/mcp/
| Port | Scope | Purpose |
|---|---|---|
18080 |
host | Selkies live desktop (HTTP) |
18443 |
host | Selkies live desktop (HTTPS) |
127.0.0.1:18787 |
local only | MCP server (streamable-http) |
127.0.0.1:19222 |
local only | Browser CDP proxy |
127.0.0.1:18082 |
local only | Selkies websocket bridge |
Standalone Python CLI for browser automation with Bitwarden integration:
# Browser
python3 skills/browser-automation/agentbrowser-cli.py tabs
python3 skills/browser-automation/agentbrowser-cli.py navigate https://example.com
python3 skills/browser-automation/agentbrowser-cli.py fill "#email" "user@test.com"
python3 skills/browser-automation/agentbrowser-cli.py screenshot
# Auto-login with Bitwarden
python3 skills/browser-automation/agentbrowser-cli.py login example.com
# Desktop
python3 skills/browser-automation/agentbrowser-cli.py desktop click 100 200
python3 skills/browser-automation/agentbrowser-cli.py desktop type "hello"Sessions survive container restarts:
| File | Content | Location |
|---|---|---|
session.enc |
Encrypted session token | /data/profile/bitwarden-state/ |
data.json |
Encrypted vault data | /dev/shm/agentbrowser-bw/.config/Bitwarden CLI/ |
Security:
session.encencrypted with Fernet (BW_STATE_KEY)data.jsonencrypted with user's master password- Both in tmpfs (RAM) — cleared on reboot
Session management:
agentbrowser_restore_session() # Restore after restart
agentbrowser_logout_bitwarden() # Clear session, keep vault
agentbrowser_full_logout_bitwarden() # Clear session AND vaultWeb interface:
/auth/bw— Bitwarden login/status page- Selkies web sidebar — "Bitwarden" button opens
/auth/bw
go-poc/
agentbrowser-go Compiled Go MCP binary (~104 tools)
pixelmatch_detect.py GeeTest captcha detector
root/defaults/
selkies-web/
agentbrowser.css Custom Selkies CSS (sidebar, theme)
agentbrowser.js Custom Selkies JS (branding, Bitwarden button)
startup.sh Runtime startup hook
skills/
agentbrowser-desktop-mcp/ MCP usage guidance
browser-automation/ CLI tool and usage patterns
.mcp.json MCP client auto-discovery
Dockerfile Container build
docker-compose.yml Orchestration
.envis ignored by git- CDP is bound to localhost
- MCP is bound to localhost
- Live desktop is protected with basic auth
- Bitwarden state persisted without exposing secrets
- Secure login returns status, not credentials
- License prohibits SaaS and commercial use
Source-Available, Non-Commercial. See LICENSE.
For commercial licensing: aitor@nimbox360.com
