Installing the Gateway Runtime
Last Modified: 2026-11-19

Installing the Gateway Runtime

After an instance is registered, install its runtime package on the infrastructure you chose as the deployment target. The following procedure describes installing a self-hosted gateway on Kubernetes, using the Helm-based installation bundle that Agent ID generates for the gateway.

Prerequisites

ItemRequirement
Install workstationA Unix-based machine that can run bash scripts, with kubectl, Helm 3.8 or later, openssl, and skopeo installed. Skopeo is used to copy the required images into your registry.kubectl must point to the target cluster, with permission to create a namespace, Secrets, and the chart’s resources. The workstation needs HTTPS access to RSA’s registry and to your own registry, whose TLS certificate skopeo and Helm trust. If your registry uses a private CA, add it to the workstation’s trust store first. If your registry requires authentication, log in with both skopeo login <registry> and helm registry login <registry>, or set MIRROR_USERNAME and enter the password when mirror.sh asks for it.
Kubernetes clusterKubernetes 1.29 or later with a default StorageClass (used by PostgreSQL and OpenBao), and about 1 vCPU and 2.5 GiB of memory available. Azure and AWS clusters are validated; for any other cluster, such as an on-premises cluster, select On-prem as the deployment target.
NetworkingYou are responsible for the networking in front of the cluster: an ingress controller and a certificate issuer, and ingress and egress rules. The nodes must be able to pull images from your registry. The gateway must be able to make outbound TCP connections to the Agent ID console’s mTLS address (shown in the bundle’s README). This traffic must be exempt from TLS inspection, because a proxy or VPN that decrypts or re-signs TLS breaks the connection. The gateway must also be able to make outbound HTTPS connections to your MCP servers and to the identity provider you bind to the gateway.
RegistryA registry that you control and that supports HTTPS. The installer copies the gateway image and chart into it from RSA’s registry. The nodes also pull dependency images from Docker Hub (postgres, valkey/valkey, openbao/openbao, curlimages/curl) and Quay (openbao/openbao). If the nodes can’t reach those registries, mirror the images to your registry as well, or use your own PostgreSQL, Redis, and Vault.

Note:  mirror.sh and install.sh are one way to install, not a requirement. If you have your own tooling for mirroring images and deploying Helm charts, use it instead; the scripts show which image and chart to copy, which Secrets the chart expects, and the Helm command.

Decide How MCP Clients Reach the Gateway

MCP clients reach the gateway at its public URL. Before you install, choose one of the following:

  • The chart’s ingress: The chart creates a Gateway API Gateway and HTTPRoute on Envoy Gateway. Envoy Gateway and a GatewayClass must already be installed.

  • Your own ingress controller (ingressnginx, OpenShift Routes, or Traefik): Point it at the gateway Service, port 80, in the gateway’s namespace. Turn off response buffering, and set read and send timeouts of at least 330 seconds, because a tool call that is waiting for a user’s approval keeps its stream open for up to five minutes.

Either way, you need a TLS certificate for the public URL’s host, and DNS for that host pointing at your ingress. On a cluster that enforces NetworkPolicy (Calico, Cilium, or OpenShift), traffic from an ingress controller other than Envoy Gateway is dropped until you set networkPolicy in values.yaml to that controller’s namespace and pod labels.

Procedure 

  1. On the Gateways page, open the Actions menu for the gateway, and click Download bundle. Extract the downloaded archive on the install workstation. The bundle contains the generated certificates, values.yaml, the mirror.sh and install.sh scripts, and a README that is tailored to this gateway and lists its steps and requirements.

  2. Open the Actions menu for the gateway, click Generate installation tokens, and copy the values you need from the Installation tokens dialog before you close it. The dialog shows a Registry credential (Registry, Username, Password, and a Mirror command) and an Enrollment token (Token, with a Download as enrollment-token option, and an Install command). The tokens are not shown again. The registry credential and the enrollment token are both valid for one hour, so have everything in the prerequisites ready first and complete the remaining steps within an hour of generating the tokens.

  3. In the extracted bundle directory, run the Mirrorcommand straight away, replacing <your registry> with the address of your own registry and using the registry username that the console shows. Enter the registry password when prompted, so that it stays out of your shell history. The script copies the gateway image and chart into your registry, verifies the image digest, and updates values.yaml to use your registry.

    RSA_REGISTRY_USERNAME='<registry username from the console>' ./mirror.sh <your registry>

  4. Edit values.yaml so it reflects your environment. The registry name is already filled in from the mirror step; update it if it is not correct. Then make the changes that match how MCP clients reach the gateway:

    • For the chart’s ingress: uncomment services.gateway.ingress.host and set it to the public URL’s host, and uncomment the ingress: block at the end of the file. Set gatewayClassName if your GatewayClass isn’t called envoy.

    • For your own ingress controller: uncomment the networkPolicy: block at the end of the file and set it to your controller’s pods.

    • Optionally, review the resource settings for running multiple instances for high availability (commented out by default). To use your own PostgreSQL, Redis, or Vault instead of the in-cluster ones, follow the comments in values.yaml; for PostgreSQL, see Using Your Own PostgreSQL.

  5. Provide the TLS certificate: For the chart’s ingress, create the TLS Secret, or set clusterIssuer in values.yaml to use cert-manager. If you use your own ingress controller, configure the certificate there instead.

    kubectl create namespace gateway‐node

    kubectl ‐n gateway‐node create secret tls gateway‐tls ‐‐cert=<cert.pem> ‐‐key=<key.pem>

  6. Run the Install command, which passes the enrollment token to the installer, and confirm the prompt. Use the enrollment token from the same Installation tokens dialog. Omit the two registry variables if your nodes can already pull from your registry. Before it creates any Secrets, install.sh checks that the cluster can reach the console and trusts its certificate. The installer then runs the Helm installation.

    export REGISTRY_USERNAME='<your registry username>'

    export REGISTRY_PASSWORD='<your registry password>'

    export ENROLLMENT_TOKEN='<enrollment token from the console>'

    ./install.sh

    • --dry-run prints every command without running any.

    • --namespace and --release change where it installs.

    • If Helm cannot pull the chart from your registry, pass a downloaded chart: CHART=./<chart><version>.tgz ./install.sh

  7. Point DNS at your ingress: Point DNS for the public URL’s host at your ingress. The console shows the gateway’s heartbeat within a few minutes.

  8. On the Gateways page, wait for the gateway’s Status to change from Registered · not connected to Healthy.

Results 

The gateway completes its initial handshake with the console, its status shows Healthy, and its Last heartbeat is updated. The gateway begins enforcing configuration once it has resources published to it. For more information, see Publishing Configuration Changes.

Note:  Once a gateway runtime is connected, an agent (for example, a coding assistant) can point its own MCP client configuration at the gateway's MCP endpoint to call the resources registered on it.

Installation Considerations

  • The registry credential and the enrollment token are valid for one hour. The enrollment token can be used only once. If the installation fails, generate new installation tokens and run the installation again.

  • The registry that you copy the images to must support HTTPS. If it requires authentication, log in with both skopeo login <registry> and helm registry login <registry> before you run mirror.sh, or set MIRROR_USERNAME and enter the password when mirror.sh asks for it.

  • The installer’s handshake with the console must not pass through TLS inspection, and neither must the gateway’s outbound connection to the console’s mTLS address (shown in the bundle’s README). A proxy or VPN that decrypts or re-signs TLS on either connection breaks the connection, so disconnect from such a VPN before you run the installer.

  • Some dependency images (PostgreSQL, Valkey, and OpenBao) are pulled from public registries (Docker Hub: postgres, valkey/valkey, openbao/openbao, curlimages/curl; Quay: openbao/openbao) rather than from RSA. Make sure the environment you deploy to can reach them, or mirror them to your own registry, or use your own PostgreSQL, Redis, and Vault.

  • Choose how MCP clients reach the gateway before you install. If you use your own ingress controller, turn off response buffering and set read and send timeouts of at least 330 seconds. On a cluster that enforces NetworkPolicy (Calico, Cilium, or OpenShift), set networkPolicy in values.yaml for any ingress controller other than Envoy Gateway.

Changing, Upgrading, or Removing the Gateway

You can change, upgrade, or remove the gateway with the same scripts that installed it.

  • Change: edit values.yaml and run install.sh again. You do not need a new token.

  • Upgrade: download the bundle again from the console, generate new installation tokens, run mirror.sh, and then run install.sh.

  • Remove: run the following commands. Deleting the namespace also deletes the volumes that hold the gateway’s and OpenBao’s data.

    helm uninstall gateway‐node ‐n gateway‐node

    kubectl delete namespace gateway‐node

  • Production: replace the default OpenBao seal, which keeps its key in a Kubernetes Secret next to the data it protects, with your Vault’s Transit engine or a cloud KMS key (vault.server.ha.raft.config in values.yaml).

Using Your Own PostgreSQL

Create the gateway’s role and database once, as an administrator. The gateway refuses to run as a superuser or as a role with BYPASSRLS.

CREATE ROLE app_ops LOGIN PASSWORD '<password>';

CREATE DATABASE gateway_runtime OWNER app_ops;

\connect gateway_runtime

ALTER SCHEMA public OWNER TO app_ops;

Set the Postgres section of values.yaml and run DB_PASSWORD='<password>' ./install.sh.

Managing the Gateway

You can use the Actions menu on the Gateways page to manage gateways as detailed in the following table.

Action

Description

View gatewayOpens the gateway's detail page, which contains the following cards: Overview, Connected resources, Roles and scopes, Policies, and Activity.
Download bundleDownloads the runtime package, which you can use to install or reinstall the gateway on your infrastructure. Existing configuration is kept. For more information, see Installing the Gateway Runtime.
DisableTemporarily stops the gateway from handling requests. Its configuration and connected resources are kept. The option changes to Enable so that you can turn the gateway back on.
DeletePermanently removes the gateway and its configuration. This action cannot be undone. Resources connected to the gateway are no longer served by it. Uninstall the runtime from your cluster separately: run helm uninstall gateway-node -n gateway-node, and then delete the gateway-node namespace with kubectl delete namespace gateway-node, which also deletes the volumes that hold the gateway’s and OpenBao’s data. For more information, see Changing, Upgrading, or Removing the Gateway.

To bind a gateway to an identity provider, click Configure in the gateway's Identity provider column; for more information, see Connecting an Identity Provider to a Gateway. To edit the identity provider details later, click Manage IdP on the gateway's detail page.