Installation

Install praxec from a pre-built binary, Cargo, or Docker.

praxec is the gateway you put in front of your coding agent so it can’t make moves you didn’t allow. Install the binary, then wire it into your editor (Claude Code, Cursor, or any MCP host).

Pick whichever method fits your setup. They all give you the praxec gateway binary. The pre-built bundle also ships praxec-plan — a deterministic critical-path-method (CPM) planning MCP server — alongside the gateway.

Quick install (recommended)

One command fetches the praxec binary for your platform from the latest GitHub release, verifies its checksum, and installs it to ~/.local/bin:

# with curl:
curl -fsSL https://raw.githubusercontent.com/praxec/praxec/main/install.sh | bash
# or with wget (minimal boxes without curl — busybox wget works):
wget -qO- https://raw.githubusercontent.com/praxec/praxec/main/install.sh | bash

The installer is POSIX shell, fetches with curl or wget, and preflight-checks its few tools (tar, awk, mktemp) with a package-manager hint instead of a bare “not found”. Pin a version or install directory with PRAXEC_VERSION=v0.0.30 / PRAXEC_BIN_DIR=... env vars.

Neither curl nor wget? Install one (apt-get install -y curl / apk add curl), or grab a bundle manually below.

Manual download

Download the latest release for your platform from GitHub Releases and verify it against the release’s checksums.sha256:

# Linux x86_64 example
curl -LO https://github.com/praxec/praxec/releases/latest/download/praxec-x86_64-unknown-linux-gnu.tar.gz
curl -LO https://github.com/praxec/praxec/releases/latest/download/checksums.sha256

# Verify
sha256sum -c checksums.sha256 --ignore-missing

# Extract — the archive contains both binaries
tar xzf praxec-*.tar.gz
./praxec --help          # the gateway CLI
# ./praxec-plan          # the bundled CPM planning MCP server (speaks MCP over stdio)

Move the binary somewhere on your PATH (e.g., /usr/local/bin) and you’re set.

Cargo (from source, once published)

cargo install praxec is coming soon — the crate isn’t published to crates.io yet, so this doesn’t work today. Until then, use the quick install above; it’s also faster since it skips the build:

# cargo install praxec          # coming soon — not yet published to crates.io

Docker

docker run -v $(pwd)/gateway.yaml:/config/gateway.yaml ghcr.io/praxec/praxec

Mount your config file into /config/gateway.yaml and the container handles the rest. This is also coming soon — the image isn’t published yet.

Initialize (one command)

With the binary installed, one more command takes you from nothing to a working gateway wired into your editor:

praxec init --with-starter-packs --yes

This single command:

• Scaffolds a working config — writes gateway.yaml and a commodity models.yaml into your config dir (~/.config/praxec, or %APPDATA%\praxec on Windows).
• Wires the starter packs — --with-starter-packs adds both open packs (cognitive-architectures and praxec-meta) under repos: and points discovery.registry at the always-latest praxec/packs registry, then runs tool provisioning for everything the packs need (installed as prebuilt binaries — no compiler required).
• Wires your editor’s MCP config — auto-detects Cursor and/or Claude Code and merges in the correct praxec server entry with absolute paths.
• Captures a provider key — prompts for an OpenRouter API key for the starter models.yaml chain (with --yes, it reads OPENROUTER_API_KEY from the environment instead and just notes if it’s unset).
• Ends in a readiness verdict — runs doctor against the result so you know immediately whether you’re ready to go.

It’s idempotent and safe: it never overwrites an existing scaffolded file or clobbers an existing editor MCP config without --force. Restart your editor afterward — that’s what picks up the new MCP server, and praxec.query / praxec.command appear.

Prefer just the bare gateway with no packs? Run praxec init alone. To wire a subset of packs, an arbitrary pack, or preview what a pack wires in before adding it, see connections and the packs registry. Every flag is listed under praxec init --help.

Verify the installation

Whichever method you used, confirm it’s working:

praxec --help

You should see the CLI help with the serve subcommand listed. If you already ran praxec init, doctor already gave you a readiness verdict — you’re set.

Discovering commands

praxec ships with a full clap-driven CLI. Beyond --help, the subcommands are discoverable per command:

praxec help <subcommand>     # long-form description + example per command

Wire praxec into your editor

praxec init already does this for you. If you installed manually, skipped init’s editor step, or use a host it doesn’t auto-detect (Zed, VS Code, Claude Desktop), declare praxec serve as an MCP server in your editor’s config by hand — the model then sees the two fixed tools (praxec.query, praxec.command) and every capability you route through the gateway passes through its gates.

See Wire praxec into your editor for the full per-editor walkthrough, then quick start to wire up your first guarded capability.

Optional: running praxec as the loop

The same repo ships a terminal runtime — praxec’s own chat TUI — where praxec is the agent loop instead of sitting behind your editor. Most people installing the binary don’t need this first; it’s a different way to run, with tighter enforcement. See How to run it for the three modes and what each one enforces.

Optional: provider API keys

You only need these if you’re running the workflow runtime that calls an LLM directly — the gateway itself doesn’t need them. In that case, set ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, etc. in your shell rc or CI secrets and the LLM client picks them up. See Provider API keys for the supported variables.