03 — The agent runner

What you will have at the end: a trigger that fires and actually starts an agent, without you typing anything.

What you need: tutorial 02 finished, Claude Code 2.1.259 or newer installed, and a brain with at least one agent in its brain-config.yaml, the file tutorial 04 walks through.

Why this exists

Connecting a client lets an agent reach the brain. It does not let the brain reach the agent.

When a trigger fires, something has to start a Claude Code session on your machine. Nothing in the browser can do that. The agent runner is that something: a small program that stays connected to your brain, listens for work arriving, and starts the right agent when it does.

Until it is running, a trigger can fire and nothing will happen.

Where it has to live

On the machine where the agents work, next to the repository they work on.

The runner starts Claude Code in a directory, so that directory has to be the one holding the code. A laptop is fine if you are working alongside the agent. Use a machine that stays on if the brain should react overnight.

1. Install it

On macOS and Linux:

curl -fsSL https://www.markdown-den.com/install.sh | sh

On Windows:

irm https://www.markdown-den.com/install.ps1 | iex

Both download the build for your machine from the latest release, check it against the published checksums.txt, put mdbrain on your PATH, and then tell you what else the machine is missing — including whether Claude Code is there and new enough. Neither asks for a password.

Check what arrived:

mdbrain --version
mdbrain --help

2. Sign in

mdbrain login

This opens your browser on markdown-den's own sign-in page and signs you in as yourself, with the same account you use in the app. The page hands the session back to the command on a loopback port; the password never goes through the terminal.

It asks for no agent key and picks no brain. Signing in is how the runner is allowed to ask what agents you have — which agents this machine runs, and what they may cost, is the next command's business.

3. Configure it

mdbrain configure

This has to be done before the first run. It reads your agent roster live and asks, on one screen:

• Which of your agents this machine runs. You can pick several. For each one it asks the server for that agent's connection key and stores it in your OS keychain — or, where there is none, in a 0600 file, and it says which. You do not paste the key from tutorial 02; the runner obtains its own.
• Which of them this runner asks for work. An agent you keep for talking to yourself does not have to be woken.
• Where each agent runs — the directory the harness starts in, which for a coding agent is its checkout.
• What pays for each agent's thinking — this machine's own Claude Code account, or an API key held in an environment variable you name.
• Three caps on a triggered session — the most turns it may take, the most dollars it may spend, and the longest it may run.
• A ceiling on sessions an hour, per agent. Blank keeps the server's ceiling of ten; a brain may lower it and never raise it.

It writes config.json and one MCP file per agent beside it. No secret is in that file: every credential field holds the name of an environment variable, so the file is safe to copy between machines.

These are properties of the machine rather than of the brain, which is why they live here and not in brain-config.yaml. One runner serves every agent you gave it — four agents on one machine is one mdbrain run, not four.

4. Start it

mdbrain run

It does not matter which directory you start it from: each agent is started in the directory you named for it in configure.

It holds a connection open to each of your brains and listens. When a trigger fires and there is something for one of its agents, it starts a Claude Code session within seconds, hands it the trigger's prompt, and waits for that agent's session to finish before starting another for the same agent. A poll every forty-five minutes sits underneath as a backstop, so work still arrives if the connection is down — the connection is what makes it prompt, not what makes it work at all.

Leave it running. There is a live view of what it is doing while it runs.

5. Check it works

In the brain, add a trigger to brain-config.yaml:

version: 1

agents:
  helper-bot: editor

triggers:
  - kind: file-arrived
    label: Something lands in inbox
    folder: inbox
    agent: helper-bot
    prompt: Read what landed at {path} and write one sentence about it on a comment thread.

Create the inbox folder and drop a document in it. The runner should start a session within a few seconds, and the agent's comment should appear on the document.

If nothing happens, work down this list:

• Is the runner actually running, and is helper-bot one of the agents you chose in configure — and marked as one that asks for work?
• Does the trigger name an agent the roster declares? A trigger naming an agent that is not in agents: never fires.
• Is the folder path in the trigger the real path in the tree?
• Does the agent have a role in this brain, from tutorial 02 step 2?

Keeping it running

Nothing here survives a reboot. mdbrain installs no service and registers no startup item, so a machine that restarts comes back with no runner on it until you start one.

Leaving mdbrain run up in a terminal is the simple answer. Where the brain has to react without you, put it under whatever already supervises long-running things on that machine. mdbrain run --once runs a single tick, waits for whatever it started, and exits, which is the shape to reach for under cron or a systemd timer. It exits 1 if any session it started did not finish cleanly, so an alert wired to it answers did every session succeed, not is the runner up.

Keeping it current

mdbrain upgrade

It resolves the latest release at run time, so it finds new versions without being told about them. A running mdbrain run also notices when a newer version exists and says so.

What you have now

A file arriving in a folder wakes an agent, which does the work and writes the result back into the brain.