Install Raven¶

Raven runs as a server (web dashboard + engine) that you reach from a browser and/or the REPL. The individual testing, findings, import/export, and basic reporting workflow is free to run without an account or AI credits. Pick the install that fits your environment; AI is optional.

Which build?¶

You are…	Use
On macOS / Windows / non-Kali Linux	Individual Docker image: tools for the shipped modules, wordlists, templates, and a local agent are bundled
On Kali / Debian 12+ / Ubuntu 22.04+	One-line install: `curl -fsSL https://chamberdoorsecurity.com/install.sh \\| sh`, upgrades with your system
On Kali, prefer a single file	`raven-server` bare binary: skip the ~3 GB image

Download the Docker image and bare binaries from the public Raven download section, or use the one-line install below. Published artifact names may still include pro; the individual core workflow does not require a paid plan.

Docker (macOS / Windows / Linux)¶

# 1. Load the image (note the tag it prints)
gunzip -c raven-pro-*.tar.gz | docker load     # Windows: docker load -i raven-pro-amd64.tar.gz

# 2. Workspace + run (replace <image-tag> with the tag from step 1: raven:pro-amd64 or raven:pro-arm64)
mkdir -p ~/raven/pentests ~/raven/auth ~/raven/config
docker run -d --name raven-pro --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v ~/raven/pentests:/home/raven/pentests \
  -v ~/raven/auth:/home/raven/.raven \
  -v ~/raven/config:/home/raven/.config/raven \
  --cap-add=NET_RAW --cap-add=NET_ADMIN \
  <image-tag>        # raven:pro-amd64, or raven:pro-arm64 on an ARM host

The three volumes retain engagement data, the separate credential-encryption key and optional pairing token, and settings and API keys, including the private BYO provider file. Back them up and keep the same mounts when replacing the container.
--cap-add=NET_RAW --cap-add=NET_ADMIN is needed for SYN scans.
On Linux, if you're scanning the LAN you're on, you can swap -p 127.0.0.1:8080:8080 for --network host. Host networking also exposes the dashboard on the host's interfaces; use it only with the appropriate network restrictions.

The bundled agent starts after you select an engagement. The web process runs as raven; the container's executor runs the shipped checks with the privileges they need. No SSH jumpbox or in-app tool installation is needed for the bundled catalog. You still supply authorized targets, any required target credentials or third-party API keys, and a network route to the targets. Custom modules may have additional dependencies.

On first boot, the individual image creates db.key on the persistent account mount at /home/raven/.raven and reuses it afterward. Explicit RAVEN_DB_KEY or RAVEN_DB_KEY_FILE settings take precedence. Back up that mount with your engagements; losing the key makes encrypted credentials unrecoverable. A missing persistent account mount leaves credential writes disabled, and encrypted data with a missing key requires the original key. See Credential Encryption.

One-line install (Kali / Debian / Ubuntu)¶

The easiest install on any Debian-family system, including Kali:

curl -fsSL https://chamberdoorsecurity.com/install.sh | sh

That adds the signed Raven apt repository and installs raven-server, so Raven upgrades with the rest of your machine (apt upgrade) instead of being re-downloaded by hand. Add the operator client with sudo apt install raven-cli.

Then start it:

raven-server start -p 8080 --no-browser

The script is short and readable. View the source before piping it to a shell if you'd rather see what it does first.

Supported distributions

Kali, Debian 12+, and Ubuntu 22.04+. The binaries need glibc 2.35 or newer. Anything older (Debian 11, Ubuntu 20.04) is not supported: the installer detects it and stops with an explanation instead of leaving you with a broken apt state. On those systems, use the Docker image above, which carries its own glibc and runs anywhere.

Releases before v0.1.0-beta73 needed glibc 2.39, so on Debian 12 or Ubuntu 22.04 make sure you are installing beta73 or newer.

Adding the repository by hand¶

If you'd rather not pipe a script to a shell, or you're managing the repo with configuration management, this is exactly what the installer does:

# 1. Prerequisites
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

# 2. Add the signing key. NOT apt-key (removed in Debian 12 / Ubuntu 24.04),
#    and NOT /etc/apt/trusted.gpg.d (that would trust this key for EVERY repo).
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://apt.chamberdoorsecurity.com/raven-archive-keyring.asc \
  | sudo gpg --dearmor -o /etc/apt/keyrings/raven-archive-keyring.gpg
sudo chmod 0644 /etc/apt/keyrings/raven-archive-keyring.gpg

# 3. Add the repository
echo "deb [signed-by=/etc/apt/keyrings/raven-archive-keyring.gpg] https://apt.chamberdoorsecurity.com stable main" \
  | sudo tee /etc/apt/sources.list.d/raven.list > /dev/null

# 4. Install
sudo apt-get update
sudo apt-get install -y raven-server   # self-hosted dashboard + job engine
sudo apt-get install -y raven-cli      # operator CLI / REPL (optional)

Upgrading from an older setup

Earlier versions of this page used a deb822 file at /etc/apt/sources.list.d/raven.sources. The installer writes raven.list instead, so if you added the repo by hand before, delete the old file. Otherwise apt update reads the repository twice and warns about a duplicate entry:

sudo rm -f /etc/apt/sources.list.d/raven.sources

Two packages are published:

Package	Command	What it is
`raven-server`	`raven-server`	The self-hosted dashboard + job engine. Binds `127.0.0.1`.
`raven-cli`	`raven-cli`	The operator CLI / REPL. Drives a local or hosted server.

Both are self-contained: they bundle their own Python runtime and PDF stack, so they depend only on libc6. raven-server recommends nmap and suggests the wider toolchain (ffuf, hashcat, sqlmap, nuclei, …), so install whatever your workflow needs; nothing is forced on you.

Don't apt install raven: that's a different tool

Debian ships an unrelated package called raven (gh0x0st/raven), which Kali inherits, and its version outranks ours, so apt install raven silently installs that instead. Our client is raven-cli, and it installs as /usr/bin/raven-cli specifically so it coexists with that package rather than replacing it. If you already use the other raven, nothing changes for you.

Versions and channels

Releases publish to the stable suite, which is what the file above subscribes to. Current builds are -beta versions (e.g. 0.1.0~beta87-1); they are ordered below a future final release, so when a GA ships apt upgrade moves you onto it correctly. Every published version stays installable, so you can pin or roll back: sudo apt install raven-server=0.1.0~beta87-1.

Architectures

amd64 and arm64 only. There is no i386 or armhf build, and no Windows package. On Windows use the Docker image.

Bare binary (bring your own toolchain)¶

Use this on a host with the tools your workflow needs, such as nmap and nuclei, installed natively. The bare binary does not bundle Docker's toolchain; unavailable tools cannot run.

Binaries are published per platform: raven-server-linux-amd64, raven-server-linux-arm64, and raven-server-darwin-arm64 (macOS, Apple Silicon).

# Linux (amd64 or arm64)
chmod +x raven-server-linux-*
sudo mv raven-server-linux-* /usr/local/bin/raven-server

# macOS (Apple Silicon). The download is unsigned and Gatekeeper-quarantined,
# so clear the flag or macOS kills it on launch. (`xattr -c` clears it and
# still exits 0 when there is nothing to clear.)
chmod +x raven-server-darwin-arm64
xattr -c raven-server-darwin-arm64
sudo mv raven-server-darwin-arm64 /usr/local/bin/raven-server

mkdir -p ~/raven/pentests
raven-server start -p 8080 --no-browser

The binary binds 127.0.0.1 by default (single-user "trust localhost"). Browse http://localhost:8080 on the same machine.

Reaching it from another machine

If the server is on a VM or remote host, don't expose it. Use an SSH tunnel:

ssh -L 8080:127.0.0.1:8080 user@host

then browse http://localhost:8080 locally. Running the binary inside a container/VM and hitting its bridge IP (e.g. 172.17.0.x) works but is fragile; prefer the tunnel or a port-mapped Docker run.

Optional AI¶

Bring your own AI or use manual prompts¶

In Settings → AI & privacy, choose OpenAI, Claude, Gemini, or a compatible API server, then save its model and credentials. Compatible API endpoints can include a local model. Native BYO currently supports reviewed engagement analysis in the web dashboard and uses your provider account, with any provider charges. It does not require Chamber Door pairing or credits.

In AI Analysis, prepare the request, review its prompt, endpoint and model, then send it explicitly. Manual prompt copy and paste-and-restore remain available. See AI Analysis for the supported paths.

Pair for managed AI¶

Pairing connects this installation to your Chamber Door account for optional managed AI. Managed advisor, chat, finding drafts, and report writing use your available Chamber Door credits.

Web UI: open the dashboard → click Pair this device → confirm at the URL it shows.

CLI:

raven-server auth login                   # bare binary
docker exec -it raven-pro raven-server auth login   # Docker

It prints a URL + code; open it, confirm, and the token is saved automatically.

Current Docker command

The current individual image exposes raven-server, matching the bare binary and apt package. Use the command shown above for account pairing.

Verify:

raven-server auth status        # or: docker exec raven-pro raven-server auth status

You should see chamberdoor (account-bound, rvn_pat_). Managed AI requests also require an available credit balance.

Privacy¶

Raven replaces known identifiers and redacts recognized credential formats on the Raven host before AI requests. The identifier mapping stays with the engagement and restores recognized response placeholders locally; redacted secrets are not restored. Anonymization cannot guarantee that all identifying details are removed. Review the request and the selected provider's data handling before sharing context. BYO sends to your chosen provider; managed AI uses the Chamber Door service.

Updating¶

When a new release drops, the dashboard shows an update banner.

`raven-server update`¶

The command works out how this box was installed and what supervises the server, then downloads, verifies, installs, restarts, and confirms the server is answering again:

raven-server update --check   # what would happen; changes nothing
raven-server update           # do it, with a confirmation prompt
raven-server update -y        # do it without prompting

It handles apt and bare binary installs. Downloads are checked against the published SHA-256 and refused on a mismatch, and the binary it replaces is kept alongside as raven-server.previous so you can roll back.

It stops rather than guesses when it cannot be sure. A Docker deployment, a source checkout, an unrecognised process on the port, or two systemd units claiming the same port all produce a refusal plus the manual steps for what was actually detected. That is deliberate: the upgrade action for each install method is wrong for the others, and the wrong restart takes a server down.

Use --no-restart to install now and restart on your own schedule.

If you run the server from a non-default engagements directory, set it where the server can see it rather than relying on the environment it happens to inherit (see Where engagements live). RAVEN_PENTESTS_DIR and RAVEN_GLOBAL_CONFIG are carried across the restart.

Doing it by hand¶

APT: sudo apt update && sudo apt upgrade, or just sudo apt install --only-upgrade raven-server raven-cli. Your ~/.raven/ pairing and pentests/ survive. To pin or roll back a version: sudo apt install raven-server=0.1.0~beta61-1 (every published version stays available).
Docker: load the new tarball, docker stop raven-pro && docker rm raven-pro, re-run with the new tag. Keep all three pentests/, auth/, and config/ mounts identical so engagement data, the credential key, and saved settings survive.
Bare binary: re-download from the Downloads page, chmod +x, replace /usr/local/bin/raven-server, restart. Your ~/.raven/ pairing survives.

Where engagements live¶

By default Raven reads engagements from ~/pentests — that is, $HOME/pentests for whichever user the server runs as.

That default is worth knowing about, because it moves. A server started by hand as ken reads /home/ken/pentests; the same server restarted under sudo, or by a systemd unit with a different User=, reads /root/pentests and finds nothing there. The dashboard comes up listing zero engagements, which looks exactly like data loss. Nothing has been deleted — the server is looking in the wrong place.

State the directory instead of inheriting it:

# Persist it (stored in the global config, survives restarts and updates)
raven-server config --set-pentests-dir /home/ken/pentests

# Or set it for one command / one service
export RAVEN_PENTESTS_DIR=/home/ken/pentests
raven-server --pentests-dir /home/ken/pentests start

raven-server config --show prints the directory currently in effect and says when an environment variable is overriding the stored value.

For a systemd unit, put it in the unit itself so it cannot drift:

[Service]
Environment=RAVEN_PENTESTS_DIR=/home/ken/pentests
Environment=RAVEN_GLOBAL_CONFIG=/etc/raven/config.yaml

Resolution order, first match wins:

RAVEN_PENTESTS_DIR
pentests_dir in the global config
$HOME/pentests

A custom global config file¶

The global config (API keys, proxy, pairing, the engagements directory) lives at ~/.config/raven/config.yaml by default, which follows $HOME the same way. To pin one file for a deployment regardless of which user the process runs as:

export RAVEN_GLOBAL_CONFIG=/etc/raven/config.yaml
# or
raven-server --config-file /etc/raven/config.yaml start

This is separate from --config / $RAVEN_CONFIG, which select a single engagement's engagement.yaml.