Home / Getting started / Agents

Agent quickstart: MCP, REST, Docker

Three doors into the same browser. Pick the one that matches what you are building; each is a copy-paste block and a restart. Ports: REST on 3000, WebDriver on 9515, CDP on 9222, all configurable in Settings.

0. Install (one minute)

Needs Node 18+. Downloads the portable build for your OS on first run, caches it under ~/.lumabrowser/, launches it. Prefer a normal install? Native installers. On first launch pick Guided Setup if you want to paste an API key up front; Automatic if you want a local model. Either way the API and MCP server are on as soon as the window opens.

1. MCP: Claude Desktop, Cursor, OpenClaw, anything MCP

Add this under mcpServers in your host's config, then restart the host:

{
  "mcpServers": {
    "lumabrowser": {
      "command": "lumabrowser",
      "args": ["--mcp"]
    }
  }
}

If lumabrowser is not on your PATH, use the full path to the executable. Your agent now has navigate, click, type, fill_form, observe_page, screenshot, get_source, and the rest, each backed by a real Chromium tab. Full list and the element-reference conventions: MCP server reference.

2. REST: open a page, click with a fallback, read it

# Open a tab
curl -X POST http://localhost:3000/api/browser/tabs \
  -H "Content-Type: application/json" \
  -d '{"url": "https://news.ycombinator.com"}'

# Click. If the selector is stale, the LLM resolves the description instead.
curl -X POST http://localhost:3000/api/browser/tabs/0/click \
  -H "Content-Type: application/json" \
  -d '{"selector": ".titleline > a", "llmFallback": "Click the first story link"}'

# Read the page as clean text
curl http://localhost:3000/api/browser/tabs/0/source?type=text

Every selector call accepts llmFallback; the fallback is logged per call so you can audit it. Forms, waits, scrolling, screenshots, network capture, and webhooks are all under the same base. REST reference.

Selenium, Playwright, Puppeteer

Your existing scripts attach unchanged: Selenium to the WebDriver server on 9515; Playwright with chromium.connectOverCDP('http://127.0.0.1:9222'); Puppeteer with puppeteer.connect({ browserURL: 'http://127.0.0.1:9222' }). Details per driver.

3. Docker: headless, with a web desktop

docker run -d \
  -p 3000:3000 \
  -p 6080:6080 \
  -v luma-data:/data \
  --shm-size=2g \
  --name lumabrowser \
  lumabyte/lumabrowser:latest

REST on 3000, a noVNC desktop on 6080 so you can watch the agent work. Point it at a model on the host with LUMA_LLM_PROVIDER and friends; the Docker guide has the compose file and every variable.

What people build first

• An agent that browses for real from Claude Desktop or Cursor, with the MCP block above. Ten minutes.
• A change monitor that fires a webhook when an element on a page changes. No usage caps.
• An n8n / Zapier / Make step that drives a real browser without per-minute cloud pricing. Recipe.
• Sub-agents with their own tools and knowledge base, orchestrated from one chat. Sub-agents.
• Your own chat tools, built in a sandbox by the assistant and published to itself. Code Mode and Tool Forge.