Runners

Where: Runners in the sidebar (#/settings/runners). Step 2 of Get set up embeds the same enrollment card.

The runner is the part of TruStacks that runs in your cluster. It clones your repos, runs the agents, evaluates policy and opens pull requests. This screen is where you enroll runners and keep them current.

What you see

Enroll a runner

1. Generate enrollment token creates a token and shows it once (Shown once, copy it now).

2. Under it, Install the runner in your cluster shows a ready-to-run command with the current published chart version as a badge:

   helm install trustacks-runner oci://ghcr.io/trustacks/charts/runner \
     --version <published version> \
     -n "<your-namespace>" --create-namespace \
     --set saas.enrollmentToken=<token>

   Copy the command from the app rather than from this page. The version comes from the control plane and changes with each release.

3. A status line polls every few seconds: Waiting for your runner to connect… (with Check now) until a runner checks in, then Runner connected.

If the app cannot confirm the current chart version, the command omits --version and installs the latest published chart, and says so.

Upgrade a runner

Shown once at least one runner is connected. It compares each connected runner’s reported version with the latest published chart and tells you which are out of date, which are ahead (for example on a pre-release), and which have not reported a version. It always shows an upgrade command:

helm upgrade trustacks-runner oci://ghcr.io/trustacks/charts/runner \
  --version <published version> \
  -n <your-namespace> --reset-then-reuse-values

Connected runners

A list of every runner that has enrolled, each marked connected or not seen, with its version and last-seen time. Remove (then Yes) deletes a runner’s record and its registered key.

Revoke enrollment tokens

Below the runner list. Use it if an enrollment token got out: committed to a repo, pasted in chat, or held by someone who has left. Anyone with a valid token can enroll a runner that receives this workspace’s jobs and credentials. You need to be a workspace owner.

1. Revoke and generate a new token opens a confirm step that lists what happens next. Confirm with Revoke and generate a new token again, or Cancel.

2. Every enrollment token for the workspace is revoked at once, and one replacement is minted. The app says how many old tokens it revoked and shows the new token once (Shown once, copy it now).

3. Give it to each runner you already run shows an upgrade command that carries the new token:

   helm upgrade trustacks-runner oci://ghcr.io/trustacks/charts/runner \
     --version <version> \
     -n "<your-namespace>" --reset-then-reuse-values \
     --set saas.enrollmentToken=<new token>

   Copy the command from the app, where the version and the new token are already filled in. Run it once per install. Install a new runner shows the install command with the new token.

What revoking does:

• A revoked token can never enroll a new runner, including for anyone who kept a copy.
• Runners on 0.2.14-rc26 or later stay connected. A runner renews its session about every 15 minutes. Under a revoked token it can still renew, but only for its own registered runner, on its own key, and the new session comes back sealed to that key. A copy of the token is no use without the runner’s private key. These runners keep working without the upgrade command, but they need the new token to enroll again if a reinstall loses their identity Secret.
• Older runners disconnect at their next renewal, within about 15 minutes, until you run the upgrade command against them. The chart mounts the token Secret as a volume, so a running pod picks up the new value at its next renewal.
• It does not remove any runner. A runner someone already enrolled with the leaked token holds a registered key, like yours does, and can keep renewing on it. Check the runner list for any you don’t recognise and Remove them. After the revoke, a removed runner cannot come back.

If you supply the token from a Secret you manage (saas.enrollmentTokenSecret), put the new token in that Secret instead of passing --set saas.enrollmentToken.

What it means

• Pull mode. The runner only makes outbound HTTPS calls: it exchanges the enrollment token for a session, then long-polls the control plane for jobs. There is no inbound connection to your cluster and no VPN.
• Connected is liveness, not presence. A row stays after its pod is gone; only a runner that has checked in recently counts as connected. The header count shows connected runners only.
• Your code is read inside your cluster. The runner clones repos and runs the agents there. What leaves the cluster is the pull request it opens, the run events it reports to TruStacks, and what the agents send to your configured LLM provider while they work (which includes file contents they read).
• The token is stored only as a hash. You can generate another token at any time, for example to add a second runner. Tokens are reusable and do not expire; they stop working only when you revoke them.

What to do here

• First time: generate a token, run the command against the cluster and namespace you chose, and wait for Runner connected. Then check the rollout on your side:

  kubectl -n <your-namespace> rollout status deploy/trustacks-runner-runner

  (With the release name trustacks-runner, the chart names the deployment trustacks-runner-runner.)

• After a release: use the upgrade card’s command. Then confirm the runner row shows the new version.

• If a token leaked: revoke and generate a new one, run the upgrade command it gives you against each install, then remove any runner in the list you don’t recognise.

• If the Overview says no runner is checking in: check the pod, its logs, and egress from the namespace (the runner needs to reach api.trustacks.com, ghcr.io, your LLM endpoint, GitHub and Sigstore).

Chart values, RBAC and egress requirements are in the Runner Helm chart reference.

How it connects

• A missing or silent runner is the top item on Overview, because nothing else can run.
• The runner uses the key from Settings and the repos connected under Applications.
• The runner reports which rules it enforces, which feeds Rules and the Maturity ceiling. Runners 0.2.14 and later (and pre-releases from 0.2.14-rc24) also report each rule’s Rego source, and pull and verify the signed constitution at start-up; older runners use the copy baked into their image. See Policy in force.

Beta limits

• Removing a runner deletes its record in TruStacks. It does not uninstall anything from your cluster (use helm uninstall for that), and it does not revoke the enrollment token, which stays valid until you revoke it under Revoke enrollment tokens. See Runner install.
• Revoking is all or nothing: it revokes every token in the workspace. Removing a runner alone does not cut it off while its token is valid; to cut off one runner, revoke and then remove it.
• A removed runner’s current session stays valid until it expires, up to about 15 minutes.
• Runners that predate version reporting show no version; the card says it cannot tell whether they are current, and upgrading is safe.