infisical relay

Relay-related commands for Infisical

Start relay

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

Start relay as background daemon (Linux only)

# Install systemd service
sudo infisical relay systemd install --host=<host> --name=<name> --token=<token>

# Uninstall systemd service
sudo infisical relay systemd uninstall

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

infisical relay start

Run the Infisical relay component. The relay handles network traffic routing between Infisical and your gateways.

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

Flags

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

# 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

--name

The name of the relay. This is an arbitrary identifier for your relay instance.

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

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.

# 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.

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.

Flags

Show properties

client-id · string · required

Your machine identity client ID.

client-secret · string · required

Your machine identity client secret.

auth-method · string · required

The authentication method to use. Must be universal-auth when using Universal Auth.

  infisical relay start --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret> --host=<host> --name=<name>

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.

Flags

Show properties

machine-identity-id · string · required

Your machine identity ID.

service-account-token-path · string

Path to the Kubernetes service account token to use. Default: /var/run/secrets/kubernetes.io/serviceaccount/token.

auth-method · string · required

The authentication method to use. Must be kubernetes when using Native Kubernetes.

  infisical relay start --auth-method=kubernetes --machine-identity-id=<machine-identity-id> --host=<host> --name=<name>

Native Azure

The Native Azure method is used to authenticate with Infisical when running in an Azure environment.

Flags

Show properties

machine-identity-id · string · required

Your machine identity ID.

auth-method · string · required

The authentication method to use. Must be azure when using Native Azure.

  infisical relay start --auth-method=azure --machine-identity-id=<machine-identity-id> --host=<host> --name=<name>

Native GCP ID Token

The Native GCP ID Token method is used to authenticate with Infisical when running in a GCP environment.

Flags

Show properties

machine-identity-id · string · required

Your machine identity ID.

auth-method · string · required

The authentication method to use. Must be gcp-id-token when using Native GCP ID Token.

  infisical relay start --auth-method=gcp-id-token --machine-identity-id=<machine-identity-id> --host=<host> --name=<name>

GCP IAM

The GCP IAM method is used to authenticate with Infisical with a GCP service account key.

Flags

Show properties

machine-identity-id · string · required

Your machine identity ID.

service-account-key-file-path · string · required

Path to your GCP service account key file (Must be in JSON format!)

auth-method · string · required

The authentication method to use. Must be gcp-iam when using GCP IAM.

  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>

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.

Flags

Show properties

machine-identity-id · string · required

Your machine identity ID.

auth-method · string · required

The authentication method to use. Must be aws-iam when using Native AWS IAM.

  infisical relay start --auth-method=aws-iam --machine-identity-id=<machine-identity-id> --host=<host> --name=<name>

OIDC Auth

The OIDC Auth method is used to authenticate with Infisical via identity tokens with OIDC.

Flags

Show properties

machine-identity-id · string · required

Your machine identity ID.

jwt · string · required

The OIDC JWT from the identity provider.

auth-method · string · required

The authentication method to use. Must be oidc-auth when using OIDC Auth.

  infisical relay start --auth-method=oidc-auth --machine-identity-id=<machine-identity-id> --jwt=<oidc-jwt> --host=<host> --name=<name>

JWT Auth

The JWT Auth method is used to authenticate with Infisical via a JWT token.

Flags

Show properties

jwt · string · required

The JWT token to use for authentication.

machine-identity-id · string · required

Your machine identity ID.

auth-method · string · required

The authentication method to use. Must be jwt-auth when using JWT Auth.

  infisical relay start --auth-method=jwt-auth --jwt=<jwt> --machine-identity-id=<machine-identity-id> --host=<host> --name=<name>

Token Auth

You can use the INFISICAL_TOKEN environment variable to authenticate with Infisical with a raw machine identity access token.

Flags

Show properties

token · string · required

The machine identity access token to use for authentication.

  infisical relay start --token=<token> --host=<host> --name=<name>

infisical relay systemd

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

infisical relay systemd <subcommand>

Subcommands

install

Install and enable systemd service for the relay. Must be run with sudo on Linux systems.

sudo infisical relay systemd install --host=<host> --name=<name> --token=<token> [flags]

Flags

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

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

--name

The name of the relay.

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

--token

Connect with Infisical using machine identity access token.

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

--domain

Domain of your self-hosted Infisical instance. Optional flag for specifying a custom domain.

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

Examples

# 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:

sudo systemctl start infisical-relay

To check the service status:

sudo systemctl status infisical-relay

To view service logs:

sudo journalctl -u infisical-relay -f

uninstall

Uninstall and remove systemd service for the relay. Must be run with sudo on Linux systems.

sudo infisical relay systemd uninstall

Examples

# 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