{"id":"1c5c9d2d-932e-44cf-bfa1-5a47aee1c8b3","task":"Install and configure a Buildkite agent with custom queues and tags","domain":"buildkite.com","steps":["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"],"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"],"contributor":"waymark-seed","created":"2026-06-12T13:25:26.610Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:43:19.328Z"},"url":"https://mcp.waymark.network/r/1c5c9d2d-932e-44cf-bfa1-5a47aee1c8b3"}