Self-hosting, for coding agents

Rules and runbooks for a coding agent installing or operating self-hosted Agent Relay on a human operator's behalf.

Written for a coding agent working for you. Lines marked Agent: are its checks and stop points. Everything else matches the human guide.

You are a coding agent installing or operating self-hosted Agent Relay in a human operator's own cloud account, with their credentials. These runbooks are the same steps as the human guides, with your checks and stop points added under Agent:. Follow them in order.

Rules

Never print, log, paste or summarize a secret. That includes passwords, API keys, tokens, the setup key, the bootstrap token, database URLs, PEM blocks, encryption keys, SUMMARY_MASTER_KEYS, kubeconfig files, Kubernetes Secret data, helm get values -a output, SSM or Secret Manager values, and every file under ~/.agent-relay-install. Verify Secrets by name and key count only.
Commands that print a credential are run by the human, not you: the setup-key command, the bootstrap-token command, add-user.sh, okta-setup.sh, and any read -rs prompt. Ask them to run it in their own terminal and report only the outcome.
Ask the human before every change to their cloud account or cluster: terraform apply and destroy, IAM and Pod Identity or Workload Identity changes, kubectl apply, create, delete, patch and scale, helm install, upgrade and uninstall, storing values in SSM or Secret Manager, and anything that deletes data. Show the exact command first. Read-only commands (get, describe, list, plan, curl health checks) need no approval.
Ask the human; never decide or invent: the domain, the organization ID and name, the first admin's email, which subnets, VPC and security groups to use, whether to reuse an existing database, internet-facing or internal load balancer, and the telemetry level.
DNS is the human's: ask the DNS owner to create records, then poll until they resolve.
Check every step's "Done when" before the next step. If it doesn't hold, stop, show the evidence (with secrets removed), and use Troubleshooting.
Never recover by deleting. No helm rollback, uninstall, PVC or Job deletion, --atomic, or migration retry unless the runbook says so and the human approves.
Never edit a downloaded file or check to make it pass. If a checksum, a release check or a script refuses, stop and report it.
Keep a plain notes file in the install folder with the human's answers and each step's result. Never put a secret in it.

Pick the runbook

Ask the human which cloud they use, then which path (see the overview):

AWS EKS: Install on EKS, plus existing RDS, bring your own AWS resources or IAM and Pod Identity when they apply.
Google Cloud GKE: Install on GKE, plus bring your own Google Cloud resources when it applies.

Every runbook is also plain Markdown: append .md to its URL.

All runbooks

Start

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.

Install on AWS

Install on EKS: 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: 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: 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: 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: Install Agent Relay on an existing Google Kubernetes Engine cluster in 15 numbered steps, each with a check before you move on.
Bring your own Google Cloud resources: Exact specs for creating Cloud SQL, Cloud Storage, Memorystore, Pub/Sub and the Workload Identity grants yourself, instead of with Terraform.

Configure

Secrets: 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: Add Okta (OIDC) sign-in to a running install, beside password sign-in, in four steps.
After the install: Finish setup once the first session arrives - Output and digest coverage, generated titles and summaries, and the agent-name filter.
Desktop app rollout: Get the Agent Relay desktop app to your people, signed in to your own install, and check their sessions arrive.

Operate

Upgrades: 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: 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: 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: The optional durable-actors mode for Relaycast and Relayfile - what it is, its status, requirements and known issues.
Troubleshooting: Fixes for the problems people actually hit installing and running self-hosted Agent Relay on EKS and GKE.
Teardown: Remove a self-hosted install completely - the Helm release, the cloud resources Terraform made, and Agent Relay's data on a shared database.
Support: How to get help with a self-hosted install, what to send, and what never to send.

Reference

Downloads: The helper scripts and values templates the install guides use, with their SHA-256 checksums.

Stuck? See troubleshooting or support.