Network requirements
Self-hosted Buildkite agents only make outbound HTTPS connections. No inbound ports need to be opened. This page lists the hosts and ports your network must allow agents to access.
Required hosts
Every self-hosted agent must be able to access the following hosts over HTTPS (port 443):
| Host | Purpose |
|---|---|
agent-edge.buildkite.com |
The default Agent API endpoint for agents running version 3.122.0 or later. Supports both streaming and polling-based job dispatch, along with agent registration, log uploads, artifact coordination, metadata, secrets, OIDC token requests, pipeline uploads, and cache operations. |
agent.buildkite.com |
The default Agent API endpoint for agents running versions earlier than version 3.122.0. Supports polling-based job dispatch only. Provides the same functionality as agent-edge.buildkite.com except for streaming job dispatch. |
buildkiteartifacts.com |
Default artifact storage. When using the built-in artifact storage, the Agent API provides upload and download URLs on this domain. |
All agent-to-Buildkite communication uses TLS encryption. The agent connects to its configured endpoint on port 443 using HTTPS. There is no need to open any inbound ports on your firewall or security groups. For more detail on how the agent communicates with Buildkite, see Buildkite architectures.
Optional hosts
Depending on your agent configuration, agents may also need to access the following hosts.
Customer-managed artifact storage
If you configure a custom artifact upload destination, agents need access to the relevant storage provider instead of, or in addition to, buildkiteartifacts.com:
| Storage provider | Hosts |
|---|---|
| Amazon S3 |
*.s3.amazonaws.com (port 443) |
| Google Cloud Storage |
storage.googleapis.com, www.googleapis.com (port 443) |
| Azure Blob Storage |
*.blob.core.windows.net (port 443) |
| Artifactory | Your Artifactory server's hostname (port 443) |
Cloud instance metadata
When running on a cloud provider, agents can automatically detect instance metadata to populate agent tags. These metadata endpoints are instance-local and do not require internet-routable firewall rules:
| Cloud provider | Endpoint | Purpose | |||
|---|---|---|---|---|---|
| Cloud provider | AWS (EC2 and ECS) | Endpoint |
169.254.169.254 (port 80, HTTP) |
Purpose | EC2 instance metadata and ECS task metadata |
| Cloud provider | Google Cloud | Endpoint |
metadata.google.internal (port 80, HTTP) |
Purpose | GCP instance metadata |
Hosts your build jobs may need
In addition to the hosts the agent itself connects to, your build scripts and plugins may require access to other services. These depend on what your pipelines do, but common examples include:
-
Source control: your Git host, such as
github.com,gitlab.com, or an internal Git server -
Package registries: such as
registry.npmjs.org,pypi.org,registry.yarnpkg.com, or Docker Hub (registry-1.docker.io,auth.docker.io,production.cloudflare.docker.com) -
Buildkite Package Registries:
api.buildkite.com(port 443) if you use Buildkite Package Registries from your build scripts - Other external services: deployment targets, notification endpoints, code analysis tools, or any other services your builds interact with
Buildkite platform egress IPs
If your internal services need to accept inbound connections from the Buildkite platform (for example, webhooks or commit status updates to a self-hosted source control system), use the Meta API to obtain the current set of platform egress IP addresses.