Cluster deploy

This guide installs the TruStacks Runner into a real Kubernetes or OpenShift cluster (eval, staging, or shared dev). The Runner is deployed as a single Helm release; it phones home to the TruStacks Control Plane over outbound mTLS only, with no inbound ports.

Supported platforms

• Vanilla Kubernetes 1.28+
• OpenShift 4.13+
• EKS, GKE, AKS (any current LTS minor)

The Helm chart’s kubeVersion constraint is >=1.28.0-0. Older clusters are not supported.

Prerequisites

You need:

• Cluster admin access to your target cluster (to create the trustacks-system namespace and apply the Runner resources).
• helm ≥ 3.14 and kubectl matching your cluster version.
• An Anthropic API key (or your OpenRouter key, if you BYO).
• A signing identity registered with the TruStacks Control Plane (required for overlay rule authoring; not required for an install that only consumes the constitution).
• Network egress from the cluster to:
  • api.anthropic.com (or your chosen LLM endpoint)
  • The TruStacks registry (for signed bundle pulls)
  • The TruStacks Control Plane endpoint
• The Helm chart source. During Beta you install from the chart in the trustacks-mvp repository; post-Beta the chart ships from a public OCI registry.

Install steps

The full sequence runs in three commands. Each is described in detail below.

1. Create the namespace and apply the policy public key

kubectl create namespace trustacks-system
kubectl -n trustacks-system apply -f https://raw.githubusercontent.com/TruStacks/trustacks-mvp/main/scripts/manifests/policy-pub-key.yaml

The policy-pub-key ConfigMap holds the Cosign public key the Runner’s init container uses to verify policy bundles before extract. The manifest pins the TruStacks signing identity.

2. Provision Runner Secrets

You need at minimum the LLM provider key and one git deploy key. See the credentials guide for the full pattern.

For an eval install with a single connected repo:

# LLM provider key
kubectl -n trustacks-system create secret generic trustacks-runner-llm \
  --from-literal=ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY"
 
# Deploy key for one app repo (private SSH key + Gitea/GitHub registration)
ssh-keygen -t ed25519 -f /tmp/sample-app-deploy -N "" -C "sample-app@trustacks"
kubectl -n trustacks-system create secret generic sample-app-deploy-key \
  --from-file=ssh-privatekey=/tmp/sample-app-deploy \
  --from-file=ssh-publickey=/tmp/sample-app-deploy.pub
kubectl -n trustacks-system label secret sample-app-deploy-key \
  trustacks.io/role=git-deploy-key \
  trustacks.io/repo=sample-app

For Connect-a-repo flows in real customer environments, the UI wizard handles this end-to-end.

3. Install the Runner chart

git clone https://github.com/TruStacks/trustacks-mvp.git
cd trustacks-mvp
 
helm install runner ./charts/runner \
  --namespace trustacks-system \
  --set image.tag=<release-tag> \
  --set policyBundle.bundleRef=ghcr.io/trustacks/policy/constitution:<release-tag> \
  --set policyBundle.insecure=false \
  --set policyBundle.verify=true

The chart is intentionally narrow: it deploys the Runner pod with the init containers (Secret discovery, policy bundle pull and verify) and a ClusterIP Service on port 8000. No Ingress is created by default; exposure is your choice.

4. Connect the Runner to the Control Plane

Set TRUSTACKS_RUNNER_CONTROL_PLANE_URL in the chart values to your Control Plane endpoint:

helm upgrade runner ./charts/runner \
  --namespace trustacks-system \
  --reuse-values \
  --set env.TRUSTACKS_RUNNER_CONTROL_PLANE_URL=https://cp.your-trustacks.io

The Control Plane URL is provisioned per-customer during onboarding.

5. Verify the install

kubectl -n trustacks-system get pods
kubectl -n trustacks-system logs deployment/runner -c policy-bundle-init

The policy-bundle-init log should end with a clean Cosign verification and the bundle extracted under /policy-runtime/. If verification fails, the Runner falls back to the image-baked bundle and logs the fallback; you can run with policyBundle.verify=false to bypass signature checks while debugging, but do not do this in production.

What lives where

Your source code stays in your network. Only findings, decisions, and agent traces leave, all of them redactable per your policy. See the architecture page for the trust boundary in context.

Network requirements

The Runner needs outbound network access to four endpoints:

• TruStacks Control Plane (mTLS) · for audit submission, rule distribution coordination, and UI event streaming.
• TruStacks rule registry (HTTPS) · for signed constitution and Specialist Pack bundle pulls.
• LLM provider endpoint (HTTPS) · api.anthropic.com by default, or your OpenRouter endpoint.
• Your Git provider (SSH or HTTPS) · for cloning repos and opening PRs.

No inbound ports. The Runner does not expose any service to the public internet.

Verifying signed images

The Runner image and the policy bundle are both Cosign-signed. To verify before installing:

# Runner image
cosign verify --key cosign.pub ghcr.io/trustacks/runner:<release-tag>
 
# Constitution bundle
cosign verify --key cosign.pub ghcr.io/trustacks/policy/constitution:<release-tag>

The TruStacks public Cosign key is published at https://trustacks.com/cosign.pub and pinned in the policy-pub-key ConfigMap from step 1.

Upgrading

Upgrades are explicit operator actions. The chart’s image.tag and policyBundle.bundleRef are pinned per release; bump them to the new release tag and run helm upgrade. The init container re-verifies the new bundle on the next pod roll.

See the constitution reference for the semver semantics of constitution version bumps.

Where to go next

• Credentials and secrets · the full four-secrets pattern, including the GitHub App setup for production Connect-a-repo flows
• GitOps integration · how ArgoCD picks up the PRs the DevOps Engineer ships
• Architecture · Data Plane · what runs where and why