TutorialsDocsmarkdownbrain.ai

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.

The runner is open source, under the MIT licence. Its code is at github.com/dguridi/mdbrain, published there with every release, so you can read exactly what will run on your machine before you install it.

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://markdownbrain.ai/install.sh | sh

On Windows:

irm https://markdownbrain.ai/install.ps1 | iex

Both download the build for your machine from the latest release, check it against the published checksums.txt, put mdbrain in a directory on your PATH (on macOS and Linux it prints the line to add if that directory is not on it yet), 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 markdownbrain.ai'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, one question at a time:

  • Which of your agents this machine runs. You can pick several. Only agents in an organization you own are offered, and it says how many it left out. 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: mdbrain as <agent> starts a session as any configured agent, with you driving it.
  • 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.
  • A ceiling on sessions an hour, asked once, last, and applied to each agent. Blank keeps the server's ceiling of ten; a brain may lower it and never raise it.

[screenshot: runner-configure-agents.png — the first question mdbrain configure asks: every agent in your organizations as a list, moved through with the arrow keys and marked with space]

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. The keys stay behind in this machine's keychain, so run mdbrain configure once on the new machine and it fetches its own.

It asks nothing about limits. A triggered session has no budget and no time limit unless you set one, and mdbrain run says so once when a session with no time limit passes two hours. Run mdbrain configure again and it opens on a menu of your agents instead of asking everything over: Enter on an agent opens its settings, Limits among them, a budget in dollars and a time limit such as 2h, each blank for none. e in mdbrain agents opens the same menu at the agent you picked.

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 its work is ready for one of its agents, it starts a Claude Code session within seconds of that, 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. In a terminal it draws a live view of what it is doing: p polls now, and q or Ctrl-C stops it. Under a service manager, or with its output going to a file, it prints plain lines instead.

[screenshot: runner-live-view.png — the live view of mdbrain run: three agents, one of them working on a file that just arrived in inbox, the two runs that finished earlier with their time and cost, the connection light, and the countdown to the next catch-up sweep]

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 about a minute later, and the agent's comment should appear on the document. A new file is held back until it has gone a minute without changing (five minutes at most), so an agent is never handed a document that is still being written. A changed file and a mention wait the same way.

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 helper-bot's key work on this machine? mdbrain agents check helper-bot presents it to the server and says whether it was accepted and in which brains, or why it was refused, and the command that fixes it where there is one.
  • 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.