# How to Configure and Deploy Relayers with Starship for Interchain Communication

> Configure and deploy relayers with Starship for interchain communication. Easily set up IBC channel management using Helm or the Starship CLI for seamless devnet deployment.

- Repository: [Hyperweb/starship](https://github.com/hyperweb-io/starship)
- Tags: how-to-guide
- Published: 2026-03-03

---

**You configure relayers in Starship by declaring them in the `relayers:` section of your Helm values file, then deploy the devnet using `helm upgrade` or the `starship` CLI, which generates Kubernetes StatefulSets that automatically initialize keys and expose REST APIs for IBC channel management.**

Starship is a **Helm-based devnet orchestrator** maintained by `hyperweb-io/starship` that spins up complete Cosmos SDK development environments including blockchain nodes, faucets, explorers, and IBC relayers. Configuring relayers for interchain communication requires understanding how the `Relayer` Go struct, Helm values schema, and Kubernetes templates interact to deploy functional packet relay infrastructure.

## Understanding Starship's Relayer Architecture

Starship implements relayers through three coordinated components that transform declarative YAML into running Kubernetes pods.

**The Configuration Model** — defined in [`starship/cmd/starship/model.go`](https://github.com/hyperweb-io/starship/blob/main/starship/cmd/starship/model.go) (lines 79-86) — provides the `Relayer` Go struct that captures name, type, replica count, chain list, and port mappings. This struct unmarshals the YAML configuration into an in-memory representation that the CLI consumes.

**Helm Values Schema** — located in [`starship/charts/devnet/values.yaml`](https://github.com/hyperweb-io/starship/blob/main/starship/charts/devnet/values.yaml) (lines 58-67) — exposes the `relayers:` array where users declare which relayer binaries to run, which chains they bridge, and any image overrides.

**Kubernetes Templates** — found under `starship/charts/devnet/templates/relayers/` — generate StatefulSets for each supported relayer type (`ts-relayer`, `go-relayer`, `hermes`, `neutron-query-relayer`). These templates mount keys, build configuration files, and run the appropriate binaries.

## Declaring Relayers in values.yaml

The `relayers:` array is the primary interface for configuring interchain communication. Each entry requires exactly two chains (source and destination) because the init container builds an [`app.yaml`](https://github.com/hyperweb-io/starship/blob/main/app.yaml) consumed by the relayer binary.

### Basic Relayer Structure

```yaml
relayers:
  - name: osmo-wasm          # Human-readable identifier

    type: ts-relayer         # Supported: ts-relayer, go-relayer, hermes, neutron-query-relayer

    replicas: 1              # Currently supports single replica per relayer

    chains:
      - osmosis-1            # Must match chain IDs defined in the same values file

      - wasmd
    ports:
      rest: 3000             # Local port for REST API

      exposer: 8081          # Optional sidecar port

```

The `chains` field must contain **exactly two entries**. The chart's init container uses these IDs to generate [`/root/.ibc-setup/app.yaml`](https://github.com/hyperweb-io/starship/blob/main//root/.ibc-setup/app.yaml) and inject the relayer mnemonic from the generated [`keys.json`](https://github.com/hyperweb-io/starship/blob/main/keys.json) (see lines 44-70 in [`ts-relayer/statefulset.yaml`](https://github.com/hyperweb-io/starship/blob/main/ts-relayer/statefulset.yaml)).

### Supported Relayer Types

Starship supports four distinct relayer implementations through dedicated templates:

- **`ts-relayer`** — TypeScript implementation based on `@confio/relayer`
- **`go-relayer`** — Cosmos SDK relayer written in Go
- **`hermes`** — Rust-based relayer by Informal Systems
- **`neutron-query-relayer`** — Specialized Go relayer for Neutron query modules

Each type selects appropriate defaults from the chart's `defaultRelayers` map, making the `image` field optional.

## Deploying the Devnet with Helm

After configuring [`values.yaml`](https://github.com/hyperweb-io/starship/blob/main/values.yaml), deploy the complete infrastructure including chains and relayers:

```bash
helm upgrade --install starship ./starship/charts/devnet \
  -f ./starship/charts/devnet/values.yaml \
  -f my-relayers.yaml \
  --create-namespace --namespace starship-dev

```

This command triggers the following sequence:

1. **Template Selection** — Helm loops over `.Values.relayers` and selects the matching template based on `type` (e.g., `if eq $relayer.type "ts-relayer"`).
2. **StatefulSet Generation** — Creates a StatefulSet named `<type>-<name>` (e.g., `ts-relayer-osmo-wasm`).
3. **Init Container Execution** — Builds [`app.yaml`](https://github.com/hyperweb-io/starship/blob/main/app.yaml) from chain IDs, injects mnemonics, and optionally transfers initial token balances (lines 44-81 of the StatefulSet template).
4. **Relayer Startup** — Runs `ibc-relayer start` (or `neutron_query_relayer start` for Neutron variants).

Alternatively, use the Starship CLI wrapper:

```bash
starship deploy  # Reads configuration from starship.yaml and executes helm upgrade

```

## Accessing Relayers via Port Forwarding

Relayers expose REST APIs for channel creation and state monitoring. Access these endpoints locally using the `starship connect` command or the helper script.

### Using the CLI

```bash
starship connect

```

The `PortForwardCmds()` method in [`starship/cmd/starship/connect.go`](https://github.com/hyperweb-io/starship/blob/main/starship/cmd/starship/connect.go) (lines 80-88) iterates over `config.Relayers`, reads local ports from `relayer.Ports.rest` and `relayer.Ports.exposer`, and generates `kubectl port-forward` commands for each pod.

### Using the Helper Script

```bash
./starship/scripts/port-forward.sh

```

Both methods output forwarding status:

```

port-forwarding: ts-relayer-osmo-wasm: port rest: to: http://localhost:3000
port-forwarding: ts-relayer-osmo-wasm: port exposer: to: http://localhost:8081

```

## Creating IBC Channels and Relaying Packets

With ports forwarded, interact with the relayer's REST API to establish channels and monitor state.

### Check Relayer State

```bash
curl http://localhost:3000/state | jq .

```

### Create an IBC Channel

```bash
curl -X POST http://localhost:3000/create_channel \
  -H "Content-Type: application/json" \
  -d '{
        "src_chain":"osmosis-1",
        "dst_chain":"wasmd",
        "order":"unordered",
        "version":"ics20-1"
      }'

```

The relayer automatically creates the channel, begins relaying packets between the configured chains, and exposes status endpoints for monitoring.

## Advanced Relayer Configuration

| Requirement | Implementation |
|-------------|----------------|
| **Custom IBC parameters** | Edit the `command` block in the appropriate [`statefulset.yaml`](https://github.com/hyperweb-io/starship/blob/main/statefulset.yaml) template to pass additional flags (e.g., `--poll`, custom channel versions). |
| **High-availability deployments** | Set `replicas: 2` or higher. The StatefulSet creates indexed pods (`RLY_INDEX`) that select unique mnemonics from [`keys.json`](https://github.com/hyperweb-io/starship/blob/main/keys.json). |
| **Custom binaries** | Override the `image` field in your values file. The chart falls back to `defaultRelayers` map entries when omitted. |
| **External relayer operation** | Extract [`/root/.ibc-setup/app.yaml`](https://github.com/hyperweb-io/starship/blob/main//root/.ibc-setup/app.yaml) from the init container and run the relayer binary locally with identical configuration. |

## Summary

- **Declare relayers** in the `relayers:` array of your Helm values file, specifying `type`, `name`, and exactly two `chains`.
- **Deploy** using `helm upgrade` or `starship deploy` to generate StatefulSets that auto-initialize keys and configuration.
- **Connect locally** via `starship connect` (implemented in [`connect.go`](https://github.com/hyperweb-io/starship/blob/main/connect.go)) to forward REST and exposer ports.
- **Manage channels** through the relayer's HTTP API at `localhost:3000/create_channel` and monitor via `/state`.
- **Customize** images, replica counts, and binary arguments through Helm values or direct template modification.

## Frequently Asked Questions

### What relayer types does Starship support?

Starship supports **four relayer implementations**: `ts-relayer` (TypeScript), `go-relayer` (Go/Cosmos SDK), `hermes` (Rust), and `neutron-query-relayer` (Go). Each type uses a dedicated StatefulSet template under `charts/devnet/templates/relayers/` with specialized init logic for key injection and configuration.

### Why must I specify exactly two chains per relayer?

The relayer's **init container** generates an [`app.yaml`](https://github.com/hyperweb-io/starship/blob/main/app.yaml) configuration file that expects a source and destination chain pair. As implemented in [`ts-relayer/statefulset.yaml`](https://github.com/hyperweb-io/starship/blob/main/ts-relayer/statefulset.yaml) (lines 44-70), the init script builds this file from the two chain IDs provided in the `chains` array, configuring the binary's connection topology.

### How do I expose relayer APIs on my local machine?

Run `starship connect` (defined in [`starship/cmd/starship/connect.go`](https://github.com/hyperweb-io/starship/blob/main/starship/cmd/starship/connect.go) lines 80-88) to execute `kubectl port-forward` commands for all relayer REST ports declared in your values file. Alternatively, execute [`./starship/scripts/port-forward.sh`](https://github.com/hyperweb-io/starship/blob/main/./starship/scripts/port-forward.sh) to forward ports for all relayers and chains simultaneously.

### Can I run multiple replicas of the same relayer?

Yes. Set `replicas: N` in your relayer configuration. The chart creates a StatefulSet with the requested replica count, where each pod receives a unique index via the `RLY_INDEX` environment variable and selects a distinct mnemonic from the generated [`keys.json`](https://github.com/hyperweb-io/starship/blob/main/keys.json) file. Note that most IBC relayer binaries are designed for single-instance operation per channel.