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

# Quickstart

> Install r5d.chat into a Kubernetes namespace, claim the administrator account, and run a first agent task.

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

## Prerequisites

<AccordionGroup>
  <Accordion title="A Kubernetes cluster with an ingress controller" icon="dharmachakra">
    Kubernetes 1.27 or later with a working `kubectl` context. The examples use
    the Traefik ingress class; substitute your own with `ingress.className`.
  </Accordion>

  <Accordion title="A storage class that supports ReadWriteOnce" icon="hard-drive">
    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`.
  </Accordion>

  <Accordion title="Helm 3.8 or later" icon="cube">
    Helm 3.8 introduced stable OCI registry support, which the chart uses for
    its alternative install path.
  </Accordion>

  <Accordion title="An OpenAI-compatible API key" icon="key">
    Any endpoint that implements `/chat/completions` and `/models` works,
    including OpenAI, OpenRouter, Together, Groq, vLLM, and Ollama behind HTTPS.
  </Accordion>
</AccordionGroup>

## 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.

<Steps>
  <Step title="Create the namespace">
    ```bash theme={null}
    kubectl create namespace r5d-chat
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    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"
    ```

    <Warning>
      `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:

      ```bash theme={null}
      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"
      ```
    </Warning>

    Back up `SETTINGS_ENCRYPTION_KEY` with your database. Losing it makes every
    stored provider credential unreadable.
  </Step>

  <Step title="Add an image pull secret for private images">
    Skip this step if the images are public.

    ```bash theme={null}
    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>"
    ```
  </Step>
</Steps>

## Install the chart

<Steps>
  <Step title="Add the Helm repository">
    ```bash theme={null}
    helm repo add r5d-chat https://charts.r5d.dev
    helm repo update
    helm search repo r5d-chat --versions
    ```
  </Step>

  <Step title="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.

    ```yaml theme={null}
    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
    ```
  </Step>

  <Step title="Validate before applying">
    Render the exact values and dry-run them against the live API server. This
    catches admission errors before anything is created.

    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Install and wait for rollout">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Confirm the health endpoint">
    ```bash theme={null}
    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.
  </Step>
</Steps>

## Claim the administrator account

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

<Steps>
  <Step title="Read the claim token">
    ```bash theme={null}
    kubectl -n r5d-chat get secret r5d-chat-secrets \
      -o jsonpath='{.data.SETUP_CLAIM_TOKEN}' | base64 -d; echo
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="Verify that setup is closed">
    ```bash theme={null}
    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.
  </Step>
</Steps>

## Connect a model and run a task

<Steps>
  <Step title="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.

    <Note>
      HTTPS is required by default, and private, loopback, link-local, and
      metadata addresses are rejected. See
      [Model providers](/configure/providers) for local-endpoint options.
    </Note>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Invite users" icon="user-plus" href="/configure/authentication">
    Create invitations, add local accounts, and connect an OIDC provider.
  </Card>

  <Card title="Brand the installation" icon="palette" href="/configure/branding">
    Set the product name, logo, favicon, and colors at runtime.
  </Card>

  <Card title="Understand the lifecycle" icon="arrows-rotate" href="/operate/workspaces">
    How idle workspaces scale to zero and keep their data.
  </Card>

  <Card title="Review security" icon="shield-halved" href="/operate/security">
    What the isolation model does and does not guarantee.
  </Card>
</CardGroup>