infisical/docs/cli/commands/relay.mdx

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

<Tabs>
  <Tab title="Start relay">
    ```bash
    infisical relay start --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 --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. Relays are organization-deployed servers that route encrypted traffic between Infisical and your gateways.

## Subcommands & flags

<AccordionGroup>
<Accordion title="infisical relay start" defaultOpen="true">
  Run the Infisical relay component. The relay handles network traffic routing between Infisical and your gateways.

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

### Flags

  <AccordionGroup>
  <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 --name=my-relay

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

  </Accordion>

  <Accordion title="--name">
    The name of the relay. This is an arbitrary identifier for your relay instance.

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

  </Accordion>
  </AccordionGroup>

### Authentication

Relays support all standard Infisical authentication methods. Choose the authentication method that best fits your environment and set the corresponding flags when starting the relay.

```bash
# Example with Universal Auth
infisical relay start --host=192.168.1.100 --name=my-relay --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret>
```

### Available Authentication Methods

The Infisical CLI supports multiple authentication methods for 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> --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> --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> --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> --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> --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> --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> --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> --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> --host=<host> --name=<name>
    ```

  </Accordion>
</AccordionGroup>

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

<AccordionGroup>
<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 --host=<host> --name=<name> --token=<token> [flags]
```

#### Flags

<AccordionGroup>
<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 --name=my-relay --token=<token>

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

</Accordion>

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

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

</Accordion>

<Accordion title="--token">
  Connect with Infisical using machine identity access token.

```bash
# Example
sudo infisical relay systemd install --token=<machine-identity-token> --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> --host=<host> --name=<name>
```

</Accordion>
</AccordionGroup>

#### Examples

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

# Install with custom domain
sudo infisical relay systemd install --domain=http://localhost:8080 --token=<token> --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>
</AccordionGroup>

</Accordion>
</AccordionGroup>