Oatmeal

Oatmeal is a single binary tray application that extends your web agent's capabilities via an MCP server with browser automation, Bash, Python, and other automation utilities.

• Quick Start
• Configuration
• Command Mode
• Exporting Files from Command Mode
• MCP Tools
• CLI Equivalents
• URI Launch Mode
• Platform Notes

Quick Start

Oatmeal is meant to be used with its complementary barebones React component: Storybook here. Build on top of this foundation to create your own custom agent interfaces, or use the MCP server directly in your agents without a UI.

Download the latest binary from releases:

• Linux: oatmeal-linux
• macOS: oatmeal-mac
• Windows: oatmeal-windows.exe

Run it:

# Linux/macOS
chmod +x ./oatmeal-*
./oatmeal-*

# Windows
.\oatmeal-windows.exe

By default, Oatmeal starts an MCP server on http://localhost:9607/mcp.

macOS note:

xattr -d com.apple.quarantine ./oatmeal-mac

Windows note:

You may need to allow the binary through SmartScreen or Windows Defender the first time you run it.

Configuration

Oatmeal works without configuration. Default behavior:

• Host: 0.0.0.0
• Port: 9607
• Browser path: auto-detected
• Page-agent model: qwen3.5-plus
• Page-agent URL: http://localhost:11434/v1
• Page-agent key: NA

Optional config sources:

• ~/.oatmeal
• ./.oatmeal
• OATMEAL_* environment variables
• CLI flags

Example config:

port = 9607
host = "0.0.0.0"
browser_path = "/path/to/browser"

[page_agent]
model = "qwen3.5-plus"
url = "http://localhost:11434/v1"
key = "NA"

Nested page-agent environment variables use double underscores:

• OATMEAL_PAGE_AGENT__MODEL
• OATMEAL_PAGE_AGENT__URL
• OATMEAL_PAGE_AGENT__KEY

Precedence is:

built-in defaults -> ~/.oatmeal -> ./.oatmeal -> OATMEAL_* -> CLI flags

Command Mode

Use --command when you want to run a shell-style script instead of starting the MCP server.

Inside command mode, both agent-browser and the shorter ab alias are available.

Examples:

./oatmeal-* --command "agent-browser open https://example.com"
./oatmeal-* --command "ab open https://example.com"
./oatmeal-* --command "ab --headed open https://example.com"
./oatmeal-* --command "name=world && echo hello-$name > /report.txt"
./oatmeal-* --command "python3 -c \"print(2 ** 10)\""

Synthetic browser helpers are also supported:

./oatmeal-* --command "ab agentic-open https://example.com"
./oatmeal-* --command "ab agentic-prompt https://example.com 'summarize this page'"
./oatmeal-* --command "ab agentic-prompt 'find the primary CTA on the current page'"

Exporting Files from Command Mode

Oatmeal detects files created during command execution with a best-effort algorithm and captures them into MCP resources automatically.

MCP Tools

When Oatmeal is running as an MCP server, it exposes these tools:

• health
• version
• cache_directory
• screenshot_system
• shell_command
• delete_resource
• delete_all_resources
• uri_scheme
• shutdown

User-facing behavior:

• shell_command runs the same script surface as CLI --command
• files generated by MCP command execution are returned as MCP resources
• cache_directory returns the cache folder used by Oatmeal, agents can use this to pass to agent-browser for file downloads
• screenshot_system captures all attached monitors as image resources
• delete_resource and delete_all_resources clean up generated resources from the current server

CLI Equivalents

Standalone CLI flags expose the same functionality as the corresponding MCP tools:

URI Launch Mode

Oatmeal supports an oatmeal:// URI handler.

You can register or remove it explicitly:

./oatmeal-* --register-uri
./oatmeal-* --unregister-uri

When Oatmeal starts in default HTTP mode, it will register the URI handler automatically if needed.

Example URIs:

• oatmeal://open?port=9911
• oatmeal://open?port=9911&host=127.0.0.1

Platform Notes

• Linux: x86_64 + aarch64
• macOS: universal binary
• Windows: 64-bit executable