TIPHYSby Intelligant AI

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. The fullest experience is on AWS EKS with Amazon Bedrock, which this guide walks through first; 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, under the recommended EKS install, uses your own Amazon Bedrock in your AWS account for every inference call. Cluster telemetry, chat context, and generated artifacts never leave your account. There is no SaaS control plane and no outbound telemetry.

The only outbound network calls the pod makes are to Bedrock and (with the cloud module) the AWS APIs for inventory reads. Everything else is in-cluster. Bedrock costs are billed to your AWS account at standard AWS rates; nothing proxies or marks up inference usage.

Alternate providers. Tiphys also supports any OpenAI-compatible endpoint via llm.provider: openai-compatible, including Azure OpenAI, Google Vertex (through a compatibility layer), self-hosted Ollama, self-hosted vLLM, and public APIs like Anthropic and OpenAI. Under a cloud-native provider (Bedrock, Azure OpenAI, Vertex) or a self-hosted provider (Ollama, vLLM), context stays inside your trust boundary. Under a public API provider (Anthropic API, OpenAI API), context reaches that provider's public endpoint under your API key. In that mode the ship-default is to keep the reader ClusterRole's Secret verbs disabled so Secret contents cannot flow into prompts. See the RBAC docs' Data residency by inference provider matrix before enabling rbac.helmValuesDecode=true.

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).
  • 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:

IRSAPod Identity
EKS version1.19 or newer1.27 or newer
Trust mechanismOIDC federationEKS service principal
One-time cluster setupCreate OIDC providerInstall eks-pod-identity-agent addon
RotationAutomatic (OIDC tokens)Automatic (EKS-managed)
RecommendedDefault for most installsUse 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 clu-core \
  --policy-document file://clu-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 point Tiphys at an OpenAI-compatible endpoint instead of Bedrock:

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.apiKey=<key> \
  --set llm.openaiCompatible.models.fast=<model> \
  --set llm.openaiCompatible.models.smart=<model>

Prefer llm.openaiCompatible.existingSecret over apiKey outside of a quick trial. 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/clu/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 list in chat returns a permission error: the reader ClusterRole has no Secret access by default, and Helm 3 stores releases as Secrets. 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.

Next

NextCapabilities overview