Quickstart: your agent's first click in 10 minutes

You need a Mac with Apple silicon and macOS 14 or newer, a Windows 10 or 11 PC, or a Linux computer; a Dyrra license key; and an AI agent that speaks MCP — Claude Code, Cursor, VS Code, Codex CLI, OpenClaw, Hermes or any other MCP client. The steps below are for a Mac; on Windows and Linux only step 2 differs.

1. Sign in — 1 minute

Open console.dyrra.dev, enter your email and open the sign-in link we send. Choose For myself. The first 10 active Macs a month are free; no card is needed.

2. Install Dyrra Agent — 2 minutes

Download the latest version, open the disk image and drag Dyrra Agent to Applications. Open it from Applications: it lives in the menu bar, there is no Dock icon.

On first launch, enter your 32-character license key. It arrives by email after you buy Dyrra — $14.99, paid once. One key covers one Mac, one Windows PC and one Linux computer.

The first launch asks for two macOS permissions — the agent can't see or click without them:

Screen Recording — to see the screen;
Accessibility — to click and type.

macOS may ask you to quit and reopen the app after the first one. That's normal.

On Windows

Windows 10 (version 2004 or later) or Windows 11 on x64. Download the installer and run it. Dyrra Agent lives in the notification area and updates itself. Enter your license key when it first opens.

On Linux

Ubuntu, Debian or Fedora on x64 or ARM64. Install from the Dyrra repository, so updates arrive with your system updates.

Ubuntu and Debian:

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://updates.dyrra.dev/linux/dyrra-archive-keyring.gpg -o /etc/apt/keyrings/dyrra.gpg
echo "deb [signed-by=/etc/apt/keyrings/dyrra.gpg] https://updates.dyrra.dev/linux/apt stable main" | sudo tee /etc/apt/sources.list.d/dyrra.list
sudo apt update && sudo apt install dyrra-agent

Fedora:

sudo curl -fsSL https://updates.dyrra.dev/linux/rpm/dyrra.repo -o /etc/yum.repos.d/dyrra.repo
sudo dnf install dyrra-agent

Then open Dyrra Agent from your applications menu and enter your license key. dyrra-agent status shows the connection state in a terminal.

3. Connect your Mac — 1 minute

In the console, My Macs → Connect. Dyrra Agent opens and asks what the agent may do on this Mac. Seeing the screen and using the mouse and keyboard are on by default; the terminal, files, clipboard and session recordings are off until you turn them on. Press Allow.

You can change this any time with Change permissions on the same page.

4. Connect your agent — 3 minutes

In the console, MCP configs → Create a key, pick your Mac and your agent, and copy the config. It already contains your key — the key is shown only once, so keep the config. Where each agent wants it is in Connect your agent below.

5. First click — 1 minute

Ask your agent:

Check my Mac with mac_status, then open Notes and type "Hello from my agent".

The agent looks at the screen tree first (mac_ui_tree), opens Notes and types. While it works, a thin frame goes around your screen. Press ⌃⌥⌘P any time to pause it.

When something doesn't work

What you see	What to do
`mac_status`: “the macOS Screen Recording permission is not granted”	System Settings → Privacy & Security → Screen & System Audio Recording → turn on Dyrra Agent, then quit and reopen it
Every action: “The Mac itself has no permission for this action”	The app was reinstalled or updated from 0.1.8 or older. Console → My Macs → Reconnect. Your agent's config stays the same
“The Dyrra app is not connected”	Open Dyrra Agent from Applications. The menu-bar icon shows the connection state
You granted the terminal, but the agent has no `mac_shell`	The tool list updates within a minute. If your client ignores list updates, restart it
“Dyrra's own interface is off limits to the agent”	That's on purpose: confirmations and the frame are for you, not the agent
“The user denied the confirmation”	Sending, paying and deleting wait for your OK on the Mac. Press Allow in the window that appears

Everything else: the API reference and sales@dyrra.dev.

Connect your agent

The console gives you each of these with your real key and Mac filled in. Here they are with placeholders.

Claude Code

Run in a terminal. --scope user makes Dyrra available in every project.

claude mcp add --env DYRRA_API_KEY=dk_live_… --env DYRRA_TARGET=con_… --scope user --transport stdio dyrra -- npx -y @dyrra/mcp

Cursor

Save as ~/.cursor/mcp.json, or merge into mcpServers if the file exists.

{
  "mcpServers": {
    "dyrra": {
      "command": "npx",
      "args": [
        "-y",
        "@dyrra/mcp"
      ],
      "env": {
        "DYRRA_API_KEY": "dk_live_…",
        "DYRRA_TARGET": "con_…"
      }
    }
  }
}

VS Code

Run in a terminal. Adds Dyrra to your VS Code user profile.

code --add-mcp '{"name":"dyrra","type":"stdio","command":"npx","args":["-y","@dyrra/mcp"],"env":{"DYRRA_API_KEY":"dk_live_…","DYRRA_TARGET":"con_…"}}'

OpenClaw

Run in a terminal. Saves Dyrra under mcp.servers in your OpenClaw config.

openclaw mcp set dyrra '{"command":"npx","args":["-y","@dyrra/mcp"],"env":{"DYRRA_API_KEY":"dk_live_…","DYRRA_TARGET":"con_…"}}'

Hermes

Add to ~/.hermes/config.yaml, then run /reload-mcp in Hermes.

mcp_servers:
  dyrra:
    command: "npx"
    args: ["-y", "@dyrra/mcp"]
    env:
      DYRRA_API_KEY: "dk_live_…"
      DYRRA_TARGET: "con_…"

Codex CLI

Run in a terminal. Codex saves it to ~/.codex/config.toml.

codex mcp add dyrra --env DYRRA_API_KEY=dk_live_… --env DYRRA_TARGET=con_… -- npx -y @dyrra/mcp

Gemini CLI

Merge into ~/.gemini/settings.json under mcpServers, then restart Gemini CLI.

{
  "mcpServers": {
    "dyrra": {
      "command": "npx",
      "args": [
        "-y",
        "@dyrra/mcp"
      ],
      "env": {
        "DYRRA_API_KEY": "dk_live_…",
        "DYRRA_TARGET": "con_…"
      }
    }
  }
}

GitHub Copilot CLI

Run in a terminal to add Dyrra to GitHub Copilot CLI. VS Code uses its separate setup tab.

copilot mcp add dyrra --env DYRRA_API_KEY=dk_live_… --env DYRRA_TARGET=con_… -- npx -y @dyrra/mcp

Cline

Cline: MCP Servers > Configure > Configure MCP Servers. Merge this JSON without replacing your existing servers.

{
  "mcpServers": {
    "dyrra": {
      "command": "npx",
      "args": [
        "-y",
        "@dyrra/mcp"
      ],
      "env": {
        "DYRRA_API_KEY": "dk_live_…",
        "DYRRA_TARGET": "con_…"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Kimi Code

Merge into ~/.kimi-code/mcp.json under mcpServers, then start a new Kimi Code session.

{
  "mcpServers": {
    "dyrra": {
      "command": "npx",
      "args": [
        "-y",
        "@dyrra/mcp"
      ],
      "env": {
        "DYRRA_API_KEY": "dk_live_…",
        "DYRRA_TARGET": "con_…"
      }
    }
  }
}

OpenCode

Merge into opencode.json (or your user config) under mcp, then restart OpenCode.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "dyrra": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@dyrra/mcp"
      ],
      "environment": {
        "DYRRA_API_KEY": "dk_live_…",
        "DYRRA_TARGET": "con_…"
      },
      "enabled": true
    }
  }
}

Ollama via Cline

In Cline, select Ollama as the provider and a tool-capable model. Then open MCP Servers > Configure > Configure MCP Servers and merge this JSON. Cline runs the tools; Ollama supplies the model.

{
  "mcpServers": {
    "dyrra": {
      "command": "npx",
      "args": [
        "-y",
        "@dyrra/mcp"
      ],
      "env": {
        "DYRRA_API_KEY": "dk_live_…",
        "DYRRA_TARGET": "con_…"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

MCP JSON

Any other MCP client: paste into its mcpServers config.

{
  "mcpServers": {
    "dyrra": {
      "command": "npx",
      "args": [
        "-y",
        "@dyrra/mcp"
      ],
      "env": {
        "DYRRA_API_KEY": "dk_live_…",
        "DYRRA_TARGET": "con_…"
      }
    }
  }
}