infisical gateway - Infisical

CLI
systemd

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

sudo infisical gateway systemd install <gateway-name> --enroll-method=token --token=<enrollment-token> --domain=<domain>

Description

The Infisical gateway runs inside your network and lets Infisical reach systems that aren’t exposed to the internet, such as a database in a private subnet or an on-premises appliance. There are two ways the gateway and Infisical reach each other:

Direct listen. The gateway listens on the address you set with --listen-address, and Infisical connects to it. No relay is needed. Self-hosted Infisical only.
Relay. The gateway opens an SSH reverse tunnel to a relay server, and Infisical reaches it back through that tunnel. No inbound ports have to be open on the gateway host.

Passing --listen-address and --target-relay-name together runs both, and Infisical uses the listen address first, keeping the relay as a fallback. See Gateway deployment for choosing a mode and the full deployment walkthrough, and Network architecture for the ports and traffic flow of each.

Subcommands & flags

infisical gateway start

Run the gateway inside the network where your target resources live. It connects to Infisical over a relay or by listening for direct connections, depending on the flags below.

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

The gateway name is provided as a positional argument.

With no --listen-address and no --target-relay-name, the gateway connects to the relay with the lowest latency. To target a specific relay, use --target-relay-name=<relay-name>. To skip relays entirely, use --listen-address=<host:port>.

Once started, the gateway component will:

Authenticate using certificates issued by Infisical
Automatically renew its certificates

In relay mode it also:

Connects to a healthy relay with the lowest latency, unless --target-relay-name names one
Establishes an outbound SSH reverse tunnel to the relay, so no inbound firewall rules are needed
Reconnects if the connection is lost, and fails over to a different healthy relay if the current one becomes unreachable

In direct listen mode it also:

Binds the port from --listen-address on every interface, unless --bind says otherwise
Accepts mutually authenticated TLS connections from Infisical on that port

Flags

--enroll-method

How the gateway authenticates with Infisical. Must match the auth method configured on the gateway in the Infisical UI. One of token, aws, or kubernetes.

token
aws
kubernetes

A one-time enrollment token from the Infisical UI bootstraps the gateway.

Show properties

string

required

The one-time enrollment token from the Infisical UI.

string

required

The URL of your Infisical instance.

infisical gateway start my-gateway --enroll-method=token --token=<enrollment-token> --domain=https://app.infisical.com

After enrollment, the gateway saves its credentials locally. You can safely re-run the same command to restart the gateway. It will detect the token has already been used and skip enrollment automatically.

The gateway signs an sts:GetCallerIdentity request with whatever AWS credentials it can resolve on the host (instance role, environment variables, shared profile), and re-authenticates on every start. No token is stored on disk.

Show properties

string

required

The gateway ID from the Infisical UI.

string

required

The URL of your Infisical instance.

infisical gateway start my-gateway --enroll-method=aws --gateway-id=<gateway-id> --domain=https://app.infisical.com

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. Infisical verifies the token against your cluster’s TokenReview API and re-authenticates on every start. No token is stored on disk.This method requires the gateway to run inside a Kubernetes pod. Deploying with the Helm chart is the recommended path.

Show properties

string

required

The gateway ID from the Infisical UI.

string

required

The URL of your Infisical instance.

string

Path to the projected service account token. Defaults to /var/run/secrets/kubernetes.io/serviceaccount/token.

infisical gateway start my-gateway --enroll-method=kubernetes --gateway-id=<gateway-id> --domain=https://app.infisical.com

See Gateway Deployment for the cluster host and allowlist configuration this method needs.

--target-relay-name

The name of the relay that this gateway should connect to. The relay must be running and registered before starting the gateway.If this flag is omitted and no --listen-address is set, the gateway connects to a healthy relay with the lowest latency.

# Example
infisical gateway start my-gateway --target-relay-name=my-relay --enroll-method=token --token=<token> --domain=<domain>

Can also be set with the INFISICAL_RELAY_NAME environment variable.For Infisical Cloud users on instance relays, the relay infrastructure is already running and managed by Infisical. If using organization relays or self-hosted instance relays, start a relay server first. See the Relay Deployment Guide.

--listen-address

The host:port address that Infisical dials to reach this gateway. Setting it runs the gateway in direct listen mode, where Infisical opens the connection and no relay is involved.The address has to be reachable from wherever Infisical runs, and it’s written into the gateway’s server certificate, so it has to be stable. An internal DNS name or a load balancer in front of the gateway both work. Changing it means re-running the command so a certificate is issued for the new address.

# Example
infisical gateway start my-gateway --listen-address=gateway.internal:8443 --enroll-method=token --token=<token> --domain=<domain>

Pass it alongside --target-relay-name to run both modes, so Infisical uses the listen address first and falls back to the relay. Running both modes covers when to keep both, and how to use it to switch modes without an outage:

infisical gateway start my-gateway --listen-address=gateway.internal:8443 --target-relay-name=my-relay --enroll-method=token --token=<token> --domain=<domain>

Can also be set with the INFISICAL_GATEWAY_LISTEN_ADDRESS environment variable.

Direct listen is only available on self-hosted Infisical.

--bind

The local host:port the gateway binds for direct connections. Defaults to every interface on the port from --listen-address. Reach for this flag only when the address Infisical dials differs from the socket the gateway should open.Use it to bind a single interface, or to listen on a different local port than the one advertised, such as behind a load balancer that terminates on 8443 and forwards to 9000.

# Advertise 8443, listen locally on 9000
infisical gateway start my-gateway --listen-address=gateway.internal:8443 --bind=0.0.0.0:9000 --enroll-method=token --token=<token> --domain=<domain>

Can also be set with the INFISICAL_GATEWAY_BIND_ADDRESS environment variable. Has no effect without --listen-address.

--domain

Domain of your self-hosted Infisical instance.

# Example
infisical gateway start <gateway-name> --domain=https://app.your-domain.com --enroll-method=token --token=<token>

--pkcs11-module

Absolute path to the PKCS#11 driver shipped by your HSM vendor. When set, the gateway loads the driver on startup and is reachable by HSM Connectors for signing operations.

# Example
infisical gateway start <gateway-name> --enroll-method=token --token=<token> --domain=<domain> --pkcs11-module=/opt/fortanix/pkcs11/fortanix_pkcs11.so

See HSM Connectors for the full setup.

infisical gateway systemd install

Install and enable the gateway as a systemd service. This command must be run with sudo on Linux.

sudo infisical gateway systemd install my-gateway --enroll-method=token --token=<enrollment-token> --domain=<domain>

Requirements

Must be run on Linux
Must be run with root/sudo privileges
Requires systemd

Flags

--enroll-method

How the gateway authenticates with Infisical. One of token or aws.

# Enrollment token
sudo infisical gateway systemd install my-gateway --enroll-method=token --token=<enrollment-token> --domain=<domain>

# AWS auth, re-authenticated on every service start
sudo infisical gateway systemd install my-gateway --enroll-method=aws --gateway-id=<gateway-id> --domain=<domain>

kubernetes is not available here. In-cluster gateways are not managed by systemd, so run infisical gateway start --enroll-method=kubernetes as the container command instead.

--token

The one-time enrollment token from the Infisical UI.

# Example
sudo infisical gateway systemd install my-gateway --enroll-method=token --token=<token> --domain=<domain>

--domain

Domain of your self-hosted Infisical instance.

# Example
sudo infisical gateway systemd install my-gateway --enroll-method=token --token=<token> --domain=https://app.your-domain.com

--target-relay-name

# Example
sudo infisical gateway systemd install my-gateway --target-relay-name=my-relay --enroll-method=token --token=<token> --domain=<domain>

For Infisical Cloud users on instance relays, the relay infrastructure is already running and managed by Infisical. If using organization relays or self-hosted instance relays, start a relay server first. See the Relay Deployment Guide.

--listen-address

The host:port address that Infisical dials to reach this gateway, which runs it in direct listen mode.

# Example
sudo infisical gateway systemd install my-gateway --listen-address=gateway.internal:8443 --enroll-method=token --token=<token> --domain=<domain>

Pass it alongside --target-relay-name to run both modes. See the infisical gateway start reference above for what the address has to satisfy.

--bind

The local host:port the gateway binds for direct connections. Defaults to every interface on the port from --listen-address.

# Example
sudo infisical gateway systemd install my-gateway --listen-address=gateway.internal:8443 --bind=0.0.0.0:9000 --enroll-method=token --token=<token> --domain=<domain>

--pkcs11-module

Absolute path to the PKCS#11 driver shipped by your HSM vendor. When set, the systemd unit captures the flag so every restart loads the same driver and the gateway is reachable by HSM Connectors.

# Example
sudo infisical gateway systemd install my-gateway --enroll-method=token --token=<token> --domain=<domain> --pkcs11-module=/opt/fortanix/pkcs11/fortanix_pkcs11.so

See HSM Connectors for the full setup.

Service details

The systemd service is installed with secure defaults:

Service file: /etc/systemd/system/<gateway-name>.service
Config file: /etc/infisical/gateways/<gateway-name>.conf
Runs with restricted privileges:
- InaccessibleDirectories=/home
- PrivateTmp=yes
- Resource limits configured for stability
Automatically restarts on failure
Enabled to start on boot
Maintains persistent SSH reverse tunnel connections to the specified relay
Handles certificate rotation and connection recovery automatically

After installation, manage the service with standard systemd commands (replace my-gateway with your gateway name):

sudo systemctl start my-gateway    # Start the service
sudo systemctl stop my-gateway     # Stop the service
sudo systemctl status my-gateway   # Check service status
sudo systemctl disable my-gateway  # Disable auto-start on boot

infisical gateway systemd uninstall

Uninstall and remove the gateway systemd service. This command must be run with sudo on Linux.

sudo infisical gateway systemd uninstall my-gateway

The gateway name is provided as a positional argument.

Frequently asked questions

Can I re-run the same enrollment command after a restart?

Yes. The CLI stores the enrollment token locally after the first successful enrollment. If you run the same command again with the same --token value, it detects the token has already been used and skips enrollment, proceeding directly to start the gateway. This means you can safely use the same command (e.g., via up-arrow in your shell) without getting “token already used” or “token expired” errors.

How are relays auto-selected?

If --target-relay-name and --listen-address are both omitted, the gateway automatically selects the optimal relay. It first checks for healthy organization relays and connects to the one with the lowest latency. If no organization relays are available, it then performs the same latency-based selection among the available managed relays.If the selected relay becomes unreachable while the gateway is running, the gateway will automatically switch to a different healthy one. Gateways started with an explicit --target-relay-name do not switch and will keep retrying the specified relay.

Which mode do I get if I pass no connection flags?

Relay mode, with a relay chosen automatically. Direct listen is opt-in: the gateway only listens for connections when you pass --listen-address.

When restarting the gateway without a relay flag, does it select a new relay every time?

No. The first time the gateway starts, it selects the optimal relay (based on latency) and caches that selection. On subsequent restarts, it will prioritize connecting to the cached relay. If it’s unable to connect, it will then re-evaluate and connect to the next most optimal relay available.

Will additional authentication methods be supported?

Yes. Additional gateway authentication methods are planned for future releases.

​Description

​Subcommands & flags

​Flags

​Requirements

​Flags

​Service details

​Frequently asked questions

Description

Subcommands & flags

Flags

Requirements

Flags

Service details

Frequently asked questions