Architecture

TruStacks has two halves. The control plane is hosted by TruStacks at app.trustacks.com and api.trustacks.com. The runner is one Helm release in your Kubernetes cluster. The runner does the work that touches your code: it clones your repositories, runs the agent crew, checks every proposal against the signed constitution, and opens pull requests into your platform repo. Your GitOps controller deploys what you merge.

Agents propose. Policy decides. Humans approve.


┌──────────────────────────────────────────────────────────────────┐
│  Control plane (hosted by TruStacks)                             │
│  Web UI, API, sign-in, job queue, audit trail, maturity history. │
│  Mints short-lived GitHub App tokens. Never connects to you.     │
└───────────────────────────────▲──────────────────────────────────┘
                                │  HTTPS, outbound from your cluster
┌───────────────────────────────┴──────────────────────────────────┐
│  Runner (one Helm release in your cluster)                       │
│  Agent crew · OPA + the signed constitution · pre-emit checks.   │
│  Clones your repos, opens PRs on your platform repo.             │
└──────────────────────────────────────────────────────────────────┘
        │ PR                                      ▲ read-only (optional)
        ▼                                         │
   Your platform repo  ──▶  your ArgoCD  ──▶  your cluster

The control plane

The hosted service you sign in to. It holds your workspace, your connected repos and Applications, the job queue, the event trail behind every analysis and proposal, maturity history, and billing. It also mints the short-lived GitHub App installation tokens the runner uses, and seals each one to your runner before handing it over.

The control plane never opens a connection into your cluster. It cannot, by design: it has no address for your runner and no credentials for your cluster.

The runner

The runner is the data plane. You install it with Helm from oci://ghcr.io/trustacks/charts/runner. See the runner Helm chart reference for values, permissions, and upgrades.

How it talks to the control plane:

Pull, not push. The runner presents its enrollment token to the control plane, receives a session token, and long-polls for jobs over HTTPS. There are no inbound ports and no mTLS tunnel.
Credentials arrive sealed. On first start the runner generates an X25519 keypair and registers the public half. Anything the control plane sends it (your LLM key, a GitHub App token) is sealed to that key. The runner writes its own Kubernetes Secrets; the control plane never holds a kubeconfig for your cluster.
Policy is local. The runner evaluates the constitution with OPA inside your cluster. See Policy in force for where that policy comes from and how the runner reports it.

What leaves your cluster

To the TruStacks control plane: analysis results (framework, language, dependencies, entrypoints), the artifacts the agents generated, policy verdicts, gap reports, and the event trail of each run. Your repository is not uploaded.
To your LLM provider: the prompts the agents send, which include the file contents they read. This goes to Anthropic or OpenRouter under the API key you supplied. See LLM provider.
To your git provider: the pull requests the runner opens.

The rules


┌──────────────────────────────────────────────────────────────────┐
│  Your overlay rules (optional, authored with the trustacks CLI)  │
├──────────────────────────────────────────────────────────────────┤
│  Constitution (TruStacks, Apache 2.0, signed, free at all tiers) │
└──────────────────────────────────────────────────────────────────┘

The constitution is the TruStacks-authored Rego policy every proposal is judged against: 24 rules today, published from the public trustacks-policy repository and signed with Sigstore. See the constitution reference.
Overlay rules are yours. Their denies are added to the constitution’s denies, so an overlay can only make the gate stricter: it adds reasons to refuse and has no way to remove one. Overlay authoring runs through the trustacks rule CLI. There is no delivery path for overlay bundles to hosted runners yet; see the constitution page.

The crew

Code Reviewer reads a service repo and reports framework, language, runtime version, dependencies, entrypoints, and whether it has tests, a Dockerfile, and CI. Frameworks with a curated pack today: Python FastAPI, Spring Boot, .NET, and Go.
DevOps Engineer turns an analysis into a proposal for your platform repo: a reusable CI workflow, a Helm chart or Kustomize base and overlays, and an ArgoCD Application. It reads the platform repo first and keeps what you changed (the read-and-preserve protocol).
Coordinator runs gap analyses and drafts Rego rules in chat. It consults the specialists during a gap analysis.
Baseline Security (specialist, every tier) consults on image scanning, SAST/SCA, secret scanning, and SBOM and signing.
SOC2 (specialist, Developer tier) maps gaps to SOC 2 control families. See Specialist Packs.

Agents do not merge or push to a default branch, and never hold cluster or cloud credentials. The runner opens pull requests. You decide what merges. The GitHub App does have Contents write on the repos you grant, so protect their default branches and keep the TruStacks app off the bypass list to have GitHub enforce this too.

The environment profile

environment-profile.yaml at the root of your platform repo declares the tools you run, by category, and the practices you attest to. The DevOps Engineer emits pipeline steps only for tools you declared. Maturity scoring reads it. See Environment profile.

How agents reach your systems

Agents use a small set of tools built into the runner: read a file, list a directory, emit an artifact. They reach GitHub through the runner’s own git client with a short-lived installation token. There are no third-party integrations for agents to use. Separately, the runner can observe your GitHub repos through GitHub’s MCP server, read-only and with no model involved, if you turn MCP Signals on. See Integration model.

Properties you can check

Property	How it holds
Agents cannot merge	The GitHub App opens pull requests. Merging is yours. Require reviews with branch protection on the platform repo.
No inbound connection to your cluster	The runner polls out over HTTPS. Nothing in the chart opens a port to the internet.
The runner observes ArgoCD, never operates it	The optional observer gets `get`, `list`, `watch` on Applications and nothing else.
Proposals that fail policy never become PRs	Pre-emit validation and the OPA gate run before the runner touches your platform repo.
Claims about your practice are yours to make	Nothing TruStacks ships pre-fills a practice attestation.

Where to go next

Proposal lifecycle · what happens between “Promote to proposal” and a deploy
Runner Helm chart · install, permissions, egress, upgrades
Constitution · the rules every proposal is judged against
Supply-chain verification · verify what you run