Bring your own agent

Agents and machines

An agent is the name, instructions, and model you @mention. A machine is where that agent runs: in Macro, in Cursor, or on a computer of your own.

Create agents in Settings → Agents. Connect a machine in Settings → Machines.

Watch a 1:17 walkthrough of MacroD.

On the Macro desktop app

The desktop app bundles macrod, so there is nothing to download. Open Settings → Machines and use the This computer card. Set up looks for a coding agent already installed on your machine, then Set up that agent configures, pairs, and starts macrod and creates the agent. No terminal and no pairing code. Open Options to choose a different agent, set the Workspace folder, or turn on Full access. Keep the app open while agents run.

The manual macrod steps below are for machines without the desktop app (servers, a second computer), and both kinds of machine can be paired to the same account.

Macro daemon

Use your local coding agent from Macro. macrod runs on your computer, connects your agent to Macro, and keeps its sessions available from your workspace.

Run the Macro daemon (macrod) on your computer or server.

Before you start

You need a macOS, Linux, or Windows computer that can stay online and an installed, authenticated coding agent. macrod recognizes Claude Code, Codex, OpenCode, OpenClaw, and Hermes. You can also configure a custom command for an Agent Client Protocol (ACP) agent.

macrod connects out to Macro. You do not need a public webhook endpoint, port forwarding, or an HTTPS tunnel.

Connect your machine

Install macrod

Run the install command for your computer in a terminal:

macOS and Linux

curl -fsSL https://raw.githubusercontent.com/macro-inc/macro/main/crates/coding_agent_worker/install/install.sh | sh

This installs macrod to ~/.local/bin and adds that folder to your PATH in your shell's startup file (~/.zshrc, ~/.bashrc and ~/.bash_profile, or fish's conf.d), once. Open a new terminal afterwards. To leave your startup files alone, run curl -fsSL … | sh -s -- --no-modify-path or set MACROD_NO_MODIFY_PATH=1.

Windows

In PowerShell:

irm https://raw.githubusercontent.com/macro-inc/macro/main/crates/coding_agent_worker/install/install.ps1 | iex

This installs macrod.exe to %LOCALAPPDATA%\Programs\macrod and adds that folder to your user PATH. Open a new terminal afterwards.

You can also download the archive for your operating system and architecture from Macro releases and extract it.

Open Settings → Machines → New machine in Macro. The page walks you through installation, configuration, and pairing.

Run macrod

Open a terminal and run:

macrod

Keep the terminal open while you use your machine.

On first launch, Quickstart lists the agents available on your machine. Select one, or choose Custom command to enter an ACP launch command.

Set Workspace to the directory your agent should work in. Everything else about the machine is managed in Macro.

Select Create and pair to generate your device code.

Enter your pairing code

The Pair macrod panel shows a device code and a link to Macro. If you are already in the terminal overview, press p to open pairing. Press c to copy the code.

Open the pairing link, or go to Settings → Machines → New machine. Enter your code and click Look up.

The macrod terminal with a device code and approval link in the Pair macrod panel — Example only—enter the code from your own macrod terminal.

Check that the code and computer match your terminal, review the machine's settings, then click Approve.

macrod connects automatically after approval. It saves your agent, workspace, and credential in ~/.macrod/macrod.toml (%USERPROFILE%\.macrod\macrod.toml on Windows). Keep this file private; do not commit it to a repository.

Create an agent that uses your machine

This computer creates the agent for you. For a machine you paired from a terminal, open Settings → Agents and click Add agent.

In New agent, set the name, @tag, and instructions. Under Where it runs, choose In your harness and pick the machine under Harness. Under Who can use it, choose Private or Team, then save. @mention the agent to start a session on your machine. A Private agent can only be mentioned by you.

Keep your machine connected

Leave macrod running and your computer awake while you use the machine. Its terminal shows your sessions, configuration, and logs. You can also check the machine in Settings → Machines.

To reconnect later, run macrod again; it loads ~/.macrod/macrod.toml from any directory. If you remove the machine, pair it again before using it. Only one macrod can run with a given configuration at a time.

Update macrod

macrod updates itself. While it runs, it checks for a new release every hour, downloads it, and verifies its checksum and that it starts. Your macrod.toml and pairing are kept. If an update fails, macrod keeps running the current version and shows the error in its Logs tab.

macOS and Linux: macrod replaces itself in place as soon as no agent turn is running. Your agent keeps running through the update, so its sessions and anything it started stay alive.
Windows: the new version is installed next to the running one, and the footer shows Update … ready — restart macrod to use it. Quit macrod and start it again to use it. The macrod command always starts the newest installed version and removes older ones.

To see what the updater did, read ~/.macrod/logs/update.log (%USERPROFILE%\.macrod\logs\update.log on Windows). Each line is one JSON event: a check with the version found, a download with its size and whether the checksum matched, an apply with the versions and how the new one was started, and a startup line each time macrod starts, including after an update. The log never holds tokens or prompts. At about 1 MB it moves to update.log.1.

To update right away, run the install command again and restart macrod.

To install a specific release, set the MACROD_VERSION environment variable to its tag, such as v2026.10.18.0, before running the install command. A running macrod still updates itself to the latest release.

To turn automatic updates off, add this to macrod.toml:

[update]
auto = false

or start macrod with MACROD_NO_UPDATE=1 set. macrod then only changes when you run the install command again.

Troubleshooting

Your agent is missing from Quickstart: check that it is installed and its command is available in the terminal where you launch macrod. For a different ACP agent, use Custom command.
Your code is invalid or expired: start a new pairing from the terminal and enter the new code. The code in the screenshot is only an example.
Your machine is offline: check that your computer is awake, macrod is running, and it can reach Macro. Check the terminal's Logs tab for errors.
macrod says your config sets [identity] or a scope in [credentials]: delete those lines from ~/.macrod/macrod.toml. The machine's name, access, and permission bypass are set in Settings → Machines.
macrod asks you to pair again after an update: it reads only ~/.macrod/macrod.toml. If you started an older macrod from a project folder, move the macrod.toml from that folder to ~/.macrod/.

To learn more about using agents in your workspace, see Agents.