GitHub Repository: github.com/Xboarder56/velociraptor-docker

Velociraptor (Server) in Docker

Run the Velocidex Velociraptor server in a container with sensible defaults, HTTPS, and prebuilt client repacks.

• Architectures: linux/amd64, linux/arm64
• Ports: 8000 (client/ingest), 8889 (GUI), 8001 (gRPC API), 8003 (Prometheus)
• Data dir: mount /velociraptor to persist config, keys, artifacts, and repacked clients
• TLS: self-signed cert generated on first run (you can rotate later)

On start, the container prints a small build banner (version, arch, base image, git commit, build date) so you can confirm what you pulled.

Quick Start

docker run -it --rm \
  -p 8000:8000 -p 8889:8889 -p 8001:8001 -p 8003:8003 \
  -v $PWD/velodata:/velociraptor \
  docker.io/xboarder56/velociraptor:latest

Open https://localhost:8889 (accept the self-signed cert) and log in with the bootstrap credentials below (you should change them right away).

The same command works with Podman by replacing docker with podman. The fully qualified docker.io/... image name avoids short-name registry ambiguity. On SELinux-enforcing hosts, label a bind mount for the container by using -v "$PWD/velodata:/velociraptor:Z".

Runtime Configuration (Environment Variables)

These variables are read at container start—no image rebuilds needed.

Persistent paths (mount a volume):

• /velociraptor/server.config.yaml — server config (auto-generated)
• /velociraptor/client.config.yaml — client config
• /velociraptor/client_bundles/ — repacked client binaries (.deb/.rpm/.exe/.msi)

Configuration ownership modes

The default remains reconcile, preserving the behavior of previous image versions and existing installations.

Use an external config with a read-only bind mount:

docker run -it --rm \
  -e VELOX_CONFIG_MODE=external \
  -e VELOX_CONFIG_FILE=/config/server.config.yaml \
  -v "$PWD/server.config.yaml:/config/server.config.yaml:ro" \
  -v "$PWD/velodata:/velociraptor" \
  -p 8000:8000 -p 8889:8889 -p 8001:8001 -p 8003:8003 \
  docker.io/xboarder56/velociraptor:latest

Because external mode cannot replace its configuration, certificate/key rotation must be handled by the external config owner. Generated client configuration and client bundles are still written beneath /velociraptor.

Bootstrap password secrets

VELOX_DEFAULT_PASSWORD_FILE follows the Docker/Podman _FILE convention. It is read only while creating a new server config and bootstrap user. The file must be readable and non-empty, and setting both password variables during initialization is an error.

secrets:
  velociraptor_admin_password:
    file: ./secrets/admin-password

services:
  velociraptor:
    image: docker.io/xboarder56/velociraptor:latest
    environment:
      VELOX_DEFAULT_PASSWORD_FILE: /run/secrets/velociraptor_admin_password
    secrets:
      - velociraptor_admin_password
    volumes:
      - ./velodata:/velociraptor

The secret value is not placed in the container environment or retained by the server process. The secret-file path remains visible in container metadata. Direct VELOX_DEFAULT_PASSWORD remains supported for compatibility, but direct environment values are visible through container inspection.

Common Run Examples

1) Run quietly (INFO mode)

This overrides the default, which is to run with verbose (DEBUG) logs.

docker run -it --rm \
  -p 8000:8000 -p 8889:8889 -p 8001:8001 -p 8003:8003 \
  -v $PWD/velodata:/velociraptor \
  -e VELOX_DEFAULT_USER=admin -e VELOX_DEFAULT_PASSWORD='S3cure!' \
  -e VELOX_START_SERVER_VERBOSE=false \
  docker.io/xboarder56/velociraptor:latest

2) Set the public URL clients should use

docker run -it --rm \
  -e VELOX_FRONTEND_HOSTNAME=velociraptor.example.com \
  -e VELOX_FRONTEND_PORT=443 \
  -e VELOX_FRONTEND_SERVER_SCHEME=https \
  -p 443:8000 -p 8889:8889 \
  -v $PWD/velodata:/velociraptor \
  docker.io/xboarder56/velociraptor:latest

3) Use different public URLs for Client and GUI

docker run -it --rm \
  -e VELOX_FRONTEND_SERVER_URL=https://ingest.example.com:8000/ \
  -e VELOX_GUI_URL=https://admin.example.com:8889/ \
  -p 8000:8000 -p 8889:8889 \
  -v $PWD/velodata:/velociraptor \
  docker.io/xboarder56/velociraptor:latest

Docker Compose

services:
  velociraptor:
    image: docker.io/xboarder56/velociraptor:latest
    restart: unless-stopped
    environment:
      VELOX_CONFIG_MODE: reconcile # backward-compatible default
      VELOX_DEFAULT_USER: admin
      VELOX_DEFAULT_PASSWORD: "S3cure!"
      VELOX_FRONTEND_HOSTNAME: velociraptor.example.com
      VELOX_START_SERVER_VERBOSE: "false"
    ports:
      - "8000:8000"   # client/ingest
      - "8889:8889"   # GUI
      - "8001:8001"   # gRPC API
      - "8003:8003"   # Metrics
    volumes:
      - ./velodata:/velociraptor

What to Expect on First Run

• The entrypoint generates a secure server.config.yaml and a client.config.yaml.
• Clients for Linux (amd64 + arm64), macOS (amd64 + arm64), and Windows (exe + msi) are repacked into /velociraptor/client_bundles/ with your server URL.
• You’ll see logs like:
  • GUI is ready to handle TLS requests on https://localhost:8889/
  • Frontend is ready to handle client TLS requests at https://localhost:8000/

Client Binaries

After startup, check ./velodata/client_bundles/ for repacked binaries:

• Linux: repacked executables for amd64 and arm64; .deb and .rpm packages for the image's native architecture
• macOS: repacked executables for amd64 and arm64
• Windows: .exe and .msi

If a specific upstream client binary isn’t available, the repack step is skipped (you’ll see a log message).

Bundled Triage Artifacts

Every image includes these official Velocidex Triage Artifacts:

• Linux.Triage.UAC
• Windows.Triage.Targets

The generated definitions are pinned to an immutable upstream commit, verified by SHA-256 during the image build, validated against the bundled Velociraptor binary, and loaded on every server start. The daily upstream workflow tracks both definitions and opens a revision PR when they change.

Security Notes

• Change the default credentials on first run; prefer VELOX_DEFAULT_PASSWORD_FILE so the password is not stored in container metadata.
• TLS is self-signed by default; rotate keys/certificates as needed from the server.
• Expose GUI/API only where appropriate; consider a reverse proxy or firewall rules.

Troubleshooting

• Seeing [DEBUG] FlowStorageManager housekeeping run?
  You likely set VELOX_START_SERVER_VERBOSE=true (adds -v). Remove it to suppress DEBUG.
• Ports already in use? Map them as needed: -p 443:8000 and set VELOX_FRONTEND_PORT=443.

Tags

• :latest — most recent successful build
• :<velociraptor-version> — e.g. :0.76.5. Floats to the latest re-release for that upstream patch.
• :<minor> — e.g. :0.76. Floats across patch releases within that minor.
• :sha-<short> — e.g. :sha-abc1234. Commit-pinned reproducible reference.
• Multi-arch manifests are published for amd64 and arm64

Build & Release Flow

This repo uses two GitHub Actions workflows:

• upstream-check.yml runs daily. It polls the Velocidex release feed and the official Triage artifact project. If it sees a newer release, re-published binaries, or updated Triage definitions, it opens a PR bumping the corresponding lockfiles. For platforms upstream hasn't published yet for the latest release, the workflow walks back through prior releases and pins those assets to the most recent release that does include them.
• build-publish.yml runs on tag pushes matching v* and on manual dispatch. It:
  1. Builds an amd64 image and runs scripts/ci-image-validation.sh against it (server starts, GUI responds, a repacked Linux client makes contact).
  2. Only if validation passes, does a multi-arch (linux/amd64, linux/arm64) buildx build and pushes to Docker Hub with provenance + SBOM attestations.

To cut a release:

1. Review and merge the PR from upstream-check.

2. Tag the merge commit with the value of VELOX_VERSION from versions.env (optionally suffixed with -<IMAGE_REVISION> when IMAGE_REVISION > 1):

   git tag v0.76.8        # first revision
   # or
   git tag v0.76.8-2      # subsequent re-release of the same upstream version
   git push --tags
   

3. Required Docker Hub secrets on the repo: DOCKERHUB_USERNAME, DOCKERHUB_TOKEN.

About This Fork

This repository is a fork of weslambert/velociraptor-docker, originally created by Wes Lambert.
It aims to maintain compatibility with the latest Velocidex Velociraptor releases while providing additional configuration options and deployment improvements for Docker environments.

All credit for the foundational work goes to Wes Lambert — this fork primarily adds quality-of-life enhancements, updated configurations, and maintenance updates.

Maintained by: Xboarder56
Upstream project: Velocidex Velociraptor