infisical gateway

Run the Infisical gateway or manage its systemd service

Start gateway

infisical gateway start --name=<name> --relay=<relay-name> --auth-method=<auth-method>

Description

The Infisical gateway provides secure access to private resources using modern TCP-based SSH tunnel architecture with enhanced security and flexible deployment options.

The gateway system uses SSH reverse tunnels over TCP, eliminating firewall complexity and providing excellent performance for enterprise environments.

Deprecation and Migration Notice: The legacy infisical gateway command (v1) will be removed in a future release. Please migrate to infisical gateway start (Gateway v2).

If you are moving from Gateway v1 to Gateway v2, this is NOT a drop-in switch. Gateway v2 creates new gateway instances with new gateway IDs. You must update any existing resources that reference gateway IDs (for example: dynamic secret configs, app connections, or other gateway-bound resources) to point to the new Gateway v2 gateway ID. Until you update those references, traffic will continue to target the old v1 gateway.

Subcommands & flags

infisical gateway start

Run the Infisical gateway component within your VPC. The gateway establishes an SSH reverse tunnel to the specified relay server and provides secure access to private resources.

infisical gateway start --relay=<relay-name> --name=<name> --auth-method=<auth-method>

The gateway component:

• Establishes outbound SSH reverse tunnels to relay servers (no inbound firewall rules needed)
• Authenticates using SSH certificates issued by Infisical
• Automatically reconnects if the connection is lost
• Provides access to private resources within your network

Authentication

The Infisical CLI supports multiple authentication methods. Below are the available authentication methods, with their respective flags.

Universal Auth

The Universal Auth method is a simple and secure way to authenticate with Infisical. It requires a client ID and a client secret to authenticate with Infisical.

Flags

Show properties

client-id · string · required

Your machine identity client ID.

client-secret · string · required

Your machine identity client secret.

auth-method · string · required

The authentication method to use. Must be universal-auth when using Universal Auth.

  infisical gateway start --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret> --relay=<relay-name> --name=<name>

Native Kubernetes

The Native Kubernetes method is used to authenticate with Infisical when running in a Kubernetes environment. It requires a service account token to authenticate with Infisical.

Flags

Show properties

machine-identity-id · string · required

Your machine identity ID.

service-account-token-path · string

Path to the Kubernetes service account token to use. Default: /var/run/secrets/kubernetes.io/serviceaccount/token.

auth-method · string · required

The authentication method to use. Must be kubernetes when using Native Kubernetes.

  infisical gateway start --auth-method=kubernetes --machine-identity-id=<machine-identity-id> --relay=<relay-name> --name=<name>

Native Azure

The Native Azure method is used to authenticate with Infisical when running in an Azure environment.

Flags

Show properties

machine-identity-id · string · required

Your machine identity ID.

auth-method · string · required

The authentication method to use. Must be azure when using Native Azure.

  infisical gateway start --auth-method=azure --machine-identity-id=<machine-identity-id> --relay=<relay-name> --name=<name>

Native GCP ID Token

The Native GCP ID Token method is used to authenticate with Infisical when running in a GCP environment.

Flags

Show properties

machine-identity-id · string · required

Your machine identity ID.

auth-method · string · required

The authentication method to use. Must be gcp-id-token when using Native GCP ID Token.

  infisical gateway start --auth-method=gcp-id-token --machine-identity-id=<machine-identity-id> --relay=<relay-name> --name=<name>

GCP IAM

The GCP IAM method is used to authenticate with Infisical with a GCP service account key.

Flags

Show properties

machine-identity-id · string · required

Your machine identity ID.

service-account-key-file-path · string · required

Path to your GCP service account key file (Must be in JSON format!)

auth-method · string · required

The authentication method to use. Must be gcp-iam when using GCP IAM.

  infisical gateway start --auth-method=gcp-iam --machine-identity-id=<machine-identity-id> --service-account-key-file-path=<service-account-key-file-path> --relay=<relay-name> --name=<name>

Native AWS IAM

The AWS IAM method is used to authenticate with Infisical with an AWS IAM role while running in an AWS environment like EC2, Lambda, etc.

Flags

Show properties

machine-identity-id · string · required

Your machine identity ID.

auth-method · string · required

The authentication method to use. Must be aws-iam when using Native AWS IAM.

  infisical gateway start --auth-method=aws-iam --machine-identity-id=<machine-identity-id> --relay=<relay-name> --name=<name>

OIDC Auth

The OIDC Auth method is used to authenticate with Infisical via identity tokens with OIDC.

Flags

Show properties

machine-identity-id · string · required

Your machine identity ID.

jwt · string · required

The OIDC JWT from the identity provider.

auth-method · string · required

The authentication method to use. Must be oidc-auth when using OIDC Auth.

  infisical gateway start --auth-method=oidc-auth --machine-identity-id=<machine-identity-id> --jwt=<oidc-jwt> --relay=<relay-name> --name=<name>

JWT Auth

The JWT Auth method is used to authenticate with Infisical via a JWT token.

Flags

Show properties

jwt · string · required

The JWT token to use for authentication.

machine-identity-id · string · required

Your machine identity ID.

auth-method · string · required

The authentication method to use. Must be jwt-auth when using JWT Auth.

  infisical gateway start --auth-method=jwt-auth --jwt=<jwt> --machine-identity-id=<machine-identity-id> --relay=<relay-name> --name=<name>

Token Auth

You can use the INFISICAL_TOKEN environment variable to authenticate with Infisical with a raw machine identity access token.

Flags

Show properties

token · string · required

The machine identity access token to use for authentication.

  infisical gateway start --token=<token> --relay=<relay-name> --name=<name>

Other Flags

--relay

The name of the relay that this gateway should connect to. The relay must be running and registered before starting the gateway.

# Example
infisical gateway start --relay=my-relay --name=my-gateway --token=<token>

Note: If using organization relays or self-hosted instance relays, you must first start a relay server using infisical relay start before connecting gateways to it. For Infisical Cloud users using instance relays, the relay infrastructure is already running and managed by Infisical.

--name

The name of the gateway instance.

# Example
infisical gateway start --name=my-gateway --relay=my-relay --token=<token>

--domain

Domain of your self-hosted Infisical instance.

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

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 --token=<token> --domain=<domain> --name=<name> --relay=<relay-name>

Requirements

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

Flags

--token

The machine identity access token to authenticate with Infisical.

# Example
sudo infisical gateway systemd install --token=<token> --name=<name> --relay=<relay-name>

You may also expose the token to the CLI by setting the environment variable INFISICAL_TOKEN before executing the install command.

--domain

Domain of your self-hosted Infisical instance.

# Example
sudo infisical gateway systemd install --domain=https://app.your-domain.com --name=<name> --relay=<relay-name>

--name

The name of the gateway instance.

# Example
sudo infisical gateway systemd install --name=my-gateway --token=<token> --relay=<relay-name>

--relay

The name of the relay that this gateway should connect to.

# Example
sudo infisical gateway systemd install --relay=my-relay --token=<token> --name=<name>

Service Details

The systemd service is installed with secure defaults:

• Service file: /etc/systemd/system/infisical-gateway.service
• Config file: /etc/infisical/gateway.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:

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

Legacy Gateway Commands (Deprecated)

infisical gateway (deprecated)

This command is deprecated and will be removed in a future release.

Please migrate to infisical gateway start for the new TCP-based SSH tunnel architecture.

Migration required: If you are currently using Gateway v1 (via infisical gateway), moving to Gateway v2 is not in-place. Gateway v2 provisions new gateway instances with new gateway IDs. Update any resources that reference a gateway ID (for example: dynamic secret configs, app connections, or other gateway-bound resources) to use the new Gateway v2 gateway ID. Until you update those references, traffic will continue to target the old v1 gateway.

Run the legacy Infisical gateway in the foreground. The gateway will connect to the relay service and maintain a persistent connection.

infisical gateway --domain=<domain> --auth-method=<auth-method>

Authentication

The Infisical CLI supports multiple authentication methods. Below are the available authentication methods, with their respective flags.

Universal Auth

The Universal Auth method is a simple and secure way to authenticate with Infisical. It requires a client ID and a client secret to authenticate with Infisical.

Flags

Show properties

client-id · string · required

Your machine identity client ID.

client-secret · string · required

Your machine identity client secret.

auth-method · string · required

The authentication method to use. Must be universal-auth when using Universal Auth.

  infisical gateway --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret>

Native Kubernetes

The Native Kubernetes method is used to authenticate with Infisical when running in a Kubernetes environment. It requires a service account token to authenticate with Infisical.

Flags

Show properties

machine-identity-id · string · required

Your machine identity ID.

service-account-token-path · string

Path to the Kubernetes service account token to use. Default: /var/run/secrets/kubernetes.io/serviceaccount/token.

auth-method · string · required

The authentication method to use. Must be kubernetes when using Native Kubernetes.

  infisical gateway --auth-method=kubernetes --machine-identity-id=<machine-identity-id>

Native Azure

The Native Azure method is used to authenticate with Infisical when running in an Azure environment.

Flags

Show properties

machine-identity-id · string · required

Your machine identity ID.

auth-method · string · required

The authentication method to use. Must be azure when using Native Azure.

  infisical gateway --auth-method=azure --machine-identity-id=<machine-identity-id>

Native GCP ID Token

The Native GCP ID Token method is used to authenticate with Infisical when running in a GCP environment.

Flags

Show properties

machine-identity-id · string · required

Your machine identity ID.

auth-method · string · required

The authentication method to use. Must be gcp-id-token when using Native GCP ID Token.

  infisical gateway --auth-method=gcp-id-token --machine-identity-id=<machine-identity-id>

GCP IAM

The GCP IAM method is used to authenticate with Infisical with a GCP service account key.

Flags

Show properties

machine-identity-id · string · required

Your machine identity ID.

service-account-key-file-path · string · required

Path to your GCP service account key file (Must be in JSON format!)

auth-method · string · required

The authentication method to use. Must be gcp-iam when using GCP IAM.

  infisical gateway --auth-method=gcp-iam --machine-identity-id=<machine-identity-id> --service-account-key-file-path=<service-account-key-file-path>

Native AWS IAM

The AWS IAM method is used to authenticate with Infisical with an AWS IAM role while running in an AWS environment like EC2, Lambda, etc.

Flags

Show properties

machine-identity-id · string · required

Your machine identity ID.

auth-method · string · required

The authentication method to use. Must be aws-iam when using Native AWS IAM.

  infisical gateway --auth-method=aws-iam --machine-identity-id=<machine-identity-id>

OIDC Auth

The OIDC Auth method is used to authenticate with Infisical via identity tokens with OIDC.

Flags

Show properties

machine-identity-id · string · required

Your machine identity ID.

jwt · string · required

The OIDC JWT from the identity provider.

auth-method · string · required

The authentication method to use. Must be oidc-auth when using OIDC Auth.

  infisical gateway --auth-method=oidc-auth --machine-identity-id=<machine-identity-id> --jwt=<oidc-jwt>

JWT Auth

The JWT Auth method is used to authenticate with Infisical via a JWT token.

Flags

Show properties

jwt · string · required

The JWT token to use for authentication.

machine-identity-id · string · required

Your machine identity ID.

auth-method · string · required

The authentication method to use. Must be jwt-auth when using JWT Auth.

  infisical gateway --auth-method=jwt-auth --jwt=<jwt> --machine-identity-id=<machine-identity-id>

Token Auth

You can use the INFISICAL_TOKEN environment variable to authenticate with Infisical with a raw machine identity access token.

Flags

Show properties

token · string · required

The machine identity access token to use for authentication.

  infisical gateway --token=<token>

Other Flags

--domain

Domain of your self-hosted Infisical instance.

# Example
infisical gateway --domain=https://app.your-domain.com

infisical gateway install (deprecated)

This command is deprecated and will be removed in a future release.

Please migrate to infisical gateway systemd install for the new TCP-based SSH tunnel architecture with enhanced security and better performance.

Migration required: If you previously installed Gateway v1 via infisical gateway install, moving to Gateway v2 is not in-place. Gateway v2 provisions new gateway instances with new gateway IDs. Update any resources that reference a gateway ID (for example: dynamic secret configs, app connections, or other gateway-bound resources) to use the new Gateway v2 gateway ID. Until you update those references, traffic will continue to target the old v1 gateway.

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

sudo infisical gateway install --token=<token> --domain=<domain>

Requirements

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

Flags

--token

The machine identity access token to authenticate with Infisical.

# Example
sudo infisical gateway install --token=<token>

You may also expose the token to the CLI by setting the environment variable INFISICAL_TOKEN before executing the install command.

--domain

Domain of your self-hosted Infisical instance.

# Example
sudo infisical gateway install --domain=https://app.your-domain.com

Service Details

The systemd service is installed with secure defaults:

• Service file: /etc/systemd/system/infisical-gateway.service
• Config file: /etc/infisical/gateway.conf
• Runs with restricted privileges:
  • InaccessibleDirectories=/home
  • PrivateTmp=yes
  • Resource limits configured for stability
• Automatically restarts on failure
• Enabled to start on boot

After installation, manage the service with standard systemd commands:

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