Back to Blog

Introducing Hextrap Artifacts: A Free, Self-Hosted Package Repository That Doesn't Call Home

Today we're announcing the first release of Hextrap Artifacts, a free, self-hosted artifact repository for Python, Go, Java, Node.js and Rust (coming soon). It's a single binary with minimal configuration, supports SSO out of the box, and it never calls home or sends telemetry, so you can use it in fully isolated environments.

Use it to host your private packages and to cache the public registries, so builds keep working when upstream is down. It's licensed Apache 2.0.

This post covers what it does and how to run it.

Running it

Download the release for your platform from the Hextrap Artifacts page, then:

cp config.example.yaml config.yaml
printf '%s' 'a long password' | hextrap-artifacts hash-password   # paste the hash into config.yaml
hextrap-artifacts -config config.yaml

Open http://localhost:8080, sign in as admin, and create an access token. The minimal config is one admin user and a storage location:

users:
  - username: admin
    password_hash: "<output of hextrap-artifacts hash-password>"
admins: [admin]

data_dir: ./data
storage:
  filesystem: ./data/blobs   # fine for trying it out; use S3 for real use

There's no database to set up. On a single server, metadata and tokens are kept as files in data_dir. You don't need Redis, a job queue or a separate web server either; background jobs and the UI are part of the binary.

The example config ships with a placeholder instead of a password hash, so a fresh install can't start with a default password. Both example configs are loaded by the test suite, so they can't drift from what the binary actually accepts.

Pointing your tools at it

Clients use the access token, never your password:

# npm
npm config set registry https://repo.example.com/npm/<repo>/
npm config set //repo.example.com/npm/<repo>/:_authToken <token>
npm publish

# pip, twine, uv
pip install --index-url https://__token__:<token>@repo.example.com/pypi/<repo>/simple/ <pkg>
twine upload --repository-url https://repo.example.com/pypi/<repo>/ -u __token__ -p <token> dist/*
uv publish --publish-url https://repo.example.com/pypi/<repo>/ -u __token__ -p <token>

Each repository's Setup tab shows the configuration for its format, including the less obvious ones. Cargo needs a trailing slash on the index URL and an explicit credential-provider, and go only sends credentials over HTTPS and reads them from ~/.netrc.

Format Publish with Proxies Client URL
npm npm publish registry.npmjs.org /npm/<repo>/
PyPI twine upload, uv publish pypi.org /pypi/<repo>/simple/
Maven mvn deploy, Gradle Maven Central /maven/<repo>/
Cargo cargo publish index.crates.io sparse+…/cargo/<repo>/index/
Go modules (proxy only) proxy.golang.org GOPROXY=…/go/<repo>
Container images docker push Docker Hub <host>/<repo>/<image>:<tag>

How the proxies behave

  • Indexes are cached for five minutes. Download links are rewritten to point at your repository.

  • Files are fetched once. The first request downloads the file and checks it against the hash the upstream declared: npm integrity, PyPI sha256, Maven .sha256/.sha1, Cargo index checksums, and container digests. Go modules are also checked against sum.golang.org. A file that doesn't match isn't stored. If several clients ask for the same uncached file at once, they share one download.

  • Cached files keep serving when upstream is down. Responses served from storage carry X-Hextrap-Cache: hit, which helps when you're debugging a build.

  • You can see where things came from. Every version is marked as published to your repository or cached from its upstream.

  • Deleting a cached version blocks it. The proxy won't fetch it again.

  • Upstreams are limited to the config file. Someone who can create a repository can't point your server at an arbitrary address.

On PyPI the repository serves the JSON simple API (PEP 691) and wheel metadata files (PEP 658), so pip and uv resolve without downloading whole wheels.

Publishing and deleting

Published versions are immutable. You can't upload a version that already exists, and a deleted version number or filename can't be reused. If 1.4.2 was deleted, nobody can publish different code as 1.4.2 later.

Deleting happens in three steps:

  1. Yank or deprecate. The version stays installable for anyone who pinned it but is hidden from new resolution (PEP 592 yank, npm deprecate).
  2. Delete. The version disappears from indexes and downloads, but can be restored for 30 days (configurable).
  3. Purge. The file is removed for good. You confirm by typing the exact package@version.

Every publish, yank, delete, restore, purge, role change and settings change goes into an audit log on your instance, with who did it, what changed, when, and from which IP.

Sign-in and roles

Sign in with a users list in the config file, or with your identity provider over OIDC (Okta, Entra ID, Keycloak, Authentik, Dex, or Google through Dex). Passwords are stored only as PBKDF2 hashes, and sign-in attempts are throttled per IP and per username. With OIDC, roles can be granted to your IdP groups, so access follows people as they join and leave teams.

Each repository has four roles: Reader (install), Developer (publish), Maintainer (yank, deprecate, manage dist-tags) and Admin (delete, change settings, grant roles). The person who creates a repository is its first Admin.

  • Instance admins are set in the config file, not in the UI, so nobody can be locked out from inside the app.

  • A repository's last Admin can't be removed until there's another.

  • CI gets repository-scoped service tokens, which can go up to Maintainer but never Admin. A leaked CI token can publish, but it can't delete anything.

  • Personal access tokens expire after 90 days by default and are stored hashed.

If your company puts every internal app behind an auth proxy such as oauth2-proxy, Pomerium or Cloudflare Access, the README lists the package-client paths to exempt. Clients like npm and pip can't complete a browser login.

Running it in production

  • Package files go to S3 or an S3-compatible store (MinIO, Cloudflare R2), stored by sha256 so identical files are kept once. SSE-S3, SSE-KMS and key prefixes are supported, and the server checks the bucket is reachable at startup. Local disk storage is for testing, and the server warns at startup when it's in use.

  • Metadata stays in data_dir on a single server. To run several replicas, set database_url to a Postgres database. The binary creates and migrates its own tables at startup.

  • Storage quotas reject publishes that would go over the limit.

  • Rate limiting is off by default. Per-token limits are useful when a CI job goes into a loop. Throttled clients get a 429 with Retry-After and RateLimit headers, and an error message in a format each client actually shows its user.

Outbound connections

The server connects only to what you configure: your OIDC issuer, your S3 endpoint, your Postgres database, and the upstream registries you've allowed. There's no telemetry, update check or license check. Because the code is open, you can verify that yourself.

Adding policy, if you want it

Hextrap Artifacts has no policy engine of its own: a proxy caches whatever the upstream registry serves, after checking its hash. If you want rules about which packages get through, you can set a proxy's upstream to a Hextrap Package Firewall, our paid service. It checks each package against allow and deny lists, a minimum age for new releases, typosquat detection and malware data. It works today for npm, PyPI, Go and Cargo proxies.

With a firewall connected, blocked packages fail with a 403 that names the firewall, and cached files are rechecked before they're served. Packages fetched through the firewall are sent to Hextrap, since that's how they get checked. Without a firewall, nothing is sent to us. The repository works the same either way.

To see what the firewall checks and how to set one up, visit the Hextrap Package Firewall page.

Comments

Loading comments…

Protect Your Supply Chain

Add a security firewall to your package manager and CI/CD pipelines.

Get Started Free