Self-host AI agents

Prerequisites

You need a Kubernetes runtime you administer, Helm, network access from the provider runtime to the hub and advertised virtual-workspace endpoints, and permission to onboard this provider. Use the common provider flow to obtain the workspace kubeconfig. The examples below use a Secret named railgrid-provider-kubeconfig with data key kubeconfig.

Postgres is the provider’s only hard dependency beyond the hub: conversations, runs, and memory live there, in plaintext. Encryption at rest is the database’s responsibility.

Install

kubectl create namespace railgrid-provider-agents
kubectl --namespace railgrid-provider-agents create secret generic railgrid-provider-kubeconfig \
  --from-file=kubeconfig=./agents.kubeconfig
kubectl --namespace railgrid-provider-agents create secret generic agents-db \
  --from-literal=database-url='postgres://USER:PASSWORD@HOST:5432/agents?sslmode=require'

agents-values.yaml:

replicaCount: 2
hub:
  url: https://railgrid-hub.railgrid-system.svc.cluster.local:9443
  # Public hub address for harness-backed agents that configure themselves.
  publicURL: https://console.example.com
  tokenSecretRef:
    name: ""
catalogEntry:
  enabled: true
store:
  databaseURLSecretRef:
    name: agents-db          # key database-url
  inMemoryStore: false

helm upgrade --install agents oci://ghcr.io/railgrid/charts/railgrid-agents-provider \
  --version CHART_VERSION --namespace railgrid-provider-agents --values agents-values.yaml

The chart README contains the matching values table for the deployed version: chart instructions .

Provider requirements

Keep store.inMemoryStore: false; the in-memory store is an explicit non-durable fallback for development. Add envFromSecret naming a Secret whose keys become environment variables when the provider itself needs model or channel credentials; tenants otherwise supply theirs through connections. Hosted MCP Apps are denied unless their HTML digests are listed in mcpApps.approvedDigests.

Verify

Run kubectl -n railgrid-provider-agents get pods and wait for Ready, then confirm a fresh catalog heartbeat in the hub. A fresh provider stays unready until a workspace enables it; see the common flow . Enable Agents in a test workspace and follow the AI agents quickstart .

Recover

If a rollout fails, keep the previous chart/image and inspect pod events and provider logs before changing the database. Restore Postgres from its supported backup, verify the Secret key and schema compatibility, then re-enable scheduled work.

Configuration reference

Chart values are authoritative for this source baseline. Keep the deployed image and chart versions recorded together.