# How to Deploy Multiple Blockchain Networks Locally Using Starship in Kubernetes

> Deploy multiple blockchain networks locally using Starship in Kubernetes. Transform YAML to devnets with a single command for efficient local development.

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

---

**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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/examples/multi-chain/configs/osmo-juno-cosmos.yaml) file demonstrates this pattern with three interconnected networks:

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

```yaml
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`](https://github.com/hyperweb-io/starship/blob/main/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:

```bash
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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/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.