infisical relay - Infisical

Description

Relay-related commands for Infisical. Relays are organization-deployed servers that route encrypted traffic between Infisical and your gateways.

Relays are created via the Infisical dashboard (Networking → Relays → Create Relay) and then deployed using the CLI commands below.

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.

Authentication

Relays support two enrollment methods. The enrollment method is set when creating the relay in the dashboard.

<AccordionGroup> <Accordion title="Token Auth"> Token auth uses a one-time enrollment token (1 hour expiry) generated from the relay detail page. The token is exchanged for a long-lived access token on first start and stored on disk for subsequent restarts.

The `--host` flag is not required — the host is stored server-side when the relay is created.

<Tabs>
  <Tab title="Foreground">
    ```bash
    infisical relay start \
      --name=<name> \
      --enroll-method=token \
      --token=<enrollment-token> \
      --domain=<your-infisical-domain>
    ```
  </Tab>
  <Tab title="Linux (systemd)">
    ```bash
    sudo infisical relay systemd install <name> \
      --enroll-method=token \
      --token=<enrollment-token> \
      --domain=<your-infisical-domain>
    sudo systemctl start <name>
    ```
  </Tab>
</Tabs>

On subsequent starts with the same enrollment token, the relay skips enrollment and uses the stored access token.

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

</Accordion> <Accordion title="AWS Auth"> AWS auth uses the host's AWS credentials (instance role, env vars, or shared profile) to authenticate via STS GetCallerIdentity. A fresh token is minted on every start — no on-disk persistence needed.

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

The `--relay-id` is the relay's UUID, visible on the relay detail page. The relay ID is persisted after first use so subsequent starts don't need `--relay-id` again.

</Accordion> </AccordionGroup>

Flags

<AccordionGroup> <Accordion title="--name"> The name of the relay. Must match the name used when creating the relay in the dashboard. </Accordion> <Accordion title="--enroll-method"> The enrollment method to use. Supported values: `token`, `aws`. </Accordion> <Accordion title="--token"> The one-time enrollment token (required when `--enroll-method=token`). Generated from the relay detail page via **Show deploy command**. </Accordion> <Accordion title="--relay-id"> The relay UUID (required when `--enroll-method=aws`). Visible on the relay detail page. </Accordion> <Accordion title="--domain"> Domain of your Infisical instance. Required for self-hosted deployments. </Accordion> </AccordionGroup> </Accordion> <Accordion title="infisical relay systemd" defaultOpen="false"> Manage systemd service for the Infisical relay on Linux systems.

Requirements

Operating System: Linux only
Privileges: Root/sudo privileges required
Systemd: The system must be running systemd

Subcommands

<AccordionGroup> <Accordion title="install"> Install and enable a systemd service for the relay. The relay name is provided as a positional argument, and the installed service is named after it, so you can run multiple relays on the same machine. See the authentication section above for the full install commands.

bash

sudo infisical relay systemd install <name> --enroll-method=token --token=<enrollment-token> --domain=<your-infisical-domain>

After installation, start and enable the service (replace <name> with your relay name):

bash

sudo systemctl start <name>

To check status and logs:

bash

sudo systemctl status <name>
sudo journalctl -u <name> -f

Service Details

Service file: /etc/systemd/system/<name>.service
Config directory: /etc/infisical/relays/
Runs with restricted privileges and automatically restarts on failure
Enabled to start on boot </Accordion>

<Accordion title="uninstall"> Uninstall and remove a relay's systemd service. The relay name is provided as a positional argument.

bash

sudo infisical relay systemd uninstall <name>

</Accordion> </AccordionGroup> </Accordion> </AccordionGroup>