> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperlane.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Run a Relayer
* For an introduction on Relayers in Hyperlane, you can check out the [Overview section](/docs/operate/overview-agents).
* We recommend you read through the [**Deploy Hyperlane Local Agents**](/docs/guides/chains/deploy-hyperlane-with-local-agents) guide to understand how to configure and run the Relayer locally, as well as the [**Run Validators**](/docs/operate/validators/run-validators) documentation before trying to run a production Relayer.
## Requirements
* **RPC nodes**
* A Relayer uses RPC nodes to read the origin chain(s), and deliver messages to the destination chain(s). The Relayer must be configured with an RPC node for all origin and destination chains.
* **One or more signing keys**
* In order to deliver messages, the Relayer must be configured with a signing key to submit transactions on each destination chain (thus need funds on those chains).
* The Relayer uses this key to sign `Mailbox.process()` transactions. The Hyperlane Relayer agent currently supports configuration with AWS KMS keys that are accessed via API keys/secrets or raw hexadecimal private keys.
* **A machine to run on**
* Relayer operators can compile the Rust binary themselves, or run a Docker image provided by Abacus Works. The binary can be run using your favorite cloud service.
**Running a Single Relayer**: A single relayer is generally sufficient and can
handle message delivery across 100+ chains efficiently. You don't need to run
separate relayers for each network - this approach can increase operational
complexity without providing performance benefits.
## Guide
* The local agent setup shows how you can run a Relayer on your *local machine*, which is **only for testing and development purposes**.
* We strongly encourage you to follow the [local agents guide](/docs/guides/chains/deploy-hyperlane-with-local-agents) to understand how to configure and run the Relayer locally.
### Keys
The Relayer needs to be able to submit transactions to many destination chains, and therefore requires access to a key for signing transactions. There are two supported key types: hexadecimal private keys (for in-memory signing), and AWS KMS based keys (best practice for production environments).
#### Hexadecimal keys
A hexadecimal private key used for in-memory signing can be used by your Relayer to sign transactions. This is the recommended setup for testing or development purposes, but may also be used in production.
#### AWS KMS keys
An AWS KMS key can be used by your Relayer to sign transactions. This is the recommended setup for a production Relayer.
See the [Agent Keys](/docs/operate/set-up-agent-keys) page to set up your
Hexadecimal or AWS KMS keys.
### Configuration
#### RPC Configuration
Hyperlane Validators and Relayers can use **multiple RPC URLs** to improve reliability and redundancy. The setup varies based on the chain type.
EVM-based chains support configuring multiple RPC endpoints for redundancy and can specify how they are used.
* **Configure multiple RPCs:** Use [`customRpcUrls`](/docs/operate/config/config-reference#chains-\-customrpcurls).
* **RPC Selection Mode ([`rpcConsensusType`](/docs/operate/config/config-reference#chains-\-rpcconsensustype))**:
* **Fallback**: The agent tries the first URL and switches to the next if needed.
* **Quorum**: Requires a majority of the URLs to agree with the exception of submitting transactions.
Cosmos-based chains require both **RPC and gRPC endpoints** for proper operation.
* **Configure multiple RPCs:** Use [`customRpcUrls`](/docs/operate/config/config-reference#chains-\-customrpcurls).
* **Configure gRPC endpoints:** Use \[`customGrpcUrls`].
* **Fallback Mechanism:** Cosmos agents always use **fallback mode**.
SVM-based chains support configuring multiple RPC endpoints. Agents automatically use **fallback mode**: if the current RPC fails or times out, they switch to the next available endpoint.
* **Configure RPCs:** Use [`customRpcUrls`](/docs/operate/config/config-reference#chains-\-customrpcurls).
For **SVM chains**, only **Fallback mode** is supported. SVM agents will automatically switch between configured RPC URLs when encountering errors or timeouts.
**SVM Relayer Funding**: When relaying messages to SVM chains, make sure your Relayer key has sufficient funds on the destination chain. The Relayer performs view calls via simulations that require the sender to have funds for successful simulation, even for read operations. Without sufficient funds, you may encounter `No return data from InboxGetRecipientIsm instruction` errors.
#### Configuration Settings
Like the local setup, there are a few base arguments you should provide when configuring your Relayer.
| Argument | Description |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--relayChains` | Comma separated names of the origin and destination chains to relay messages between. For example: `ethereum,polygon,avalanche`. |
| `--db` | The path to where the Relayer should write persistent data to disk. Ensure this path to be persistent when using cloud setups. When using Docker, make sure to mount the persistent path/volume into the container. See [config-reference](/docs/operate/config/config-reference#db) for more info. |
| `--allowLocalCheckpointSyncers` | If `true`, this will allow the Relayer to look for Validator signatures on the Relayer's local filesystem. In a production environment, this should be `false`. If you're running a Validator on the same machine by following the Validator local setup instructions, set this to `true` so that your Relayer can access the local Validator signatures. |
Your Relayer takes both command line arguments and environment variables as
configuration. Take a look at the [agent
configuration](/docs/operate/config/agent-config) page and the [configuration
reference](/docs/operate/config/config-reference) for a full list of
configuration possibilities.
You can also provide the path to additional configuration files as a comma separated list with the [`CONFIG_FILES` environment variable](/docs/operate/config/config-reference#config_files). If you choose to run in Docker, see the docker section of [agent configuration](/docs/operate/config/agent-config) for tips on mounting your config files into your Docker container.
### Setup-specific configuration
These configurations requirements differ depending on which key setup instructions you followed.
If you created a [hexadecimal key](../set-up-agent-keys), configure the default signer like so:
| Argument | Description |
| --------------------- | -------------------------------------------------------------------------------------------------- |
| `--defaultSigner.key` | A hexadecimal private key used to sign transactions for all chains. For example: `1b3dead...beef`. |
If you created an [AWS KMS key](../set-up-agent-keys), configure the default signer like so:
| Argument | Description |
| ------------------------ | ---------------------------------------------------------------------------------------------------------- |
| `--defaultSigner.type` | Set to `aws`. |
| `--defaultSigner.id` | The alias of your Relayer's AWS KMS key, prefixed with `alias/`. For example: `alias/hyperlane-relayer-1`. |
| `--defaultSigner.region` | The region of your AWS KMS key. For example: `us-east-1`. |
For chain-specific signers (i.e. to customize the key to use for each chain) take a look at the [configuration reference](/docs/operate/config/config-reference)
## Start Relaying
### Setup
The recommended installation method for a production environment is using a Docker image.
First download the docker image:
```bash theme={null}
docker pull --platform linux/amd64 ghcr.io/hyperlane-xyz/hyperlane-agent:agents-v2.2.0
```
**Clone and setup**
First, clone the Hyperlane monorepo:
```sh theme={null}
git clone git@github.com:hyperlane-xyz/hyperlane-monorepo.git
```
Then follow the [setup instructions](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/rust/README.md) in the `rust` directory. This should setup `rustup` as well as Rosetta 2 if you are on Apple Silicon.
```sh theme={null}
# install rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# (apple silicon only) install rosetta 2
softwareupdate --install-rosetta --agree-to-license
```
Build the Relayer:
```sh theme={null}
cargo build --release bin relayer
```
### Running the agent
If the Relayer's keys have been configured with AWS KMS, you will have to provide the AWS access key and secret as environment variables.
| Environment variable | Description |
| ----------------------- | ----------------------------------------------------- |
| `AWS_ACCESS_KEY_ID` | The access key ID of your Relayer's AWS IAM user. |
| `AWS_SECRET_ACCESS_KEY` | The secret access key of your Relayer's AWS IAM user. |
For a refresher, check out the [Agent Keys](/docs/operate/set-up-agent-keys) guide.
Then start the container with the relevant arguments. For example, your configuration for AWS:
```sh theme={null}
docker run \
-it \
-e AWS_ACCESS_KEY_ID=ABCDEFGHIJKLMNOP \
-e AWS_SECRET_ACCESS_KEY=xX-haha-nice-try-Xx \
--mount ... \
ghcr.io/hyperlane-xyz/hyperlane-agent:agents-v2.2.0 \
./relayer \
--db /hyperlane_db \
--relayChains , \
--defaultSigner.type aws \
--defaultSigner.id alias/hyperlane-relayer-1 \
--defaultSigner.region us-east-1 \
```
If you're running Validators with a local setup on the same machine and running a local Relayer to access these Validator signatures, be sure to [mount](https://docs.docker.com/storage/bind-mounts/) your local Validator's signature directory into your Relayer at the same path that you used when [announcing your Validator](/docs/operate/validators/run-validators#announcing-your-validator)
For example, if your local Validator is writing signatures to `/tmp/hyperlane-validator-signatures-ethereum`, you should mount a directory for the Docker container:
```sh theme={null}
docker run \
-it \
-e CONFIG_FILES=/config/agent-config.json \
--mount type=bind,source=$CONFIG_FILES,target=/config/agent-config.json,readonly \
--mount type=bind,source="$(pwd)"/hyperlane-validator-signatures-ethereum,target=/tmp/hyperlane-validator-signatures-ethereum,readonly \
--mount type=bind,source="$(pwd)"/hyperlane_db,target=/hyperlane_db \
ghcr.io/hyperlane-xyz/hyperlane-agent:agents-v2.2.0 \
./relayer \
--db /hyperlane_db \
--relayChains ethereum,polygon,avalanche \
--allowLocalCheckpointSyncers true \
--defaultSigner.key \
```
See these instructions for building from source without Docker.
We can run the built binary from within the `hyperlane-monorepo/rust` directory:
```sh theme={null}
# set AWS environment variables
export AWS_ACCESS_KEY_ID=ABCDEFGHIJKLMNOP
export AWS_SECRET_ACCESS_KEY=xX-haha-nice-try-Xx
# run the Relayer
./target/release/relayer \
--db /hyperlane_db \
--relayChains , \
--defaultSigner.type aws \
--defaultSigner.id alias/hyperlane-relayer-1 \
--defaultSigner.region us-east-1 \
```
## Indexing
The Relayer needs to index all historic messages for the origin chain(s). This information is stored in a local database on disk (set with `db` in the config). This means running a Relayer for the first time may take some extra time to catch up with the current state.