Bring your own agent
Connect a self-hosted ACP agent harness to Kuuumba with macrod.
Bring Your Own Agent will be available soon.
You can run any Agent Client Protocol (ACP)-compatible agent harness directly in Kuuumba.
Kuuumba provides macrod, a small daemon that runs on your computer and waits for agent sessions. When you start a session or @mention your custom agent, macrod launches your configured harness, sends it the prompt, and bridges its ACP connection to Kuuumba.
Self-hosted agents can run real commands on your computer. Anyone who can prompt the agent may be able to affect its configured workspace. Use a dedicated workspace and grant channel access carefully.
Before you start
You need:
- A machine that can keep an agent harness and
macrodrunning - 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.
Open Settings → Bots → Create bot. Enable Make this bot a coding agent, choose the channels it can join, and create it.
Copy the agent token when it appears. Kuuumba shows it only once, but you can create a new one later if you lose it.
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.
Open the latest Kuuumba release and download the macrod archive for your OS and architecture. Currently, we officially support macOS and Linux.
macrod listens on port 8790 and receives requests at POST /macro-events. Kuuumba must be able to reach that endpoint over public HTTPS.
For the Cloudflare quick tunnel described above, run:
```bash
cloudflared tunnel --url http://localhost:8790
```
Keep this process running and copy the URL it prints.
<div class="callout note"><span class="callout-icon"><svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg></span><div class="callout-body">
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.
Create macro.toml beside the macrod binary:
```toml
[macro]
api_url = "https://agent-harness.kuumba.dev"
storage_url = "https://storage.kuumba.dev"
owner_user_id = "macro|you@example.com"
bot_token = "mbot_..."
bot_scope = "user"
[server]
port = 8790
public_url = "https://example.trycloudflare.com/macro-events"
[harness]
command = "your-acp-agent"
args = []
[workspace]
path = "/absolute/path/to/your/repository"
repo_url = "https://github.com/you/your-repository"
```
Change `you@example.com` in `owner_user_id` to the email address you use to sign in to Kuuumba. Replace `mbot_...` with the token from the first step. Set `command` and `args` to the ACP launch command from the second step.
Keep the HTTPS tunnel running, then start macrod from a shell where your harness command is available:
```bash
./macrod --config ./macro.toml
```
When `macrod` reports that it is listening for agent triggers, @mention the agent in one of its Kuuumba channels.