Gateway Deployment - Infisical

Infisical Gateways enables secure communication between your private resources and the Infisical platform without exposing inbound ports in your network. This guide covers everything you need to deploy and configure Infisical Gateways.

Deployment Steps

<Steps> <Step title="Set Up a Relay Server"> Ensure a relay server is running and accessible before you deploy any gateways. You have two options: - **Managed relay (Infisical Cloud, US/EU only):** If you are using Infisical Cloud in the US or EU regions, you can use the provided managed relay. - **Self-hosted relay:** For all other cases, you must deploy your own relay server. See the [Relay Deployment Guide](/documentation/platform/gateways/relay-deployment). </Step> <Step title="Create the Gateway in the UI"> 1. Navigate to **Organization Settings > Networking > Gateways**. 2. Click **Create Gateway**. ![Create Gateway button](/images/platform/gateways/gateway-create-button.png) 3. Enter a name for the gateway. ![Create Gateway form](/images/platform/gateways/gateway-create-form.png) 4. (Optional) Open the new gateway's detail page and click the edit icon next to **Authentication** to switch the auth method. Two methods are supported: - **Token** (default): a one-time enrollment token (1h expiry) bootstraps the gateway. - **AWS**: the gateway authenticates by signing an `sts:GetCallerIdentity` request with whatever AWS credentials it can resolve on the host (instance role, env vars, shared profile). Configure the allowed principal ARNs and/or account IDs that match your hosts. 5. Click **Show deploy command** in the **Deployment** card. Pick a relay (or "Auto Select Relay") and copy the generated CLI command. </Step> <Step title="Install the Infisical CLI"> Make sure the Infisical CLI is installed on the target machine. See the [CLI Installation Guide](/cli/overview) for instructions. </Step> <Step title="Configure Network & Firewall"> Ensure your network and firewall settings allow the gateway to connect to all required services. All connections are outbound only; no inbound ports need to be opened.

| Protocol | Destination                          | Port | Purpose                                    |
| -------- | ------------------------------------ | ---- | ------------------------------------------ |
| TCP      | Relay Server IP/Hostname             | 2222 | SSH reverse tunnel establishment           |
| TCP      | Infisical instance host (US/EU, other)  | 443  | API communication and certificate requests |

For managed relays, allow outbound traffic to the provided relay server IP/hostname. For self-hosted relays, allow outbound traffic to your own relay server address.

If you are in a corporate environment with strict egress filtering, ensure outbound TCP 2222 to relay servers and outbound HTTPS 443 to Infisical API endpoints are allowed.

</Step> <Step title="Run the CLI Command"> Run the command you copied from the UI on the target machine. This single command enrolls the gateway and starts it immediately.

<AccordionGroup>
  <Accordion title="Token Auth">
    A one-time enrollment token (1h expiry) bootstraps the gateway.

    <Tabs>
      <Tab title="Linux (Production)">
        ```bash
        sudo infisical gateway systemd install <gateway-name> \
          --enroll-method=token \
          --token=<enrollment-token> \
          --domain=<your-infisical-domain>
        sudo systemctl start infisical-gateway
        ```
      </Tab>
      <Tab title="Foreground">
        ```bash
        infisical gateway start <gateway-name> \
          --enroll-method=token \
          --token=<enrollment-token> \
          --domain=<your-infisical-domain>
        ```
      </Tab>
    </Tabs>
  </Accordion>
  <Accordion title="AWS Auth">
    The host must have AWS credentials whose principal matches your allowlist. The gateway re-authenticates via STS on every start.

    <Tabs>
      <Tab title="Linux (Production)">
        ```bash
        sudo infisical gateway systemd install <gateway-name> \
          --enroll-method=aws \
          --gateway-id=<gateway-id> \
          --domain=<your-infisical-domain>
        sudo systemctl start infisical-gateway
        ```
      </Tab>
      <Tab title="Foreground">
        ```bash
        infisical gateway start <gateway-name> \
          --enroll-method=aws \
          --gateway-id=<gateway-id> \
          --domain=<your-infisical-domain>
        ```
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

<Warning>
  The systemd install command requires Linux with root/sudo privileges.
</Warning>

<Info>
  Token-method enrollment tokens are single-use and expire after 1 hour. If the token expires before deployment, click **Show deploy command** again on the detail page to generate a new one.
</Info>

<Info>
  You can safely re-run the same command to restart the gateway. The CLI detects the token has already been used locally and skips enrollment automatically.
</Info>

</Step> <Step title="Verify Your Gateway Deployment"> After deployment, verify your gateway is working: 1. **Check logs** for "Gateway started successfully" message. 2. **Verify registration** in the Infisical UI. Navigate to **Networking > Gateways** and confirm the gateway shows a "Healthy" status. 3. **Test connectivity** by creating a resource that uses the gateway to access a private service. </Step> </Steps>

Managing a gateway

From the gateway's detail page (click the gateway row in the list):

Show deploy command — Generates a fresh enrollment token (token method) or re-displays the AWS start command. Clicking this on a token-method gateway does not disconnect the running gateway; the next login with the new token rotates credentials atomically.
Edit auth method — Switch between Token and AWS, or update the AWS allowlists. Existing gateways keep their JWT until they restart and re-authenticate.
Options → Revoke Access — Disconnects the running gateway and invalidates outstanding enrollment tokens. The gateway must re-authenticate to reconnect. Gated by the dedicated revoke-gateway-access permission, separate from edit-gateways.
Options → Delete Gateway — Permanently removes the gateway.

To migrate a gateway to a different host with zero downtime: click Show deploy command to generate a fresh token, run it on the new host, and the new login will rotate credentials away from the old host.

Frequently Asked Questions

<AccordionGroup> <Accordion title="Do I need to open any inbound ports on my firewall?"> No inbound ports need to be opened for gateways. The gateway only makes outbound connections:

Outbound SSH to relay servers on port 2222
Outbound HTTPS to Infisical API endpoints on port 443
SSH reverse tunnels handle all communication - no return traffic configuration needed

This design maintains security by avoiding the need for inbound firewall rules that could expose your network to external threats.

</Accordion> <Accordion title="How do I test network connectivity from the gateway?"> Test relay connectivity and outbound API access from the gateway:

Test SSH port to relay:

bash

nc -zv <relay-ip> 2222

Test outbound API access (replace with your Infisical domain if different):

bash

curl -I https://app.infisical.com

</Accordion> <Accordion title="How do I troubleshoot relay connectivity issues?"> If the gateway cannot connect to the relay:

Verify the relay server is running and accessible
Check firewall rules allow outbound connections on port 2222
Confirm the relay name matches exactly
Test SSH port to relay:

bash

nc -zv <relay-ip> 2222

</Accordion> <Accordion title="How do I troubleshoot authentication failures?"> For token method: ensure the enrollment token has not expired or already been used. Open the gateway's detail page and click **Show deploy command** to generate a fresh token.

For AWS method: ensure the host has AWS credentials available (instance role, env vars, or shared profile) and the resolved principal/account is in the allowlist on the gateway's detail page. </Accordion>

<Accordion title="Where can I find gateway logs?"> Check gateway logs for detailed error information:

systemd service:

bash

sudo journalctl -u infisical-gateway -f

Local installation: Logs appear in the terminal where you started the gateway </Accordion>

<Accordion title="What happens if my enrollment token expires?"> Enrollment tokens expire after 1 hour. If the token expires before deployment, open the gateway's detail page and click **Show deploy command** to generate a new one. </Accordion> <Accordion title="Where are gateway credentials stored?"> For **token-method** gateways, the access token and domain are saved to a config file scoped by gateway name:

Running as root/sudo: /etc/infisical/gateways/<name>.conf
Running as a regular user: ~/.infisical/gateways/<name>.conf

For AWS-method gateways, no JWT is persisted to disk. The gateway re-authenticates by signing a fresh STS request on every start using the host's AWS credentials. Only the gateway id and domain are stored locally.

For systemd-based installations, the configuration is at /etc/infisical/gateway.conf. All config files are created with restricted permissions (0600). </Accordion>

<Accordion title="Can I run multiple gateways on the same machine?"> Yes. Each gateway stores its credentials in a separate config file scoped by name (e.g., `~/.infisical/gateways/my-gateway.conf`). You can enroll and start multiple gateways in separate terminal sessions using different names. </Accordion> <Accordion title="What happens if there is a network interruption?"> The gateway is designed to handle network interruptions gracefully:

Automatic reconnection: The gateway will automatically attempt to reconnect to relay servers if the SSH connection is lost
Connection retry logic: Built-in retry mechanisms handle temporary network outages without manual intervention
Persistent SSH tunnels: SSH connections are automatically re-established when connectivity is restored
Certificate rotation: The gateway handles certificate renewal automatically during reconnection
Graceful degradation: The gateway logs connection issues and continues attempting to restore connectivity

No manual intervention is typically required during network interruptions.

</Accordion> </AccordionGroup>