Skip to main content
Kubernetes support is currently in early access. To get on the list, book a demo call with the Tembo team: Book a Demo
Complete the prerequisites and set up GitHub first. The values below name its Secret in github.existingSecret; leave that out to set up GitHub later. With their Helm values, the chart’s defaults run everything Tembo needs: the platform, Postgres and Redis, and a pool of agent hosts. To change any of it, see Configuration. Don’t pass --wait to the first helm install with Helm 4. Its default wait strategy waits for the host pool, which becomes ready only after the chart’s post-install database migrations run, so the install times out. Later helm upgrade --wait runs are fine, since migrations run before the upgrade. The chart is at oci://registry.tembo.io/tembo. Sign Helm in to the registry with your license key as the password:
Each chart version runs one Tembo release, so --version below is the only version you pin; to upgrade Tembo, upgrade to a newer chart. To see the latest version:

On AWS

Create values.yaml:
ingress.aws serves Tembo through internet-facing ALBs that redirect HTTP to HTTPS, with your ACM certificate. Install the chart with the module’s values, tembo.json from AWS prerequisites, first so yours override them:
Without external-dns, create DNS records once the load balancers exist (kubectl -n tembo get ingress,svc shows them): your public hostname for the Ingress, and private records for the internal Services. Follow Networking for Postgres, Redis, Sandbar and preview DNS. The first agent host is ready in about four minutes:

On GCP

Create values.yaml:
ingress.gcp serves Tembo through GKE’s Ingress with a Google-managed certificate for your hostname, and redirects HTTP to HTTPS. Install the chart with the module’s values, tembo.json from GCP prerequisites, first so yours override them:
Without external-dns, create DNS records once the load balancers exist (kubectl -n tembo get ingress,svc shows them): your public hostname for the Ingress, and Cloud DNS private records for Postgres, Redis and Sandbar. Configure preview DNS and TLS too. The certificate is issued once your hostname resolves to the Ingress, which can take up to an hour. The first agent host is ready in a few minutes:

On Azure

Coming soon.

After installing

  1. Sign in. Open https://<your-host>, sign up and create your workspace. To use Google or GitHub login, configure Google sign-in or GitHub sign-in before inviting teammates.
  2. Add model credentials in Settings > Models before starting a session. Configure the provider for the agent and model you select, plus the credentials needed for internal prompts, such as session titles.
  3. Connect GitHub in Settings > Integrations (see Connect GitHub).
  4. Start a session on one of your repositories. Confirm a turn finishes and a session title appears; then send another message to verify continued connectivity.
Self-hosted installs don’t email invitations: teammates sign up at https://<your-host>/sign-up, then you invite them under Settings > Workspace > Members.

Troubleshooting

A first-install dry run fails on missing custom resources. helm install --dry-run=server cannot install the chart’s CRDs, so custom resource validation can fail on a fresh cluster. helm template also cannot read github.existingSecret, google.existingSecret or configSecrets. These errors do not by themselves mean the real install will fail. See GitOps and helm template for offline rendering. On GCP, kubectl hangs. Check control-plane access and fetch credentials for the DNS endpoint. An IP endpoint with an empty authorized-networks allowlist can time out without an immediate error. Connecting a personal GitHub account fails with “Missing OAuth redirect URL”. Configure GitHub sign-in and connected accounts; the repository GitHub App settings alone do not enable it. A host doesn’t reach Ready. The controller replaces a host that doesn’t register within 15 minutes. Read its boot log and look for tembo-host-config:
Hosts must reach the cluster’s API endpoint and resolve and connect to the private postgres. and redis. hostnames. On GCP, check the private endpoint’s authorized networks as well as firewall rules. Boot logs may contain configuration URLs or credentials; redact them before sharing. Connecting GitHub fails with “Failed to get extra data for integration”. The GitHub App needs the Members organization permission. Set it to Read-only, approve the change on your organization’s installation, then connect again. GitHub says it sent an installation request. Only owners of the GitHub organization can connect it. The agent can’t clone a repository. Enable it in Settings > Repositories. Webhooks never arrive. Check the GitHub App’s Advanced > Recent deliveries. If GitHub can’t connect, your Ingress, or the public one with ingress.public, isn’t reachable from the internet. If deliveries succeed, check the app’s webhook secret against the one the install notes print. Inviting a teammate fails with “Organization member not found”. They need to sign up first. Sessions fail with a provider 401, or titles never appear. Check the selected agent’s credentials and the separate requirements for internal prompts in Settings > Models. A working provider for one agent does not authorize every model. Sessions fail at once, with “too many clients already” in the API’s logs. Postgres is out of connections. See Postgres and Redis. On GCP, agents fail with “Unable to connect” once a few sessions run. The agent host is out of Cloud NAT ports. Turn on dynamic port allocation (see VPC and subnetwork). The NAT’s dropped_sent_packets_count metric with reason OUT_OF_RESOURCES confirms it. A session fails with “Host CPU count (…) is too small” or “Host total memory (…) is too small”. Its size doesn’t fit your hosts’ instance type. See Instance types.

Need Help?

If you run into any issues, contact support@tembo.io.