# Starship v1 vs v2: Architecture Differences and Migration Guide

> Explore Starship v1 vs v2 architecture differences. Learn how the new KubernetesJS client enables direct API deployments and provides a clear migration path.

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

---

**Starship v2 replaces the Helm-based shell command architecture of v1 with a programmatic KubernetesJS client, enabling direct API deployment and manifest generation while maintaining backward-compatible configuration files.**

Starship v1 and v2 represent two distinct architectural approaches for orchestrating Cosmos blockchain development environments in Kubernetes. While v1 relies on Helm charts and external shell commands for deployment, v2 introduces a KubernetesJS-based workflow that generates manifests programmatically and applies them via the Kubernetes API. This guide examines the technical differences between **Starship v1 vs v2** and provides a concrete migration path based on the `hyperweb-io/starship` source code.

## Architectural Differences Between Starship v1 and v2

### Deployment Model: Helm Charts vs KubernetesJS API

**Starship v1** uses a hybrid deployment approach combining TypeScript client libraries with Helm charts located in `starship/charts/devnet`. The infrastructure is managed through external shell commands including `helm`, `kubectl`, and `docker`, with the client orchestrating these tools to render and apply templates.

**Starship v2** eliminates all shell-command dependencies. According to the repository's main README, the architecture migrates to a **KubernetesJS-based** system where the `@starship-ci/generator` package programmatically creates YAML manifests from configuration files. The CLI then applies these resources directly via the Kubernetes API rather than invoking Helm, as implemented in [`starship/cmd/starship/root.go`](https://github.com/hyperweb-io/starship/blob/main/starship/cmd/starship/root.go).

### Core Services and Client Architecture

Both versions maintain identical Go microservices for blockchain operations. The services in [`starship/faucet/main.go`](https://github.com/hyperweb-io/starship/blob/main/starship/faucet/main.go), [`starship/registry/main.go`](https://github.com/hyperweb-io/starship/blob/main/starship/registry/main.go), and [`starship/exposer/main.go`](https://github.com/hyperweb-io/starship/blob/main/starship/exposer/main.go) remain largely unchanged between versions, preserving business logic for token distribution, chain registry, and endpoint exposure.

The critical architectural shift occurs in the client layer. In v2, the CLI commands (`start`, `stop`, `list`, `connect`) are implemented using a `k8s.io/client-go`-style API client that communicates directly with the cluster. This replaces the v1 pattern where the TypeScript client invoked Helm to manage the lifecycle of these services.

### Configuration Handling

Both versions consume the same [`config.yaml`](https://github.com/hyperweb-io/starship/blob/main/config.yaml) format without syntax changes. However, the processing differs significantly:

- **v1**: Passes [`config.yaml`](https://github.com/hyperweb-io/starship/blob/main/config.yaml) directly to Helm for template rendering within the `starship/charts/devnet` directory
- **v2**: Uses the `KubernetesGenerator` class from `@starship-ci/generator` to transform the `StarshipConfig` object into concrete Kubernetes resources programmatically

## Step-by-Step Migration Path from v1 to v2

1. **Switch to the v2 branch**

   Checkout the current development branch from `hyperweb-io/starship`:
   
   ```bash
   git checkout main   # main == v2

   ```

2. **Install the v2 CLI**

   Replace legacy tooling with the new NPM package that communicates via KubernetesJS:
   
   ```bash
   npm i -g @starship-ci/cli
   ```

3. **Add the manifest generator**

   Install the package responsible for converting configurations to Kubernetes YAML:
   
   ```bash
   npm i @starship-ci/generator
   ```

4. **Generate Kubernetes manifests**

   Convert your existing [`config.yaml`](https://github.com/hyperweb-io/starship/blob/main/config.yaml) into inspectable, version-controlled YAML files:
   
   ```typescript
   import { KubernetesGenerator } from '@starship-ci/generator';
   import { StarshipConfig } from '@starship-ci/types';

   const config: StarshipConfig = {/* your config.yaml parsed as JSON */};
   const generator = new KubernetesGenerator(config);
   
   // Produce all manifests
   const manifests = await generator.generateAll();
   
   // Write to disk for review and version control
   await generator.writeManifests('./k8s-manifests');
   ```

5. **Review generated manifests**

   Inspect the plain YAML files in `./k8s-manifests` before deployment. This step allows manual adjustment and ensures the generated resources match your infrastructure requirements.

6. **Deploy via Kubernetes API**

   Use the v2 CLI to apply manifests directly without Helm intermediaries:
   
   ```bash
   starship start ./k8s-manifests
   ```

7. **Remove Helm artifacts**

   Once you verify the v2 workflow functions correctly for all required chains, delete legacy Helm-specific files such as `starship/charts/*` from your repository to prevent configuration drift.

8. **Update CI/CD pipelines**

   Replace Helm-centric pipeline steps (`helm install`, `helm upgrade`) with the new CLI commands:
   
   ```bash
   starship start ./k8s-manifests
   starship stop --name my-starship --namespace default
   ```

9. **Adopt advanced v2 features**

   Leverage additional capabilities documented in [`packages/packages/generator/README.md`](https://github.com/hyperweb-io/starship/blob/main/packages/packages/generator/README.md), including programmatic resource tweaking, enhanced error handling, and KubernetesJS client mocking for unit tests.

## Code Examples: Old vs New Workflows

### v1 Helm-Based Deployment

The legacy workflow requires repository setup and chart installation with value overrides:

```bash
helm repo add starship https://hyperweb-io.github.io/starship
helm repo update
helm install -f custom-values.yaml starship/devnet --generate-name

```

### v2 Programmatic Deployment

The new workflow generates manifests first, then deploys via the Kubernetes API:

```typescript
import { KubernetesGenerator } from '@starship-ci/generator';
import { StarshipConfig } from '@starship-ci/types';
import { execSync } from 'child_process';

// Load config and generate manifests
const config: StarshipConfig = /* parsed config.yaml */;
const generator = new KubernetesGenerator(config);
await generator.writeManifests('./k8s-manifests');

// Deploy using KubernetesJS client under the hood
execSync('starship start ./k8s-manifests', { stdio: 'inherit' });

```

### Lifecycle Management Commands

v2 provides direct CLI commands for managing deployment lifecycles:

```bash

# Stop a specific deployment

starship stop --name my-starship --namespace default

# Establish port-forwarding

starship connect --config config.yaml --namespace default

```

## Key Source Files and Repository Structure

Understanding the file structure clarifies the architectural shift from shell-command orchestration to programmatic API access:

- **[`starship/charts/devnet/values.yaml`](https://github.com/hyperweb-io/starship/blob/main/starship/charts/devnet/values.yaml)** – Helm chart configuration used by v1 for templating and deployment parameters.

- **[`starship/cmd/starship/root.go`](https://github.com/hyperweb-io/starship/blob/main/starship/cmd/starship/root.go)** – v2 CLI entry point implementing `start`, `list`, `stop`, and `connect` commands using the KubernetesJS client rather than shell invocations.

- **[`packages/packages/generator/README.md`](https://github.com/hyperweb-io/starship/blob/main/packages/packages/generator/README.md)** – Documentation for the `@starship-ci/generator` package, detailing how `StarshipConfig` objects transform into Kubernetes YAML manifests via the `KubernetesGenerator` class.

- **[`starship/faucet/main.go`](https://github.com/hyperweb-io/starship/blob/main/starship/faucet/main.go)**, **[`starship/registry/main.go`](https://github.com/hyperweb-io/starship/blob/main/starship/registry/main.go)**, **[`starship/exposer/main.go`](https://github.com/hyperweb-io/starship/blob/main/starship/exposer/main.go)** – Core Go microservices maintaining consistent business logic across both versions, handling blockchain-specific operations independent of the deployment layer.

- **[`starship/tools/main.go`](https://github.com/hyperweb-io/starship/blob/main/starship/tools/main.go)** – Shared utility functions supporting both CLI versions and providing common helper methods.

## Summary

- **Starship v1** utilizes Helm charts and shell commands (`helm`, `kubectl`) for Kubernetes deployment, while **Starship v2** employs a KubernetesJS client for direct API communication and programmatic manifest generation.
- Both versions share identical [`config.yaml`](https://github.com/hyperweb-io/starship/blob/main/config.yaml) formats and core Go services (`faucet`, `registry`, `exposer`), ensuring continuity in blockchain business logic.
- Migration requires installing `@starship-ci/cli` and `@starship-ci/generator`, generating manifests from existing configurations, and replacing Helm commands with `starship start`.
- v2 enables manifest version control, programmatic resource adjustment, and improved testing capabilities through KubernetesJS client mocking.
- v2 remains under active development; production environments should continue using the stable v1 branch until v2 reaches general availability.

## Frequently Asked Questions

### Is Starship v2 production-ready?

No. According to the `hyperweb-io/starship` repository documentation, v2 is currently under active development and not yet recommended for production use. Mission-critical environments should continue using the stable v1 branch available at the `v1` branch until v2 receives an official release designation.

### Do I need to modify my config.yaml when migrating to v2?

No. The [`config.yaml`](https://github.com/hyperweb-io/starship/blob/main/config.yaml) syntax remains unchanged between versions. The v2 `KubernetesGenerator` accepts the same `StarshipConfig` type used in v1, allowing you to migrate existing configuration files without modification. The generator handles the transformation into Kubernetes manifests programmatically.

### What happens to the Go microservices in Starship v2?

The core Go services—including `starship/faucet`, `starship/registry`, and `starship/exposer`—remain largely unchanged. These microservices continue to provide identical business logic for blockchain operations; only the deployment mechanism changes from Helm-managed pod templates to programmatically generated manifests applied via the Kubernetes API.

### Can I use Helm alongside Starship v2?

While technically possible during the migration period, the recommended approach involves completely replacing Helm workflows with v2's KubernetesJS-based deployment. Once you verify the v2 workflow functions correctly for your specific chains, you should remove Helm artifacts such as `starship/charts/*` to avoid configuration drift and reduce maintenance overhead.