How to Deploy Multiple Blockchain Networks Locally Using Starship in Kubernetes

Starship is a CLI-driven tool that transforms declarative YAML configurations into fully-featured Kubernetes devnets, enabling you to deploy multiple blockchain networks locally with a single command.

Starship, developed by hyperweb-io, simplifies local blockchain development by orchestrating multi-chain environments inside Kubernetes. By defining your desired networks in a YAML file and running starship start, you can spin up interconnected Cosmos SDK-based chains, complete with validators, relayers, and exploratory tools, all within your local kind or existing cluster.

Understanding Starship's Architecture

The deployment pipeline follows a strict sequence from configuration parsing to Kubernetes resource generation. According to the source code in cmd/starship/main.go, the CLI loads your YAML file into a Config struct before initiating any cluster operations.

Configuration Parsing and Helm Setup

When you execute starship start <config.yaml>, the tool first validates your configuration and initializes the Helm environment. In cmd/starship/charts.go, the AddOrUpdateChartRepo function contacts the Helm repository defined in your config—typically https://hyperweb-io.github.io/starship—and validates the chart version against the requested release.

Chart Installation and Resource Generation

The InstallChart function (also in cmd/starship/charts.go) builds a Helm Install client, merges values from your configuration file, and executes the release into the target namespace. This renders one StatefulSet per validator with associated sidecars including exposers, faucets, and relayers. Each validator's Docker image is pulled from the chains[].image field you specify, or falls back to default images defined in charts/devnet/values.yaml.

Configuring Multiple Blockchain Networks

A multi-chain devnet requires only a list of chain objects under the top-level chains key in your YAML configuration. The examples/multi-chain/configs/osmo-juno-cosmos.yaml file demonstrates this pattern with three interconnected networks:

chains:
  - id: osmosis-1
    name: osmosis
    numValidators: 1
    ports:
      rest: 1313
      rpc: 26653
  - id: juno-1
    name: juno
    numValidators: 1
    ports:
      rest: 1315
      rpc: 26655
  - id: cosmoshub-1
    name: cosmoshub
    numValidators: 1
    ports:
      rest: 1317
      rpc: 26657

Each id becomes the Kubernetes Service name for that chain. The numValidators field dictates how many validator pods the chart creates—the first pod serves as the genesis node, while subsequent validators spin up concurrently and connect to the genesis peer.

Enabling Inter-Chain Communication with Relayers

To enable cross-chain transactions between your deployed networks, configure relayers under the relayers key. The repository supports multiple relayer implementations, with Hermes being the most common for Cosmos SDK chains.

relayers:
  - name: osmos-juno
    type: hermes
    replicas: 1
    chains:
      - osmosis-1
      - juno-1
  - name: osmos-cosmos
    type: hermes
    replicas: 1
    chains:
      - osmosis-1
      - cosmoshub-1

The docs/config/relayers.mdx file documents all supported relayer types and their specific configuration options, including Inter-Chain Security (ICS) support and custom image overrides.

Step-by-Step Deployment Process

Deploying your multi-chain environment follows a three-phase workflow using the Starship CLI:

1. Initialize the deployment: Run starship start multi-chain.yaml to parse the configuration, fetch the Helm chart, and create the release named starship in your target namespace.

2. Verify installation: Execute starship list to confirm the Helm release shows status deployed and all pods are running.

3. Establish local connectivity: Run starship connect multi-chain.yaml to execute kubectl port-forward for every port defined in your chains and relayers. This invokes client.RunPortForward from the exposer package (referenced in cmd/starship/root.go), binding local ports like localhost:1313 to the Osmosis REST endpoint inside the cluster.

After connecting, verify your deployment with standard HTTP requests:

curl http://localhost:1313  # Osmosis REST API

curl http://localhost:1315  # Juno REST API

Advanced Configuration Options

Beyond basic chain deployment, Starship supports additional infrastructure components configurable through the same YAML manifest.

Explorer and Registry Services

Enable the explorer block to deploy a web UI for visualizing blocks, transactions, and cross-chain activity. The registry block exposes a name-service endpoint for dynamic chain discovery by client applications.

Automated Faucet Deployment

Configure a CosmJS or Starship-native faucet by adding a faucet block to your configuration. The faucet service implementation resides in starship/faucet/ and automatically distributes test tokens to developer wallets when enabled in values.yaml.

Resource Tuning and Custom Scripts

Per-chain resource limits, custom initialization scripts, and upgrade testing scenarios are fully supported. Reference docs/config/chains.mdx for the complete schema covering image overrides, genesis account funding, and ICS provider/consumer chain configurations.

Summary

• Starship converts YAML configurations into Kubernetes devnets using Helm charts defined in charts/devnet/.
• The chains array in your config file defines multiple blockchain networks, each deployed as separate StatefulSets with configurable validator counts.
• Relayers (typically Hermes) enable inter-chain communication and are defined under the relayers key with explicit chain pairing.
• Use starship start to deploy, starship connect to port-forward local access, and starship list to verify release status.
• Optional components like explorers, registries, and faucets extend the devnet functionality without requiring external infrastructure.

Frequently Asked Questions

What Kubernetes environments are compatible with Starship?

Starship runs on any standard Kubernetes cluster, including local kind or k3d installations for development, as well as remote cloud clusters for team-based testing. The only external dependencies required on your workstation are kubectl and the Starship CLI binary; all blockchain-specific binaries are containerized within the deployed pods.

How do I customize the Docker images for my validators?

Specify the image field within any chain object in your YAML configuration. If omitted, Starship uses default images defined in charts/devnet/values.yaml (lines 14-23), which provide standard Cosmos SDK chain binaries. You can reference public registries or private repositories accessible to your cluster.

Can I deploy chains that require different consensus mechanisms?

Yes. Starship supports any Cosmos SDK-based blockchain, including those with custom consensus configurations or Inter-Chain Security (ICS) setups. The docs/config/chains.mdx file documents parameters for provider chains, consumer chains, and standalone networks. Each chain runs in isolation within its own StatefulSet, allowing heterogeneous consensus mechanisms to coexist in the same devnet.

How do I tear down a multi-chain deployment?

Run starship stop <config.yaml> to remove the Helm release and all associated Kubernetes resources, including StatefulSets, Services, and persistent volumes. This command effectively reverses the starship start operation, cleaning the namespace for subsequent deployments without manual kubectl intervention.

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