Where Does the Buildkite Agent Store Config?
The Buildkite agent keeps its config, hooks, and build checkouts together: ~/.buildkite-agent for user installs, /etc/buildkite-agent for packages.
Last updated
The Buildkite agent is pleasantly self-contained: config, hooks, and build checkouts live side by side. The cfg file holds the token and agent settings, the hooks folder holds lifecycle scripts, and the builds folder holds the checkouts those scripts operate on.
Install method decides the root. A manual download uses a folder in the user's home; the system package uses /etc on Linux and C:\buildkite-agent on Windows. Hooks need execute bits on Unix, and the agent user must own the tree, or jobs fail in confusing ways.
Where Buildkite stores this, by platform
~/.buildkite-agent/buildkite-agent.cfg
Config, hooks, and builds side by side. Package installs use /etc/buildkite-agent/buildkite-agent.cfg instead. Systemd logs go to the journal; bare buildkite-agent start only logs to stdout.
C:\buildkite-agent\buildkite-agent.cfg
Same trio of config, hooks, and builds under one root. Lock down the folder permissions: the agent executes hook scripts and repository code, so multi-user machines deserve care here.
Frequently asked questions
Which config file does my agent read?
User installs use ~/.buildkite-agent/buildkite-agent.cfg; package installs use /etc/buildkite-agent/buildkite-agent.cfg. The --config flag and BUILDKITE_AGENT_CONFIG override both, so check how the agent was launched.
How do I add an agent-wide hook?
Copy the relevant example hook and drop the .sample extension. Agent hooks run for every job on that machine, unlike repository hooks in .buildkite/hooks which travel with the code.
Notice an outdated path? Let us know.