#Reference runner: Atmos

Tags: Substrate · Automation · Self-host Substrate: Atmos

The customer-deployed Docker runner for the atmos-workflow trigger. Atmos has no hosted API, so Terrantula ships this reference runner as a wrapper you deploy on your own infrastructure. Terrantula never hosts this runner. It's the substrate companion to the Atmos cattle demo.

#What you'll see

The atmos-workflow trigger HTTP-POSTs a structured dispatch payload to this runner. The runner:

1. Receives the payload at POST /dispatch and validates the bearer token.
2. Clones your Atmos repo from ATMOS_REPO_URL@ATMOS_REPO_BRANCH.
3. Runs atmos workflow <name> -s <stack> --vars ... inside an isolated, auto-cleaned temp dir.
4. POSTs back to Terrantula's callback URL with success or failure.

On the callback, the ActionRun transitions to succeeded/failed and the target entity moves to its onSuccess/onFailure state. The runner runs Atmos inside your workflow definition; Terrantula never runs atmos terraform apply directly. It runs as a non-root user (UID 1001) and uses StrictHostKeyChecking=yes for SSH clones — it never disables host-key checking.

#Try it

Deploy in under 30 minutes:

# 1. Generate a runner auth token and store it as a Terrantula secret.
openssl rand -hex 32
terrantula secrets set atmos-runner-token --value <your-token> --project <project-id>

# 2. Deploy the runner with Docker Compose.
cp examples/runners/atmos/docker-compose.yml ./atmos-runner/docker-compose.yml
export RUNNER_AUTH_TOKEN=<your-token>
export ATMOS_REPO_URL=git@github.com:your-org/your-atmos-repo.git
docker compose -f ./atmos-runner/docker-compose.yml up -d

The runner listens on port 8080 (expose it via your load balancer or ingress). Point your Action's trigger at it:

trigger:
  type: atmos-workflow
  workflow: provision-tenant
  stack: "tenant-{{ parameters.customer_id }}"
  runner:
    endpoint: https://atmos-runner.your-domain.com/dispatch
    auth:
      type: bearer
      token: "{{ secrets.atmos-runner-token }}"
  waitForCompletion: true

Key environment variables: RUNNER_AUTH_TOKEN (required), ATMOS_REPO_URL (required), ATMOS_REPO_BRANCH (default main), and GIT_SSH_KEY + ATMOS_REPO_KNOWN_HOSTS for private repos over SSH.

#Key files

#Related docs

• Cattle: per-tenant SaaS (Atmos) — the demo that uses this runner.
• On-ramp: from Atmos.
• Triggers Reference — the atmos-workflow trigger.
• Multi-tenancy & self-hosting.

#View on GitHub

examples/runners/atmos