Skip to main content

waymark-browser

Command-line companion for Waymark, an open-source desktop browser that AI agents and people use together. Waymark gives agents an MCP endpoint, keeps their clipboard and pointer isolated from your desktop, routes CAPTCHAs through local OCR → AI → human hand-off, and records every action with the page snapshot it was based on.

This package installs and runs the desktop app, drives it from your terminal, and bridges it to MCP clients that only speak stdio. It has no Python dependencies.

pip install waymark-browser            # CLI only
pip install "waymark-browser[ocr]"     # plus local ddddocr for text CAPTCHAs

Waymark itself is an Electron app, so you also need Node.js 22+.

Quick start

waymark setup        # download and build the app into ~/.waymark/app
waymark start        # open the browser window; MCP at http://127.0.0.1:9510/mcp
waymark doctor       # check Node.js, the install and the connection

On a Linux server without a display, use xvfb-run -a waymark start --foreground.

Connect an AI agent

Claude Code (HTTP):

claude mcp add --transport http waymark http://127.0.0.1:9510/mcp

Codex (~/.codex/config.toml):

[mcp_servers.waymark]
url = "http://127.0.0.1:9510/mcp"

Clients that only support stdio:

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

Drive the browser from the terminal

waymark open https://example.com     # -> Opened tab 2
waymark snapshot 2                   # interactive elements with refs e1, e2, ...
waymark fill 2 e4 "noise cancelling headphones"
waymark press 2 Enter
waymark read 2 --limit 2000          # visible text (or --html for the rendered DOM)
waymark audit --limit 20             # what happened, when, on which page
waymark pause / waymark resume       # take the browser back from agents

All commands accept --json for machine-readable output and --url (or WAYMARK_URL) to target another instance. waymark call TOOL '{"json": "args"}' reaches any MCP tool directly.

Command What it does
setup [--dir] [--ref] Download the app source for this CLI's version and build it
start [--port] [--foreground] / stop Run the desktop app in the background or attached
status, doctor Automation state, pending challenges; environment checks
tabs, open, goto, back, forward, reload, close Tabs and navigation
snapshot, read, click, hover, fill, paste, press, scroll, wait Page actions by snapshot ref
audit, trace ID Action ledger and the snapshot behind one action
challenge [action] [id] Inspect or advance CAPTCHA jobs
pause, resume User control lease: agents are refused while paused
mcp [--autostart] stdio MCP bridge
tools, call Raw MCP access

中文说明

waymark-browser 是开源 AI 浏览器 Waymark 的命令行工具:一条命令安装并启动浏览器、在终端里打开网页/点击/填写/读取、查看 AI 的每一步操作记录,并为只支持 stdio 的 MCP 客户端提供桥接。安装 waymark-browser[ocr] 可启用本地 ddddocr 识别文字验证码。需要 Node.js 22 及以上。

License: MIT

Metadata

Release files for waymark-browser 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for waymark-browser 0.2.0
File Size Uploaded Provenance Actions
waymark_browser-0.2.0.tar.gz 16.3 kB With provenance Details for waymark_browser-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for waymark-browser 0.2.0
File Interpreter ABI Platform Actions
waymark_browser-0.2.0-py3-none-any.whl Python 3 none any Details for waymark_browser-0.2.0-py3-none-any.whl

Total release size: 32.7 kB

Release files / waymark_browser-0.2.0.tar.gz

Download URL waymark_browser-0.2.0.tar.gz
Size 16.3 kB
Tags Source
SHA-256 checksum
How to use checksums
60714a71fd26908897afc8cf1df998f88c0435b71748969a5fc434dea9b49cd4
BLAKE2b-256 checksum
How to use checksums
30d89644602abea6ef6393d32aa5a81024ca4709cb35c00eecbf478d6b3d6766
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / waymark_browser-0.2.0-py3-none-any.whl

Download URL waymark_browser-0.2.0-py3-none-any.whl
Size 16.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d739ab15bdff22cde2351ff0d3d670b5f186bf2fd3502b2efed0a0c66309e387
BLAKE2b-256 checksum
How to use checksums
1c2914d70a7676f3227f63aff9a980ab5815da6479d9ef89da9160d0d4a700fa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for waymark-browser 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for waymark_browser-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page