Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

8.8 KB
Raw Blame
---
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.">
      ![The macrod terminal with a device code and approval link in the Pair macrod panel](/images/macrod-pairing-example.png)
    </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).