Docs / Getting Started

Install

pip install ryvx-*.whl         # the wheel from /download/ -- see below
playwright install chromium   # needed for render_js_page; everything else works without it

Grab the wheel from the download page (Linux CLI; no GitHub account or sign-in needed) and install it as above. That installs Ryvx as a package, so ryvx works as an ordinary command anywhere. Ryvx isn't on PyPI yet, so there is no pip install ryvx from the internet; the wheel from /download/ is the published install path.

Maintainer / dev install only: the main harryc295/ryvx source repo is private, so pip install . or running from a clone only works if you already have access to it. If you do: pip install -r requirements.txt to get the dependencies, then use python -m ryvx in place of ryvx in every example below.

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 authorised to test needs an explicit flag: see Authorisation & 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.py files 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-labelled), so you can see real findings, report, and dashboard output before running your own.

Next

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