Skip to main content
MacStadium’s Buildkite integration lets you run CI/CD jobs on Orka VMs, either as permanent agents you manage yourself or ephemeral agents that spin up before a job and are deleted once it completes. Ephemeral agents work through a proxy. A long-running Buildkite agent overwrites its own bootstrap step so that it doesn’t run the job locally. Instead, it deploys an Orka VM, delegates the job to it over SSH, and tears the VM down afterward. Permanent agents skip that layer entirely: you install a normal Buildkite agent directly on an Orka VM and reuse it across builds. New to Orka? See how teams use it for CI/CD.

​
Prerequisites

​
Set up a permanent agent

Useful when you want to reuse the same agent across builds instead of recreating it every time.
  1. Deploy an Orka VM with the orka3 CLI or the API.
  2. Install a Buildkite agent on it, following Buildkite’s own instructions.
  3. Run your pipelines against that agent as you would any other.
Communication is always initiated from the agent to the Buildkite server, so your Orka environment needs visibility to Buildkite, not the other way around.

​
Set up an ephemeral agent

This is the path most CI teams want: a clean VM per job, torn down afterward.

​
1. Build an Orka base image with a Buildkite agent installed

  1. Deploy an Orka VM with SSH enabled.
  2. Install Homebrew on it if it isn’t already, then install the agent:
  1. Confirm SSH login with a private key works. The proxy agent uses this to reach the VM.
  2. Save the VM as a new base image:

​
2. Create an Orka VM config from that image

The proxy agent uses this config to deploy the ephemeral VM for each job.

​
3. Create a service account and token

Use this token, not a personal one. Personal tokens expire after one hour and will break a long-running proxy agent.

​
4. Run the proxy agent

The recommended path is the provided Dockerfile:
Replace <ORKA_TOKEN> with the service account token from step 3 and <VM_CONFIGURATION_NAME> with the VM config from step 2. Mount both the SSH key for connecting to the ephemeral agent and any keys the build job needs for its own repositories into /buildkite-secrets. The container needs network visibility to your Orka environment, same as any other client.
BUILDKITE_AGENT_TAGS is a standard Buildkite agent variable, not specific to this integration. It routes pipeline steps that target a queue with agents: {queue: ...} to this proxy agent. Without it, the agent joins your cluster’s default self-hosted queue, so steps that target a specific named queue won’t match it. If your cluster has no default self-hosted queue (or the default is a Buildkite-hosted queue), the agent doesn’t register at all.
To pin a specific Buildkite agent base image version instead of latest, pass --build-arg BASE_VERSION=<VERSION> to docker build.
If you’d rather set the proxy agent up by hand instead of via Docker, see manual setup.

​
Secrets and credentials

This integration doesn’t add or restrict how you manage secrets. Credentials for jobs on the ephemeral agent are handled the same way they are for any Buildkite agent, through your pipeline’s normal Buildkite secrets and environment variable configuration. If your requirements call for centralized secret management (Vault, AWS Secrets Manager, or similar), configure that the same way you would for any other Buildkite agent.

​
Configuration reference

​
Environment variables

These don’t have to be baked into the proxy agent’s docker run command. Since Buildkite injects each pipeline’s environment variables into the job before the bootstrap script runs, setting them instead at the pipeline or step level overrides the container’s defaults per job. This matters most for ORKA_CONFIG_NAME: setting it per-pipeline lets one proxy agent serve multiple VM configs, rather than locking a single running agent to whatever config it started with.

​
Advanced: per-job Buildkite variable overrides

The ephemeral agent accepts _SUBAGENT-suffixed versions of several Buildkite agent variables. Each overrides the corresponding variable without the suffix for the job running on the ephemeral VM: BUILDKITE_AGENT_ACCESS_TOKEN_SUBAGENT, BUILDKITE_BUILD_PATH_SUBAGENT, BUILDKITE_HOOKS_PATH_SUBAGENT, BUILDKITE_PLUGINS_PATH_SUBAGENT, BUILDKITE_PLUGINS_ENABLED_SUBAGENT, BUILDKITE_PLUGIN_VALIDATION_SUBAGENT, BUILDKITE_LOCAL_HOOKS_ENABLED_SUBAGENT, BUILDKITE_SSH_KEYSCAN_SUBAGENT, and BUILDKITE_AGENT_DEBUG_SUBAGENT. See Buildkite’s environment variable reference for what each underlying variable does.

​
IP mapping for overlapping networks

If your own network’s address range overlaps with your Orka environment’s private range, the proxy agent needs to reach nodes by public IP instead. Create /var/buildkite/settings.json in the proxy agent container:
Contact MacStadium Support for your nodes’ public IPs.

​
Beyond a single agent

  • Image caching. If cold starts on a new base image are slow, see Image Caching to pre-cache it on specific nodes ahead of time.
  • Burst capacity. If a fixed pool isn’t enough during peak build periods, Orka Burst adds on-demand elastic capacity without a long-term hardware commitment.

​
Troubleshooting

​
Support

Open a ticket in the MacStadium Portal and include the proxy agent’s logs.