> ## Documentation Index
> Fetch the complete documentation index at: https://warden-re.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install WARDEN and run the full reverse-engineering pipeline: first on generated samples, then on your own Emscripten module.

WARDEN's core path is pure Python and the standard library, so a fresh clone runs with **no
native toolchain** (no Ghidra, no Emscripten, no WABT).

## Install

<Steps>
  <Step title="Clone and create a virtual environment">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    git clone https://github.com/purpshell/warden.git
    cd warden
    python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
    ```
  </Step>

  <Step title="Install the package">
    The base install is dependency-light (just a CLI shell).

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    pip install -e .
    ```

    <Check>Verify it worked: `warden version` prints the installed version.</Check>
  </Step>
</Steps>

## Run the whole pipeline (offline)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
warden demo
```

This generates sample modules and walks every stage end-to-end, with no network and no
toolchain. You'll see the Oracle identify runtime functions at score 1.00 and infer the
Emscripten version, the agent crew recover a name from a string cross-reference to reach 100%
coverage, and a `v1 → v2` diff carry annotations forward and print a semantic changelog.

<Tip>
  `warden demo` is the fastest way to understand WARDEN. Run it once, then point the real
  commands below at your own module.
</Tip>

## Reverse-engineer your own module

<Steps>
  <Step title="Create a project and ingest the target">
    Ingestion parses the `.wasm` (and optional Emscripten JS glue), fingerprints every function,
    and seeds names for free from exports, imports, and the name section.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    warden init                                              # creates ./warden.db
    warden ingest app_v1.wasm --glue app_v1.js --label v1
    warden coverage v1                                       # how much is named already?
    warden funcs v1 --unnamed                                # what still needs a name?
    ```
  </Step>

  <Step title="Identify runtime code with the Oracle">
    Build a signature corpus from any module that still carries a name section (a debug or
    `--profiling-funcs` build), then identify the stripped target against it. This typically
    collapses a large fraction of a module to known musl/runtime code instantly.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    warden oracle build runtime_debug.wasm --out oracle.json --emver 3.1.55 --opt -O2
    warden oracle identify v1 --store oracle.json
    ```

    <Info>
      To build a full corpus from the Emscripten toolchain across a version × flag matrix, use
      the containerized farm in `scripts/corpus/`. See [the Oracle guide](/pipeline/oracle).
    </Info>
  </Step>

  <Step title="Name the rest with the agent crew">
    The crew proposes names for the application-specific remainder, gated by a verifier and the
    provenance/confidence economy. Runs with an offline heuristic by default; set
    `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` (and `pip install -e '.[agents]'`) for the LLM crew.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    warden agent v1
    ```
  </Step>

  <Step title="Review, lock, and export">
    Record verified names (sovereign over agents), then emit a deliverable.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    warden show v1 7
    warden set-name v1 7 verify_license     # provenance=human, locked
    warden export v1 --format pseudo        # or: headers | kb-text | ghidra
    ```
  </Step>

  <Step title="When a new version ships, diff it">
    Carry annotations forward automatically and review only the genuine deltas.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    warden ingest app_v2.wasm --label v2
    warden diff v1 v2
    ```

    The changelog separates real app changes (review these) from runtime/toolchain churn (an
    Emscripten bump, safely ignored). [Read about diffing →](/pipeline/diff)
  </Step>
</Steps>

## Optional power-ups

The base install is intentionally minimal. Opt into extras as you need them.

<CodeGroup>
  ```bash LLM agent crew theme={"theme":{"light":"github-light","dark":"github-dark"}}
  pip install -e '.[agents]'   # real model-driven naming; set OPENAI_API_KEY or ANTHROPIC_API_KEY
  ```

  ```bash MCP server theme={"theme":{"light":"github-light","dark":"github-dark"}}
  pip install -e '.[mcp]'      # drive the KB from any MCP-capable agent
  warden mcp
  ```

  ```bash Dev tooling theme={"theme":{"light":"github-light","dark":"github-dark"}}
  pip install -e '.[dev]'      # pytest, ruff, mypy, pre-commit
  ```

  ```bash Everything theme={"theme":{"light":"github-light","dark":"github-dark"}}
  pip install -e '.[all]'
  ```
</CodeGroup>

<CardGroup cols={2}>
  <Card title="Next: the mental model" icon="brain" href="/concepts">
    Three ideas make every WARDEN command click. Read them before going deeper.
  </Card>

  <Card title="The reverse-engineering loop" icon="repeat" href="/workflow">
    The practical, command-by-command guide to reverse-engineering a real module as a loop.
  </Card>
</CardGroup>