infisical/docs/cli/commands/gateway.mdx

---
title: "infisical gateway"
description: "Run the Infisical gateway or manage its systemd service"
---

<Tabs>
  <Tab title="Start gateway">
    ```bash
    sudo infisical gateway start --name=<name> --auth-method=<auth-method>
    ```
  </Tab>
  <Tab title="Start gateway as background daemon (Linux only)">
    ```bash
    sudo infisical gateway systemd install --token=<token> --domain=<domain> --name=<name>
    ```
  </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.

<Warning>
**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.

</Warning>

## 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
sudo infisical gateway start --name=<name> --auth-method=<auth-method>
```

<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

### Authentication

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

<AccordionGroup>
  <Accordion title="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.

      <ParamField query="Flags">
      <Expandable title="properties">
          <ParamField query="client-id" type="string" required>
          Your machine identity client ID.
          </ParamField>
          <ParamField query="client-secret" type="string" required>
          Your machine identity client secret.
          </ParamField>
          <ParamField query="auth-method" type="string" required>
            The authentication method to use. Must be `universal-auth` when using Universal Auth.
          </ParamField>
      </Expandable>
    </ParamField>

    ```bash
      sudo infisical gateway start --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret> --name=<name>
    ```

  </Accordion>
  <Accordion title="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.

      <ParamField query="Flags">
      <Expandable title="properties">
          <ParamField query="machine-identity-id" type="string" required>
          Your machine identity ID.
          </ParamField>
          <ParamField query="service-account-token-path" type="string" optional>
            Path to the Kubernetes service account token to use. Default: `/var/run/secrets/kubernetes.io/serviceaccount/token`.
          </ParamField>
          <ParamField query="auth-method" type="string" required>
            The authentication method to use. Must be `kubernetes` when using Native Kubernetes.
          </ParamField>
      </Expandable>

    </ParamField>


    ```bash
      sudo infisical gateway start --auth-method=kubernetes --machine-identity-id=<machine-identity-id> --name=<name>
    ```

  </Accordion>
  <Accordion title="Native Azure">
    The Native Azure method is used to authenticate with Infisical when running in an Azure environment.

    <ParamField query="Flags">
      <Expandable title="properties">
          <ParamField query="machine-identity-id" type="string" required>
            Your machine identity ID.
          </ParamField>
          <ParamField query="auth-method" type="string" required>
            The authentication method to use. Must be `azure` when using Native Azure.
          </ParamField>
      </Expandable>
    </ParamField>



    ```bash
      sudo infisical gateway start --auth-method=azure --machine-identity-id=<machine-identity-id> --name=<name>
    ```

  </Accordion>
  <Accordion title="Native GCP ID Token">
    The Native GCP ID Token method is used to authenticate with Infisical when running in a GCP environment.

    <ParamField query="Flags">
      <Expandable title="properties">
          <ParamField query="machine-identity-id" type="string" required>
            Your machine identity ID.
          </ParamField>
          <ParamField query="auth-method" type="string" required>
            The authentication method to use. Must be `gcp-id-token` when using Native GCP ID Token.
          </ParamField>
      </Expandable>
    </ParamField>



    ```bash
      sudo infisical gateway start --auth-method=gcp-id-token --machine-identity-id=<machine-identity-id> --name=<name>
    ```

  </Accordion>
  <Accordion title="GCP IAM">
    The GCP IAM method is used to authenticate with Infisical with a GCP service account key.

    <ParamField query="Flags">
      <Expandable title="properties">
          <ParamField query="machine-identity-id" type="string" required>
          Your machine identity ID.
          </ParamField>
          <ParamField query="service-account-key-file-path" type="string" required>
            Path to your GCP service account key file _(Must be in JSON format!)_
          </ParamField>
          <ParamField query="auth-method" type="string" required>
            The authentication method to use. Must be `gcp-iam` when using GCP IAM.
          </ParamField>
      </Expandable>
    </ParamField>

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

  </Accordion>
  <Accordion title="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.

    <ParamField query="Flags">
      <Expandable title="properties">
          <ParamField query="machine-identity-id" type="string" required>
            Your machine identity ID.
          </ParamField>
          <ParamField query="auth-method" type="string" required>
            The authentication method to use. Must be `aws-iam` when using Native AWS IAM.
          </ParamField>
      </Expandable>
    </ParamField>

      ```bash
        sudo infisical gateway start --auth-method=aws-iam --machine-identity-id=<machine-identity-id> --name=<name>
      ```

  </Accordion>
  <Accordion title="OIDC Auth">
    The OIDC Auth method is used to authenticate with Infisical via identity tokens with OIDC.

    <ParamField query="Flags">
      <Expandable title="properties">
          <ParamField query="machine-identity-id" type="string" required>
            Your machine identity ID.
          </ParamField>
          <ParamField query="jwt" type="string" required>
            The OIDC JWT from the identity provider.
          </ParamField>
          <ParamField query="auth-method" type="string" required>
            The authentication method to use. Must be `oidc-auth` when using OIDC Auth.
          </ParamField>
      </Expandable>
    </ParamField>

    ```bash
      sudo infisical gateway start --auth-method=oidc-auth --machine-identity-id=<machine-identity-id> --jwt=<oidc-jwt> --name=<name>
    ```

  </Accordion>

  <Accordion title="JWT Auth">
    The JWT Auth method is used to authenticate with Infisical via a JWT token.

    <ParamField query="Flags">
      <Expandable title="properties">
          <ParamField query="jwt" type="string" required>
            The JWT token to use for authentication.
          </ParamField>
          <ParamField query="machine-identity-id" type="string" required>
            Your machine identity ID.
          </ParamField>
          <ParamField query="auth-method" type="string" required>
            The authentication method to use. Must be `jwt-auth` when using JWT Auth.
          </ParamField>
      </Expandable>
    </ParamField>


    ```bash
      sudo infisical gateway start --auth-method=jwt-auth --jwt=<jwt> --machine-identity-id=<machine-identity-id> --name=<name>
    ```

  </Accordion>
  <Accordion title="Token Auth">
    You can use the `INFISICAL_TOKEN` environment variable to authenticate with Infisical with a raw machine identity access token.

    <ParamField query="Flags">
      <Expandable title="properties">
          <ParamField query="token" type="string" required>
            The machine identity access token to use for authentication.
          </ParamField>
      </Expandable>
    </ParamField>

    ```bash
      sudo infisical gateway start --token=<token> --name=<name>
    ```

  </Accordion>
</AccordionGroup>

### Other Flags

  <AccordionGroup>
  <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 start --target-relay-name=my-relay --name=my-gateway --token=<token>
    ```

    **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="--name">
    The name of the gateway instance.

    ```bash
    # Example
    sudo infisical gateway start --name=my-gateway --token=<token>
    ```

  </Accordion>

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

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

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

### Requirements

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

### Flags

  <AccordionGroup>
  <Accordion title="--token">
    The machine identity access token to authenticate with Infisical.

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

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

  </Accordion>

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

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

  </Accordion>

  <Accordion title="--name">
    The name of the gateway instance.

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

  </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 --target-relay-name=my-relay --token=<token> --name=<name>
    ```

    **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/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:

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

</Accordion>
</AccordionGroup>

## Legacy Gateway Commands

<AccordionGroup>
<Accordion title="infisical gateway (deprecated)">
  <Warning>
  **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.

  </Warning>

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

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

<AccordionGroup>
  <Accordion title="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.

      <ParamField query="Flags">
      <Expandable title="properties">
          <ParamField query="client-id" type="string" required>
          Your machine identity client ID.
          </ParamField>
          <ParamField query="client-secret" type="string" required>
          Your machine identity client secret.
          </ParamField>
          <ParamField query="auth-method" type="string" required>
            The authentication method to use. Must be `universal-auth` when using Universal Auth.
          </ParamField>
      </Expandable>
    </ParamField>

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

  </Accordion>
  <Accordion title="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.

      <ParamField query="Flags">
      <Expandable title="properties">
          <ParamField query="machine-identity-id" type="string" required>
          Your machine identity ID.
          </ParamField>
          <ParamField query="service-account-token-path" type="string" optional>
            Path to the Kubernetes service account token to use. Default: `/var/run/secrets/kubernetes.io/serviceaccount/token`.
          </ParamField>
          <ParamField query="auth-method" type="string" required>
            The authentication method to use. Must be `kubernetes` when using Native Kubernetes.
          </ParamField>
      </Expandable>

    </ParamField>


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

  </Accordion>
  <Accordion title="Native Azure">
    The Native Azure method is used to authenticate with Infisical when running in an Azure environment.

    <ParamField query="Flags">
      <Expandable title="properties">
          <ParamField query="machine-identity-id" type="string" required>
            Your machine identity ID.
          </ParamField>
          <ParamField query="auth-method" type="string" required>
            The authentication method to use. Must be `azure` when using Native Azure.
          </ParamField>
      </Expandable>
    </ParamField>



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

  </Accordion>
  <Accordion title="Native GCP ID Token">
    The Native GCP ID Token method is used to authenticate with Infisical when running in a GCP environment.

    <ParamField query="Flags">
      <Expandable title="properties">
          <ParamField query="machine-identity-id" type="string" required>
            Your machine identity ID.
          </ParamField>
          <ParamField query="auth-method" type="string" required>
            The authentication method to use. Must be `gcp-id-token` when using Native GCP ID Token.
          </ParamField>
      </Expandable>
    </ParamField>



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

  </Accordion>
  <Accordion title="GCP IAM">
    The GCP IAM method is used to authenticate with Infisical with a GCP service account key.

    <ParamField query="Flags">
      <Expandable title="properties">
          <ParamField query="machine-identity-id" type="string" required>
          Your machine identity ID.
          </ParamField>
          <ParamField query="service-account-key-file-path" type="string" required>
            Path to your GCP service account key file _(Must be in JSON format!)_
          </ParamField>
          <ParamField query="auth-method" type="string" required>
            The authentication method to use. Must be `gcp-iam` when using GCP IAM.
          </ParamField>
      </Expandable>
    </ParamField>

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

  </Accordion>
  <Accordion title="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.

    <ParamField query="Flags">
      <Expandable title="properties">
          <ParamField query="machine-identity-id" type="string" required>
            Your machine identity ID.
          </ParamField>
          <ParamField query="auth-method" type="string" required>
            The authentication method to use. Must be `aws-iam` when using Native AWS IAM.
          </ParamField>
      </Expandable>
    </ParamField>

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

  </Accordion>
  <Accordion title="OIDC Auth">
    The OIDC Auth method is used to authenticate with Infisical via identity tokens with OIDC.

    <ParamField query="Flags">
      <Expandable title="properties">
          <ParamField query="machine-identity-id" type="string" required>
            Your machine identity ID.
          </ParamField>
          <ParamField query="jwt" type="string" required>
            The OIDC JWT from the identity provider.
          </ParamField>
          <ParamField query="auth-method" type="string" required>
            The authentication method to use. Must be `oidc-auth` when using OIDC Auth.
          </ParamField>
      </Expandable>
    </ParamField>

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

  </Accordion>

  <Accordion title="JWT Auth">
    The JWT Auth method is used to authenticate with Infisical via a JWT token.

    <ParamField query="Flags">
      <Expandable title="properties">
          <ParamField query="jwt" type="string" required>
            The JWT token to use for authentication.
          </ParamField>
          <ParamField query="machine-identity-id" type="string" required>
            Your machine identity ID.
          </ParamField>
          <ParamField query="auth-method" type="string" required>
            The authentication method to use. Must be `jwt-auth` when using JWT Auth.
          </ParamField>
      </Expandable>
    </ParamField>


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

  </Accordion>
  <Accordion title="Token Auth">
    You can use the `INFISICAL_TOKEN` environment variable to authenticate with Infisical with a raw machine identity access token.

    <ParamField query="Flags">
      <Expandable title="properties">
          <ParamField query="token" type="string" required>
            The machine identity access token to use for authentication.
          </ParamField>
      </Expandable>
    </ParamField>

    ```bash
      infisical gateway --token=<token>
    ```

  </Accordion>
</AccordionGroup>

### Other Flags

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

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

  </Accordion>
  </AccordionGroup>
</Accordion>

<Accordion title="infisical gateway install (deprecated)">
  <Warning>
  **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.

  </Warning>

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

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

### Requirements

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

### Flags

  <AccordionGroup>
  <Accordion title="--token">
    The machine identity access token to authenticate with Infisical.

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

  </Accordion>

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

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

  </Accordion>
  </AccordionGroup>

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

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

</Accordion>
</AccordionGroup>

## Frequently Asked Questions

<AccordionGroup>
  <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>
</AccordionGroup>