Skip to main content
infisical gateway start <name> --enroll-method=token --token=<enrollment-token> --domain=<domain>

​
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 resource. 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 the network where your target resources are located. The gateway establishes an SSH reverse tunnel to a relay server and provides secure access to private resources within your network.
infisical gateway start <name> --enroll-method=token --token=<enrollment-token> --domain=<domain>
The gateway name is provided as a positional argument.
By default, the gateway automatically connects to the relay with the lowest latency. To target a specific relay, use the --target-relay-name=<relay-name> flag.
Once started, the gateway component will:
  • Automatically connect to a healthy relay with the lowest latency (unless the --target-relay-name flag is specified)
  • Establish outbound SSH reverse tunnel to relay server (no inbound firewall rules needed)
  • Authenticate using SSH certificates issued by Infisical
  • Automatically reconnect if the connection is lost
  • Provide access to private resources within your network

​
Flags

The enrollment method to use. Currently only token is supported. Additional authentication methods will be available in the future.
​
Flags
  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 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, the gateway will automatically connect 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>
Note: For Infisical Cloud users using instance relays, the relay infrastructure is already running and managed by Infisical. If using organization relays or self-hosted instance relays, you must first start a relay server. For more information on deploying relays, refer to the Relay Deployment Guide.
Domain of your self-hosted Infisical instance.
# Example
infisical gateway start <name> --domain=https://app.your-domain.com --enroll-method=token --token=<token>
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

The enrollment method to use. Currently only token is supported.
# Example
sudo infisical gateway systemd install my-gateway --enroll-method=token --token=<enrollment-token> --domain=<domain>
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 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
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, the gateway will automatically connect to a healthy relay with the lowest latency.
# Example
sudo infisical gateway systemd install my-gateway --target-relay-name=my-relay --enroll-method=token --token=<token> --domain=<domain>
Note: For Infisical Cloud users using instance relays, the relay infrastructure is already running and managed by Infisical. If using organization relays or self-hosted instance relays, you must first start a relay server. For more information on deploying relays, refer to the Relay Deployment Guide.

​
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

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>

​
Other Flags

Domain of your self-hosted Infisical instance.
# Example
infisical gateway --domain=https://app.your-domain.com
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

​
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

​
Frequently Asked Questions

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.
If the --target-relay-name flag is 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.
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.
Yes. Additional gateway authentication methods are planned for future releases.