Stout: the registry that refuses known-bad code at the gate

How It Works

When you request a package through the proxy, Stout follows this flow:

1. Request

Package manager hits Stout

2. Cache check

Is it cached and fresh?

3. Fetch upstream

If not cached, fetch from origin

4. Store

Cache metadata + artifact in S3

5. Serve

Return to client, serve from cache next time

Cache misses still become warm installs

Packages are fetched from the upstream source on first request, cached locally, and served from cache on subsequent requests, with zero build wait.

Organization-scoped pull-through

Use the global proxy path for shared caching, or put an organization slug after /o/ to route installs through that organization's trust gate. Organization-scoped installs are advisory by default, then enforce high and critical CVEs once enabled; malware heuristics gate supported source ecosystems, while Docker malware findings are surfaced as advisory.

registry=https://your-stout-host/npm/

Pattern

org-scoped URLs

https://your-stout-host/o/<org-slug>/npm/
https://your-stout-host/o/<org-slug>/python/simple/
https://your-stout-host/o/<org-slug>/go
https://your-stout-host/o/<org-slug>/<ecosystem>/

The same shape works across supported ecosystems. For namespace-aware registries, keep the ecosystem's normal subpath after the organization prefix, such as /o/acme/nuget/v3/index.json or /o/acme/docker/library/nginx.

Metadata TTL

Metadata is cached with a configurable TTL (default 5 minutes). Stale data is served if the upstream is unreachable.

Artifact Caching

Artifacts (tarballs, wheels, JARs) are stored in S3 on first fetch and served directly on subsequent requests.

Safe Defaults

512 MB max artifact size, 30s upstream timeout, path traversal protection, and namespace isolation from user-published packages.

Proxy defaults are intentionally bounded

Safe defaults include a 512 MB max artifact size, 30s upstream timeout, path traversal protection, and namespace isolation from user-published packages.

Ecosystems

npm Go Python Ruby Rust Maven NuGet Docker Helm PHP / Composer Dart / Flutter Swift Terraform

Configure Package Managers

Proxy caching does not run package scripts

Scripts are not executed during proxy caching for security.

npm

Default Upstream

https://registry.npmjs.org

Usage

npm config set registry https://your-stout-host/npm/

Scoped packages (@org/pkg) are fully supported. Scripts are not executed during proxy caching for security.

Go

Default Upstream

https://proxy.golang.org

Usage

go env -w GOPROXY=https://your-stout-host/go,direct

Falls back to direct fetching if the package is not available via the proxy. Supports the GOPROXY protocol including .info, .mod, and .zip endpoints.

Python

python

Default Upstream

https://pypi.org

Usage

# Per-command

pip install --index-url https://your-stout-host/python/simple/ package-name

Supports PEP 503 Simple Repository API. Package names are normalized (lowercase, hyphens to underscores).

Ruby

ruby

Default Upstream

https://rubygems.org

Usage

# Bundler mirror

bundle config set mirror.https://rubygems.org https://your-stout-host/ruby/

Works as a drop-in replacement for rubygems.org. Bundler mirror mode transparently redirects all gem fetches.

Rust

rust

Default Upstream

https://crates.io

Usage

[source.crates-io]
replace-with = "stout"

[source.stout]
registry = "sparse+https://your-stout-host/rust/_proxy/"

Replaces the crates.io source with the Stout proxy — no credential needed for the mirror. All transitive dependencies are also fetched through the proxy. A first-party crate index (/rust/~you/) is authenticated: see its package page for the token setup.

Install Through Stout

Mirror configuration can require a service restart

Restart Docker daemon after changing daemon.json.

Maven

maven

Default Upstream

https://repo1.maven.org/maven2

Usage

<repositories>
  <repository>
    <id>stout</id>
    <url>https://your-stout-host/maven/</url>
  </repository>
</repositories>

Can be configured as a Maven Central mirror in settings.xml to proxy all dependency resolution. Supports both release and snapshot repositories.

NuGet

nuget

Default Upstream

https://api.nuget.org/v3

Usage

# Add as a source

dotnet nuget add source https://your-stout-host/nuget/v3/index.json -n stout

Implements the NuGet V3 API. Can be used alongside or as a replacement for nuget.org.

Docker

docker

Default Upstream

https://registry-1.docker.io

Usage

# No global config needed. Use the full image path

docker pull your-stout-host/docker/library/nginx:latest

Implements the OCI Distribution Spec. Library images use the library/ prefix. Restart Docker daemon after changing daemon.json.

Helm

helm

Default Upstream

https://charts.helm.sh/stable

Usage

helm repo add stout https://your-stout-host/helm/

Supports both traditional Helm repos and OCI-based chart registries.

PHP / Composer

php

Default Upstream

https://packagist.org

Usage

# Globally

composer config -g repos.stout composer https://your-stout-host/php/

Implements the Composer repository API. Supports provider-includes and lazy provider loading for efficient metadata fetching.

Cache & Refresh

Warm common packages before first use

Pre-populate the cache with popular packages so first requests are instant. Stout ships with 130+ seed packages across all ecosystems.

Dart / Flutter

dart

Default Upstream

https://pub.dev

Usage

# Set the hosted URL

export PUB_HOSTED_URL=https://your-stout-host/dart/

Set PUB_HOSTED_URL to proxy all pub.dev traffic. Per-dependency hosted URLs are also supported for selective proxying.

Swift

swift

Default Upstream

Swift Package Registry

Usage

swift package-registry set https://your-stout-host/swift/

Implements SE-0292 (Swift Package Registry). Registry URLs can be set globally or per-project.

Terraform

terraform

Default Upstream

https://registry.terraform.io

Usage

provider_installation {
  network_mirror {
    url = "https://your-stout-host/terraform/"
  }
}

Supports both modules and providers. The proxy handles the Terraform Registry Protocol for discovery, versions, and downloads.

Admin Configuration

Administrators can configure the proxy via the admin panel or API.

Enable / Disable

Toggle the proxy on or off from Admin → Proxy. When disabled, all requests go directly to the local registry only.

Custom Upstreams

Override the default upstream URL for any ecosystem. Useful for pointing at internal mirrors or Artifactory instances.

proxy config

PUT /api/v1/admin/proxy/config
{
  "enabled": true,
  "metadata_ttl": "10m",
  "upstreams": {
    "npm": "https://my-internal-registry.corp/npm/",
    "go": "https://goproxy.corp"
  }
}

Cache Warmup

Pre-populate the cache with popular packages so first requests are instant. Stout ships with 130+ seed packages across all ecosystems.

cache warmup

POST /api/v1/admin/proxy/warm
{
  "concurrency": 5,
  "artifacts": true
}

Runs in the background. Check status at GET /api/v1/admin/proxy/warm/status.

Seed Packages

Manage which packages are pre-warmed. Add custom packages or use the discover endpoint to auto-populate from upstream popularity rankings.

seed packages

# Add custom seed packages
POST /api/v1/admin/proxy/seed-packages
{
  "packages": [
    { "package_type": "npm", "name": "my-internal-lib" }
  ]
}

# Auto-discover popular packages from upstreams
POST /api/v1/admin/proxy/discover
{ "top": 50, "warm": true }