Keys / Buildkite

BUILDKITE_AGENT_TOKEN

The agent token a self-hosted Buildkite agent registers with its cluster with.

Expires
never by default; or a date you choose
API
create, list, update and revoke, with an API access token

Get it

Create one on buildkite.com. The steps aren't recorded yet.

Set it

BUILDKITE_AGENT_TOKEN=...

The Buildkite agent reads it as its --token, and removes it from each job's environment. Or keep it out of .env with keypin: keypin run -- npm run dev

Replace it

  1. In Agents, open the cluster's Agent Tokens page and create a new token with the same allowed IP addresses, queue access and permissions.
  2. Deploy it everywhere that reads BUILDKITE_AGENT_TOKEN. Agents use it when they start.
  3. Check that no agent still starts with the old token, then revoke it. Revoking doesn't disconnect agents that are already connected.

Set rotate_every on the key in keypin.toml and a rotated date on its vault item, and keypin status shows when it's due.

Sources, checked 2026-11-16