Velociraptor endpoint agents are called
clients. Clients connect to
the server and wait for instructions, which mostly consist of VQL
statements, then run any VQL queries and return the result to the
There are several ways to run clients, depending on your needs. Ultimately however, the same Velociraptor binary is run with the client configuration file generated in the previous setup steps, providing it with the key material and configuration.
This page summarizes the recommended ways to run the clients and discusses the pros and cons of each approach.
Note that all Velociraptor binaries (for a particular operating system) are the same. There is no distinction between the client binaries and server binaries. Therefore you can run the server or the client on each supported platform. It’s simply command line options telling the binary to behave as a server or client.
This method is most suitable for testing your deployment. In a command shell, simply run the client using the client configuration.
$ velociraptor --config client.config.yaml client -v
The first time the client connects it will
enroll. The enrolment
process requires the client to reveal basic information about itself
to the server.
Note that this type of interactive execution will work effectively the same way for all versions of the client (Windows, Linux, or Mac). In the sections that follow, we show options for more scalable and/or permanent use.
An MSI is a standard Windows installer package. The advantages are that most enterprise system administration tools are used to deploying software in MSI packages. Therefore you can use SCCM or Group Policy to add the MSI to the assigned software group.
For more information, see How to use Group Policy to remotely install software in Windows Server 2008 and in Windows Server 2003
The recommended way to install Velociraptor as a client on Windows is via the release MSI on the Github releases page.
One of the main benefits in using the official Velociraptor MSI is that the MSI and the executable are signed. Windows Defender aggressively quarantines unsigned binaries, so it is highly recommended that Velociraptor be signed.
Since the Velociraptor client requires a unique configuration file to identify the location of the server, we can’t package the configuration file in the official release. Therefore, the official MSI does not include a configuration file. It must be provided separately.
The official release installs the Velociraptor executable into
C:\Program Files\Velociraptor\ then creates a new Windows service
that points to this executable and starts automatically at boot
time. If an existing Velociraptor service is already installed, it
will be overwritten.
When the service starts, it attempts to load the configuration file
C:\Program Files\Velociraptor\Velociraptor.config.yaml. Note
that this is a different name to the configuration file generated by
the interactive config generator, which was
your client config file is named otherwise, simply rename it to
Velociraptor.config.yaml (case insensitive) and move it into the
C:\Program Files\Velociraptor folder.
If that file is not found, Velociraptor will wait and retry periodically to locate the configuration file. When the file is found, the client will be started.
So to summarize, when installing from the official MSI package you need to:
Assign the MSI via Group Policy, or use some other method to deploy the official MSI installer.
Copy the configuration file from a share to the Velociraptor program directory. This can be done via Group Policy Scheduled tasks or another way (see the Group Policy procedure outlined below). As soon as the configuration file is copied, Velociraptor will begin communicating with the server.
The official Velociraptor MSI does not include the configuration file and therefore requires further steps to deploy. In practice it is almost always easier to build a custom MSI which includes your own configuration file embedded in it.
Velociraptor already includes a Wix Framework configuration file that creates a proper custom MSI with embedded configuration. You can also customize this Wix file to specify a different service name, destination location etc.
To do so, follow follow the instructions here
To summarize the process, you will need to:
docs/wixdirectory into a new working directory on your host.
docs/wixsteps you through the typical settings to customize.
Install the Wix application on your Windows host.
Add your custom client.config.xml file and the appropriate Velociraptor
executable to a subdirectory of your build directory called
When installing using an MSI, simply run
msiexec /i velociraptor_custom.msi
To install the binary, create the service and start it.
It is also possible to tell the executable to install itself as a Windows service instead of using an MSI. This option is not recommended because it does not use a proper package manager, and therefore Velociraptor can not be easily uninstalled or upgraded.
Nevertheless this approach is possible to do via the Group Policy scheduled tasks procedure outlined below. Simply run the following command:
# velociraptor.exe --config client.config.yaml service install
This will copy the binary to the location specified in the
configuration file under
Client.windows_installer. You can also
change the name of the binary and the service name if you wish.
service install directive can be used to install Velociraptor on
Mac client. The following command installs binary & config to /usr/local/sbin.
Persistence is via launchd (check with
ps -eaf | grep velo and
sudo launchctl list | grep velo)
# velociraptor --config client.config.yaml service install
The service can be uninstalled with the following command:
# /usr/local/sbin/velociraptor service remove --config=/usr/local/sbin/velociraptor.config.yaml
ps -eaf | grep velo and
sudo launchctl list | grep velo.
The dpkg (Debian) or rpm (Red Hat/CentOS/Fedora) tools can be used to install Velociraptor on Linux clients after creating an appropriate package.
# velociraptor-vx.x.x-linux-amd64 --config client.config.yaml debian client
# sudo dpkg -i velociraptor_x.x.x_client.deb
# sudo apt-get remove velociraptor-client
Create (Most OS variants with systemctl)
# velociraptor-vx.x.x-linux-amd64 --config client.config.yaml rpm client
Create (OS variants without systemctl and old GLIBC i.e. CentOS6)
# velociraptor-vx.x.x-linux-amd64-centos --config client.config.yaml rpm client --use_sysv
# sudo rpm -i velociraptor_x.x.x_client.rpm
# rpm -qa | grep -i velociraptor # sudo rpm -e velociraptor-x.x.x.X86_64
There has been a lot of interest in “agentless hunting” especially using PowerShell.
There are many reasons why agentless hunting is appealing - there are already a ton of endpoint agents and yet another one may not be welcome. Sometimes we need to deploy endpoint agents as part of a DFIR engagement and we may not want to permanently install yet another agent on endpoints.
In the agentless deployment scenario, we simply run the binary from a network share using Group Policy settings. The downside to this approach is that the endpoint needs to be on the domain network to receive the Group Policy update (and have the network share accessible) before it can run Velociraptor.
When we run in agentless mode, we are typically interested in collecting a bunch of artifacts via hunts and then exiting - the agent will not restart after a reboot. So this method is suitable for quick hunts on corporate (non roaming) assets.
The first step is to create a network share with the Velociraptor binary and its configuration file. We will run the binary from the share in this example, but for more reliability you may want to copy the binary into e.g. a temp folder on the end point in case the system becomes disconnected from the domain. For quick hunts though, it should be fine.
We create a directory on the server. Note that in the below example, we’re creating on a Domain Controller, but we strongly recommend using another location on real deployments.
In this example we created a directory called
and ensured that it’s read-only. We shared the directory as the name
We now place the Velociraptor executable and client config file in
that directory and verify that it can run the binary from the network
share. The binary should be accessible via
Next we create the Group Policy object, which forces all domain connected machines to run the Velociraptor client. We use the Group Policy Management Console:
Select the OU or the entire domain and click “Create New GPO”:
Now right click the GPO object and select “Edit”:
We will create a new scheduled task. Rather than schedule it at a particular time, we will select to run it immediately. This will force the command to run as soon as the endpoint updates its Group Policy settings, because we don’t want to wait for the next reboot of the endpoint.
Next we give the task a name and a description. In order to allow
Velociraptor to access raw devices (e.g. to collect memory or NTFS
artifacts) we can specify that the client will run at
NT_AUTHORITY\SYSTEM privileges and run without any user being logged
It’s also worth ticking the “hidden” checkbox here to prevent a console box from appearing.
Next click the Actions tab and add a new action. This is where we
launch the Velociraptor client. The program will simply be launched
from the share (i.e.
\\DC\Deployment\velociraptor.exe) and we give
it the arguments allowing it to read the provided configuration file
--config \\DC\Deployment\client.config.yaml client -v).
In the “Setting” tab we can control how long we want the client to run. For a quick hunt, this may be an hour or two depending on the network size and hunt scope. For a more comprehensive DFIR collection, be prepared to wait several hours or even days while user machines are naturally disconnected and reconnected from the network. The GPO will ensure the client is killed after the allotted time.
Once the GPO is installed it becomes active for all domain machines. You can now schedule any hunts you wish using the Velociraptor GUI. When a domain machine refreshes its Group Policy, it will run the client, which will enrol and immediately participate in any outstanding hunts - thus collecting and delivering its artifacts to the server.
After the allotted time has passed, the client will shut down without having installed anything on the endpoint.
You can force a Group Policy update by running the
program. Now you can verify that Velociraptor is running:
The client’s identity is derived from the client’s cryptographic
certificate which is stored in the
writeback location on the
endpoint (For example by default
We generally try to preserve this file between updates in order to
ensure clients do not change their client id. The default provided
Wix script ensures the file remains (even if the package is
uninstalled completely) in order to ensure a consistent client id for
Generally it is sufficient to repackage the latest client binary in a new MSI, after downloading it from the GitHub Release Page. Installing the new MSI is simply a matter of using standard software management tools.
It is possible to remotely upgrade the client by pushing the new MSI
to the endpoint and installing it. This is handled by the
Admin.Client.Upgrade artifact. To use it, simply collect the
artifact from the endpoint and click the tool setup screen.
In the tools setup screen select the MSI to push from your browser and upload it to the server.
Note that when installing the MSI using Velociraptor, the Velociraptor process will be killed part way through collecting the artifact, so it would appear to never complete it (in the GUI the flow looks hung). This is OK and part of the upgrade process.
To verify that clients are upgraded we recommend running the
Generic.Client.Info hunt periodically. This hunt will refresh the
server’s datastore of client details (including reporting the client’s