# 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. Rendered page: https://agentrelay.com/docs/self-hosting/agents Markdown endpoint: https://agentrelay.com/docs/self-hosting/agents.md --- 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 1. **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. 2. **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. 3. **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. 4. **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. 5. **DNS is the human's:** ask the DNS owner to create records, then poll until they resolve. 6. **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](https://agentrelay.com/docs/self-hosting/agents/troubleshooting). 7. **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. 8. **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. 9. **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](https://agentrelay.com/docs/self-hosting/agents/overview)): - AWS EKS: [Install on EKS](https://agentrelay.com/docs/self-hosting/agents/install-eks), plus [existing RDS](https://agentrelay.com/docs/self-hosting/agents/existing-rds), [bring your own AWS resources](https://agentrelay.com/docs/self-hosting/agents/bring-your-own-aws) or [IAM and Pod Identity](https://agentrelay.com/docs/self-hosting/agents/iam-pod-identity) when they apply. - Google Cloud GKE: [Install on GKE](https://agentrelay.com/docs/self-hosting/agents/install-gke), plus [bring your own Google Cloud resources](https://agentrelay.com/docs/self-hosting/agents/bring-your-own-gcp) when it applies. Every runbook is also plain Markdown: append `.md` to its URL. ## All runbooks **Start** - [Self-hosting Agent Relay](https://agentrelay.com/docs/self-hosting/agents/overview.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/agents/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/agents/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/agents/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/agents/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/agents/install-gke.md): 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](https://agentrelay.com/docs/self-hosting/agents/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. **Configure** - [Secrets](https://agentrelay.com/docs/self-hosting/agents/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/agents/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/agents/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/agents/desktop-app.md): Get the Agent Relay desktop app to your people, signed in to your own install, and check their sessions arrive. **Operate** - [Upgrades](https://agentrelay.com/docs/self-hosting/agents/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/agents/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/agents/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/agents/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/agents/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/agents/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/agents/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/agents/downloads.md): The helper scripts and values templates the install guides use, with their SHA-256 checksums.