Documentation

Getting started

This page gets a velodex binary running on your machine. It is the same first two steps whatever you serve (install the binary, start the server), so it lives here in Core. Once velodex is listening, pick the ecosystem you use and its getting-started tutorial carries on from there: caching an upstream, installing or pulling, and publishing your own.

Prerequisites

Two things: a velodex binary, and a client for the ecosystem you serve: an installer like pip or uv for Python packages, or a container client like docker or podman for images. The ecosystem tutorial names the exact client.

Install velodex through whichever channel fits; installation lists them all:

# standalone binary, no Python involved
curl -LsSf https://github.com/tox-dev/velodex/releases/latest/download/velodex-installer.sh | sh
uv tool install velodex
pip install velodex
# needs a Rust toolchain (https://rustup.rs); rust-toolchain.toml pins the version
git clone https://github.com/tox-dev/velodex.git
cd velodex
cargo build --release

Start velodex

velodex needs no configuration to start. Run it and it listens on 127.0.0.1:4433 with a default topology: a cached proxy of an upstream, a private hosted store, and a virtual index combining them:

velodex serve            # ./target/release/velodex serve when built from source

Open http://127.0.0.1:4433/ for the web dashboard: the configured indexes, their roles, and live request counters. Leave the server running.

Continue with your ecosystem

velodex is up. From here the steps depend on what you serve: the client, the wire protocol, and how you publish differ by ecosystem. Follow the tutorial for yours:

  • PyPI: Python packages: cache pypi.org, install with pip and uv, publish a private package, then yank and delete it.
  • OCI: container images: cache Docker Hub, pull an image, build and push one of your own, then verify it round-trips.

Each starts from a running velodex and takes about ten minutes.

Where next

On this page