Install and first run in 10 minutes

The Windows installer and the pip path, ensure, first indexing, first query and agent connection — with real numbers and typical pitfalls.

本文尚未翻译成当前语言——正在显示 English.

Requirements #

Component	Value
Python	3.13+ (verified on 3.14); no administrator rights needed
Platform	Windows + PowerShell 7.6 verified; Linux/macOS — the common pip path (not E2E-verified)
Disk	~2.5 GB environment; index ~1 MB per 1–2 source files
Optional	JDK 21 + Joern (~5–6 GB) for the CPG layer; a GPU to accelerate embeddings
Network	PyPI at install time; one-time ~240 MB embedding model

Path A — Windows (verified) #

PowerShell

./scripts/install.ps1                 # venv in ~/.ragraf/venv, dependencies, self-check
./scripts/install.ps1 -WithTruststore # corporate TLS proxy: pip certificates via truststore
./scripts/install-joern.ps1 -Download # optional CPG layer (SHA-256 archive verification)

The installer writes a transcript to ~/.ragraf/logs/, verifies every step and prints a summary table; -SummaryJson gives a machine-readable result. All network operations have timeouts and pipe draining (the installer refactor closed the deadlock on large outputs — INSTALLER-REFACTOR-NOTES, defects D-01…D-17).

Path B — common (Linux/macOS/Windows without scripts) #

Shell

python3.13 -m venv .venv && source .venv/bin/activate
pip install -e .
ragraf --help

Corpus and first indexing #

Shell

ragraf ensure /path/to/project --json

ensure is the "put things in order" command: it finds an existing corpus, creates a config for an unknown directory, and reindexes when checksums diverge. The index lands in <project>/.ragraf/ — add that directory to .gitignore.

Time reference points (323-file PHP corpus, CPU): full indexing 71 s, of which CPG (Joern) is 64 s; without Joern — seconds. The first vector-enabled indexing additionally downloads the model (~240 MB, once).

First queries #

Shell

ragraf -p cfg.yaml query search "reindex threshold" --with-text
ragraf -p cfg.yaml query symbol --name corpus_hash
ragraf -p cfg.yaml query schema --table z_agr_payments
ragraf -p cfg.yaml status

Remember the flag order: -p and --json go before the subcommand (exception — ensure --json). The full list is in the CLI reference.

Agent connection (MCP) #

In the MCP client config:

JSON

{
  "mcpServers": {
    "ragraf": {
      "command": "python",
      "args": [
        "/path/to/RAGRAF/tools/ragraf-mcp.py",
        "--project", "/path/to/corpus.yaml",
        "--agent", "my-agent",
        "--agent-kind", "external"
      ]
    }
  }
}

--agent-kind: autoclaw (the author's environment — extended telemetry) · external · internal. The server exposes 23 ragraf_* tools over stdio. Step-by-step scenarios for AutoClaw, SagaAI and DeepSeek Harness — in the site's integrations section.

Admin panel (optional) #

Shell

ragraf admin        # → http://127.0.0.1:8777 (loopback only)

The mutation token is printed to the console at startup (or set RAGRAF_ADMIN_TOKEN). How the panel works and what it shows — in the panel article; an interactive replica — the site emulator.

Typical first-minutes pitfalls #

Symptom	Cause	Fix
`unrecognized argument -p`	flag after the subcommand	`ragraf -p cfg query …`
selftest is "red" but everything works	selftest is a report, not a gate (always exit 0)	read the report body: joern/java are optional
`certificate verify failed` downloading the model	corporate TLS proxy	`install.ps1 -WithTruststore` or `pip install truststore`
`slice` answers with code 3	no Joern → capability=degraded	`install-joern.ps1 -Download` or live without slice
model won't download, internet works, but answers lack vectors	`--no-vectors` in command history	rebuild: `ragraf reindex`

Next: the agent working regimen →