Launch your first Velocity pilot

Velocity becomes real once you see packets flowing. This quickstart trims the reference handbook down to the essentials so you can validate the runtime on a laptop, VM, or lab server.

What you need on hand

• Rust toolchain 1.81 or newer (use rustup default stable if unsure).
• Node 20+ to build the docs UI and optional templates.
• A Linux host with UDP/4433 reachable. Local testing works fine with loopback.
• git, cargo, and npm in your shell.

Tip: on macOS or Windows, run the pilot inside an Ubuntu container or WSL2 instance to avoid firewall surprises.

Step 1 — Install the toolkit

git clone https://github.com/AndrewCTF/ProjectVelocity.git
cd ProjectVelocity
cargo build --release --workspace

Copy target/release/velocity to a directory on your PATH, or keep the workspace checked out and rely on cargo run commands while experimenting.

Step 2 — Mint a hybrid certificate

cargo run -p velocity-cli -- cert issue --dns localhost --out certs/localhost

The command spits out a Dilithium + ECDSA pair so Velocity can speak to today’s clients while preparing for post-quantum requirements. Store the files under certs/ for the next step.

Step 3 — Shape a starter config

server:
  listen: "0.0.0.0:4433"
  tls:
    certificate: "certs/localhost/fullchain.pem"
    private_key: "certs/localhost/privkey.pem"
  profiles:
    default: balanced
    permit: [light, balanced, secure]
content:
  sites:
    - hostname: localhost
      root: "./public"
telemetry:
  metrics_listen: "127.0.0.1:9300"
  structured_logs: true

Save this as serve.simple.yaml. It exposes a static site from ./public and publishes Prometheus metrics on 127.0.0.1:9300.

Step 4 — Boot Velocity

cargo run -p velocity-cli -- serve --config serve.simple.yaml

When the log shows listening on 0.0.0.0:4433, Velocity is ready for traffic. Leave the process running and open a second terminal for validation.

Step 5 — Prove the handshake

cargo run -p velocity-cli -- client get https://localhost/ --alpn velocity/1 --insecure

The CLI prints the negotiated profile and status code. Repeat the call with --alpn h3 to confirm the HTTP/3 fallback path operates as expected.

Where to go next

• Graduate the pilot by following the Operator handbook checklists.
• Automate builds and restarts with the Deployment playbook.
• Benchmark your environment before inviting more teams via the Benchmarking guide.