Your first unbreakable rule, in about a minute

step 1

Install the binary

$ curl -fsSL https://raw.githubusercontent.com/praxec/praxec/main/install.sh | bash   # installs the praxec binary to ~/.local/bin

praxec is the kernel — the gateway/MCP server you wire into an agent host. The installer fetches the release binary for your platform, verifies its checksum, and drops it in ~/.local/bin — no Rust toolchain required. (cargo install praxec is coming soon, once the crate is published to crates.io; the optional pxcontrol-plane TUI ships the same way, later — you don't need it for this quickstart.) Full details, wget alternative, and manual downloads:Installation.

the fast path

Or: one command to a running gateway

With the binary installed, a single command scaffolds a working config, wires the starter packs, wires your editor's MCP config, and ends in a readiness check:

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

praxec init --with-starter-packs --yes does the wiring for you:

• Scaffolds config — writes a working gateway.yaml and a commodity models.yaml into your config dir.
• Wires the starter packs — --with-starter-packs adds both open packs (cognitive-architectures and praxec-meta) and runs tool provisioning as prebuilt binaries, no compiler needed.
• Wires your editor — auto-detects Cursor and/or Claude Code and merges in the praxec MCP server entry with absolute paths.
• Captures a provider key and finishes with a doctor readiness verdict.

cognitive-architectures is the canonical SWE-lifecycle library, which pulls in cpm-planner, fmeca,elicitation, and scientific-process. See them all on the packs & tools page. Want a subset instead of both starter packs? --packs cognitive-architectureswires just one; see praxec init --help for every flag.

The rest of this page builds a workflow by hand — the slower path, but the one that shows you the mechanism. Skip towiring it into your editor if you took the fast path.

step 2

Write a nine-line workflow

Save this as ship-guard.yaml:

version: "1.0.0"
workflows:
  ship_guard:
    initialState: unchecked
    states:
      unchecked:
        transitions:
          run_check: { target: checked }   # the only move offered here
      checked:
        transitions:
          ship: { target: shipped }        # ship exists ONLY here
      shipped: {}

A three-state machine. The rule lives in its shape: ship is declared only inside checked, and the only way intochecked is run_check. So fromunchecked, ship is not a move that exists.

step 3

Validate, then serve

$ praxec check --config ship-guard.yaml   # validate first — exits 1 on errors
$ praxec serve --config ship-guard.yaml   # MCP server over stdio, waiting for a host

check catches unreachable states, dead ends, and schema errors before anything runs — the same command you'll later put in CI.serve starts the kernel as an MCP server over stdio.

step 4

Wire it into your agent host

Declare praxec serve as an MCP server in your host's config — Claude Code, Cursor, Zed, VS Code, Claude Desktop, or any MCP host. The shape is the same everywhere:

{
  "mcpServers": {
    "praxec": {
      "command": "/absolute/path/to/praxec",
      "args": ["serve", "--config", "/absolute/path/to/ship-guard.yaml"]
    }
  }
}

step 5

Ask it to ship — and watch it get refused

Ask your agent: "Start the ship_guard workflow and ship the change." It starts the workflow, lands inunchecked, and gets exactly one link back:run_check. If it reaches for ship anyway:

→ praxec.command { "transition": "ship" }
← { "result": { "status": "rejected" },
    "error":  { "code": "INVALID_TRANSITION" },
    "links":  [ { "rel": "run_check" } ] }

The wrong action wasn't discouraged — it was unreachable. The refusal hands back the legal move, the agent runs the check, and only then doesship appear. You didn't write a prompt. You wrote nine lines of YAML.

step 6

Give the gate teeth

Right now run_check just advances the state. Point it at your real test command and the gate becomes enforceable reality:

connections:
  shell:
    kind: cli
    command: npm            # or: cargo, pytest, /bin/bash …
workflows:
  ship_guard:
    initialState: unchecked
    states:
      unchecked:
        transitions:
          run_check:
            target: checked
            executor: { kind: cli, connection: shell, args: ["test"] }
      checked:
        transitions:
          ship: { target: shipped }
      shipped: {}

Now run_check runs npm test. If the suite fails, the transition fails, you stay in unchecked — andship never becomes reachable. The agent cannot ship past a red suite, because the move to do so only exists on the other side of a green one.

where next

From one rule to a system

• Install a workflow pack — enforced TDD, deploy gates, and approval flows from Git, instead of writing your own.
• Wire in real capabilities — CLIs, HTTP services, MCP tools, scripts, sub-workflows, humans.
• Harden it for production — durable stores, audit and replay, px doctor, hot reload.
• Understand the kernel — the inversion, bounded contexts, and validated transitions in depth.