Quick start

This page walks through the minimal steps to get the donmai daemon running and dispatch an agent session against a Linear backlog.

Install

brew tap RenseiAI/homebrew-tap
brew install donmai

Configure the daemon

Run the interactive setup wizard. It writes ~/.donmai/daemon.yaml:

donmai daemon setup

The wizard walks five steps:

Machine identity - a machine ID (auto-generated default) and an optional region hint
Capacity - cores and memory reserved for the system, and the max concurrent sessions
Orchestrator - where work assignments come from. Pick a remote orchestrator (a hosted platform endpoint if your org runs one, or your own self-hosted orchestrator; you supply the URL and a registration token, via DONMAI_DAEMON_TOKEN or at the prompt) or the local file queue (single-user) option for solo use, which needs no URL and no token
Project allowlist - which repositories this machine is allowed to run sessions for (the wizard offers the current directory's git remote)
Auto-update - channel, schedule, and drain timeout

You can also edit ~/.donmai/daemon.yaml directly. See the full configuration reference.

Install the daemon service

donmai daemon install

This registers a launchd service (macOS) or systemd unit (Linux) that keeps the daemon running across reboots.

donmai daemon status

Example output (field shapes match the binary's donmai daemon status table; values are illustrative):

  Daemon:     ready
  Machine:    demo-host
  Version:    0.38.2
  PID:        42531
  Uptime:     6s
  Sessions:   0 / 8
  Projects:   1 allowed
  Timestamp:  2026-06-11T01:42:01Z

Dispatch agents

Use the built-in orchestrator to pick up Linear issues and dispatch agents:

# Process the backlog for a Linear project
donmai orchestrator --project MyProjectName

# Process a single known issue
donmai orchestrator --single PROJ-123

Agents run inside the daemon's session pool. Watch activity in real time:

# Live fleet status
donmai status

# List running sessions
donmai agent list

# Tail logs
donmai daemon logs

Stop the daemon

# Drain active sessions first, then stop
donmai daemon drain

# Or stop immediately
donmai daemon stop

Next steps

Configuration reference - full daemon.yaml key reference and environment variables
Plugins overview - extend agent tool sets with ToolPlugin packages
Workflow node contracts - ActionDefinition, TriggerDefinition, and workflow YAML grammar