High-performance, self-hosted multi-language package registry and pull-through registry proxy for private software supply chains.

Starmetal gives teams one controlled path for package-manager traffic across ecosystems. It speaks native registry protocols, proxies upstream reads, stores artifacts behind a common service layer, verifies cached bytes with Blake3, and applies policy before dependencies reach clients.

StarMetal is experimental. All currently implemented registry read/proxy workflows are experimental core capabilities; native publishing is not supported yet, and local publishing remains experimental and disabled by default.

PyPI · npm · Cargo · Hex · Maven · RubyGems · NuGet · pub.dev · Go · Zig · Swift

Install · Quick Start · Registry Support · Docker · Configuration · Deployment · Release · Architecture · ADRs

Modern teams pull dependencies from several registries, each with different protocols, metadata formats, auth expectations, and client behavior. Starmetal puts those workflows behind one self-hosted service boundary so operators can centralize caching, integrity checks, policy, storage, and observability without asking developers to stop using native package-manager clients.

Starmetal sits between package-manager clients and upstream registries:

Starmetal is built for private/internal deployments first. It is not yet a public internet-facing registry product, and every registry workflow should be treated as experimental until fresh live native-client E2E passes for that ecosystem.

Go, Zig, and Swift are git-sourced (ADR-0023): rather than proxying a package-index protocol, their adapters mirror an upstream git repository through the starmetal-git crate's GitMirror port and translate tags/trees into each ecosystem's artifact shape. They bypass CachingPackageService entirely, are disabled by default, and are gated behind the go/zig/swift build features.

Planned registry work includes OCI/distribution, Composer, Conda, Debian/APT, and RPM/YUM. See ADR-0011 for experimental support criteria and promotion gates. Configured Ed25519 Starmetal DSSE sidecars are experimental. Protocol-native signing, PQ signing, and client-verified PQ support are planned only; ecdsa-p256-sha256, ml-dsa65, and the pq feature are reserved until matching client-visible verification is implemented and tested.

Docker is the primary deployment path. Release builds also publish verified sm installers for npm and PyPI, Homebrew bottles through Goldziher/homebrew-tap, and GitHub release archives for direct download.

docker run --rm -p 8080:8080 -v starmetal-data:/var/lib/starmetal ghcr.io/goldziher/starmetal:latest
brew install Goldziher/tap/starmetal
npm install -g starmetal
pipx install starmetal

The npm package requires Node 22+. The PyPI package requires Python 3.10+. Both download the matching prebuilt binary from GitHub Releases and verify it against the release checksums file. The crates.io starmetal package currently holds the public namespace while the Rust crate publishing layout is finalized.

Requirements:

• Rust edition 2024, Rust 1.85+
• Task for the documented workflow commands
• sccache, optional but used automatically by Taskfile cargo commands

# First-time setup: hooks, sccache check, generated AI config
task setup

# Build and run tests
task ci

# Install the local sm binary from this checkout
cargo install --path crates/starmetal-cli --bin sm

# Or install the prebuilt sm binary from the latest GitHub release via cargo-binstall
# (starmetal-cli is not on crates.io, so point binstall at the git repo)
cargo binstall --git https://github.com/Goldziher/starmetal starmetal-cli

# Start Starmetal with defaults on 127.0.0.1:8080
sm serve

# Write a starter config
sm config init

# Inspect registries without a config file
sm --no-config --storage-backend memory registry status

# Fetch one artifact through the cache path
sm package fetch pypi six 1.16.0 six-1.16.0.tar.gz

Run live native-client E2E before treating an experimental read workflow as ready:

task test:e2e:pypi
task test:e2e:npm
task test:e2e:cargo
task test:e2e:hex

task ci:live-e2e runs live schema freshness plus the PyPI, npm, Cargo, and Hex read gates. Maven, RubyGems, NuGet, and pub.dev have separate live tasks and must pass before their workflows are promoted.

Docker is the primary deployment path for private experimental installs. The image uses Chainguard builder and runtime bases, runs as non-root, and uses one image for both API and CLI operations. Its entrypoint is sm; its default command is serve, so no args starts the API server, and args after the image name run normal CLI or MCP commands.

Published images use GitHub Container Registry: ghcr.io/goldziher/starmetal.

docker build -t starmetal:local .
docker run --rm -p 8080:8080 -v starmetal-data:/var/lib/starmetal starmetal:local
docker run --rm starmetal:local config validate
docker run --rm starmetal:local mcp serve

Run the deterministic local proxy gate:

task docker:proxy:e2e

That gate builds the image, runs a local fixture upstream plus StarMetal on an isolated Docker network, exercises every implemented registry route with HTTP assertions, runs native client containers for PyPI, npm, Cargo, Maven, RubyGems, NuGet, and pub.dev, restarts StarMetal with the same OpenDAL filesystem volume, and repeats the checks with the fixture upstream stopped. It also runs pnpm read-through install, cached reinstall with a fresh pnpm store, and experimental local npm publish-then-install. The pnpm publish pass proves only the local npm publishing substrate; it is not a supported native publishing claim for npm or any other ecosystem. The native client pass disables read auth because package-manager support for Bearer read auth is uneven; the HTTP pass covers auth behavior.

Use a mounted config file for production settings, auth tokens, public_base_url, and S3/GCS OpenDAL options:

docker run --rm \
  -p 8080:8080 \
  -v ./starmetal.toml:/etc/starmetal/starmetal.toml:ro \
  -v starmetal-data:/var/lib/starmetal \
  starmetal:local

The default container config is docker/starmetal.toml.

Starmetal defaults to loopback binding and filesystem storage. A minimal private deployment usually starts from:

[server]
bind = "127.0.0.1:8080"
public_base_url = "https://starmetal.internal.example.com"
cors_allowed_origins = []
max_upload_bytes = 536870912

[storage]
backend = "fs"
path = "/var/lib/starmetal"

[auth]
enabled = true
tokens = ["replace-with-a-secret-token"]

# [metadata]       # experimental Postgres content model: dedup, GC, retention
# enabled = true
# database_url = "postgresql://user:password@host:5432/starmetal"

# [supply_chain]   # experimental OSV vulnerability gate at ingest and serve
# enabled = true

Upstream URLs must be HTTPS and public by default. Local, private-network, or insecure upstreams require explicit allow_private_network and allow_insecure settings. See docs/configuration.md for every option and validation rule, and docs/deployment.md for private deployment guidance.

The CLI command is sm. Config lookup still supports STARMETAL_CONFIG and starmetal.toml for compatibility; the CLI and MCP server can run without a config file using built-in defaults plus explicit flags.

Common CLI operations:

sm config show
sm config validate
sm registry status
sm package list pypi
sm package versions npm is-odd
sm package metadata cargo once_cell 1.19.0
sm package fetch npm is-odd 3.0.1 is-odd-3.0.1.tgz --output ./is-odd.tgz
sm cache delete-artifact npm is-odd 3.0.1 is-odd-3.0.1.tgz --yes

Use --output json for machine-readable output. MCP runs over stdio:

sm mcp serve
sm mcp serve --allow-writes

MCP read tools are always available. Mutating tools, including experimental local publish, yank, unyank, and cache delete, require --allow-writes.

The experimental update feature (included in the CLI full build) adds a Phase 0 dependency-update engine, scoped to Cargo manifests and GitHub. It reuses PackageService as its version datasource, so update lookups go through the same pull-through cache, Blake3 verification, and policy checks as the proxy.

sm update scan .
sm update run goldziher/starmetal --dry-run

sm update scan <path> scans a local directory tree for Cargo.toml files and reports available patch, minor, and major updates. sm update run <owner>/<name> scans a GitHub repository and opens or updates a pull request; --dry-run reports available updates without opening a pull request. Both commands accept --pin and --allow-prerelease. run requires a GitHub token, passed with --token or, preferably, the STARMETAL_GITHUB_TOKEN environment variable. See ADR-0016 and ADR-0017.

Starmetal uses hexagonal architecture: protocol adapters and storage backends sit outside a shared service/core boundary.

See docs/architecture.md for diagrams and component details.

Normal PR-safe gate:

task fmt:check
task clippy
task test:all
task schema:check
task schema:validate
task conformance
task docker:proxy:e2e
task security
task ci

task docker:proxy:e2e uses disposable client containers, not host package-manager CLIs. Live E2E and live Docker pressure tests are intentionally separate from normal PR CI because they require public registry access.

Schema provenance, fetched upstream artifacts, Starmetal-derived JSON Schemas, and grammar fixtures live under schemas/:

• schemas/registries/ - derived registry schemas where the protocol is JSON-like
• schemas/starmetal/ - config and lockfile schemas
• schemas/README.md - source links and registry-by-registry derivation notes

• 0001 - Hexagonal Architecture
• 0002 - Tower Middleware
• 0003 - OpenDAL Storage
• 0004 - Blake3 and Lock File
• 0005 - Protocol Adapters
• 0006 - Feature Flags
• 0007 - JSON Schema Validation
• 0008 - Registry Expansion, superseded
• 0009 - Publishing and Upload Workflows
• 0010 - CLI and MCP Operations
• 0011 - Experimental Support Matrix
• 0012 - CI Quality Gates
• 0013 - Basemind and AI-Rulez Alignment
• 0014 - Management Admin Surface
• 0015 - Statistics and Operational Metrics
• 0016 - Dependency Update Engine
• 0017 - Forge and Git Integration Port
• 0018 - Universal Artifact Repository Direction
• 0019 - Repository Kinds and the Recipe/Facet Model, accepted (partial)
• 0020 - Universal Content Model and Garbage Collection
• 0021 - Native Hosted Publishing, accepted (partial)
• 0022 - Access Control Model
• 0023 - Git as a Dependency Source, accepted (partial)
• 0024 - Supply-Chain Security Pipeline, accepted (partial)
• 0025 - Supply-Chain Enforcement Architecture (As-Built)

MIT