# Buildkite Agent: a self-hosted build runner you point at Buildkite > The Buildkite Agent is a Go binary that polls Buildkite for jobs, runs them on your own machines, and reports logs and artifacts back. It suits teams that want hosted orchestration but their own compute; it is not a standalone CI server. **buildkite/agent** — Project brief: The Buildkite Agent is an open-source toolkit written in Go for securely running build jobs on any device or network. - Repository: https://github.com/buildkite/agent - Website: https://buildkite.com/ - Stars: 1,086 · Forks: 386 - Language: Go - License: MIT - Published: 2026-08-08 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/buildkite-agent ## What the Buildkite Agent actually does The README describes the agent as a small, cross-platform build runner whose main responsibilities are polling buildkite.com for work, running build jobs, reporting back the status code and output log, and uploading the job's artifacts. That list is the whole product. The agent is the execution half of Buildkite: the hosted service holds the pipeline definitions, the queue, the web UI and the job history, and the agent is the process that picks up a job on a machine you own and runs it. That split is the reason to consider it. If your builds need to touch a private network, a licensed toolchain, or a machine with specific hardware, you can put an agent there and keep the orchestration hosted. The trade-off is that the agent is not useful alone. There is no local scheduler, no web interface and no job queue in this repository. Point it at a token that is not tied to a Buildkite organization and there is nothing for it to poll. ## The polling loop, the token, and the build path Two pieces of configuration are required to start an agent, according to the README: an agent token from the Agents page in Buildkite, and a build path. The token identifies the agent to the service; the build path is the directory where jobs are checked out and run. Everything else the agent does follows from that loop: it polls, receives a job, executes it, streams the log back, and uploads artifacts named by the pipeline. The command surface reflects the same model. The help output lists subcommands including start, annotate, annotation, artifact, env and lock. Annotations write back to the build page in the Buildkite UI from inside a running job, which is how a job can surface a summary or a link without the pipeline author touching the API. The lock subcommand exists because agents can share a host, and two jobs that must not run at the same time need a lock outside the pipeline definition. The agent also reports which features are in use unless you disable it, and the README points at AgentStartConfig.Features for the list of what is tracked. Nothing sensitive or identifying is sent, per the README, but the switch is there. ## Installing the agent and starting a first agent The README does not duplicate installation instructions. It points at the Agents page inside Buildkite for personalised instructions and at buildkite.com/docs/agent/self-hosted/install for the documented paths, which cover Ubuntu and Debian via apt, macOS via homebrew, Windows, and Linux generally. Use those, because the exact package names and repository setup live there and not in this repository. Once the binary is on the machine, starting an agent needs only the token and a build path: ```bash buildkite-agent start --token= --build-path=/tmp/buildkite-builds ``` The README gives this exact form. The agent will poll Buildkite and wait for jobs. If you want to see what it is doing while you bring it up, the development instructions add a debug flag to the same command: ```bash buildkite-agent start --debug --build-path=/tmp/buildkite-builds --token "abc" ``` To turn off feature reporting, add the flag the README names: ```bash buildkite-agent start --token= --build-path=/tmp/buildkite-builds --no-feature-reporting ``` If you would rather not install anything, the project publishes Docker images on Docker Hub under buildkite/agent, tagged with the agent SemVer components followed by the operating system. The README's example: agent 3.45.6 is published as 3-ubuntu-20.04, 3.45-ubuntu-20.04 and 3.45.6-ubuntu-20.04, tracking minor, patch and exact versions respectively. Supported image bases listed in the README are Alpine 3.18 and Ubuntu 20.04, 22.04, 24.04 and 26.04 LTS on x86_64. Building from source is also documented: clone the repository, run go build, and start the binary, or run go run *.go start directly. ## Platform tiers and the support boundary The README splits architectures into three tiers, and the split matters more than the marketing line about portability. Tier 1, guaranteed to work, is linux x86_64, linux arm64 and windows x86_64. Tier 2, guaranteed to build, adds linux x86, windows x86, darwin x86_64 and darwin arm64. Tier 3 is community supported: binaries exist for various other platforms and the agent should build anywhere Go does, but official support is not provided. Operating system support is a separate list, and it is narrower than the architecture list in places: Ubuntu 20.04 and newer, Debian 8 and newer, RHEL 7 and newer, CentOS 7 and 8, Amazon Linux 2, macOS 12 through 15 and 26, and Windows 10, 11 and Server 2016, 2019 and 2022. The README warns that future minor releases may drop support for end-of-life operating systems, typically as the latest stable Go release drops them. On Linux hosts the agent requires dbus. That is a real dependency for minimal container images, and it is stated plainly rather than buried. There is a second boundary that is easy to miss: the README says support for security and bug fixes is provided on the current major release only. Running an older major version means you are outside that promise. The repository's recent releases show both a v3.137.2 line and a v4.0.0-beta series, so the current major is in transition at the time of writing, and the beta is not the same thing as the stable line. ## Where the agent is the wrong tool The agent cannot schedule. It has no notion of a pipeline graph, no queue, no retry policy of its own and no UI. Every one of those lives in the hosted service. If you want a single binary that accepts a webhook, decides what to run and shows you the result, this is not it, and no amount of configuration will make it one. It is also the wrong choice if your constraint is that no build metadata may leave your network. The agent polls buildkite.com by design; the README's telemetry section is about feature reporting, not about removing the connection to the mothership. Disabling feature reporting changes what is sent, not whether the agent talks to Buildkite. Finally, the Go module is not a library you should depend on casually. The README states that the module published by this repository, the one you would import as github.com/buildkite/agent/v4, is not considered to be versioned using semantic versioning, that breaking changes may be introduced in minor releases, and that using the agent as a runtime dependency of your Go app is at your own risk. That is an unusually direct warning, and it should be read as one. ## How this differs from running your own CI server The obvious alternative is a self-hosted CI server such as Jenkins, which you install and operate end to end. The difference is where the state lives. With Jenkins, the controller is yours: the job definitions, the queue, the credentials store, the web UI and the build history all sit on a machine you run, and the agents are comparatively thin. With the Buildkite Agent, the orchestration is a hosted service and the agent is the only thing you operate. You get less to run and less to back up, and you give up control of the scheduling layer and the build history. That trade-off shows up in day-to-day work. Patching the agent is a package upgrade on your hosts, and the repository's packaging and install scripts exist for that. Patching a self-hosted controller is a project. On the other side, if the hosted service is unreachable, the agent has nothing to poll, whereas a self-hosted controller keeps its queue locally. Neither model is strictly better; they fail in different places. ## Licence, upgrades and what maintenance costs The agent is MIT licensed, and the binary ships an acknowledgements subcommand that prints the licences and notices of the open source software incorporated into it. That is the practical way to audit the dependency tree for a build you are about to distribute, and it is worth running once on the exact version you deploy rather than reasoning about it from go.mod. MIT is permissive, but the agent's dependencies carry their own terms, and the acknowledgements output is the authoritative list for the build in front of you. This is a description of what the repository provides, not legal advice. The upgrade cost is bounded by the platform policy: security and bug fixes land on the current major release only, and minor releases may drop end-of-life operating systems. In practice that means the agent version and the host OS version are coupled, and an upgrade of one can force the other. The repository's last push was on 2026-08-28, and the releases on that date include v3.137.2 alongside v4.0.0-beta.17, so a v3 to v4 move is the live question for anyone on the stable line, and the beta tag means the v4 series is still settling. Plan the OS support window and the major version together, not separately. ## Conclusion Adopt it if you already use Buildkite and want jobs to run on hardware you control, and you accept that the agent is useless without the Buildkite service behind it. Do not adopt it as a standalone CI server: it has no scheduler, UI or queue of its own. Before rolling it out, verify that your target OS and architecture appear in the repository's support tiers, and decide whether to pass --no-feature-reporting to buildkite-agent start. If you plan to import github.com/buildkite/agent/v4 into your own Go program, note that the README states the module is not versioned using semantic versioning and that breaking changes may appear in minor releases. ## FAQ ### Does the Buildkite Agent run without a Buildkite account? No. The README describes polling buildkite.com for work as one of the agent's main responsibilities, and starting an agent requires an agent token from the Agents page in Buildkite. Without that service there is nothing for the agent to poll. ### How do I install the Buildkite Agent? The README does not list install steps itself. It points at the Agents page inside Buildkite for personalised instructions and at the Buildkite docs page for self-hosted installation, which cover apt on Ubuntu and Debian, homebrew on macOS, Windows and Linux. Docker images are published on Docker Hub under buildkite/agent. ### Can I turn off the telemetry the Buildkite Agent sends? Yes. The README states that the agent sends information about which features are in use, that nothing sensitive or identifying is sent, and that you can disable this by adding the --no-feature-reporting flag to your buildkite-agent start call. ### Which platforms does the Buildkite Agent support? The README lists linux x86_64, linux arm64 and windows x86_64 as Tier 1, guaranteed to work, with linux x86, windows x86, darwin x86_64 and darwin arm64 as Tier 2, guaranteed to build. Everything else is Tier 3 and community supported. On Linux hosts the agent requires dbus. ## Sources - [Official documentation](https://buildkite.com/) - [Official README](https://github.com/buildkite/agent#readme) - [Project repository](https://github.com/buildkite/agent) - [Release notes](https://github.com/buildkite/agent/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/buildkite-agent