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+.

The desktop interface supports English (default), Simplified Chinese, Japanese, Korean, Spanish, French, German and Portuguese. Choose Settings → Language in the app, or use the selector on the start or audit page. The choice persists across restarts. CLI commands, diagnostics and MCP fields remain in English.

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.3.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.3.0
File Size Uploaded Provenance Actions
waymark_browser-0.3.0.tar.gz 16.5 kB With provenance Details for waymark_browser-0.3.0.tar.gz

Built distribution (wheel)

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

Total release size: 33.0 kB

Release files / waymark_browser-0.3.0.tar.gz

Download URL waymark_browser-0.3.0.tar.gz
Size 16.5 kB
Tags Source
SHA-256 checksum
How to use checksums
a9eafb12863398279a0ffcdda1dc07f0ad9e57129e12474a7e27a52ea99a53aa
BLAKE2b-256 checksum
How to use checksums
842fe25fe2ae7ee8acfc899fc78a968dea9c5a6aae2458051355c9cd5250dc27
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.3.0-py3-none-any.whl

Download URL waymark_browser-0.3.0-py3-none-any.whl
Size 16.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6187d6bc369539d0203f78e004a61026d0b90e469abe9cc31b7dcfc9b5a593ae
BLAKE2b-256 checksum
How to use checksums
0ff5a7d019f8283ae0da26dc27427adc0834b1174cd4c786682d29cea3aed7fb
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.3.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.3.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.3.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