Skip to content

Install

Kerkov needs uv and Python 3.11+. A few features have extra prerequisites, all optional:

  • Docker with a running daemon — only for the managed OWASP ZAP and managed SearXNG integrations, and for running Kerkov itself in containers.
  • Syft / Grype on PATH — for sbom_generate and vulnerability_scan.
  • Chromium — for the browser tool (uv run python -m playwright install chromium).

You do not need a .env file for ordinary interactive use; on first run Kerkov prompts for a provider credential and stores it in your OS keyring.

Intel macOS build prerequisites

Patched cryptography releases no longer publish Intel macOS wheels, so Intel Macs build this dependency from source for both CLI and web installs. Install the Xcode command line tools, Rust, and OpenSSL before using any of the installation methods below. With Homebrew:

xcode-select --install  # Skip if the command line tools are already installed.
brew install rust openssl@3
export OPENSSL_DIR="$(brew --prefix openssl@3)"

Run the installation command in the same shell so the build can find OpenSSL. See the upstream cryptography build instructions for other package managers. Do not downgrade cryptography to restore wheel-only installation: the older Intel wheels have known security vulnerabilities.

From source

The reliable path today, and what contributors use:

git clone https://github.com/Kerkov-Security/kerkov.git
cd kerkov
uv sync --locked
uv run kerkov

On first launch, choose a provider and follow the masked credential prompt. Kerkov validates the key before saving it to your OS keyring; on headless systems without a keyring it can fall back to a user-only file under ~/.kerkov/. See Configuration for how credentials and settings are resolved.

Python 3.10 is no longer supported because the patched WebSocket dependency requires Python 3.11+. The development pin and one-line installer use Python 3.13.

Install directly from GitHub

To install the current main branch as an isolated uv tool without a working tree:

uv tool install --python 3.13 git+https://github.com/Kerkov-Security/kerkov.git
kerkov

One-line installer (Linux and macOS)

Available at the first tagged release

The one-line installer pulls a versioned wheel from GitHub Releases, so it works once the first release is published. Until then, use From source or Install directly from GitHub above.

curl -fsSL https://raw.githubusercontent.com/Kerkov-Security/kerkov/main/install.sh | bash
kerkov

The installer supports x86_64 and arm64. It installs uv if needed, provisions Python when missing, and installs the wheel into an isolated uv tool environment with commands in ~/.kerkov/bin. It sets up PATH for bash, zsh, fish, and sh login profiles; open a new terminal or run the printed PATH command before launching. Re-run it to upgrade; uninstall with uv tool uninstall kerkov (your ~/.kerkov/ data is left intact).

Common variations:

# Pin a release
curl -fsSL .../install.sh | VERSION=0.1.0 bash
# Include the web console and download Chromium
curl -fsSL .../install.sh | bash -s -- --web --chromium
# Unattended: no Chromium, no shell-profile edits
curl -fsSL .../install.sh | bash -s -- --no-chromium --no-modify-path

It also seeds skills, agent profiles, config/http_profiles.yaml, and an empty approvals.yaml override template under ~/.kerkov/. A private .bundled-assets.json records hashes of shipped files. Upgrades refresh defaults that still match their recorded version, while preserving edits, unknown files, credentials, and approval overrides. Known defaults from older pre-manifest installs are recognized by their shipped hashes; unrecognized differences are preserved with a comparison notice. Symlinked files and directories are preserved. Installed CLI and web sessions also perform this refresh at startup, including after a direct uv tool upgrade. Source checkouts use repository assets directly.

One-line installer (Windows)

The same release requirement applies. In PowerShell (Windows PowerShell 5.1 or PowerShell 7):

irm https://raw.githubusercontent.com/Kerkov-Security/kerkov/main/install.ps1 | iex
kerkov

It mirrors the Linux and macOS installer: x86_64 and arm64, uv bootstrap, Python 3.13, commands in %USERPROFILE%\.kerkov\bin, and the same seeded defaults. Instead of editing shell profiles, it prepends that directory to your user PATH in the registry and keeps %VAR%-style entries unexpanded. Windows puts system PATH entries before user ones, so an older kerkov installed system-wide still wins until you uninstall it.

Options are environment variables, plus flags passed through a script block:

# Pin a release
$env:VERSION = '0.1.0'; irm .../install.ps1 | iex
# Include the web console and download Chromium
& ([scriptblock]::Create((irm .../install.ps1))) --web --chromium
# From a downloaded copy
powershell -ExecutionPolicy Bypass -File install.ps1 --no-chromium --no-modify-path

Some interactive features are POSIX-only. For example, Ctrl-O during a turn needs a POSIX TTY; at the chat prompt it works everywhere.

Manual install

Download the universal wheel from GitHub Releases and, with a compatible Python (3.11–3.14) in an activated virtual environment:

python -m pip install /path/to/kerkov-<version>-py3-none-any.whl
kerkov --version
kerkov

PyPI publication is not configured.

Docker Compose

Build the local image and start the hardened Kerkov + ZAP stack:

docker buildx build --load --file image/Dockerfile --tag kerkov:local .
export ZAP_API_KEY="$(openssl rand -hex 32)"
KERKOV_IMAGE=kerkov:local docker compose run --rm --service-ports kerkov
docker compose down

Kerkov runs as a non-root user on a read-only root filesystem. Runtime state lives in the kerkov-state volume; ./workspace is mounted at /workspace. The ZAP API stays internal to the Compose network.

The web console (optional)

The web console needs the web extra:

uv sync --locked --extra web
uv run kerkov --interface web           # starts the server and opens a browser
uv run --no-sync kerkov-web runserver   # or start it directly on http://127.0.0.1:8764

See the web console guide for what it does and does not support.

OpenGrep (optional, for sast_scan)

sast_scan uses the local OpenGrep engine — no account or API key. Kerkov uses an opengrep already on PATH, or you can install the official binary explicitly:

kerkov setup opengrep

This verifies the download against the SHA-256 digest in GitHub's release metadata and installs under ~/.kerkov/tools/opengrep/ without sudo. Scans never install software themselves: if OpenGrep is missing, sast_scan reports this command and stops before producing artifacts.

Next