> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tembo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy

> Install Tembo on your cluster with one helm install.

> [!NOTE]
>
> Kubernetes support is currently in early access. To get on the list, book a demo call with the Tembo team: [Book a Demo](https://book.avoma.com/tembo/tembo-demo/)

Complete the [prerequisites](https://docs.tembo.io/features/self-hosted/kubernetes/prerequisites/overview.md) and set up [GitHub](https://docs.tembo.io/features/self-hosted/kubernetes/prerequisites/github.md) 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](https://docs.tembo.io/features/self-hosted/kubernetes/configuration.md).

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:

```bash theme={null}
read -s TEMBO_LICENSE_KEY
echo "$TEMBO_LICENSE_KEY" | helm registry login registry.tembo.io --username tembo --password-stdin
```

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:

```bash theme={null}
helm show chart oci://registry.tembo.io/tembo | grep '^version'
```

***

## On AWS

Create `values.yaml`:

```yaml theme={null}
licenseKey: '<your-license-key>'

ingress:
  className: alb
  host: tembo.example.com
  aws:
    enabled: true

github:
  existingSecret: tembo-github-app
```

`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](https://docs.tembo.io/features/self-hosted/kubernetes/prerequisites/aws.md#configure-the-chart-with-its-outputs), first so yours override them:

```bash theme={null}
helm install tembo oci://registry.tembo.io/tembo --version <version> \
  -n tembo --create-namespace \
  -f tembo.json -f values.yaml
```

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](https://docs.tembo.io/features/self-hosted/kubernetes/prerequisites/networking.md#2-dns) for Postgres, Redis, Sandbar and preview DNS.

The first agent host is ready in about four minutes:

```bash theme={null}
kubectl -n tembo get tembohosts
```

## On GCP

Create `values.yaml`:

```yaml theme={null}
licenseKey: '<your-license-key>'

ingress:
  host: tembo.example.com
  gcp:
    enabled: true

github:
  existingSecret: tembo-github-app
```

`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](https://docs.tembo.io/features/self-hosted/kubernetes/prerequisites/gcp.md#configure-the-chart-with-its-outputs), first so yours override them:

```bash theme={null}
helm install tembo oci://registry.tembo.io/tembo --version <version> \
  -n tembo --create-namespace \
  -f tembo.json -f values.yaml
```

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](https://docs.tembo.io/features/self-hosted/kubernetes/prerequisites/gcp.md#dns) for Postgres, Redis and Sandbar. Configure [preview DNS and TLS](https://docs.tembo.io/features/self-hosted/kubernetes/prerequisites/networking.md) 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:

```bash theme={null}
kubectl -n tembo get tembohosts
```

## 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](https://docs.tembo.io/features/self-hosted/kubernetes/prerequisites/gcp.md#sign-in-with-google) or [GitHub sign-in](https://docs.tembo.io/features/self-hosted/kubernetes/prerequisites/github.md#github-sign-in-and-connected-accounts) 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](https://docs.tembo.io/features/self-hosted/kubernetes/configuration.md#model-providers), such as session titles.
3. **Connect GitHub** in **Settings > Integrations** (see [Connect GitHub](https://docs.tembo.io/features/self-hosted/kubernetes/prerequisites/github.md#step-5-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](https://docs.tembo.io/features/self-hosted/kubernetes/prerequisites/github.md#gitops-and-helm-template) for offline rendering.

**On GCP, `kubectl` hangs.** Check [control-plane access](https://docs.tembo.io/features/self-hosted/kubernetes/prerequisites/gcp.md#vpc-and-subnetwork) 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](https://docs.tembo.io/features/self-hosted/kubernetes/prerequisites/github.md#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`:

```bash theme={null}
# AWS
aws ec2 get-console-output --instance-id <instance-id> --latest

# GCP
gcloud compute instances get-serial-port-output <instance> \
  --project=<hosts-project> --zone=<zone> | grep 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](https://docs.tembo.io/features/self-hosted/kubernetes/configuration.md#model-providers) 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](https://docs.tembo.io/features/self-hosted/kubernetes/configuration.md#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](https://docs.tembo.io/features/self-hosted/kubernetes/prerequisites/gcp.md#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](https://docs.tembo.io/features/self-hosted/kubernetes/configuration.md#instance-types).

***

## Need Help?

If you run into any issues, contact [support@tembo.io](mailto:support@tembo.io).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.