buildkite-agent start

The Buildkite Agent’s start command is used to manually start an agent and register it with Buildkite.

Starting an Agent


   buildkite-agent start [arguments...]


   When a job is ready to run it will call the "bootstrap-script"
   and pass it all the environment variables required for the job to run.
   This script is responsible for checking out the code, and running the
   actual build script defined in the pipeline.

   The agent will run any jobs within a PTY (pseudo terminal) if available.


   $ buildkite-agent start --token xxx


   --config value                        Path to a configuration file [$BUILDKITE_AGENT_CONFIG]
   --token value                         Your account agent token [$BUILDKITE_AGENT_TOKEN]
   --name value                          The name of the agent [$BUILDKITE_AGENT_NAME]
   --priority value                      The priority of the agent (higher priorities are assigned work first) [$BUILDKITE_AGENT_PRIORITY]
   --disconnect-after-job                Disconnect the agent after running a job [$BUILDKITE_AGENT_DISCONNECT_AFTER_JOB]
   --disconnect-after-job-timeout value  When --disconnect-after-job is specified, the number of seconds to wait for a job before shutting down (default: 120) [$BUILDKITE_AGENT_DISCONNECT_AFTER_JOB_TIMEOUT]
   --cancel-grace-period value           The number of seconds running processes are given to gracefully terminate before they are killed when a job is cancelled (default: 10) [$BUILDKITE_CANCEL_GRACE_PERIOD]
   --shell value                         The shell commamnd used to interpret build commands, e.g /bin/bash -e -c (default: "/bin/bash -e -c") [$BUILDKITE_SHELL]
   --tags value                          A comma-separated list of tags for the agent (e.g. "linux" or "mac,xcode=8") [$BUILDKITE_AGENT_TAGS]
   --tags-from-host                      Include tags from the host (hostname, machine-id, os) [$BUILDKITE_AGENT_TAGS_FROM_HOST]
   --tags-from-ec2                       Include the host's EC2 meta-data as tags (instance-id, instance-type, and ami-id) [$BUILDKITE_AGENT_TAGS_FROM_EC2]
   --tags-from-ec2-tags                  Include the host's EC2 tags as tags [$BUILDKITE_AGENT_TAGS_FROM_EC2_TAGS]
   --tags-from-gcp                       Include the host's Google Cloud meta-data as tags (instance-id, machine-type, preemptible, project-id, region, and zone) [$BUILDKITE_AGENT_TAGS_FROM_GCP]
   --wait-for-ec2-tags-timeout value     The amount of time to wait for tags from EC2 before proceeding (default: 10s) [$BUILDKITE_AGENT_WAIT_FOR_EC2_TAGS_TIMEOUT]
   --git-clone-flags value               Flags to pass to the "git clone" command (default: "-v") [$BUILDKITE_GIT_CLONE_FLAGS]
   --git-clean-flags value               Flags to pass to "git clean" command (default: "-ffxdq") [$BUILDKITE_GIT_CLEAN_FLAGS]
   --bootstrap-script value              The command that is executed for bootstrapping a job, defaults to the bootstrap sub-command of this binary [$BUILDKITE_BOOTSTRAP_SCRIPT_PATH]
   --build-path value                    Path to where the builds will run from [$BUILDKITE_BUILD_PATH]
   --hooks-path value                    Directory where the hook scripts are found [$BUILDKITE_HOOKS_PATH]
   --plugins-path value                  Directory where the plugins are saved to [$BUILDKITE_PLUGINS_PATH]
   --timestamp-lines                     Prepend timestamps on each line of output. [$BUILDKITE_TIMESTAMP_LINES]
   --no-pty                              Do not run jobs within a pseudo terminal [$BUILDKITE_NO_PTY]
   --no-ssh-keyscan                      Don't automatically run ssh-keyscan before checkout [$BUILDKITE_NO_SSH_KEYSCAN]
   --no-command-eval                     Don't allow this agent to run arbitrary console commands, including plugins [$BUILDKITE_NO_COMMAND_EVAL]
   --no-plugins                          Don't allow this agent to load plugins [$BUILDKITE_NO_PLUGINS]
   --no-plugin-validation                Don't validate plugin configuration and requirements [$BUILDKITE_NO_PLUGIN_VALIDATION]
   --no-local-hooks                      Don't allow local hooks to be run from checked out repositories [$BUILDKITE_NO_LOCAL_HOOKS]
   --no-git-submodules                   Don't automatically checkout git submodules [$BUILDKITE_NO_GIT_SUBMODULES, $BUILDKITE_DISABLE_GIT_SUBMODULES]
   --no-http2                            Disable HTTP2 when communicating with the Agent API. [$BUILDKITE_NO_HTTP2]
   --metrics-datadog                     Send metrics to DogStatsD for Datadog [$BUILDKITE_METRICS_DATADOG]
   --metrics-datadog-host value          The dogstatsd instance to send metrics to via udp (default: "") [$BUILDKITE_METRICS_DATADOG_HOST]
   --spawn value                         The number of agents to spawn in parallel (default: 1) [$BUILDKITE_AGENT_SPAWN]
   --experiment value                    Enable experimental features within the buildkite-agent [$BUILDKITE_AGENT_EXPERIMENT]
   --endpoint value                      The Agent API endpoint (default: "") [$BUILDKITE_AGENT_ENDPOINT]
   --no-color                            Don't show colors in logging [$BUILDKITE_AGENT_NO_COLOR]
   --debug                               Enable debug mode [$BUILDKITE_AGENT_DEBUG]
   --debug-http                          Enable HTTP debug mode, which dumps all request and response bodies to the log [$BUILDKITE_AGENT_DEBUG_HTTP]

Setting Tags

Each agent has tags (in 2.x we called this metadata) which can be used to group and target the agents in your build pipelines. This way you're free to dynamically scale your agents and target them based on their capabilities rather than maintaining a static list.

To set an agent’s tags you can set it in the configuration file:


or with the --tags command line flag:

buildkite-agent start --tags "docker=true" --tags "ruby2=true"

or with the BUILDKITE_AGENT_TAGS an environment variable:

env BUILDKITE_AGENT_TAGS="docker=true,ruby2=true" buildkite-agent start

Agent Targeting

Once you've started agents with tags you can target them in the build pipeline using agent query rules.

Here's an example of targeting agents that are running with the tag postgres and value of 1.9.4:

Agent Selector showing a single match

To do this from uploaded pipeline.yml you would do:

  - command: ""
      postgres: "1.9.4"

You can also match for any agent with a postgres tag by omitting the value after the = sign, or by using *, for example:

Agent Selector showing a single match

To do this from an uploaded pipeline.yml you would do:

  - command: ""
      postgres: '*'

Partial wildcard matching (e.g. postgres=1.9* or postgres=*1.9) is not yet supported.

The Queue Tag

The queue tag works differently from other tags, and can be used for isolating jobs and agents. See the agent queues documentation for more information about using queues.

Sourcing Tags from Amazon Web Services

You can load an Agent's tags from the underlying Amazon EC2 instance using --tags-from-ec2-tags for the instance tags and --tags-from-ec2 to load the EC2 metadata (e.g instance name and machine type).

Sourcing Tags from Google Cloud

You can load an Agent's tags from the underlying Google Cloud metadata using --tags-from-gcp.