Skip to content

About

No description, website, or topics provided.

Resources

Stars

7 stars

Watchers

0 watching

Forks

Repository files navigation

AgentBrowser

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

Demo

AgentBrowser demo

Why this project exists

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

What it includes

  • 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

Main capabilities

1. Live desktop you can actually see

Open the streamed desktop in your browser and watch or interact with the running desktop session in real time.

2. Local agent control through CDP

Attach Playwright or any CDP-compatible client to the running browser without exposing it publicly.

3. MCP-compatible browser and desktop automation

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.

4. Niri-aware desktop control

Control workspaces, windows, screenshots, app spawning, and desktop actions through endpoints that understand the active Niri session.

5. Rendered Markdown extraction

Fetch a page and convert its rendered content into cleaner Markdown for downstream agent use.

6. Secret-blind login flows

Authenticate to Bitwarden once, then let the service perform site logins with auto-TOTP without returning usernames, passwords, or TOTP codes to the agent.

High-level architecture

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

Quick start

cp .env.example .env
docker compose up -d --build

Then:

  1. Edit .env
  2. Change at least SELKIES_BASIC_AUTH_PASSWORD
  3. Set a strong BW_STATE_KEY if you want persistent Bitwarden sessions
  4. Open http://localhost:18080

Connect your MCP client

Claude Desktop / Claude Code

claude mcp add agentbrowser http://127.0.0.1:18787/mcp/

Codex (OpenAI)

codex mcp add agentbrowser http://127.0.0.1:18787/mcp/

OpenCode

Auto-discovery via .mcp.json in the project root, or add manually:

{
  "mcp": {
    "agentbrowser": {
      "type": "remote",
      "url": "http://127.0.0.1:18787/mcp/"
    }
  }
}

Any MCP-compatible client

Endpoint: http://127.0.0.1:18787/mcp/

Ports

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

CLI tool

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"

Bitwarden session persistence

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.enc encrypted with Fernet (BW_STATE_KEY)
  • data.json encrypted 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 vault

Web interface:

  • /auth/bw — Bitwarden login/status page
  • Selkies web sidebar — "Bitwarden" button opens /auth/bw

Project structure

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

Security model

  • .env is 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

License

Source-Available, Non-Commercial. See LICENSE.

For commercial licensing: aitor@nimbox360.com

About

No description, website, or topics provided.

Resources

Stars

7 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages