Install and connect

This page is for the human setting up the project. The agent will use mdBoard; you need to install it and give the agent a stable contract.

Requirements

• Git on PATH.
• mdBoard on PATH for the agent.
• A coding agent that can run terminal commands in the repository.
• Linux or macOS for the full workflow. Windows is not yet tested.

Install mdBoard

Release binary

Download the archive for your platform from GitHub Releases, verify SHA256SUMS, and put mdboard on PATH.

Build from source

git clone https://github.com/mdboard-io/mdboard.git
cd mdboard
cargo build --release -p mdboard-cli
install -m 755 target/release/mdboard "$HOME/.local/bin/mdboard"
export PATH="$HOME/.local/bin:$PATH"
mdboard --version

Docker

docker pull mdboard/mdboard:latest
docker run --rm -v "$PWD:/workspace" mdboard/mdboard:latest --version

The container runs as a non-root user. Mount the repository at /workspace.

Create the board

From the root of an existing Git repository:

mdboard init

init asks for:

The roadmap limit is an option: --roadmap-limit (default 5).

You can keep the default cost model and later ask the agent to look up current pricing for the model and subscription you use. See Estimation and cost.

For automation:

mdboard init --upstream main \
  --roadmap-limit 5 \
  --subscription "DeepSeek-V4.1-Flash (off-peak)" \
  --eur-per-million-tokens 0.21

init writes:

• mdboard.toml — branches, limits, approval mode, meeting cadence and cost model;
• .mdboard/actors.toml — the human and agent actors;
• .mdboard/cards/, .mdboard/events/, .mdboard/meetings/, .mdboard/reviews/, .mdboard/reports/;
• BOARD.md and ROADMAP.md, generated from the initial board;
• a short AGENTS.md that points to mdboard runbook.

Commit the initialized board before you start a iteration.

Set up the humans and the agent

.mdboard/actors.toml starts with:

[actors.owner]
kind = "human"
display_name = "Owner"
roles = ["owner"]

[actors.member]
kind = "human"
display_name = "Product member"
roles = ["member"]

[actors.agent]
kind = "agent"
display_name = "Coding agent"
roles = ["agent"]

• owner — final authority: accept ideas, accept batches, override the roadmap limit, merge and release.
• member — spark, refine, pitch, review and attend the consortium.
• agent — the one writer that operates mdBoard and implements batches.

Add more members if the consortium has more humans. Do not add a second concurrent agent writer to the same upstream iteration.

Connect the agent

Give the agent a short onboarding instruction:

Read AGENTS.md, then run `mdboard runbook` and `mdboard context`.
You are the agent for this repository. Follow the runbook.
You never self-approve, never merge, and never change state without the
authorisation the runbook requires. Introduce yourself and brief me.

The agent should read the runbook every session. The runbook is stable across installations; AGENTS.md only points to it.

Verify

Ask the agent to report:

Agent: mdBoard is installed. Upstream iteration is not open yet.
          Roadmap: 0 of 5. No pending meetings. No active batch.
          I can start a iteration or help you spark an idea.

Humans can also check the shared view with mdboard serve --actor owner and the printed login URL. The HTML board reads the new process records; human review, consortium decisions and meeting actions happen there.

Start a iteration

The agent opens the working iteration:

Human: Start the upstream iteration.
Agent: I opened iteration 1 from nightly and took the writer lease.
          The board is ready for a spark.

Behind the scenes, mdboard upstream start records the iteration, its base commit and the writer lease in .mdboard/upstream.md.

Trust boundary

Chat-only authorisation is an audit convention, not cryptographic proof. mdBoard records the human statement and authoriser, but a misbehaving agent with write access could forge an event. The Security page explains what the model does and does not guarantee.

Next

• Your first conversation
• The runbook
• Roles and authority
• Configuration