Quickstart

This guide takes a cluster from empty to a working installation. It should take about fifteen minutes.

Prerequisites

A Kubernetes cluster with an ingress controller

Kubernetes 1.27 or later with a working kubectl context. The examples use the Traefik ingress class; substitute your own with ingress.className.

A storage class that supports ReadWriteOnce

Each user workspace and the bundled database request a ReadWriteOnce volume. The examples use rook-ceph-block. Set your own with workspace.storageClass and postgresql.storageClass.

Helm 3.8 or later

Helm 3.8 introduced stable OCI registry support, which the chart uses for its alternative install path.

An OpenAI-compatible API key

Any endpoint that implements /chat/completions and /models works, including OpenAI, OpenRouter, Together, Groq, vLLM, and Ollama behind HTTPS.

Create the namespace and secrets

The chart reads its sensitive configuration from a Kubernetes Secret. Generate the values locally so they never enter your shell history or a values file.

Create the namespace

kubectl create namespace r5d-chat

Generate and store the application secrets

BETTER_AUTH_SECRET signs session cookies and SETTINGS_ENCRYPTION_KEY encrypts stored provider credentials. Both must be at least 32 characters. SETUP_CLAIM_TOKEN prevents a stranger from claiming the installation before you do.

kubectl -n r5d-chat create secret generic r5d-chat-secrets \
  --from-literal=BETTER_AUTH_SECRET="$(openssl rand -base64 36)" \
  --from-literal=SETTINGS_ENCRYPTION_KEY="$(openssl rand -base64 36)" \
  --from-literal=SETUP_CLAIM_TOKEN="$(openssl rand -hex 24)" \
  --from-literal=POSTGRES_PASSWORD="$(openssl rand -base64 24)" \
  --from-literal=DATABASE_URL="postgresql://r5d_chat:PLACEHOLDER@r5d-chat-r5d-chat-postgresql:5432/r5d_chat"

DATABASE_URL must contain the same password as POSTGRES_PASSWORD when you use the bundled database. Generate the password once into a shell variable and substitute it into both keys, or set both after generating:

PGPASS="$(openssl rand -base64 24 | tr -d '/+=')"
kubectl -n r5d-chat create secret generic r5d-chat-secrets \
  --from-literal=BETTER_AUTH_SECRET="$(openssl rand -base64 36)" \
  --from-literal=SETTINGS_ENCRYPTION_KEY="$(openssl rand -base64 36)" \
  --from-literal=SETUP_CLAIM_TOKEN="$(openssl rand -hex 24)" \
  --from-literal=POSTGRES_PASSWORD="$PGPASS" \
  --from-literal=DATABASE_URL="postgresql://r5d_chat:${PGPASS}@r5d-chat-r5d-chat-postgresql:5432/r5d_chat"

Back up SETTINGS_ENCRYPTION_KEY with your database. Losing it makes every stored provider credential unreadable.

Add an image pull secret for private images

Skip this step if the images are public.

kubectl -n r5d-chat create secret docker-registry ghcr-pull \
  --docker-server=ghcr.io \
  --docker-username="<github-username>" \
  --docker-password="<github-token-with-read:packages>"

Install the chart

Add the Helm repository

helm repo add r5d-chat https://charts.r5d.dev
helm repo update
helm search repo r5d-chat --versions

Write a values file

Create values.yaml. publicUrl must be the exact external URL, because it is used for cookies, redirects, and the workspace callback address.

publicUrl: https://chat.example.com

existingSecret: r5d-chat-secrets

ingress:
  enabled: true
  className: traefik
  host: chat.example.com

postgresql:
  storageClass: rook-ceph-block
  storageSize: 5Gi

workspace:
  storageClass: rook-ceph-block
  storageSize: 10Gi
  idleSeconds: 1800

# Uncomment for private images.
# imagePullSecrets:
#   - name: ghcr-pull
# workspace:
#   imagePullSecret: ghcr-pull

Validate before applying

Render the exact values and dry-run them against the live API server. This catches admission errors before anything is created.

helm template r5d-chat r5d-chat/r5d-chat \
  --namespace r5d-chat -f values.yaml > /tmp/r5d-chat.yaml
kubectl apply --dry-run=server -f /tmp/r5d-chat.yaml

Install and wait for rollout

helm install r5d-chat r5d-chat/r5d-chat \
  --namespace r5d-chat --create-namespace \
  -f values.yaml --wait --timeout 10m

kubectl -n r5d-chat rollout status deployment/r5d-chat-r5d-chat
kubectl -n r5d-chat get pods,pvc,ingress

Database migrations run in an init container before the application starts, so a successful rollout means the schema is current.

Confirm the health endpoint

curl -fsS https://chat.example.com/api/health

A healthy installation returns {"ok":true}. This endpoint checks database connectivity, so a 503 usually means DATABASE_URL is wrong.

Claim the administrator account

The first successful setup request becomes the administrator and permanently closes public setup. Claim it immediately after exposing the installation.

Read the claim token

kubectl -n r5d-chat get secret r5d-chat-secrets \
  -o jsonpath='{.data.SETUP_CLAIM_TOKEN}' | base64 -d; echo

Complete setup in the browser

Open https://chat.example.com. The setup form asks for a name, email, password of at least 12 characters containing a letter and a number, and the claim token.

Verify that setup is closed

curl -fsS https://chat.example.com/api/setup

Expect {"required":false,...}. If it still reports true, the account was not created and the installation is still claimable.

Connect a model and run a task

Add a provider

Go to Settings → Providers and add an OpenAI-compatible endpoint with its base URL and API key. Use Test connection, which requests <base URL>/models through the server’s outbound URL guard.

HTTPS is required by default, and private, loopback, link-local, and metadata addresses are rejected. See Model providers for local-endpoint options.

Add a model

Add a model to the provider with its provider model ID, a display name, a context-window limit, and a maximum output token count. The first model you create becomes your default automatically.

Give the agent something to do

Start a chat and ask for real work, for example:

Create a CSV of the first 20 Fibonacci numbers in ~/artifacts,
then plot it as a PNG and give me both files.

The first message starts your workspace pod, which takes a few seconds. The agent writes files, runs Python, and returns download links.

Next steps

Invite users

Create invitations, add local accounts, and connect an OIDC provider.

Brand the installation

Set the product name, logo, favicon, and colors at runtime.

Understand the lifecycle

How idle workspaces scale to zero and keep their data.

Review security

What the isolation model does and does not guarantee.

Get started

Install

Configure

Operate

Reference

Prerequisites

Create the namespace and secrets

Install the chart

Claim the administrator account

Connect a model and run a task

Next steps

Invite users

Brand the installation

Understand the lifecycle

Review security

​Prerequisites

​Create the namespace and secrets

​Install the chart

​Claim the administrator account

​Connect a model and run a task

​Next steps

Invite users

Brand the installation

Understand the lifecycle

Review security

Prerequisites

Create the namespace and secrets

Install the chart

Claim the administrator account

Connect a model and run a task

Next steps