Skip to main content
Bring Your Own Agent will be available soon.
You can run any Agent Client Protocol (ACP)-compatible agent harness directly in Macro. Macro provides macrod, a small daemon that runs on your computer and waits for agent sessions. When you @mention an agent that runs on your harness, macrod launches your configured harness, sends it the prompt, and bridges its ACP connection to Macro. A harness can be private (only you can run agents on it) or team (any teammate can create agents that run on it).
Self-hosted agents can run real commands on your computer. Anyone who can prompt an agent bound to your harness may be able to affect its configured workspace. Use a dedicated workspace, grant channel access carefully, and think twice before sharing a harness with your team.

​
Before you start

You need:
  • A machine that can keep an agent harness and macrod running
  • An ACP-compatible harness installed and configured on that machine
  • A public HTTPS endpoint that forwards webhooks (in this demo, to port 8790)
Cloudflare Tunnel can provide the HTTPS endpoint needed to receive webhooks without opening a router port. To use it, install cloudflared and run cloudflared tunnel --url http://localhost:8790. Then copy the temporary https://....trycloudflare.com URL and append /macro-events for the public_url below.
1

Prepare an agent harness

Install your preferred ACP-compatible agent and identify the command that starts its ACP server. Verify that command before configuring macrod.These harnesses provide ACP entrypoints:
  • Claude Code: npx -y @agentclientprotocol/claude-agent-acp
  • Codex: npx -y @agentclientprotocol/codex-acp
  • Hermes: hermes-acp (run hermes-acp --check first)
  • OpenCode: opencode acp
  • OpenClaw: openclaw acp
Claude Code and Codex require their linked adapter packages because the base claude and codex commands do not expose ACP servers directly.
2

Download macrod

Open the latest Macro release and download the macrod archive for your OS and architecture. Currently, we officially support macOS and Linux.
3

Start the HTTPS tunnel

macrod listens on port 8790 and receives requests at POST /macro-events. Macro must be able to reach that endpoint over public HTTPS.For the Cloudflare quick tunnel described above, run:
Keep this process running and copy the URL it prints.
A quick-tunnel URL changes whenever cloudflared restarts. Create a named Cloudflare tunnel for a stable endpoint.
Alternatively, you can port-forward or deploy your harness to a cloud server.
4

Configure macrod

Create macro.toml beside the macrod binary. No tokens or account details go here - identity comes from pairing in the next step.
Set command and args to the ACP launch command from the first step.
5

Pair the daemon

Start macrod from a shell where your harness command is available:
On first run it prints a pairing code and a link into Macro’s Settings → Harness page. Open the link, confirm the code matches, choose Private or Team, and approve. macrod picks the credential up automatically and saves it to macro.credentials.json next to the config.To pair again later (for example after revoking the harness), run ./macrod login.
6

Create an agent on your harness

Open Settings → Agents → New agent and pick your harness under Harness. If the harness is shared with your team, teammates can do the same.Then @mention the agent in a channel it can reach. macrod opens the session and your local harness answers.

​
Keep it connected

Both macrod and your HTTPS tunnel must stay running for you to start self-hosted agent sessions from Macro. The Settings → Harness page shows whether your daemon is currently connected. To stop a harness for good, remove it from Settings → Harness; that revokes its credential, and the daemon will tell you to run macrod login if you start it again.