# Self-host AI agents

Deployment prerequisites, verification, and recovery for AI agents.

Source: https://railgrid.ai/docs/self-hosting/providers/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](https://railgrid.ai/docs/self-hosting/providers/) 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

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

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

```bash
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](https://github.com/railgrid/railgrid/blob/main/providers/agents/deploy/chart/README.md).

## 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](https://railgrid.ai/docs/self-hosting/providers/#a-fresh-provider-is-unready-until-a-workspace-binds-it). Enable Agents in a test workspace and follow the [AI agents quickstart](https://railgrid.ai/docs/use/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](https://github.com/railgrid/railgrid/blob/main/providers/agents/deploy/chart/values.yaml) are authoritative for this source baseline. Keep the deployed image and chart versions recorded together.