Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
---
title: "Bring your own agent"
sidebarTitle: "Bring your own agent"
icon: "terminal"
description: "Bring Claude Code, Codex, or another local agent into your Macro workspace with macrod."
---
## Agents and runtimes
An **agent** is the name, instructions, and model you @mention. A **runtime** is where that agent runs: in Macro, in Cursor, or on your own machine.
Create agents in **Settings → Agents**. Connect a machine in **Settings → Runtimes**.
## On the Macro desktop app
The desktop app bundles `macrod`, so there is nothing to download. Open **Settings → Runtimes** 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 the runtime 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 runtime 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.
<Info>
Macro Daemon is for advanced users that want to connect agents running in your terminal. For example, if you run Claude Code on your server.
</Info>
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.
<Warning>
Your local agent can run commands and edit files on your computer. Choose a dedicated workspace and review access before sharing a runtime with your team. Leave permission bypass off unless you intend to allow actions without approval.
</Warning>
## Connect your runtime
<Steps>
<Step title="Install macrod">
Run the install command for your computer in a terminal:
<Tabs>
<Tab title="macOS and Linux">
```bash
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`.
</Tab>
<Tab title="Windows">
In PowerShell:
```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.
</Tab>
</Tabs>
You can also download the archive for your operating system and architecture from [Macro releases](https://github.com/macro-inc/macro/releases) and extract it.
Open **Settings → Runtimes → New runtime** in Macro. The page walks you through installation, configuration, and pairing.
</Step>
<Step title="Run macrod">
Open a terminal and run:
```bash
macrod
```
Keep the terminal open while you use your runtime.
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 runtime is managed in Macro.
Select **Create and pair** to generate your device code.
<Note>
Claude Code and Codex use ACP adapters, which `macrod` installs with `npm` the first time you select them. Their presets require the agent's command and `npm` to be available in the shell where you start `macrod`. On Windows, Claude Code works from either its native installer or `npm install -g @anthropic-ai/claude-code`.
</Note>
</Step>
<Step title="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 <kbd>p</kbd> to open pairing. Press <kbd>c</kbd> to copy the code.
Open the pairing link, or go to **Settings → Runtimes → New runtime**. Enter your code and click **Look up**.
<Frame caption="Example only—enter the code from your own macrod terminal.">

</Frame>
Check that the code and computer match your terminal, review the runtime'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.
</Step>
</Steps>
## Create an agent that uses your runtime
**This computer** creates the agent for you. For a runtime 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 runtime connected
Leave `macrod` running and your computer awake while you use the runtime. Its terminal shows your sessions, configuration, and logs. You can also check the runtime in **Settings → Runtimes**.
To reconnect later, run `macrod` again; it loads `~/.macrod/macrod.toml` from any directory. If you revoke the runtime, 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`:
```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 runtime 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 runtime's name, access, and permission bypass are set in **Settings → Runtimes**.
- **`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](/product/agents).