Install Tiphys

This is the end-to-end install guide. Follow it top to bottom and you'll have Tiphys running in your cluster in about 15 minutes.

Tiphys runs on any Kubernetes 1.29+ cluster, with the model of your choice (Choose your model). This guide walks through EKS with Amazon Bedrock first, since its IAM steps are the longest; Other clusters covers AKS, GKE, and on-prem.

Tiphys is free

Every module is available without a license. There is no subscription, no usage metering, and no license server.

Your data stays in your account

Tiphys runs inside your cluster and sends its prompts only to the model you choose. With your cloud's model service (Amazon Bedrock, Vertex AI, Azure) or a model you host, chat context and cluster details stay inside your own account, project or tenant, and the model's costs are billed there at standard rates; nothing proxies or marks up inference. With the Anthropic API, prompts go to Anthropic under your API key and your agreement with Anthropic. There is no outbound telemetry, and no phone-home unless you turn on controlPlane.enabled (off by default), which only reads Intelligant AI's public status for Tiphys and sends nothing about your cluster.

The only outbound calls the pod makes are to your model and (with the cloud module) your cloud's APIs for inventory reads, plus that status read if you opt in to the control plane (configuration). Everything else is in-cluster. Under a public API, the ship-default keeps the reader ClusterRole's Secret verbs off so Secret contents can't flow into prompts; see Data residency by inference provider before enabling rbac.helmValuesDecode=true.

Choose your model

Tiphys is tuned for Claude, and every provider below except the last serves it. Whatever you choose, the model must use tools and take at least 64k tokens of context.

Provider	`llm.provider`	Access
The Anthropic API	`anthropic`	An API key, in a Secret
Amazon Bedrock	`bedrock` (default)	Keyless (IRSA or EKS Pod Identity)
Google Cloud Vertex AI	`vertex`	Keyless (workload identity)
Microsoft Azure: AI Foundry or Azure OpenAI	`azure`	Keyless (workload identity), or the resource's key
Any OpenAI-compatible endpoint	`openai-compatible`	A key, if it needs one

Prefer a keyless provider where you can: there's no key to rotate or leak. Configuration has every value and the keyless setup for each.

Prerequisites

Kubernetes 1.29 or newer. The backend runs as a native sidecar container; on older clusters the pod stays in Init.
kubectl, helm 3.14+, and (for EKS) the aws CLI configured for the target account.
Cluster-admin access for the one-time setup (IAM role, trust policy, RBAC install).
Access to your model: for Bedrock, model access enabled in your chosen region for Claude Haiku and Claude Sonnet. New AWS accounts: open the Bedrock console, click through the model-access opt-in, and wait a few minutes. Bedrock requests return 403 until the model is opted in.

Step 1: Choose IRSA or EKS Pod Identity

Tiphys authenticates pod-to-AWS via one of:

	IRSA	Pod Identity
EKS version	1.19 or newer	1.27 or newer
Trust mechanism	OIDC federation	EKS service principal
One-time cluster setup	Create OIDC provider	Install eks-pod-identity-agent addon
Rotation	Automatic (OIDC tokens)	Automatic (EKS-managed)
Recommended	Default for most installs	Use if already adopted

The rest of this guide uses IRSA. If you already run Pod Identity, skip Step 2 and create a Pod Identity association on the tiphys service account after the Helm install (Step 5).

Step 2: Register the cluster's OIDC provider (IRSA only)

eksctl utils associate-iam-oidc-provider \
  --cluster <your-cluster-name> \
  --approve

Only happens once per cluster. If you provisioned the cluster with terraform-aws-modules/eks/aws and set enable_irsa = true, this is already done.

Step 3: Create the IAM role

Name it something like tiphys-irsa-role. The role's trust policy must match the tiphys service account in the tiphys namespace.

Get your cluster's OIDC provider ID:

aws eks describe-cluster \
  --name <your-cluster> \
  --query "cluster.identity.oidc.issuer" \
  --output text

The ID is the suffix on that URL. Save the trust policy below as trust-policy.json, replacing the three placeholders:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<AWS_ACCOUNT_ID>:oidc-provider/oidc.eks.<REGION>.amazonaws.com/id/<OIDC_ID>"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "oidc.eks.<REGION>.amazonaws.com/id/<OIDC_ID>:sub": "system:serviceaccount:tiphys:tiphys",
          "oidc.eks.<REGION>.amazonaws.com/id/<OIDC_ID>:aud": "sts.amazonaws.com"
        }
      }
    }
  ]
}

Create the role:

aws iam create-role \
  --role-name tiphys-irsa-role \
  --assume-role-policy-document file://trust-policy.json

Step 4: Attach policies per module

Copy the policy JSON for each module you plan to enable from IAM setup. That page is the canonical copy and is checked against the policies in the repo on every change.

Core: always required. Bedrock inference plus CloudWatch reads.
Cloud: required if you set modules.cloud.enabled=true. Read-only AWS inventory and cost. It never grants secretsmanager:GetSecretValue; Tiphys reads secret metadata, never contents.
Core Plus: writes are Kubernetes-side only, through the chart's writer ClusterRole, so this policy adds no AWS write access.

Save each as a file and attach it inline:

aws iam put-role-policy \
  --role-name tiphys-irsa-role \
  --policy-name tiphys-core \
  --policy-document file://tiphys-core.json

Step 5: Install with Helm

The chart and multi-arch images (linux/amd64 + linux/arm64) are published to GitHub Container Registry.

helm install tiphys \
  oci://ghcr.io/intelligant-ai/charts/tiphys \
  --version <version> \
  --namespace tiphys --create-namespace \
  --set service_account_role_arn="arn:aws:iam::<ACCOUNT_ID>:role/tiphys-irsa-role" \
  --set llm.bedrock.region=<REGION>

To turn on more modules, add for example --set modules.cloud.enabled=true or --set modules.corePlus.enabled=true --set modules.corePlus.writeOperations.enabled=true. See Modules and Configuration.

Air-gapped clusters: mirror the two images and the chart to an internal registry, then set images.backend.repository and images.frontend.repository (plus images.pullSecrets if that registry needs credentials).

Other clusters

On AKS, GKE, or on-prem clusters, skip the IAM steps and choose your model. With the Anthropic API, keep the key in a Secret:

kubectl create namespace tiphys
kubectl create secret generic tiphys-anthropic -n tiphys \
  --from-literal=api_key=<your Anthropic API key>
helm install tiphys \
  oci://ghcr.io/intelligant-ai/charts/tiphys \
  --version <version> \
  --namespace tiphys \
  --set llm.provider=anthropic \
  --set llm.anthropic.existingSecret=tiphys-anthropic

Claude on Vertex AI from GKE, keyless through workload identity:

helm install tiphys \
  oci://ghcr.io/intelligant-ai/charts/tiphys \
  --version <version> \
  --namespace tiphys --create-namespace \
  --set llm.provider=vertex \
  --set llm.vertex.project=<project> \
  --set llm.vertex.region=us-east5 \
  --set llm.vertex.serviceAccount=<name>@<project>.iam.gserviceaccount.com

Claude in Azure AI Foundry from AKS, keyless through workload identity:

helm install tiphys \
  oci://ghcr.io/intelligant-ai/charts/tiphys \
  --version <version> \
  --namespace tiphys --create-namespace \
  --set llm.provider=azure \
  --set llm.azure.endpoint=https://<resource>.services.ai.azure.com \
  --set llm.azure.workloadIdentity.clientId=<managed identity client ID>

Or any OpenAI-compatible endpoint (a gateway, vLLM, Ollama):

helm install tiphys \
  oci://ghcr.io/intelligant-ai/charts/tiphys \
  --version <version> \
  --namespace tiphys --create-namespace \
  --set llm.provider=openai-compatible \
  --set llm.openaiCompatible.endpoint=https://<your-endpoint>/v1 \
  --set llm.openaiCompatible.existingSecret=<secret with api_key> \
  --set llm.openaiCompatible.models.fast=<model> \
  --set llm.openaiCompatible.models.smart=<model>

Configuration covers the roles and trust each keyless provider needs. The cloud module's inventory reads are AWS-only today.

Step 6: Open the UI

kubectl port-forward -n tiphys svc/tiphys 8080:8080

Open http://localhost:8080 and sign in as admin. On first start Tiphys creates the account with a one-time password and keeps it on its state volume. Print it with:

kubectl -n tiphys exec tiphys-0 -c backend -- cat /var/lib/tiphys/initial-admin-password

The first sign-in asks you to choose your own password, and the one-time password stops working. If you forget it later:

kubectl -n tiphys exec tiphys-0 -c backend -- python -m ops_agent.reset_admin

After signing in, the dashboard shows module status and the first knowledge-graph scan (takes 5-30 seconds depending on cluster size).

For production access (ALB, ingress, auth-aware proxy for per-operator accountability), see UI Access.

Step 7: First conversation

Try these to verify the install:

Health check: "What's the health of my cluster?" kicks off the reporter on demand and surfaces findings by severity.
Convention detection: "What conventions have you learned about this cluster?" lists the patterns the scanner picked up.
Cloud inventory (cloud module): "What IAM roles does this account have?" lists them via the IRSA role.
Manifest generation (Core Plus): "Create a web service manifest for a workload called api in namespace staging, image myorg/api:1.0, exposed on 8080."

Common install issues

Pod stuck in Init: the cluster is older than Kubernetes 1.29, so the backend sidecar is treated as an init container that never finishes. Upgrade the cluster.
ImagePullBackOff: the nodes can't reach ghcr.io, or you're pulling from a mirror that needs images.pullSecrets.
403 from Bedrock: the IRSA role is missing bedrock:InvokeModel / bedrock:Converse, or Bedrock model access wasn't requested in the console. The chat surface prints the exact failing action with a paste-ready IAM fragment.
Cloud module shows active: false after enabling in Helm: most commonly a missing cloud policy attachment or a trust-policy typo. Run aws_irsa_mapping from the chat UI for a one-shot diagnosis.
Helm releases in chat have no status, history or values, or helm_call values returns a permission error: the reader ClusterRole has no Secret access by default, and Helm 3 stores releases as Secrets, so Tiphys lists releases from the labels Helm puts on what it installs ("source": "labels"). For the full view, set rbac.helmValuesDecode=true, only after reading Data residency by inference provider.
Prometheus tool errors with "not configured": Tiphys auto-discovers Prometheus via Services whose name contains prometheus on port 9090. If your install uses a proxy or a non-standard name, set integrations.prometheus.url explicitly in Helm values.

Verifying the setup

Hit /api/status or the Knowledge view in the UI. You should see:

All expected modules showing active: true
No blockedReason on any module
Cloud integrations (Prometheus, metrics-server, external-secrets) detected as expected

If an AWS API call fails at runtime, Tiphys surfaces the exact missing action in chat with a paste-ready policy fragment:

The agent was denied 'ListRoles' on aws:iam
Fix: add iam:ListRoles to the policy attached to tiphys-irsa-role.

Add the action and reattach the policy. If multiple calls fail in quick succession, grant the superset rather than iterating one at a time.

Try it on a local cluster: the Tiphys SaaS on kind, k3d or Docker Desktop, with nothing to install but the connector
Configuration: every Helm value explained
Modules: what each module unlocks
Write Operations: the approval flow for Core Plus
Troubleshooting: common runtime issues
UI Access: production ingress + auth-aware proxy
Backup and Restore: protecting the state PVC