infisical/docs/cli/commands/relay.mdx

---
title: "infisical relay"
description: "Relay-related commands for Infisical"
---

<Tabs>
  <Tab title="Start relay">
    ```bash
    infisical relay start --type=<type> --host=<host> --name=<name> --auth-method=<auth-method>
    ```
  </Tab>
  <Tab title="Start relay as background daemon (Linux only)">
    ```bash
    # Install systemd service
    sudo infisical relay systemd install --type=<type> --host=<host> --name=<name> --token=<token>
    
    # Uninstall systemd service
    sudo infisical relay systemd uninstall
    ```
  </Tab>
</Tabs>

## Description

Relay-related commands for Infisical that provide identity-aware relay infrastructure for routing encrypted traffic:

- **Relay**: Identity-aware server that routes encrypted traffic (can be instance-wide or organization-specific)

The relay system uses SSH reverse tunnels over TCP, eliminating firewall complexity and providing excellent performance for enterprise environments.

## Subcommands & flags

<Accordion title="infisical relay start" defaultOpen="true">
  Run the Infisical relay component. The relay handles network traffic routing and can operate in different modes.

```bash
infisical relay start --type=<type> --host=<host> --name=<name> --auth-method=<auth-method>
```

### Flags

  <Accordion title="--type">
    The type of relay to run. Must be either 'instance' or 'org'.
    
    - **`instance`**: Shared relay server that can be used by all organizations on your Infisical instance. Set up by the instance administrator. Uses `INFISICAL_RELAY_AUTH_SECRET` environment variable for authentication, which must be configured by the instance admin.
    - **`org`**: Dedicated relay server that individual organizations deploy and manage in their own infrastructure. Provides enhanced security, custom geographic placement, and compliance benefits. Uses standard Infisical authentication methods.

    ```bash
    # Organization relay (customer-deployed)
    infisical relay start --type=org --host=192.168.1.100 --name=my-org-relay

    # Instance relay (configured by instance admin)
    INFISICAL_RELAY_AUTH_SECRET=<secret> infisical relay start --type=instance --host=10.0.1.50 --name=shared-relay
    ```

  </Accordion>

  <Accordion title="--host">
    The host (IP address or hostname) of the instance where the relay is deployed. This must be a static public IP or resolvable hostname that gateways can reach.

    ```bash
    # Example with IP address
    infisical relay start --host=203.0.113.100 --type=org --name=my-relay

    # Example with hostname
    infisical relay start --host=relay.example.com --type=org --name=my-relay
    ```

  </Accordion>

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

    ```bash
    # Example
    infisical relay start --name=my-relay --type=org --host=192.168.1.100
    ```

  </Accordion>

### Authentication

**Organization Relays (`--type=org`):**
Deploy your own relay server in your infrastructure for enhanced security and reduced latency. Supports all standard Infisical authentication methods documented below.

**Instance Relays (`--type=instance`):**
Shared relay servers that serve all organizations on your Infisical instance. For Infisical Cloud, these are already running and ready to use. For self-hosted deployments, they're set up by the instance administrator. Authentication is handled via the `INFISICAL_RELAY_AUTH_SECRET` environment variable.

```bash
# Organization relay with Universal Auth (customer-deployed)
infisical relay start --type=org --host=192.168.1.100 --name=my-org-relay --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret>

# Instance relay (configured by instance admin)
INFISICAL_RELAY_AUTH_SECRET=<secret> infisical relay start --type=instance --host=10.0.1.50 --name=shared-relay
```

### Authentication Methods

The Infisical CLI supports multiple authentication methods for organization relays. 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 relay start --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret> --type=org --host=<host> --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 relay start --auth-method=kubernetes --machine-identity-id=<machine-identity-id> --type=org --host=<host> --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 relay start --auth-method=azure --machine-identity-id=<machine-identity-id> --type=org --host=<host> --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 relay start --auth-method=gcp-id-token --machine-identity-id=<machine-identity-id> --type=org --host=<host> --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 relay start --auth-method=gcp-iam --machine-identity-id=<machine-identity-id> --service-account-key-file-path=<service-account-key-file-path> --type=org --host=<host> --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 relay start --auth-method=aws-iam --machine-identity-id=<machine-identity-id> --type=org --host=<host> --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 relay start --auth-method=oidc-auth --machine-identity-id=<machine-identity-id> --jwt=<oidc-jwt> --type=org --host=<host> --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 relay start --auth-method=jwt-auth --jwt=<jwt> --machine-identity-id=<machine-identity-id> --type=org --host=<host> --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 relay start --token=<token> --type=org --host=<host> --name=<name>
    ```

  </Accordion>
</AccordionGroup>

### Deployment Considerations

**When to use Instance Relays (`--type=instance`):**

- You want to get started quickly without setting up your own relay infrastructure
- You're using Infisical Cloud and want to leverage the existing relay infrastructure
- You're on a self-hosted instance where the admin has already set up shared relays
- You don't need custom geographic placement of relay servers
- You don't have specific compliance requirements that require dedicated infrastructure
- You want to minimize operational overhead by using shared infrastructure

**When to use Organization Relays (`--type=org`):**

- You need lower latency by deploying relay servers closer to your resources
- You have security requirements that mandate running infrastructure in your own environment
- You have compliance requirements such as data sovereignty or air-gapped environments
- You need custom network policies or specific networking configurations
- You have high-scale performance requirements that shared infrastructure can't meet
- You want full control over your relay infrastructure and its configuration

</Accordion>

<Accordion title="infisical relay systemd" defaultOpen="false">
  Manage systemd service for Infisical relay. This allows you to install and run the relay as a systemd service on Linux systems.
  ### Requirements
  - **Operating System**: Linux only (systemd is not supported on other operating systems)
  - **Privileges**: Root/sudo privileges required for both install and uninstall operations
  - **Systemd**: The system must be running systemd as the init system

```bash
infisical relay systemd <subcommand>
```

### Subcommands

<Accordion title="install">
  Install and enable systemd service for the relay. Must be run with sudo on Linux systems.

```bash
sudo infisical relay systemd install --type=<type> --host=<host> --name=<name> [flags]
```

#### Flags

<Accordion title="--type">
  The type of relay to run. Must be either 'instance' or 'org'.
  
  - **`instance`**: Shared relay server that can be used by all organizations on your Infisical instance. Requires `--relay-auth-secret` flag or `INFISICAL_RELAY_AUTH_SECRET` environment variable.
  - **`org`**: Dedicated relay server that individual organizations deploy and manage in their own infrastructure. Requires `--token` flag.

```bash
# Organization relay
sudo infisical relay systemd install --type=org --host=192.168.1.100 --name=my-org-relay --token=<token>

# Instance relay
sudo infisical relay systemd install --type=instance --host=10.0.1.50 --name=shared-relay --relay-auth-secret=<secret>
```

</Accordion>

<Accordion title="--host">
  The host (IP address or hostname) of the instance where the relay is deployed. This must be a static public IP or resolvable hostname that gateways can reach.

```bash
# Example with IP address
sudo infisical relay systemd install --host=203.0.113.100 --type=org --name=my-relay --token=<token>

# Example with hostname
sudo infisical relay systemd install --host=relay.example.com --type=org --name=my-relay --token=<token>
```

</Accordion>

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

```bash
# Example
sudo infisical relay systemd install --name=my-relay --type=org --host=192.168.1.100 --token=<token>
```

</Accordion>

<Accordion title="--token">
  Connect with Infisical using machine identity access token. Required for organization relays (`--type=org`).

```bash
# Example
sudo infisical relay systemd install --token=<machine-identity-token> --type=org --host=<host> --name=<name>
```

</Accordion>

<Accordion title="--domain">
  Domain of your self-hosted Infisical instance. Optional flag for specifying a custom domain.

```bash
# Example
sudo infisical relay systemd install --domain=http://localhost:8080 --token=<token> --type=org --host=<host> --name=<name>
```

</Accordion>

<Accordion title="--relay-auth-secret">
  Relay auth secret. Required for instance relays (`--type=instance`) if the `INFISICAL_RELAY_AUTH_SECRET` environment variable is not set.

```bash
# Example
sudo infisical relay systemd install --relay-auth-secret=<secret> --type=instance --host=<host> --name=<name>
```

</Accordion>

#### Examples

```bash
# Install organization relay with token authentication
sudo infisical relay systemd install --type=org --host=192.168.1.100 --name=my-org-relay --token=<machine-identity-token>

# Install instance relay with auth secret
sudo infisical relay systemd install --type=instance --host=10.0.1.50 --name=shared-relay --relay-auth-secret=<secret>

# Install with custom domain
sudo infisical relay systemd install --domain=http://localhost:8080 --token=<token> --type=org --host=<host> --name=<name>
```

#### Post-installation

After successful installation, the service will be enabled but not started. To start the service:

```bash
sudo systemctl start infisical-relay
```

To check the service status:

```bash
sudo systemctl status infisical-relay
```

To view service logs:

```bash
sudo journalctl -u infisical-relay -f
```

</Accordion>

<Accordion title="uninstall">
  Uninstall and remove systemd service for the relay. Must be run with sudo on Linux systems.

```bash
sudo infisical relay systemd uninstall
```

#### Examples

```bash
# Uninstall the relay systemd service
sudo infisical relay systemd uninstall
```

#### What it does

- Stops the `infisical-relay` systemd service if it's running
- Disables the service from starting on boot
- Removes the systemd service file
- Cleans up the service configuration

</Accordion>

</Accordion>