How to Install Velociraptor on Ubuntu

Velociraptor is a DFIR and endpoint visibility platform: a Linux server collects artifacts from agents over a persistent TLS connection, and analysts work through a web GUI or VQL. On Ubuntu the supported production path is not “drop a binary and run it as root”—you generate a server.config.yaml, build the official Debian server package, and let velociraptor_server.service run the frontend as the velociraptor user.

This guide walks through how to install Velociraptor on Ubuntu using the current upstream flow (release 0.77.1 on my test host). I cover config generation, the .deb install, adding a GUI admin, port checks, a local client smoke test, and firewall notes. Older blog posts often pin ancient versions, skip the Debian package, or open only port 8889 while forgetting 8000 for agents—those gaps are called out inline.

Tested on: Ubuntu 25.04 (Plucky Puffin); kernel 6.14.0-37-generic.

Quick command summary

What you are installing

There is no default service on port 8300—community guides sometimes confuse it with 8003.

Velociraptor stores data on the local filesystem under the configured datastore (for example /var/lib/velociraptor). Plan disk space before you enroll many endpoints; see check disk space on Linux if the volume is tight.

Prerequisites

On the Ubuntu server:

• 64-bit Ubuntu 22.04 LTS or newer (22.04, 24.04, 25.04 tested in community and vendor docs).
• sudo and curl or wget.
• Open ports as needed: 8000/tcp for clients; 8889/tcp only if you expose the GUI (SSH tunnel is safer).
• A hostname or IP clients can resolve to the Frontend URL (for lab work, localhost / 127.0.0.1 is fine).

For a five-minute evaluation without packaging, skip ahead to Try Instant Velociraptor first and return here when you want a persistent server.

Try Instant Velociraptor first

Official docs recommend ./velociraptor gui for learning: one process, loopback-only GUI, default login admin / password, datastore under a temp folder. That is ideal for VQL and artifact experiments, not production.

curl -fsSL -L -o velociraptor \
  https://github.com/Velocidex/velociraptor/releases/download/v0.77.1/velociraptor-v0.77.1-linux-amd64
chmod +x velociraptor
./velociraptor gui

Use a dedicated datastore when you need persistence across reboots:

./velociraptor --datastore ~/velociraptor-gui-data gui

Install Velociraptor server on Ubuntu (official Debian path)

Step 1: Download the release binary

mkdir -p ~/velociraptor && cd ~/velociraptor
curl -fsSL -L -o velociraptor \
  https://github.com/Velocidex/velociraptor/releases/download/v0.77.1/velociraptor-v0.77.1-linux-amd64
chmod +x velociraptor
./velociraptor version

On my host:

version: 0.77.1
commit: 3137c7f71
build_time: "2026-06-22T15:32:15Z"
architecture: amd64

Pick the latest GitHub release if 0.77.1 is superseded—keep the version consistent across server build, .deb, and clients.

Step 2: Generate server.config.yaml

Interactive wizard (recommended when you have a TTY):

./velociraptor config generate -i

Choose Self Signed SSL for a lab, set the Frontend DNS/IP your clients will use, and confirm ports 8000 / 8889.

Non-interactive generation (scriptable, what I used):

./velociraptor config generate > server.config.yaml

Defaults include https://localhost:8000/ for clients, GUI on 127.0.0.1:8889, and datastore /var/tmp/velociraptor/. For a packaged server, point the datastore at /var/lib/velociraptor and tighten Frontend bind for a localhost lab:

cp server.config.yaml server.config.lab.yaml
sed -i 's|/var/tmp/velociraptor/|/var/lib/velociraptor/|g' server.config.lab.yaml
sed -i '/^Frontend:/,/^[^ ]/ s/bind_address: 0.0.0.0/bind_address: 127.0.0.1/' server.config.lab.yaml

For production, set Frontend.hostname to the DNS name agents will use, keep bind_address: 0.0.0.0 on the Frontend if clients connect remotely, and plan TLS (Let's Encrypt or SSO) per official deployment docs.

config generate -i fails without a TTY (invalid input when piped)—use a real terminal, expect, or the non-interactive path above.

Step 3: Build the Debian server package

./velociraptor --config server.config.lab.yaml debian server --binary ./velociraptor
ls -lh velociraptor-server-*.amd64.deb

deb_create: writing file velociraptor-server-0.77.1.amd64.deb
-rw------- 1 user user 30M ... velociraptor-server-0.77.1.amd64.deb

This embeds your config and installs binaries under /usr/local/bin with a velociraptor_server systemd unit—cleaner than hand-written units in older tutorials.

Step 4: Install with dpkg

sudo dpkg -i velociraptor-server-0.77.1.amd64.deb
sudo systemctl enable --now velociraptor_server
sudo systemctl status velociraptor_server --no-pager

Setting up velociraptor-server (0.77.1) ...
Adding system user `velociraptor' ...
Created symlink ... velociraptor_server.service
● velociraptor_server.service - Velociraptor server
     Active: active (running)

Config lands in /etc/velociraptor/server.config.yaml owned by velociraptor. Datastore files live under /var/lib/velociraptor.

Step 5: Create a GUI administrator

Non-interactive config generate enables Basic auth but does not create users. Add one as the velociraptor account:

sudo -u velociraptor /usr/local/bin/velociraptor \
  --config /etc/velociraptor/server.config.yaml \
  user add --role=administrator admin 'YOUR_SECURE_PASSWORD'
sudo systemctl restart velociraptor_server

Running user add as root prints an error that Velociraptor should run as the velociraptor user—that is expected.

Step 6: Verify ports and GUI

ss -tlnp | grep -E '8000|8889|8001|8003'

LISTEN 127.0.0.1:8889  ... velociraptor
LISTEN 127.0.0.1:8001  ... velociraptor
LISTEN 127.0.0.1:8000  ... velociraptor
LISTEN 127.0.0.1:8003  ... velociraptor

Probe the GUI (self-signed TLS):

curl --noproxy '*' -k -sS -o /dev/null -w 'HTTP:%{http_code}\n' https://127.0.0.1:8889/

HTTP:307

A redirect to /app/index.html is normal. With credentials:

curl --noproxy '*' -k -u 'admin:YOUR_SECURE_PASSWORD' -sS -o /dev/null -w 'HTTP:%{http_code}\n' \
  https://127.0.0.1:8889/app/index.html

HTTP:200

If curl returns 403 without --noproxy '*', check http_proxy—localhost requests may be sent through a proxy on this host.

Browse from your workstation via SSH tunnel:

ssh -L 8889:127.0.0.1:8889 user@your-server

Then open https://127.0.0.1:8889 locally and accept the self-signed certificate.

Firewall and remote clients

Allow agent traffic on the Frontend port:

sudo ufw allow 8000/tcp comment 'Velociraptor frontend'

Open 8889 only when you intentionally expose the GUI:

sudo ufw allow 8889/tcp comment 'Velociraptor GUI'

Several older third-party guides mention port 8889 for the GUI but omit 8000 for the Frontend—remote agents will not enroll without Frontend access.

Ensure Frontend.hostname in server.config.yaml matches what clients resolve (DNS A/AAAA record or /etc/hosts in a lab).

Enroll a Linux client (smoke test)

Export client configuration from the server:

sudo /usr/local/bin/velociraptor \
  --config /etc/velociraptor/server.config.yaml \
  config client > ~/client.config.yaml

The YAML includes server_urls pointing at your Frontend, for example https://localhost:8000/.

For a quick interactive client on the same machine, point writeback to a writable path (default /etc/velociraptor.writeback.yaml needs root):

sed 's|writeback_linux: /etc/velociraptor.writeback.yaml|writeback_linux: /tmp/velociraptor.writeback.yaml|' \
  ~/client.config.yaml > ~/client.config.lab.yaml
timeout 15 ./velociraptor --config ~/client.config.lab.yaml client -v

Loading config from file client.config.lab.yaml
Generating new private key....
Starting Crypto for client C.3caf71aa5ba63977

Production Linux endpoints use packaged clients:

./velociraptor --config server.config.lab.yaml debian client --binary ./velociraptor
sudo dpkg -i velociraptor-client_*.deb

Windows endpoints typically use the Server.Utils.CreateMSI artifact in the GUI to bake client.config.yaml into an MSI.

How this differs from older guides

Uninstall Velociraptor

sudo systemctl stop velociraptor_server
sudo systemctl disable velociraptor_server
sudo dpkg -P velociraptor-server
sudo rm -rf /var/lib/velociraptor /etc/velociraptor

Confirm ports are free:

ss -tlnp | grep -E '8000|8889' || echo "ports free"

Troubleshooting

References

• Velociraptor deployment overview
• Velociraptor GitHub releases

Summary

To install Velociraptor on Ubuntu, download the linux-amd64 binary, generate server.config.yaml, run velociraptor debian server, and install the resulting velociraptor-server package with dpkg. Enable velociraptor_server, add a GUI user with user add as the velociraptor account, and verify ports 8000 and 8889. Use an SSH tunnel for admin access in a lab, open 8000 on the firewall for real agents, and deploy clients with config client plus debian client packages. For a quick trial without packaging, ./velociraptor gui is enough to explore the platform.