Distillation Labs

Distillation Labs / Agentyc / Documentation

Agentyc docs

Installation, shared-browser setup, state handling, deterministic extraction, and debugging guidance for running Agentyc as a browser MCP runtime in real developer workflows.

Product page GitHub ↗

Overview

Agentyc is a deterministic browser MCP runtime for coding agents. It exposes a public stdio MCP server, talks to Chrome or Chromium over CDP, and returns compact browser state with stable refs so agents can inspect and act without depending on brittle selectors or full-DOM dumps.

The product story is intentionally narrow: browser automation for coding agents, not an autonomous agent framework. It does not rely on an LLM fallback in the default browser runtime, and it keeps core workflows local-first by default.

Without Agentyc

Agents read large DOM payloads, reconstruct selectors repeatedly, and lose time debugging browser behavior through indirect abstractions.

With Agentyc

Agents inspect compact state, target stable refs, wait on real network activity, and debug the live browser from one deterministic MCP surface.

Installation

The default path is simple: install with `uv`, run `agentyc`, then point your MCP-capable coding agent at the local command. No API key is required for the default browser runtime. 

uv tool install agentyc
agentyc
agentyc init

Compatibility

  • Python 3.11 or newer
  • Local Chrome or Chromium, or an existing browser exposed over CDP
  • stdio MCP runtime with direct CDP browser control
  • No Playwright dependency in the public browser path

Quickstart

01

Install

uv tool install agentyc

02

Run the MCP server

agentyc

03

Register the server

claude mcp add agentyc -- agentyc

04

Inspect the page

browser_get_state(mode="min")

Client configuration

Claude Code

claude mcp add agentyc -- agentyc

Claude Desktop / Cursor / Windsurf

{
  "mcpServers": {
    "agentyc": {
      "command": "agentyc"
    }
  }
}

OpenCode

{
  "mcp": {
    "agentyc": {
      "type": "local",
      "command": ["agentyc"]
    }
  }
}

Shared browser

Agentyc supports a shared-browser model for parallel agent work. A primary agent launches one browser, then additional runtimes attach to the same browser profile and automatically claim their own collaboration tab. 

agentyc browser --port 9222 --detach
agentyc mcp --reuse-local-browser --runtime-label "Agent-1"
agentyc mcp --cdp-url ws://127.0.0.1:9222/devtools/browser/... --runtime-label "Agent-2"

Operational model

  • Each runtime gets its own owned tab by default
  • Cookies and local storage stay shared with the browser profile
  • State snapshots, refs, and logs stay scoped to the owned tab
  • `browser_new_tab` is the right next step when one runtime needs another surface

State and refs

Primary primitive

`browser_get_state` returns structured browser state instead of a raw DOM dump.

Stable refs

Interactive elements get refs like `e123`, which are the preferred targeting contract.

Compact modes

Start with `mode="min"` and escalate only when compact state omitted something you need.

Since hash

Use `since_hash` for follow-up polling so unchanged pages return metadata only.

Deterministic extraction

`browser_extract_content` stays deterministic in the public MCP runtime. When the query matches a supported route, Agentyc can extract links, link collections, images, tables, lists, form fields, or key-value panels without handing the page to an LLM.

Good queries

  • `table rows`
  • `all links`
  • `form fields`
  • `key value pairs`

Observability and debugging

  1. Step 01

    Read browser console output through `browser_get_console_logs()`.

  2. Step 02

    Inspect recent traffic with `browser_get_network_log()`.

  3. Step 03

    Wait for one precise request or response before continuing.

  4. Step 04

    Inspect or replay one captured request when an app is API-heavy.

  5. Step 05

    Apply narrow mocks or throttling per tab instead of faking the whole browser.

  6. Step 06

    Export one debug bundle with state, logs, network, trace summary, and optional screenshot.

  7. Step 07

    Use `browser_set_intent` and the optional HUD surfaces for short operator-facing progress labels.

  8. Step 08

    Capture traces when browser performance itself is the debugging target.

Configuration

The public runtime mainly reads `AGENTYC_` environment variables. The defaults are intentionally practical for local browser automation, while CI and shared-browser setups usually add explicit headless or reuse settings.

Variable Example Purpose
AGENTYC_HEADLESS false Run the browser headless when you need CI or background automation.
AGENTYC_ALLOWED_DOMAINS example.com,*.example.org Restrict navigation to an allowlist when you want tighter runtime safety.
AGENTYC_REUSE_LOCAL_BROWSER 1 Auto-attach to the latest locally launched Agentyc browser without copying a CDP URL.
AGENTYC_ACTION_TIMEOUT_S 180 Per-action timeout enforced by the runtime for browser operations.
AGENTYC_HUD_OVERLAY 1 Mirror sanitized runtime activity in the optional desktop HUD window.
AGENTYC_LOGGING_LEVEL info Set Agentyc logging verbosity for local debugging and support.

Tool reference

Agentyc ships 66 MCP tools. These are the ones developers usually reach for first when wiring a coding agent into real browser work.

Start here

browser_get_state(mode="min")

Primary browser inspection primitive. Returns compact page state with stable refs.

browser_navigate(url="https://example.com")

Navigate to a URL, optionally in a new tab.

browser_wait_for_stable_dom()

Let client-rendered pages settle before you inspect or act again.

browser_search_page(pattern="pricing")

Search long pages without manually scrolling or dumping the whole document.

Interaction

browser_click(ref="e123")

Click by stable ref, index, or coordinates.

browser_type(ref="e145", text="hello")

Clear and type into a field.

browser_select_option(ref="e212", text="Enterprise")

Pick a select option by visible label.

browser_new_tab(url="https://example.com")

Open a new working surface without disturbing another runtime.

Debugging & extraction

browser_extract_content(query="table rows")

Deterministically extract common page structures without LLM fallback.

browser_wait_for_response(url_substring="/api", status=200)

Synchronize precisely against API activity.

browser_inspect_network_entry(url_substring="/api/orders")

Inspect one request or response, including bodies when needed.

browser_export_debug_bundle(include_screenshot=true)

Return a compact artifact with state, logs, network, trace summary, and optional screenshot.

Benchmarks

Import time

194.4 ms

Cold session init

1027.4 ms

Average tool latency

43.3 ms

P95 tool latency

161.6 ms

Screenshot reduction

8.3× smaller

Tool surface

66 MCP tools

Troubleshooting

Command not found after install

Verify `uv tool install agentyc` completed and that your uv tool bin directory is on `PATH`. If needed, run the server from an activated environment instead.

Agent loses refs after a re-render

Call `browser_get_state()` again and use the fresh `e123` refs. Stable refs survive normal re-renders, but a changed DOM still means you should re-read state before retrying.

Need multiple agents in the same authenticated browser

Start one shared browser with `agentyc browser --port 9222 --detach`, then attach additional runtimes with `agentyc mcp --reuse-local-browser` or `--cdp-url ...`.

Need browser debugging data after a failure

Use `browser_export_debug_bundle()` for a compact state-plus-logs artifact, or wait for a precise request and inspect it with `browser_inspect_network_entry()`.