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

> Easily set up explorer and registry services in your Starship environment. Deploy pods and forward ports with a simple starship up command. Learn more now.

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

---

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

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

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

```go
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

```bash

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

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