Skip to content

Install

Pion is one binary. Pick the path that matches your machine; every path ends at a server answering PING on port 1974. The text on this page is the README's own install section, included at build time.

macOS on Apple Silicon — the fastest path from nothing to a serving Pion:

If this 404s, the first release has not been published yet — build from source below (a couple of commands with pixi), or use the Docker image. This block works the moment the first tagged release is out.

curl -fsSL https://github.com/pavelhorak/pion/releases/latest/download/pion-macos-arm64.tar.gz | tar xz
cd pion-*-macos-arm64
./pion-server.sh                 # port 1974
redis-cli -p 1974 PING           # +PONG

Roughly 2 MB: the binary, the three Mojo runtime dylibs it actually links against, and the Metal shader library that --metal-attention needs. No toolchain, no Python, no model download. Verify the download against the release's SHA256SUMS if you care to (shasum -a 256 -c SHA256SUMS).

Launch through pion-server.sh, not bin/pion-server directly — the binary's rpath points at the build machine's toolchain, and the wrapper is what points it at the bundled lib/. WAL, snapshots and blob arenas are written to the working directory you launch from.

For Linux and other platforms there is no prebuilt tarball yet: use the Docker image above, or build from source. scripts/package_release.sh produces a tarball for whatever platform you run it on, so a Linux release is a matter of running it on a Linux box.

The client for the prompt-cache path. It needs a running pion-server --kvcache --metal-attention -w 1 from the macOS tab.

Runnable end to end, with the before/after timings printed: examples/prompt_cache_demo.py. Install with pip install -e 'pion-vllm-mlx/[mlx]' (not on PyPI yet).

No image is published to a registry yet, so build one first — hermetically from source, or in seconds around a binary you already have:

docker build -t pion .                              # from source, ~20 min
docker build --target runtime-prebuilt -t pion .    # wraps ./pion-server, seconds
                                                    # (Linux host only — the image
                                                    #  runs the binary in the context)

docker run -p 1974:1974 -v pion-data:/data pion
redis-cli -p 1974 PING     # +PONG

The from-source target is verified end to end as of 0.985 on linux/arm64: a 161 MB image that passes Gate 1 (114/114) and the full Redis parity suite from outside the container, and keeps its keyspace across docker restart through the /data volume.

Data (WAL, snapshots, blob arenas) lives in the /data volume, so it survives container restarts. Three things worth knowing:

  • The default command passes --epoll, because Docker's default seccomp profile blocks the io_uring syscalls (Docker ≥ 25). For the faster io_uring path, run with --security-opt seccomp=unconfined and drop --epoll.
  • The slim image ships no Python, so it runs with --no-auto-embed. Features that need an embedding model (semantic cache, auto-embed) want a host install or the AI image variant.
  • Use a named volume (-v pion-data:/data) as shown. The server runs as the unprivileged pion user, and a named volume inherits /data's ownership from the image; a bind mount (-v $(pwd)/data:/data) keeps the host directory's owner instead, so the WAL cannot be created. For a bind mount, chown the host directory to the image's pion uid first.

Prerequisites: - pixi builds and runs everything here — curl -fsSL https://pixi.sh/install.sh | bash, then restart your shell. It brings its own Mojo toolchain; nothing else needs installing. - redis-cli for the snippets below (brew install redis / apt install redis-tools). Any Redis client works — Pion speaks RESP2 and RESP3. - macOS: the Metal shader step (xcrun metal) needs full Xcode (not just Command Line Tools). Without it the build prints [Metal] skipped and reuses the tracked src/ffi/metal_compute.metallib, so --metal-attention still works — you only need Xcode if you edit metal_compute.metal. To rebuild the shader, install Xcode from the App Store, then xcode-select -s /Applications/Xcode.app/Contents/Developer. - Linux (GPU): pixi run build calls /usr/local/cuda/bin/nvcc and links cudart. Install CUDA 12 + cudart first. - Linux (no GPU): use pixi run build-portable — GPU-free build (no nvcc, no cudart, portable x86-64-v2 binary). Disables --metal-attention and --cuda-attention but all KV / vector / AI commands work. It produces ./pion-server-dev, not ./pion-server — substitute that name in every command below.

git clone https://github.com/pavelhorak/pion.git && cd pion
pixi install
pixi run build                        # produces ./pion-server
./pion-server                         # port 1974, one shared keyspace

Before you expose it to a network

Security model, in one paragraph. Pion listens on 127.0.0.1 by default and there is no TLS. Setting a password (--requirepass-file, PION_REQUIREPASS, or --requirepass) switches the default to all interfaces, following Redis's protected-mode convention — a password is taken as the signal that you intend to serve remotely. Override either way with --bind <addr>; an address that does not parse is a startup failure, never a silent fall back to 0.0.0.0. The bind address applies to every listener: the RESP port, the binary lane on port+1, the WAL replication stream on port+10000, and gossip/Raft. Note that replication and gossip are unauthenticated — anyone who can reach port+10000 can stream the WAL — so put those behind a private network, and terminate TLS at a proxy if you need encryption in transit. Running with --bind 0.0.0.0 and no password prints a warning at startup and means exactly what it says. See SECURITY.md. No telemetry: Pion never phones home — no update check, no analytics — and connects out only to what you configure or enable; the full list is in SECURITY.md.

Next: First five minutes — the Redis wire, vector search, the semantic cache and the four Pion lines.