# Source: https://infisical.com/docs/cli/commands/relay.md

> ## Documentation Index
> Fetch the complete documentation index at: https://infisical.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# infisical relay

> Relay-related commands for Infisical

<Tabs>
  <Tab title="Start relay">
    ```bash  theme={"dark"}
    infisical relay start --host=<host> --name=<name> --auth-method=<auth-method>
    ```
  </Tab>

  <Tab title="Start relay as background daemon (Linux only)">
    ```bash  theme={"dark"}
    # 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  theme={"dark"}
    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  theme={"dark"}
        # 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  theme={"dark"}
        # 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  theme={"dark"}
    # 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  theme={"dark"}
          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  theme={"dark"}
          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  theme={"dark"}
          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  theme={"dark"}
          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  theme={"dark"}
          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  theme={"dark"}
          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  theme={"dark"}
          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  theme={"dark"}
          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  theme={"dark"}
          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  theme={"dark"}
    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  theme={"dark"}
        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  theme={"dark"}
            # 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  theme={"dark"}
            # 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  theme={"dark"}
            # 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  theme={"dark"}
            # Example
            sudo infisical relay systemd install --domain=http://localhost:8080 --token=<token> --host=<host> --name=<name>
            ```
          </Accordion>
        </AccordionGroup>

        #### Examples

        ```bash  theme={"dark"}
        # 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  theme={"dark"}
        sudo systemctl start infisical-relay
        ```

        To check the service status:

        ```bash  theme={"dark"}
        sudo systemctl status infisical-relay
        ```

        To view service logs:

        ```bash  theme={"dark"}
        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  theme={"dark"}
        sudo infisical relay systemd uninstall
        ```

        #### Examples

        ```bash  theme={"dark"}
        # 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>