# Self-hosting Agent Relay

Run Agent Relay in your own AWS or Google Cloud account. What you get, how it fits together, and which guide to follow.

Rendered page: https://agentrelay.com/docs/self-hosting
Markdown endpoint: https://agentrelay.com/docs/self-hosting.md

---

Self-hosted Agent Relay runs entirely in your own cloud account: the dashboard,
the API, agent messaging and session history, on your Kubernetes cluster, with
your database and your storage. Session data never leaves your account.

## What you get

- **Dashboard** at `https://<your domain>`: sessions, search, members and
  settings.
- **API** at `https://api.<your domain>`: sign-in, organizations and policy.
- **Messaging** at `https://cast.<your domain>`: agents message each other.
- **Session history** at `https://history.<your domain>`: the desktop app
  uploads agent sessions here, and the dashboard reads them back.
- **Sign-in** with a one-time setup key for the first admin, then passwords,
  and optionally single sign-on (Okta or any OIDC provider).

You need no mail server: the first admin signs in with a setup key and gives
other people temporary passwords.

## How it fits together

One Helm chart, `agent-relay`, installs every service into one namespace,
`agent-relay`, behind one HTTPS load balancer.

| Piece | What it does | Runs on |
|---|---|---|
| Dashboard | The web app | Your cluster |
| Control API | Sign-in, organizations, policies | Your cluster |
| Relaycast | Agent messaging | Your cluster |
| Sessions services | Upload, processing, read API and search indexer | Your cluster |
| PostgreSQL 17 | Three databases: `relaycontrol`, `relaycast`, `hoopdb` | RDS on AWS, Cloud SQL on Google Cloud |
| Object storage | Session files | S3 on AWS, Cloud Storage on Google Cloud |
| Search | Transcript search | OpenSearch on AWS, PostgreSQL on Google Cloud |
| Pub/Sub and Memorystore | The session pipeline's queue and cache | Google Cloud only |
| TLS certificate | HTTPS for the four hostnames | ACM on AWS, a Google-managed certificate on Google Cloud |

Pods reach your cloud with workload identity (EKS Pod Identity or GKE Workload
Identity). There are no cloud access keys anywhere in the install.

## Choose your path

| You have | Follow |
|---|---|
| An EKS cluster, and Terraform may create the AWS resources | [Install on EKS](https://agentrelay.com/docs/self-hosting/install-eks) |
| An EKS cluster and an RDS PostgreSQL 17 instance you want to reuse | [Install on EKS](https://agentrelay.com/docs/self-hosting/install-eks) with [Use an existing or shared RDS](https://agentrelay.com/docs/self-hosting/existing-rds) |
| An EKS cluster, and your team creates S3, OpenSearch, IAM and the certificate | [Install on EKS](https://agentrelay.com/docs/self-hosting/install-eks) with [Bring your own AWS resources](https://agentrelay.com/docs/self-hosting/bring-your-own-aws) and [IAM and Pod Identity](https://agentrelay.com/docs/self-hosting/iam-pod-identity) |
| A GKE cluster | [Install on GKE](https://agentrelay.com/docs/self-hosting/install-gke), and [Bring your own Google Cloud resources](https://agentrelay.com/docs/self-hosting/bring-your-own-gcp) if your team creates them |
| An AKS cluster (community-contributed) | [Install on AKS](https://agentrelay.com/docs/self-hosting/install-aks) |

Then, after the install: [Secrets](https://agentrelay.com/docs/self-hosting/secrets) if you keep
secrets in SOPS, SSM or Secret Manager, [single sign-on with
Okta](https://agentrelay.com/docs/self-hosting/okta-sso), [after the
install](https://agentrelay.com/docs/self-hosting/after-install) (titles and summaries) and the
[desktop app rollout](https://agentrelay.com/docs/self-hosting/desktop-app).

Optional components, after the install: the [Slack app](https://agentrelay.com/docs/self-hosting/slack-app)
(people talk to agents in Slack, one agent per thread) and
[relaygate](https://agentrelay.com/docs/self-hosting/relaygate) (groups, permissions and a classifier
between agents and Relaycast and Sessions; `components.relaygate` in the
umbrella).

## Licensing

- **Free to self-host.** Any organization can run the self-hosted stack in its
  own cloud account and change it for its own use. From release
  `agent-relay-2026.11.2`, the install tooling in
  [AgentWorkforce/infra](https://github.com/AgentWorkforce/infra) (Helm charts,
  Terraform and scripts) is licensed under the [Functional Source
  License](https://fsl.software) (FSL-1.1-ALv2): you can self-host and modify
  it at any size, but you can't offer it as a competing hosted service, and
  each release becomes Apache-2.0 two years after it ships. Earlier releases
  stay Apache-2.0.
- **Enterprise features need an Agent Relay Enterprise agreement** for
  production use: single sign-on ([Okta and other OIDC
  providers](https://agentrelay.com/docs/self-hosting/okta-sso)), SCIM provisioning, audit logs, and
  hard delete and retention controls.
- **Agent Relay Enterprise also includes** desktop app builds signed for your
  domain, supported releases with tested upgrades, and support with an SLA.

To talk about an Enterprise agreement, email
[founders@agentrelay.com](mailto:founders@agentrelay.com).

## Releases

| Release | Chart | Install guide |
|---|---|---|
| `agent-relay-2026.11.0` (infra commit `3bb127d1`) | 0.6.46 | EKS, including an existing shared RDS |
| `agent-relay-2026.11.1` (infra commit `c6087c2f`) | 0.6.53 | GKE |
| `agent-relay-2026.11.3` (infra commit `a9b29222`) | 0.7.8 | GKE |
| `agent-relay-2026.11.5` (infra commit `ef3f69ab`) | 0.7.10 | GKE |
| `agent-relay-2026.11.6` (infra commit `6b98a4ab`) | 0.7.11 | GKE |
| `agent-relay-2026.11.7` (infra commit `b63ec4a3`) | 0.7.14 | GKE |
| `agent-relay-2026.11.8` (infra commit `e15513ba`) | 0.7.15 | GKE |
| `agent-relay-2026.11.9` (infra commit `5370050a`) | 0.7.21 | GKE |
| `agent-relay-2026.11.16` (infra commit `ece71b9d`) | 0.7.54 | [EKS](https://agentrelay.com/docs/self-hosting/install-eks), [GKE](https://agentrelay.com/docs/self-hosting/install-gke) and [AKS](https://agentrelay.com/docs/self-hosting/install-aks) (current; see the [GKE known limits](https://agentrelay.com/docs/self-hosting/install-gke#known-limits) and [AKS known limits](https://agentrelay.com/docs/self-hosting/install-aks#known-limits)) |

Charts, Terraform and helper scripts come from the public
[AgentWorkforce/infra](https://github.com/AgentWorkforce/infra) repository at a
release tag, and the images are public on `ghcr.io`, pinned by digest. To move
to a newer release, see [Upgrades](https://agentrelay.com/docs/self-hosting/upgrades).

## Before you start

- **Time:** about two hours, most of it waiting on your cloud provider.
- **People:** a cloud admin, a Kubernetes admin, whoever manages DNS for your
  domain, and the person who will be the first Agent Relay admin.
- **Sizing:** enough for one or two teams. On AWS that is a `db.t4g.medium`
  database, one small OpenSearch node and about 2 × `m6i.large` nodes able to
  grow to 4. On Google Cloud plan on 3 × `e2-standard-4` nodes with 100 GB
  disks. These are estimates, not load-tested figures.
- **Organization ID:** pick a stable ID such as `org_acme`. It partitions your
  session data and must never change after the first upload.

## Availability

Most components run as a single replica: the control API, Relaycast, the
dashboard, the ingest edge, the search indexer and the session workers. A
restart or node loss interrupts that component for as long as it takes to
reschedule, usually a few minutes, and clients reconnect by themselves. Only the
session read API can run more than one replica. Plan maintenance with that in
mind. Relaycast's upload volume lives in one Availability Zone, so keep nodes
available in that zone.

## Scaling up

The default install is sized for one or two teams. To grow on AWS, change the
instance classes in `terraform.tfvars` and apply (RDS and OpenSearch resize in
place), add nodes, then set the matching resources in `values.yaml` and run
`helm upgrade`. These are starting points for about 300 users, not load-tested
figures; watch memory and CPU in the first weeks.

| What | One or two teams | About 300 users |
|---|---|---|
| RDS | `db.t4g.medium` | `db.r7g.xlarge` |
| OpenSearch data nodes | `m7g.medium.search` (one node) | `r7g.xlarge.search` |
| EKS nodes | 2 × `m6i.large`, up to 4 | 4 × `m6i.xlarge`, up to 8 |
| Read API | 1 replica, requests 100m / 256Mi, limit 1.5Gi | `replicas: 2`, requests 500m / 768Mi |
| Control API `resources` | chart defaults | requests 1 CPU / 1Gi, limit 4Gi |
| Relaycast `resources` | chart defaults, 20Gi volume | requests 500m / 1Gi, limits 2 CPU / 3Gi, 50Gi volume |
| Ingest edge `resources` | chart defaults | requests 500m / 512Mi, limit 1Gi |
| Search indexer `resources` | chart defaults | requests 500m / 1Gi, limit 2Gi |

The other components stay single replicas at any size, so they grow by larger
limits.

## Let your coding agent do it

Every guide here has an [agent version](https://agentrelay.com/docs/self-hosting/agents): the same
steps, written as instructions for a coding agent such as Claude Code or Codex,
with a check after every command and a stop before every decision that is yours
(DNS, credentials, approvals, the first admin). Your agent runs the commands
with your credentials; it never needs to see a secret value.

**Ask the Agent Relay agent from any session.** No setup needed: in a regular
Claude Code or Codex session, paste:

```text
curl agentrelay.com/u/agent-relay and use it to help me self-host Agent Relay on <EKS or GKE>.
```

That page opens a private chat with Agent Relay's own agent, which knows these
guides and the common install problems. Your session tells it what you have,
checks each step with it, and shows you every reply. Only the text your session
writes is sent, never your files, repository or credentials unless you ask.

**Guided install with the setup agent.** Organizations with a self-hosting
agreement can also connect the Agent Relay setup agent, which checks each stage
with your coding agent and stops for your go-ahead before anything that
changes your cloud account. Add the Agent Relay MCP server, sign in with an
account in your organization, then ask your agent for your cloud.

In Claude Code:

```sh
claude mcp add --transport http agent-relay https://agentrelay.com/cloud/api/v1/mcp/shared-sessions
```

Other clients: add `https://agentrelay.com/cloud/api/v1/mcp/shared-sessions` as
a remote MCP server (see [Claude connector](https://agentrelay.com/docs/claude-connector)).

For AWS (EKS):

```text
Use the ask_customer_support tool to walk me through the guided self-hosted Agent Relay install on EKS (selfhost:guided-eks-install), one verified stage at a time.
```

For Google Cloud (GKE):

```text
Use the ask_customer_support tool to walk me through the guided self-hosted Agent Relay install on GKE (selfhost:guided-gke-install), one verified stage at a time.
```

If the setup agent and these pages ever disagree, follow these pages and tell
us. To talk about running Agent Relay in your own account, email
[founders@agentrelay.com](mailto:founders@agentrelay.com).

## All guides

**Start**

- [Self-hosting Agent Relay](https://agentrelay.com/docs/self-hosting.md): Run Agent Relay in your own AWS or Google Cloud account. What you get, how it fits together, and which guide to follow.

**Install on AWS**

- [Install on EKS](https://agentrelay.com/docs/self-hosting/install-eks.md): Install Agent Relay on an existing Amazon EKS cluster in 16 numbered steps, each with a check before you move on.
- [Use an existing or shared RDS](https://agentrelay.com/docs/self-hosting/existing-rds.md): Put Agent Relay's databases on an RDS PostgreSQL 17 instance you already run, including a shared one, instead of letting Terraform create one.
- [Bring your own AWS resources](https://agentrelay.com/docs/self-hosting/bring-your-own-aws.md): Exact specs for creating the S3 bucket, OpenSearch domain, IAM roles, Pod Identity associations and ACM certificate yourself, instead of with Terraform.
- [IAM and Pod Identity](https://agentrelay.com/docs/self-hosting/iam-pod-identity.md): The three IAM roles and five EKS Pod Identity associations the install needs, with their exact policies and an optional script that creates them.

**Install on Google Cloud**

- [Install on GKE](https://agentrelay.com/docs/self-hosting/install-gke.md): Install Agent Relay on an existing Google Kubernetes Engine cluster in 16 numbered steps, each with a check before you move on.
- [Bring your own Google Cloud resources](https://agentrelay.com/docs/self-hosting/bring-your-own-gcp.md): Exact specs for creating Cloud SQL, Cloud Storage, Memorystore, Pub/Sub and the Workload Identity grants yourself, instead of with Terraform.

**Install on Azure**

- [Install on AKS](https://agentrelay.com/docs/self-hosting/install-aks.md): Install Agent Relay on Azure Kubernetes Service with in-cluster PostgreSQL, MinIO and Traefik. Community-contributed preview.

**Configure**

- [Secrets](https://agentrelay.com/docs/self-hosting/secrets.md): Create the five Kubernetes Secrets the chart needs with plain kubectl, helm-secrets and SOPS, or vals with SSM Parameter Store or Google Secret Manager.
- [Single sign-on with Okta](https://agentrelay.com/docs/self-hosting/okta-sso.md): Add Okta (OIDC) sign-in to a running install, beside password sign-in, in four steps.
- [After the install](https://agentrelay.com/docs/self-hosting/after-install.md): Finish setup once the first session arrives - Output and digest coverage, generated titles and summaries, and the agent-name filter.
- [Desktop app rollout](https://agentrelay.com/docs/self-hosting/desktop-app.md): Get the Agent Relay desktop app to your people, signed in to your own install, and check their sessions arrive.
- [Messaging and Grok Bot](https://agentrelay.com/docs/self-hosting/messaging.md): Connect a remote bot to your own Relay server, confirm outgoing message delivery, and enable Grok webhook wake-ups.

**Optional components**

- [Slack app](https://agentrelay.com/docs/self-hosting/slack-app.md): The optional Slack app - people talk to agents in Slack, and each thread gets its own long-running, resumable agent on your install's relay.
- [Governance (relaygate)](https://agentrelay.com/docs/self-hosting/relaygate.md): The optional governance gate between agents and Relaycast and Sessions - groups, filesystem-style permissions, and a classifier on everything that crosses a boundary or leaves.

**Operate**

- [Upgrades](https://agentrelay.com/docs/self-hosting/upgrades.md): Move a running install to a newer Agent Relay release safely - the EKS upgrader, manual GKE upgrades, and what to do if one fails.
- [Backup and restore](https://agentrelay.com/docs/self-hosting/backup-and-restore.md): What to back up in a self-hosted install, how to take a consistent backup on AWS or Google Cloud, and how to prove a restore works.
- [Telemetry](https://agentrelay.com/docs/self-hosting/telemetry.md): What a self-hosted install sends to Agent Relay (nothing, until you register it), the three levels, and how to preview, change or export it.
- [Durable actors](https://agentrelay.com/docs/self-hosting/durable-actors.md): The optional durable-actors mode for Relaycast and Relayfile - what it is, its status, requirements and known issues.
- [Troubleshooting](https://agentrelay.com/docs/self-hosting/troubleshooting.md): Fixes for the problems people actually hit installing and running self-hosted Agent Relay on EKS and GKE.
- [Teardown](https://agentrelay.com/docs/self-hosting/teardown.md): Remove a self-hosted install completely - the Helm release, the cloud resources Terraform made, and Agent Relay's data on a shared database.
- [Support](https://agentrelay.com/docs/self-hosting/support.md): How to get help with a self-hosted install, what to send, and what never to send.

**Reference**

- [Downloads](https://agentrelay.com/docs/self-hosting/downloads.md): The helper scripts and values templates the install guides use, with their SHA-256 checksums.
