How to Set Up Explorer and Registry Services in a Starship Environment

Enable the explorer and registry blocks in your Starship configuration file and run starship up to automatically deploy the pods and forward their ports to your local machine.

Starship is a modular Kubernetes-based test harness for Cosmos SDK chains. To visualize blockchain activity and query aggregated chain metadata, you can enable the optional explorer and registry services that ship with the hyperweb-io/starship repository. This guide walks through the exact configuration steps, source file locations, and code required to activate these components.

Understanding the Explorer and Registry Architecture

Starship treats both components as optional features defined in the core configuration model.

Explorer Service

The explorer provides a lightweight web UI (powered by ping-pub) for browsing blocks, transactions, and accounts on your test chains. In starship/cmd/starship/model.go, the Feature struct defines the schema for optional services, and the HelmConfig struct includes an Explorer field that maps directly to your YAML configuration.

Registry Service

The registry is a gRPC and REST service that aggregates chain metadata—including chain IDs, peer addresses, assets, and IBC connection details. The service definition lives in starship/proto/registry/service.proto, with generated Go code available in registry/registry/service.pb.go. Like the explorer, it is declared as a Feature within HelmConfig.

Configuring Explorer and Registry in Your YAML

To activate these services, add top-level explorer and registry keys to your Starship configuration file. The structure follows the Feature schema defined in the source.

explorer:
  enabled: true
  ports:
    rest: 8080

registry:
  enabled: true
  ports:
    rest: 8081
    grpc: 9091

The enabled boolean toggles the Helm chart deployment, while the ports map specifies the local ports you want forwarded. You can see a real-world implementation in examples/multi-chain/configs/osmo-juno-cosmos.yaml, which demonstrates a multi-chain setup utilizing both services.

Default Helm values are defined in starship/charts/devnet/values.yaml, where you can inspect the default container images, resource limits, and internal service ports.

Deploying and Accessing the Services

Once your configuration is ready, deploy the environment using the Starship CLI.

starship up -c path/to/your/config.yaml

Automatic Port Forwarding

The starship client handles Kubernetes port-forwarding automatically. In starship/cmd/starship/connect.go, the Client.PortForwardCmds() method constructs kubectl port-forward commands for every enabled feature.

For the explorer, it forwards the svc/explorer Kubernetes service to your configured local port. For the registry, it forwards svc/registry to both the REST and gRPC ports defined in your YAML.

Pod Verification

Before forwarding, the client verifies that the pods are running. The code checks for explorer- and registry- pod name prefixes in the namespace:

if config.Explorer != nil && config.Explorer.Enabled {
    if !strInList(pods, "explorer-") {
        return fmt.Errorf("explorer pod not found …")
    }
}
if config.Registry != nil && config.Registry.Enabled {
    if !strInList(pods, "registry-") {
        return fmt.Errorf("registry pod not found …")
    }
}

Access URLs

After successful deployment, access the services at the following endpoints:

• Explorer UI: http://localhost:<explorer.rest> (e.g., http://localhost:8080)
• Registry REST: http://localhost:<registry.rest>/chain_ids (e.g., http://localhost:8081/chain_ids)
• Registry gRPC: localhost:<registry.grpc> (e.g., localhost:9091)

Interacting with the Registry Service

You can query the registry via REST or using the provided Go client located in clients/go/client.

REST Example

# List all registered chain IDs

curl http://localhost:8081/chain_ids

# Get specific chain details

curl http://localhost:8081/chain/osmosis-1

Go gRPC Client Example

The protobuf-generated client supports methods like ListChainIDs, GetChain, and ListChainPeers.

package main

import (
    "context"
    "log"

    registry "github.com/hyperweb-io/starship/registry/registry"
    "google.golang.org/grpc"
)

func main() {
    conn, err := grpc.Dial("localhost:9091", grpc.WithInsecure())
    if err != nil { log.Fatal(err) }
    defer conn.Close()

    client := registry.NewRegistryClient(conn)

    // List all chain IDs
    ids, err := client.ListChainIDs(context.Background(), &registry.Empty{})
    if err != nil { log.Fatal(err) }
    log.Printf("Chains: %v", ids.ChainIds)

    // Get details for a specific chain
    chain, err := client.GetChain(context.Background(), &registry.RequestChain{Chain: "osmosis-1"})
    if err != nil { log.Fatal(err) }
    log.Printf("Chain %s RPC: %s", chain.ChainId, chain.GetRpc().Address)
}

Summary

• Add explorer and registry blocks with enabled: true to your Starship YAML configuration.
• Define local port mappings under each service's ports key to override defaults.
• Run starship up to deploy Helm charts and automatically forward ports via starship/cmd/starship/connect.go.
• Access the explorer UI at your configured REST port and query the registry via REST or gRPC at the designated ports.
• Use the Go client in clients/go/client or the generated protobuf code in registry/registry/service.pb.go for programmatic registry access.

Frequently Asked Questions

What are the default ports for the explorer and registry services?

By default, the Helm chart (starship/charts/devnet/values.yaml) exposes the explorer on port 8080 and the registry on ports 8080 for REST and 9090 for gRPC internally. However, you should always map these to distinct local ports in your configuration to avoid conflicts.

How do I verify that the explorer and registry pods are running correctly?

The Starship CLI automatically checks for pods with the explorer- and registry- prefixes before attempting port forwarding, as implemented in starship/cmd/starship/connect.go. You can also manually verify with kubectl get pods -n <your-namespace> to ensure both services show a Running status.

Can I customize the Docker images used for the explorer or registry?

Yes. While the default images are defined in starship/charts/devnet/values.yaml, you can override them by specifying image details in your configuration's Helm values or by modifying the chart directly before deployment.

Is the registry service required for IBC testing?

No, the registry is optional, but it significantly simplifies IBC testing by providing a centralized source for chain IDs, connection information, and peer addresses. Without it, you would need to manually track these details across multiple chain configurations.

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