Install & Pair¶

Raven runs as a server (web dashboard + engine) that you reach from a browser and/or the REPL. Pick the install that fits your environment, then pair the device once to enable AI.

Which build?¶

You are…	Use
On macOS / Windows / non-Kali Linux	Pro Docker: the Kali toolchain is bundled, nothing else to install
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 Downloads page at app.chamberdoorsecurity.com (signed in), or use the one-line install below.

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 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 keep your engagement data, pairing token and API keys (Settings, so Shodan, GitHub, DeHashed) on the host, so they survive upgrades and container recreation.
--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 8080:8080 for --network host.

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~beta61-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~beta61-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)¶

Only recommended on Kali (or another host with nmap, nuclei, etc. installed natively). On a host without those tools, tool-using features silently fail.

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.

First-time pairing (enables AI)¶

Pairing connects this device to your Chamber Door account. One-time per machine.

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 auth login   # Docker

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

The Docker command is raven, not raven-server

Inside the Pro image the CLI is installed as raven. raven-server is the name of the bare binary and of the apt package, and it does not exist inside the container, so docker exec ... raven-server ... fails with "executable file not found". To check on your own image, run docker run --rm <image-tag> --help, which prints the same raven form.

Verify:

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

You should see chamberdoor (account-bound, rvn_pat_). AI features now work.

Privacy¶

Engagement data is anonymized on your machine before it's sent to the AI proxy: hosts, domains, emails, and usernames are replaced with placeholders, and the response is mapped back to your real data locally. Chamber Door never sees raw engagement content, only anonymized snippets + account metadata.

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. Your pentests/ + auth/ volumes survive. Keep the volume mounts identical, or the new container comes up pointing at an empty engagements directory.
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.