Portability & Requirements¶

This page is an honest map of what tatara actually requires to run, what is merely the maintainer's personal stack, and how portable the platform really is today. It is written for platform architects, senior devops, and senior developers who are evaluating whether they can run tatara on their stack: any GitOps mechanism, any coding agent, their own identity and data services.

The reference deployment documented in Prerequisites lists everything the maintainer runs. That page is a shopping list for reproducing the reference environment. This page is the opposite exercise: it separates the handful of things tatara genuinely cannot run without from the many things that are one person's deployment choices, and it is candid about where the two have become welded together in the code as shipped.

The short version¶

Tatara was architected to be portable across three axes: the coding agent, the GitOps / deploy mechanism, and the SCM provider. The seams for all three exist in the code. Two of them are genuinely usable today; one is not.

Underneath those three axes, five things are unconditionally required and have no off switch today: Kubernetes, a coding agent, an SCM, an OIDC identity provider, and the memory graph stack. These are covered below.

graph TD
    subgraph HARD["Hard substrate - required, no off switch"]
        K8S["Kubernetes<br/><i>the platform IS a controller-runtime operator</i>"]
        OIDC["OIDC identity provider<br/><i>3 mandatory boot env vars, no no-auth mode</i>"]
        MEM["Memory graph stack<br/><i>LightRAG + Neo4j + CNPG Postgres</i>"]
    end
    subgraph SEAMS["Portability seams - designed to be swappable"]
        AGENT["Coding agent<br/><b>seam open, one welded impl</b>"]
        DEPLOY["GitOps / deploy<br/><b>act external, supervision welded</b>"]
        SCM["SCM provider<br/><b>github | gitlab</b>"]
    end
    K8S --> SEAMS
    OIDC --> SEAMS
    MEM --> SEAMS

Irreducible requirements¶

These cannot be removed without a rewrite or significant new engineering. If any of them is a hard no for your environment, tatara as shipped is not for you yet.

1. Kubernetes¶

Not negotiable. The platform is a controller-runtime operator. Five root CRDs (Project, Repository, Task, Subtask, QueuedEvent) are the state store; every agent turn runs as a Pod; the manager calls ctrl.GetConfigOrDie() at boot and cannot start without a cluster. (WorkItem is not a CRD - it is an embedded WorkItemRef struct carried in Task.Status.WorkItems as the per-Project work-item ledger; kubectl get workitems returns nothing.) There is no alternative scheduler and no non-Kubernetes state backend. "Run tatara without Kubernetes" is not a configuration - it would be a different product.

2. A coding agent¶

Tatara exists to drive a coding agent, so needing one is irreducible by definition. What is not irreducible by design - but is a de-facto requirement today - is that the agent be Claude Code specifically. See Seam 1 below. The requirement "an agent" is real; the requirement "this exact agent" is an unfulfilled-intent coupling, not a design necessity.

3. An SCM, from the set¶

Tatara reads issues and writes PRs, so it needs a source-control host. This is the best-abstracted axis: provider selection is a switch over github and gitlab, both fully implemented, with header-based provider auto-detection. Needing an SCM is irreducible; the specific provider is swappable within those two. A third provider (Gitea, Forgejo, Bitbucket) is a code change, and some capabilities (GitHub Projects v2, push-CD deploy supervision) are GitHub-only. See Seam 3.

4. An OIDC identity provider¶

Every tatara API is OIDC-gated. The operator validates OIDC_ISSUER, OIDC_AUDIENCE, and OPERATOR_OIDC_SECRET_NAME as mandatory at boot (config.go returns an error if any is empty), and the memory server wraps every handler in auth with no auth-disabled mode. All agent pods share one OIDC client identity.

The good news: verification is standards-based (go-oidc discovery), so any compliant issuer works - this is not Keycloak-locked. The hard part: needing an IdP at all is a firm requirement today, with no single-tenant / dev "auth off" mode. If you cannot stand up an OIDC issuer, you cannot boot the platform.

5. The memory graph stack¶

This is the highest-leverage coupling and the one most likely to surprise evaluators. The memory stack (the tatara-memory facade + LightRAG + Neo4j + CloudNativePG Postgres) is mandatory, not optional:

• Every Task hard-gates on project.Status.Memory.Phase == "Ready" before an agent pod is built. No memory, no agents - anywhere.
• The operator provisions the stack unconditionally; there is no code path that skips it.
• MemorySpec exposes only footprint knobs (pgInstances, pgStorage, neo4jStorage). There is no enabled field.

This drags in the CloudNativePG operator as a hard transitive dependency and means no agent runs anywhere without a fully healthy memory stack. It is irreducible as-shipped, but it is the single decoupling that would most widen who can run tatara: a memory.enabled: false toggle (mirroring the existing grafana.enabled pattern) would let a team run the issue-to-PR loop against a much smaller data footprint.

The maintainer's stack (NOT required)¶

Everything in this section is a deployment choice made by the maintainer for the reference cluster. None of it is a platform requirement, and most of it is already cleanly swappable. Where a "not required" item is nonetheless welded into the code today, that caveat is called out and cross-referenced to the coupling hotspots.

How portable is it, really?¶

Candid section. The seams are drawn; the values behind two of them are welded.

Seam 1: the coding agent¶

The wire is generic. The implementation behind it is not.

The operator talks to the agent over plain HTTP: POST /v1/messages with {text, callbackUrl} returns a turnId; the operator polls; the agent posts an agent-neutral turn-complete callback carrying the final text plus token usage. Nothing in that contract is Claude-specific, which is why the operator is roughly 90% agent-agnostic.

But below that seam there is exactly one adapter, and it is a hand-built, version-specific Claude Code TUI supervisor: PTY keystroke driving, bracketed- paste submission, "Bypass Permissions" dialog navigation, a Stop-hook that parses ~/.claude/projects/*.jsonl transcripts, and the whole .claude/ config tree - all reverse-engineered against a pinned binary. Worse, the coupling leaks up into the operator: ValidatePodSecretRefs fails the Project if the Anthropic secret name is empty (pod.go:135), and the credential is injected under the hardcoded env name CLAUDE_CODE_OAUTH_TOKEN (pod.go:460).

"Swap the agent" today means writing a brand-new wrapper binary and editing operator pod-spawn plus CRD validation. It is not a config flip. The honest status of "any coding agent" is: architecturally anticipated, not yet delivered.

Seam 2: GitOps and deploy¶

The deploy act is fully external. The deploy confirmation is fully welded.

The operator makes zero helm, kubectl, or helmfile calls - verified. It never deploys anything itself; it only watches a deploy cascade complete so it can close the originating issue once the code is actually live. That means the deploy mechanism is completely swappable: point your merges at Argo CD, Flux, or CI-driven kubectl and the core loop (issue -> PR -> merge -> done) does not notice.

What is welded is the deploy-supervision feature. Six non-configurable Go values in deploy_supervision.go assume the maintainer's exact CD stack:

• helmfileRepoName = "tatara-helmfile" - the terminal repo name is hardcoded.
• applyWorkflowFile = "apply.yaml" - the confirm workflow filename is hardcoded.
• deployPinFiles - the expected pin-file layout.
• the release-artifact attribution map.
• the helmfile .gotmpl-block regex used to match version pins.
• a GitHub-only DeployWatcher (a GitLab reader logs "cascade unsupervisable here" and parks).

None of these are on the CRD. If no repo named exactly tatara-helmfile is enrolled, or your file layout differs, every cascade silently times out and parks with a deploy-timeout. Confirmation works by GET-ing git-committed helmfile files at the apply SHA and regex-matching pins, and by reading the highest vX.Y.Z git tag - so OCI-digest / commit-SHA deploy flows (Argo image-updater, Flux) publish no matching signal even on GitHub.

Seam 3: the SCM provider¶

The most portable axis, with honest edges.

Provider access is behind clean Client / SCMReader / SCMWriter interfaces with two complete implementations and header-based provider auto-detection. Within {github, gitlab} this is genuinely a config choice. The edges:

• Provider selection is a closed switch (registry.go), so a third provider is a drop-in code change, not configuration.
• Several capabilities are GitHub-only: Projects v2, the DeployWatcher (see Seam 2), and semver push-CD labels. On GitLab these degrade rather than fail, but you do not get feature parity.

For the read/write core - issues, comments, PRs/MRs, commit CI status - both providers are first-class.

Coupling hotspots¶

The couplings that stand between "tatara as shipped" and "tatara on your stack", ranked by how much they block the design intent. Each is real engineering, not a config change.

Can you run tatara on your stack?¶

A quick self-assessment. "Yes" means it works today with configuration; "Code" means it needs engineering first.

Honest verdict¶

See also¶

• Prerequisites - the full reference-stack shopping list this page reinterprets.
• CI/CD & Deploy Model - how the maintainer's helmfile GitOps cascade works in detail.
• Identity & OIDC - the OIDC client inventory and why every API is auth-gated.
• Memory Architecture - what the mandatory memory stack does and why.
• Agent Execution - the operator/agent HTTP wire that the portability seam is built on.
• Why tatara - trade-offs and minimum viable adoption.