Skip to main content
Glama

OpenBoxy

Give your AI agents a real browser and terminal.

OpenBoxy equips chat-only AI agents with a persistent Chromium browser, workspace shell, and live human takeover over MCP—in a self-hosted, single-container Streamable HTTP MCP server (/mcp) with a live web UI (/, /view, /view/terminal) where you can watch or click Take Control to handle logins, 2FA, or CAPTCHAs by hand.

Each API token maps to an isolated user sandbox (/data/users/<userId>/profile, /workspace, and /home), so multiple users (or multiple AI clients) can connect safely.

Screenshots

Sign In (/login)

OpenBoxy Sign In

Live Browser View (/view)

OpenBoxy Live Browser View


Quick Start

  1. Create .env from the example:

    cp .env.openboxy.example .env

    Generate your default API token (OPENBOXY_MCP_TOKEN):

    openssl rand -hex 32

    Optionally add more users in .env:

    OPENBOXY_USERS=alice:tok_alice_xxx,bob:tok_bob_xxx
  2. Start OpenBoxy:

    docker compose -f docker-compose.openboxy.yml up -d --build
  3. Verify:

    • Health check: curl http://127.0.0.1:3100/healthz

    • Web UI (Browser & Terminal): http://127.0.0.1:3100/


Related MCP server: orchords-web-pilot

Connecting External AI Clients (/mcp)

OpenBoxy supports OAuth 2.0 PKCE + Dynamic Client Registration and Static Bearer Tokens.

Point your client at https://your-domain/mcp with no manual headers. In OpenCode (~/.config/opencode/opencode.jsonc):

{
  "mcp": {
    "boxy": {
      "type": "remote",
      "url": "https://your-domain/mcp",
      "enabled": true
    }
  }
}

Then run /mcps in OpenCode, select boxy, and sign in at /oauth/authorize using your API token. Your OAuth session is bound to that token's user sandbox.

Option B: Static Bearer Token

{
  "mcpServers": {
    "boxy": {
      "serverUrl": "https://your-domain/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Exposed MCP Tools

  • Terminal & Files: shell, read_file, write_file, edit_file, list_dir

  • Browser: browser_navigate, browser_snapshot, browser_read, browser_click, browser_type, browser_press, browser_scroll, screenshot, browser_view

  • Browser Downloads: Any file downloaded in the live browser automatically saves to workspace/downloads/ and appears in /view/files.


Plugins (Custom Tools)

Drop .ts / .js plugin files into /data/plugins (or set OPENBOXY_PLUGINS_DIR) to register custom MCP tools without modifying OpenBoxy core:

import type { OpenBoxyPlugin } from "/app/src/plugins.ts";

export default {
  name: "my-custom-tool",
  // Optional: restrict to specific userIds
  // allowedUsers: ["default"],
  register(ctx) {
    ctx.registerTool(
      "open_my_app",
      {
        description: "Open my internal web app and prefill an input.",
        inputSchema: { query: ctx.z.string() },
      },
      async ({ query }) => {
        await ctx.sandbox.withPage(ctx.userId, async (page) => {
          await page.goto("http://my-service:8080");
          // ...prefill page...
        });
        return ctx.textResult({
          viewUrl: `${ctx.publicUrl}/view`,
          filesUrl: `${ctx.publicUrl}/view/files`,
        });
      },
    );
  },
} satisfies OpenBoxyPlugin;

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Exposes a remote browser as MCP tools via Playwright, enabling AI agents to navigate and interact with web pages through DOM snapshots, clicks, typing, and form operations.
      40
      14 npm
      14
      Apache 2.0
    • F
      license
      A
      quality
      C
      maintenance
      Enables coding agents to drive a real Playwright-backed browser session, navigating, observing, interacting, and capturing proof on web pages via MCP tools across stdio and Streamable HTTP transports.
      15
      2
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents and clients to control a real Chromium browser through MCP tool calls, including navigation, clicking, typing, JavaScript evaluation, screenshots, and DOM snapshots. Supports multiple isolated sessions over authenticated HTTP with no disk writes.
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to drive a live, persistent self-hosted Chromium session over MCP, running browser actions via Playwright/CDP, capturing page snapshots, screenshots and videos, and managing uploads and downloads in the same tabs and signed-in accounts a human user can take over at any time.
      28 npm
      Apache 2.0