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
    infisical gateway start --name=<name> --relay=<relay-name> --auth-method=<auth-method>
    ```
  </Tab>
  <Tab title="Install gateway service">
    ```bash
    sudo infisical gateway systemd install --token=<token> --domain=<domain> --name=<name> --relay=<relay-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.

## Subcommands & flags

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

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

<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 start --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret> --relay=<relay-name> --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
      infisical gateway start --auth-method=kubernetes --machine-identity-id=<machine-identity-id> --relay=<relay-name> --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
      infisical gateway start --auth-method=azure --machine-identity-id=<machine-identity-id> --relay=<relay-name> --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
      infisical gateway start --auth-method=gcp-id-token --machine-identity-id=<machine-identity-id> --relay=<relay-name> --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
      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>
    ```

  </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 start --auth-method=aws-iam --machine-identity-id=<machine-identity-id> --relay=<relay-name> --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
      infisical gateway start --auth-method=oidc-auth --machine-identity-id=<machine-identity-id> --jwt=<oidc-jwt> --relay=<relay-name> --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
      infisical gateway start --auth-method=jwt-auth --jwt=<jwt> --machine-identity-id=<machine-identity-id> --relay=<relay-name> --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
      infisical gateway start --token=<token> --relay=<relay-name> --name=<name>
    ```

  </Accordion>
</AccordionGroup>

### Other Flags

  <Accordion title="--relay">
    The name of the relay that this gateway should connect to. The relay must be running and registered before starting the gateway.

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

  </Accordion>

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

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

  </Accordion>

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

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

  </Accordion>
</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> --relay=<relay-name>
```

### Requirements

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

### Flags

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

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

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

  </Accordion>

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

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

  </Accordion>

  <Accordion title="--relay">
    The name of the relay that this gateway should connect to.

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

  </Accordion>

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

## Legacy Gateway Commands (Deprecated)

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

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

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

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

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

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