Install the agent via the platform package manager (e.g., brew install buildkite/buildkite/buildkite-agent on macOS, or the Linux bash installer) and locate the configuration file at /etc/buildkite-agent/buildkite-agent.cfg
Set token to the agent token from your Buildkite cluster's agent token settings page; each cluster has its own token that scopes agent registration
Set tags (previously called metadata) to a comma-separated list of key=value pairs: tags="queue=linux-x86,env=production,docker=true" — the queue tag controls which pipeline steps dispatch to this agent
Start the agent with buildkite-agent start; multiple agents on one host can be started by running the command multiple times or setting spawn=N in the config to fork N workers
Target the agent in a pipeline step with agents: {queue: linux-x86, docker: 'true'} — all specified key=value pairs must match for the step to dispatch
Use Buildkite Clusters (Organization Settings > Clusters) to group agents and restrict which pipelines can use each cluster's agents for multi-tenant isolation
Known gotchas
The legacy unclustered (default) queue and Clusters-based queues are separate routing systems; agents registered with a cluster token do not receive jobs from the unclustered queue and vice versa
Tags are matched with AND logic — if you specify multiple tags in a step's agents block, the agent must have all of them; a missing tag leaves the step queued forever
Buildkite agent v3 introduced the spawn option; earlier versions required running multiple agent processes manually via systemd template units or launchd plists
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp