Gateway deployment

Infisical Gateways enables secure communication between your private resources and the Infisical platform without exposing inbound ports in your network. This guide covers everything you need to deploy and configure Infisical Gateways.

For a complete Helm chart reference for Kubernetes deployments, see the Gateway Helm chart documentation.

Deployment steps

Set Up a Relay Server

Ensure a relay server is running and accessible before you deploy any gateways. You have two options:

Managed relay (Infisical Cloud, US/EU only): If you are using Infisical Cloud in the US or EU regions, you can use the provided managed relay.
Self-hosted relay: For all other cases, you must deploy your own relay server. See the Relay Deployment Guide.

Create the Gateway in the UI

Navigate to Organization Settings > Networking > Gateways.
Click Create Gateway.
Enter a name for the gateway.
(Optional) Open the new gateway’s detail page and change the method under Authentication in the Details card. Three methods are supported:
- Token (default): a one-time enrollment token (1h expiry) bootstraps the gateway.
- AWS: the gateway authenticates by signing an sts:GetCallerIdentity request with whatever AWS credentials it can resolve on the host (instance role, env vars, shared profile). Configure the allowed principal ARNs and/or account IDs that match your hosts.
- Kubernetes: the gateway authenticates with the projected service account token of the pod it runs in, so no credential has to be distributed to the cluster. Configure the cluster’s API server URL and the allowed namespaces and/or service account names.
Click Show deploy command in the Deployment card. Pick a relay (or “Auto Select Relay”) and copy the generated CLI command.

Install the Infisical CLI

Make sure the Infisical CLI is installed on the target machine. See the CLI Installation Guide for instructions.

Configure Network & Firewall

Ensure your network and firewall settings allow the gateway to connect to all required services. All connections are outbound only; no inbound ports need to be opened.

Protocol	Destination	Port	Purpose
TCP	Relay Server IP/Hostname	2222	SSH reverse tunnel establishment
TCP	Infisical instance host (US/EU, other)	443	API communication and certificate requests

For managed relays, allow outbound traffic to the provided relay server IP/hostname. For self-hosted relays, allow outbound traffic to your own relay server address.If you are in a corporate environment with strict egress filtering, ensure outbound TCP 2222 to relay servers and outbound HTTPS 443 to Infisical API endpoints are allowed.

For the full connection model, a complete port reference, and firewall details (including self-hosted relays and HTTP forward proxies), see the Network Architecture page.

Run the CLI Command

Run the command you copied from the UI on the target machine. This single command enrolls the gateway and starts it immediately.

Token Auth

A one-time enrollment token (1h expiry) bootstraps the gateway.

Linux (Production)
Foreground
Kubernetes (Helm)

sudo infisical gateway systemd install <gateway-name> \
  --enroll-method=token \
  --token=<enrollment-token> \
  --domain=<your-infisical-domain>
sudo systemctl start <gateway-name>

infisical gateway start <gateway-name> \
  --enroll-method=token \
  --token=<enrollment-token> \
  --domain=<your-infisical-domain>

Install the Infisical Helm chart repository:

helm repo add infisical https://dl.cloudsmith.io/public/infisical/helm-charts/helm/charts/
helm repo update

Create a Kubernetes Secret with your enrollment token:

kubectl create secret generic gateway-enrollment-token \
  --from-literal=enrollment-token=<enrollment-token>

Install the gateway:

helm install infisical-gateway infisical/infisical-gateway \
  --set gateway.name=<gateway-name> \
  --set gateway.enrollment.method=token \
  --set gateway.enrollment.token.existingSecretRef=gateway-enrollment-token \
  --set gateway.domain=<your-infisical-domain>

A PersistentVolumeClaim is created by default to store enrollment credentials across pod restarts. The enrollment token is single-use. Without persistent storage, the gateway cannot restart after the initial enrollment.

You can also pass the token inline (the chart creates the Secret for you):

helm install infisical-gateway infisical/infisical-gateway \
  --set gateway.name=<gateway-name> \
  --set gateway.enrollment.method=token \
  --set gateway.enrollment.token.value=<enrollment-token> \
  --set gateway.domain=<your-infisical-domain>

AWS Auth

The host must have AWS credentials whose principal matches your allowlist. The gateway re-authenticates via STS on every start.

Linux (Production)
Foreground
Kubernetes (Helm)

sudo infisical gateway systemd install <gateway-name> \
  --enroll-method=aws \
  --gateway-id=<gateway-id> \
  --domain=<your-infisical-domain>
sudo systemctl start <gateway-name>

infisical gateway start <gateway-name> \
  --enroll-method=aws \
  --gateway-id=<gateway-id> \
  --domain=<your-infisical-domain>

Install the Infisical Helm chart repository:

helm repo add infisical https://dl.cloudsmith.io/public/infisical/helm-charts/helm/charts/
helm repo update

Install the gateway with IAM Roles for Service Accounts (IRSA):

helm install infisical-gateway infisical/infisical-gateway \
  --set gateway.name=<gateway-name> \
  --set gateway.enrollment.method=aws \
  --set gateway.enrollment.aws.gatewayId=<gateway-id> \
  --set gateway.domain=<your-infisical-domain> \
  --set serviceAccount.annotations."eks\.amazonaws\.com/role-arn"=arn:aws:iam::<account-id>:role/<role-name>

Ensure the IAM role’s trust policy allows the Kubernetes service account to assume it, and that the role’s ARN or account ID is in the gateway’s AWS auth allowlist in the Infisical UI.

Kubernetes Auth

The gateway sends the projected service account token of its own pod, and Infisical verifies it against your cluster’s TokenReview API. Nothing has to be copied into the cluster, so this is the method to use when gateway creation is automated. The gateway re-authenticates on every start.Before deploying, configure the Kubernetes auth method on the gateway’s detail page:

Field	Description
Gateway	Optional. Routes the check through an existing gateway or gateway pool instead of Infisical calling the API server directly. Use this when the API server has no address Infisical can reach.
Review Mode	Shown once a proxy is selected. See the private cluster section below.
Kubernetes Host	The cluster API server URL, reachable from Infisical (for example `https://my-cluster.example.com:6443`). Not required when Review Mode is Gateway as Reviewer.
Allowed Namespaces	Namespaces whose service accounts may authenticate as this gateway. Supports `*` wildcards.
Allowed Service Account Names	Service account names that may authenticate as this gateway. Supports `*` wildcards.
Allowed Audience	Optional. The audience the token must carry.
CA Certificate	The CA that issued the API server’s certificate. Needed unless that certificate is already trusted by the public trust store, which for a cluster CA it will not be.
Token Reviewer JWT	Optional. A token with the `system:auth-delegator` ClusterRole. Leave empty to let the gateway’s own service account review its token, which the Helm chart configures by default.

At least one of Allowed Namespaces or Allowed Service Account Names must be set, so that not every pod in the cluster can enroll as the gateway.

Clusters with a private API server

By default Infisical calls your API server directly, which requires an address it can reach. If your API server is private, select a gateway or gateway pool under Gateway and the check is tunnelled through it instead. Two modes are available:

Review Mode	Who performs the check	Requires
Gateway as Reviewer	The selected gateway, using its own service account	That gateway runs as a pod in the same cluster. No host or reviewer token needed.
Manual Token Reviewer JWT (API)	Infisical, tunnelling through the gateway	A Kubernetes host and a reviewer token. Works from any gateway that can reach the API server, including one on a VM in the same network.

A gateway pool can only be used with Manual Token Reviewer JWT (API), where any healthy member performs the check and one gateway going offline does not stop the others from authenticating. Gateway as Reviewer requires a specific gateway, because in that mode the selected gateway decides the outcome and pool membership can change after the config is saved.

A gateway cannot review its own token. The proxy runs over the gateway’s own tunnel, which only exists once it has already authenticated, so the reviewer must be a different gateway that is already enrolled and connected.This means the first gateway in a private cluster cannot use Kubernetes auth. Enrol it with an enrollment token or AWS auth, then point later gateways at it. Deleting a gateway that other gateways use as their reviewer is refused until they are pointed elsewhere.

Kubernetes (Helm)
Other in-cluster deployment

Install the Infisical Helm chart repository:

helm repo add infisical https://dl.cloudsmith.io/public/infisical/helm-charts/helm/charts/
helm repo update

Install the gateway:

helm install infisical-gateway infisical/infisical-gateway \
  --namespace infisical-gateway --create-namespace \
  --set gateway.name=<gateway-name> \
  --set gateway.enrollment.method=kubernetes \
  --set gateway.enrollment.kubernetes.gatewayId=<gateway-id> \
  --set gateway.domain=<your-infisical-domain>

The chart binds the gateway’s service account to the system:auth-delegator ClusterRole by default, which is what lets its own token act as the token reviewer. Set serviceAccount.createAsAuthDelegator=false only if you configure a separate Token Reviewer JWT on the gateway instead.

Make sure the release namespace and service account name match the allowlists you configured. With the command above, that is namespace infisical-gateway and service account infisical-gateway.

If you deploy the gateway container yourself rather than through the chart, run it with:

infisical gateway start <gateway-name> \
  --enroll-method=kubernetes \
  --gateway-id=<gateway-id> \
  --domain=<your-infisical-domain>

The pod needs its service account token automounted (the default), and either the service account must hold the system:auth-delegator ClusterRole or a separate Token Reviewer JWT must be configured on the gateway.

Infisical must be able to reach the cluster’s API server to review the token. For a cluster with no publicly reachable API server, use Token or AWS auth instead.

The systemd install command requires Linux with root/sudo privileges.

Token-method enrollment tokens are single-use and expire after 1 hour. If the token expires before deployment, click Show deploy command again on the detail page to generate a new one.

You can safely re-run the same command to restart the gateway. The CLI detects the token has already been used locally and skips enrollment automatically.

Verify Your Gateway Deployment

After deployment, verify your gateway is working:

Check logs for “Gateway started successfully” message.
Verify registration in the Infisical UI. Navigate to Networking > Gateways and confirm the gateway shows a “Healthy” status.
Test connectivity by creating a resource that uses the gateway to access a private service.

Managing a gateway

From the gateway’s detail page (click the gateway row in the list):

Show deploy command: Generates a fresh enrollment token (token method) or re-displays the start command for the AWS and Kubernetes methods. Clicking this on a token-method gateway does not disconnect the running gateway; the next login with the new token rotates credentials atomically.
Edit auth method: Switch between Token, AWS, and Kubernetes, or update the allowlists of the current method. Existing gateways keep their JWT until they restart and re-authenticate.
Options → Revoke Access — Disconnects the running gateway and invalidates outstanding enrollment tokens. The gateway must re-authenticate to reconnect. Gated by the dedicated revoke-gateway-access permission, separate from edit-gateways.
Options → Delete Gateway — Permanently removes the gateway.

To migrate a gateway to a different host with zero downtime: click Show deploy command to generate a fresh token, run it on the new host, and the new login will rotate credentials away from the old host.

Frequently asked questions

Do I need to open any inbound ports on my firewall?

No inbound ports need to be opened for gateways. The gateway only makes outbound connections:

Outbound SSH to relay servers on port 2222
Outbound HTTPS to Infisical API endpoints on port 443
SSH reverse tunnels handle all communication - no return traffic configuration needed

This design maintains security by avoiding the need for inbound firewall rules that could expose your network to external threats.

How do I test network connectivity from the gateway?

Test relay connectivity and outbound API access from the gateway:

Test SSH port to relay:

nc -zv <relay-ip> 2222

Test outbound API access (replace with your Infisical domain if different):

curl -I https://app.infisical.com

How do I troubleshoot relay connectivity issues?

If the gateway cannot connect to the relay:

Verify the relay server is running and accessible
Check firewall rules allow outbound connections on port 2222
Confirm the relay name matches exactly
Test SSH port to relay:

nc -zv <relay-ip> 2222

How do I troubleshoot authentication failures?

For token method: ensure the enrollment token has not expired or already been used. Open the gateway’s detail page and click Show deploy command to generate a fresh token.For AWS method: ensure the host has AWS credentials available (instance role, env vars, or shared profile) and the resolved principal/account is in the allowlist on the gateway’s detail page.For Kubernetes method: ensure Infisical can reach the configured Kubernetes host, that the pod’s namespace and service account are in the allowlists, and that the reviewer (the gateway’s own service account by default) holds the system:auth-delegator ClusterRole. The gateway’s audit log records the reviewed namespace and service account name for each login, and the reason code for each failure.

Where can I find gateway logs?

Check gateway logs for detailed error information:

systemd service:
sudo journalctl -u <gateway-name> -f
Local installation: Logs appear in the terminal where you started the gateway

What happens if my enrollment token expires?

Enrollment tokens expire after 1 hour. If the token expires before deployment, open the gateway’s detail page and click Show deploy command to generate a new one.

Where are gateway credentials stored?

For token-method gateways, the access token and domain are saved to a config file scoped by gateway name:

Running as root/sudo: /etc/infisical/gateways/<gateway-name>.conf
Running as a regular user: ~/.infisical/gateways/<gateway-name>.conf

For AWS-method and Kubernetes-method gateways, no JWT is persisted to disk. The gateway re-authenticates on every start, by signing a fresh STS request with the host’s AWS credentials or by presenting the pod’s service account token. Only the gateway id and domain are stored locally.For systemd-based installations, the configuration is at /etc/infisical/gateways/<gateway-name>.conf. All config files are created with restricted permissions (0600).

Can I run multiple gateways on the same machine?

Yes. Each gateway stores its credentials in a separate config file scoped by name (e.g., ~/.infisical/gateways/my-gateway.conf). You can enroll and start multiple gateways in separate terminal sessions using different names.

What happens if there is a network interruption?

The gateway is designed to handle network interruptions gracefully:

Automatic reconnection: The gateway will automatically attempt to reconnect to relay servers if the SSH connection is lost
Connection retry logic: Built-in retry mechanisms handle temporary network outages without manual intervention
Automatic failover: Gateways configured with automatic relay selection will switch to a different healthy relay if the current one becomes unreachable
Gateway Pools: If the gateway itself becomes unavailable, a Gateway Pool will automatically route through a healthy member
Persistent SSH tunnels: SSH connections are automatically re-established when connectivity is restored
Certificate rotation: The gateway handles certificate renewal automatically during reconnection
Graceful degradation: The gateway logs connection issues and continues attempting to restore connectivity

No manual intervention is typically required during network interruptions.

Getting started

Platform reference

Connectivity

Authentication methods

Self-host Infisical

Internals

Contributing

Gateway deployment

Deployment steps

Clusters with a private API server

Managing a gateway

Frequently asked questions

​Deployment steps

​Clusters with a private API server

​Managing a gateway

​Frequently asked questions

Deployment steps

Clusters with a private API server

Managing a gateway

Frequently asked questions