How to Configure and Deploy Relayers with Starship for Interchain Communication

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 (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 (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 consumed by the relayer binary.

Basic Relayer Structure

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 and inject the relayer mnemonic from the generated keys.json (see lines 44-70 in 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, deploy the complete infrastructure including chains and relayers:

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

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

starship connect

The PortForwardCmds() method in 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

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

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

Create an IBC Channel

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 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.
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 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) 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 configuration file that expects a source and destination chain pair. As implemented in 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 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 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 file. Note that most IBC relayer binaries are designed for single-instance operation per channel.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}