Install on Kubernetes

Choose a namespace and create it

The credentials have to exist before the chart that reads them, and a Secret is only readable by workloads in its own namespace, so the namespace comes first:

kubectl create namespace octo

Everything below assumes octo. Use whatever name you like.

Mint the credentials

Three secrets, generated once, on your machine. Nothing about them comes from Octo: they are random bytes with specific shapes. (The auth and embeddings Secrets come later, in the steps that turn those features on.)

# Postgres password for the bundled database
kubectl -n octo create secret generic octo-db-password \
  --from-literal=postgres-password="$(openssl rand -hex 24)"

# AES-256 key encrypting KV secret namespaces at rest: base64 of 32 raw bytes
kubectl -n octo create secret generic octo-kv-key \
  --from-literal=kv-encryption-key="$(openssl rand -base64 32)"

# HMAC key deriving every dev run's identity and public hostname
kubectl -n octo create secret generic octo-devrun-key \
  --from-literal=dev-run-hash-secret="$(openssl rand -base64 32)"

Write a values file

One file, and it holds no credentials: only the names of the Secrets you just created.

ingress:
  # The hostname you will point at your ingress controller.
  host: octo.example.com
  # The controller that should claim this Ingress. Omit it only if your cluster
  # marks one IngressClass default (`kubectl get ingressclass` says).
  className: nginx
  tls:
    # cert-manager issues a certificate per host over HTTP-01. See step 5 for
    # the alternatives.
    mode: cert-manager
    clusterIssuer: letsencrypt-prod
    secretName: octo-tls

postgres:
  auth:
    existingSecret: octo-db-password
    existingSecretPasswordKey: postgres-password

kv:
  existingSecret: octo-kv-key
  existingSecretKey: kv-encryption-key

orchestrator:
  devRuns:
    existingSecret: octo-devrun-key
    existingSecretKey: dev-run-hash-secret

That is a complete install. NATS, Redis, the observability service, the retention sweep and the schema job are on by default and need nothing said about them.

Install the chart

helm install octo oci://ghcr.io/juancavallotti/charts/octo \--version 0.11.7 \--namespace octo \--values octo-values.yaml

No --create-namespace: you made it in step 1, and Helm creating it would mean the Secrets had nowhere to go.

The chart pulls its images from Docker Hub by default, at the version of the chart itself: image.tag falls back to appVersion, so a chart installs the images of its own release rather than drifting onto latest. To pull from your own registry, add image.registry and, for a private one, defaults.imagePullSecrets.

Watch it come up:

kubectl -n octo get pods -w

Six pods reach Running, plus a schema Job that runs once and completes. If Postgres stays Pending, its volume has nowhere to come from; check kubectl get storageclass and kubectl -n octo describe pvc.

Point DNS at it, and settle TLS

Find the address your controller published, and create an A (or CNAME) record for ingress.host pointing at it:

kubectl -n octo get ingress

TLS is one of five modes, and which one you want is a property of your cluster rather than of Octo:

With cert-manager, DNS must resolve before the certificate can be issued, since the HTTP-01 challenge is a request to your own hostname. The first minute after DNS lands may serve the controller's default certificate; watch the real one arrive with:

kubectl -n octo get certificate

Open the editor

Visit https://octo.example.com in a browser.

The editor is open to anyone who can reach it at this point; step 7 is how you close it. If the host resolves to nothing, the usual cause is that no controller claimed the Ingress. kubectl -n octo describe ingress shows which class it asked for; kubectl get ingressclass shows what the cluster has.

Configure single sign-on

Signing in is how anybody reaches the editor — there is no open mode, and the chart refuses to render without the settings below. Any provider that speaks the authorization-code flow works. Register a client with yours, with this redirect URI:

https://octo.example.com/api/auth/callback/oidc

Then create the auth Secret, holding both credentials, because the chart reads them from one reference:

kubectl -n octo create secret generic octo-auth-creds \
  --from-literal=oidc-client-secret='<the client secret your provider issued>' \
  --from-literal=auth-secret="$(openssl rand -base64 32)"

and add to your values file:

auth:
  oidc:
    issuer: https://id.example.com
    clientId: octo
    # Optional: what the sign-in button calls your provider.
    providerName: Acme SSO
  existingSecret: octo-auth-creds
  # Optional: restrict writes to these roles. Empty means every role except
  # platform:monitor.
  writeRoles: ""

Upgrade to apply it:

helm upgrade octo oci://ghcr.io/juancavallotti/charts/octo \--version 0.11.7 --namespace octo --values octo-values.yaml

Publish your integrations

Each integration you deploy from the editor can get its own public hostname under a domain you nominate. Add:

orchestrator:
  # Integrations are published at {slug}.apps.example.com.
  baseDomain: apps.example.com
  # The controller that claims the Ingress the orchestrator creates per
  # deployment. Usually the same one as ingress.className, and it is also what
  # the branded 502/503 page is selected from, so name it even where the cluster
  # has a default IngressClass.
  ingressClass: nginx

wildcardTLS:
  # One *.apps.example.com certificate rather than one per subdomain.
  enabled: true
  clusterIssuer: letsencrypt-dns
  secretName: octo-wildcard-tls

Then point *.apps.example.com at the same ingress address.

Prefer the wildcard over per-host certificates, especially with dev runs on. A per-host certificate puts every hostname you deploy into public Certificate Transparency logs; one wildcard publishes the domain and nothing under it. The wildcard needs a DNS-01 ClusterIssuer, because HTTP-01 cannot issue a wildcard, which means giving cert-manager credentials for the zone.

Leaving baseDomain unset is supported: integrations still deploy and work, reachable in-cluster, with no external address.

Turn on semantic memory search (optional)

With an embedding server, searching agent memory ranks by meaning; without one it ranks by matching text. Both are supported.

kubectl -n octo create secret generic octo-embeddings-key \
  --from-literal=apiKey='<your provider key>'

embeddings:
  enabled: true
  connectorType: llm-openai   # or llm-gemini, llm-openrouter
  model: text-embedding-3-small
  dimensions: 1536
  existingSecret: octo-embeddings-key
  existingSecretKey: apiKey

The key is held in this one pod, rather than in every integration's pod.