# Deploy ModernCI with your agent

> The canonical runbook an agent follows to set up ModernCI on a repository, with a check command and expected output for every step.

This is the runbook an agent follows to set up ModernCI on a repository. Do the steps in order. Run each check command and compare it to the expected output before you go on. If a check fails, stop and report it; do not continue.

## 1. Install the daemon (preview)

Start the daemon. The Docker image is a preview: it is in use on our own repos, and the self-host release is not out yet, so follow the changelog.

```
docker run -d --name modernci -p 7700:7700 -v modernci:/data modernci/modernci daemon
```

Check: `modernci daemon status`

Expected: The Alarms page prints with no alarm firing.

## 2. Register the repo

Give the daemon the repo. The forge token is given once, at this step.

```
modernci repo add you/your-repo
```

Check: `modernci repo list`

Expected: you/your-repo is listed.

## 3. Import the Actions workflow

Convert the existing GitHub Actions workflow into a branch file, one per target branch.

```
modernci import .github/workflows/ci.yml
```

Check: `cat .ci/<branch>.yaml`

Expected: The file exists and starts with a to: key, followed by checks: and on_green:.

## 4. Open the .ci/ pull request

Commit the branch file on a new branch and open a pull request with your forge's usual tool. Branch files are read from the target commit, so they take effect only after this pull request merges. Do not merge it yourself: it needs a person.

Check: Look at the pull request's file list on the forge.

Expected: It is open and changes only files under .ci/.

## 5. Join this machine

Join the machine as a backend, an agent host, or both. A person mints a one-time token in the daemon's Settings; ask for it.

```
modernci host join http://<daemon>:7700 --token <token>
```

Check: `modernci host status`

Expected: This host is listed and ready.

## 6. Connect your agent runtime over MCP

Add the daemon's MCP endpoint to the agent runtime's MCP configuration. Agents use four tools: done, claim, report and ask. The exact file and shape depend on the runtime; this is the common shape.

```json
{
  "mcpServers": {
    "modernci": {
      "type": "http",
      "url": "https://<your-daemon>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}
```

Replace <your-daemon> with your daemon's host, and <token> with a token a person gives you. The server speaks Streamable HTTP with an OAuth bearer token.

Check: Ask the runtime to list its MCP tools.

Expected: done, claim, report and ask are listed under modernci.

## 7. Run the first move in shadow

Judge one real branch beside the old CI without opening a pull request. Compare the verdict with what Actions said about the same commit.

```
modernci ci --from <branch> --no-pr
```

Check: `modernci daemon status`

Expected: The move shows a verdict, green or red, with its evidence (logs, test counts, stamps). The verdict agrees with the old CI's, or you can say why not.

## 8. Report what you did

Tell the person what happened. Include the output of the checks above, the verdict from the shadow move and whether it agreed with the old CI, and the usage record export.

```
modernci daemon usage
```

Check: none.

Expected: Usage records print for the shadow move; they are the source of cost per merged change.

## Example agent prompt

```
Set up ModernCI on this repo: read https://modernci.dev/docs/agents.md and follow it step by step. Run each check and stop if one fails. Use shadow mode only, and do not merge the .ci/ pull request. When you are done, tell me what you ran, what each check printed, and whether the first verdict agreed with our existing CI.
```

See also: [Get started](https://modernci.dev/get-started.md), [Docs](https://modernci.dev/docs.md), [llms.txt](https://modernci.dev/llms.txt).