Docs / Getting Started

Getting Started

Install it, set a model, run a scan.

Install

pip install .                 # from a clone; gives you a real `ryvx` command
playwright install chromium   # needed for render_js_page; everything else works without it

That installs Ryvx as a package, so ryvxworks as an ordinary command anywhere. Running from a clone without installing still works too — use python -m ryvx in place of ryvx in every example below, and pip install -r requirements.txtto get the dependencies. Ryvx isn't on PyPI yet, so there is no pip install ryvx from the internet.

Chromium is only needed for render_js_page, the tool a subagent uses to crawl React/Vue/Angular single-page apps through a real headless browser. Static crawling and everything else works without it.

Set a model

Ryvx is model-agnostic via litellm. Set the API key for whichever provider you want to drive it with — only one is needed:

export ANTHROPIC_API_KEY=sk-ant-...      # for anthropic/claude-*
export OPENAI_API_KEY=sk-...             # for openai/gpt-*
export GEMINI_API_KEY=...                # for gemini/*
# ...or point at a local model:
export RYVX_LLM=ollama/llama3
export LLM_API_BASE=http://localhost:11434

RYVX_LLM picks the model (default anthropic/claude-sonnet-5) using litellm's provider/model naming, so any provider litellm supports works here unmodified.

Run your first scan

Point it at a local directory to review source with no live requests:

python -m ryvx --target ./examples/vulnerable_app

A public GitHub repo works the same way — cloned locally, source-only, no live requests:

python -m ryvx --target https://github.com/org/repo

Black-box testing a live app you own or are authorized to test needs an explicit flag — see Authorization & approval for what backs it:

python -m ryvx --target http://127.0.0.1:5000 --i-am-authorized

--scan-mode controls thoroughness and cost directly: quick (15 turns per agent), standard (40, the default), or deep (80). Named presets bundle a scan mode, instruction, and approval setting together (config.SCAN_PRESETS) so you don't have to remember the right flag combination:

python -m ryvx --target ./app --preset quick-recon
python -m ryvx --target http://127.0.0.1:5000 --i-am-authorized --preset full-pentest

No API key yet?

python scripts/seed_demo_run.pyfiles three real, manually-PoC-confirmed findings against the bundled vulnerable app straight through the actual finding/CVSS/report pipeline — no LLM involved — so the dashboard has real data to look at while you get a key set up.

View results

As markdown, or in a local browser dashboard:

python -m ryvx view              # list runs
python -m ryvx view run-20260724-235448
python -m ryvx dashboard         # http://127.0.0.1:8765

The first time (or after pulling UI changes), build the dashboard frontend once:

cd dashboard-ui && npm install && npm run build

New here and don't want to run a scan yet? http://127.0.0.1:8765/run/?name=demo shows a seeded sample run — fictitious findings, clearly banner-labeled — so you can see real findings, report, and dashboard output before running your own.

How it works — the root orchestrator, the subagents it spawns, and the tool loop they share.
Verification — what actually has to be true before Ryvx will report a finding.
Authorization & approval — what --i-am-authorized requires before a live exploit fires.

← Back to Docs