Hosted agents terminal access

The Buildkite hosted agents feature provides you with terminal/console access to jobs running on hosted agents. This feature is useful in allowing you to:

  • Understand what components are installed, as you set up your pipeline.
  • Test the behavior of different scripts (because they may not be well-documented).
  • Debug issues that are not reproducible in your local environment.

This can be useful when migrating your pipelines across to queues on Buildkite hosted agents.

Use terminal access on hosted agents

Assuming that terminal access is active across your Buildkite organization, you can access this terminal access feature from a currently building pipeline, when the job of the relevant step is being built.

The terminal access feature is available to users who have/are any of the following:

  • build permissions on the pipeline that created the job
  • a maintainer of the cluster containing this pipeline
  • a Buildkite organization administrator of this cluster

As a pipeline is being built, expand the relevant step and as its job is being built, select its Open Terminal button. A new browser window will open with terminal you can use to execute commands to investigate your hosted agent's environment, test script behavior and debug other issues.

Accessing the SSH button through the Buildkite UI

Deactivate and reactivate terminal access on hosted agents

By default, the terminal access feature for Buildkite hosted agents is active.

If this feature is not active, you can reactivate it for all hosted agents across all clusters within your Buildkite organization. Reactivating or deactivating the terminal access feature requires Buildkite organization administrator permissions.

To deactivate or reactivate the hosted agent terminal access feature:

  1. Select Settings in the global navigation to access the Organization Settings page.
  2. Select Pipelines > Settings to access your organization's Pipeline Settings page.
  3. Scroll down to the Hosted Agents SSH and to:
    • Deactivate this feature, select the Disable SSH button, followed by Disable Hosted Agents SSH in the confirmation message.
    • Reactivate this feature, select the Enable SSH button, followed by Enable Hosted Agents SSH in the confirmation message.

Terminal access will now be either removed or made available to all Buildkite hosted agents across all clusters within your Buildkite organization.

When this feature is active, be aware that users require either:

  • Build permissions on relevant pipelines to use this feature on these pipelines' jobs.
  • Cluster maintainer permissions on the cluster the pipeline belongs to, or Buildkite organization administrator permissions.