infisical gateway - Infisical

<Tabs> <Tab title="CLI"> ```bash infisical gateway start <gateway-name> --enroll-method=token --token=<enrollment-token> --domain=<domain> ``` </Tab> <Tab title="systemd"> ```bash sudo infisical gateway systemd install <gateway-name> --enroll-method=token --token=<enrollment-token> --domain=<domain> ``` </Tab> </Tabs>

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.

Subcommands & flags

<AccordionGroup> <Accordion title="infisical gateway start" defaultOpen="true"> 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.

bash

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

The gateway name is provided as a positional argument.

<Info> 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. </Info>

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

<AccordionGroup> <Accordion title="--enroll-method"> The enrollment method to use. Currently only `token` is supported. Additional authentication methods will be available in the future.

  <ParamField query="Flags">
  <Expandable title="properties">
      <ParamField query="enroll-method" type="string" required>
        Must be `token` when using an enrollment token.
      </ParamField>
      <ParamField query="token" type="string" required>
        The one-time enrollment token from the Infisical UI.
      </ParamField>
      <ParamField query="domain" type="string" required>
        The URL of your Infisical instance.
      </ParamField>
  </Expandable>
</ParamField>

```bash
  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.

</Accordion> <Accordion title="--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, the gateway will automatically connect to a healthy relay with the lowest latency.

```bash
# 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](/documentation/platform/gateways/relay-deployment).

</Accordion> <Accordion title="--domain"> Domain of your self-hosted Infisical instance.

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

</Accordion> </AccordionGroup> </Accordion> <Accordion title="infisical gateway systemd install"> Install and enable the gateway as a systemd service. This command must be run with sudo on Linux.

bash

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

<AccordionGroup> <Accordion title="--enroll-method"> The enrollment method to use. Currently only `token` is supported.

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

</Accordion> <Accordion title="--token"> The one-time enrollment token from the Infisical UI.

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

</Accordion> <Accordion title="--domain"> Domain of your self-hosted Infisical instance.

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

</Accordion> <Accordion title="--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, the gateway will automatically connect to a healthy relay with the lowest latency.

```bash
# 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](/documentation/platform/gateways/relay-deployment).

</Accordion> </AccordionGroup>

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):

bash

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

</Accordion> <Accordion title="infisical gateway systemd uninstall"> Uninstall and remove the gateway systemd service. This command must be run with sudo on Linux.

bash

sudo infisical gateway systemd uninstall my-gateway

The gateway name is provided as a positional argument.

</Accordion> </AccordionGroup>

Frequently Asked Questions

<AccordionGroup> <Accordion title="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. </Accordion> <Accordion title="How are relays auto-selected?"> 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. </Accordion> <Accordion title="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. </Accordion> <Accordion title="Will additional authentication methods be supported?"> Yes. Additional gateway authentication methods are planned for future releases. </Accordion> </AccordionGroup>