google/grr: remote live forensics for incident response

The problem GRR Rapid Response was built to answer

A compromised machine is a crime scene that is also still running. Pulling the disk for offline analysis loses memory, open sockets, and logged-in sessions, and it takes the host out of service. GRR Rapid Response is built for the other approach: leave the machine running and query it remotely. The README describes it as an incident response framework focused on remote live forensics, and the architecture is stated plainly there: a Python client (agent) installed on target systems, plus Python server infrastructure that manages and talks to the clients. The audience is incident response and security teams that operate a fleet, not a single laptop. If you are investigating one machine you own, the client-server split is more moving parts than the job needs. If you have thousands of endpoints and an alert that names three of them, the split is the point: you install the agent once and then run investigations through the server without touching the hosts again.

Agent, server, and Fleetspeak: how a request actually travels

The repository layout separates the two halves. The grr/ directory holds the framework, api_client/ holds a programmatic client for the server, and docker_config_files/ holds the per-component configuration that the Compose stack mounts into containers. The Compose file makes the dependency chain explicit rather than leaving it to prose. The grr-admin-ui service depends on db with condition: service_healthy and on fleetspeak-admin with condition: service_started, which tells you the admin UI will not come up until MySQL answers a ping and the Fleetspeak admin service has started. That ordering matters operationally: a stack that appears hung is often just the database healthcheck not yet passing. The db service is mysql:8.4 with tuned flags including max_allowed_packet=40M, log_bin_trust_function_creators=1, innodb_redo_log_capacity=167772160, innodb_log_file_size=2500M and restrict-fk-on-non-standard-key=OFF. Those are not defaults you would guess at; they are the settings this stack expects. The admin UI publishes port 8000, and the database publishes 3306, both on a shared server-network. Client installers are handled through a named volume, client_installers, mounted into both the admin UI container and the client container, so the repacked installers produced by the server are visible to the client side. The entrypoint for grr-admin-ui runs /configs/server/repack_clients.sh before starting grr, which means repacking happens as part of bringing the stack up, not as a separate manual step.

Installing GRR Rapid Response with Docker Compose

The compose.yaml header points at the documentation page for running the stack and names the container registry. It also draws a line between two modes: compose.yaml runs the stack from images fetched from the GitHub container registry, while compose.watch.yaml runs the stack from source code. Start with the image-based path. The Compose file references ghcr.io/google/grr:latest for the admin UI, and the Dockerfile comments note that an image build is triggered on every push to the repository. From the repository root, the stack is brought up with:

docker compose -f compose.yaml up

What you should see is the db container reaching a healthy state first, then fleetspeak-admin starting, then grr-admin-ui running its repack script and starting the server. The admin UI is then reachable on port 8000. The database is exposed on 3306, which is convenient locally and worth thinking about anywhere else.

To run a single server component directly rather than through Compose, the Dockerfile gives this example, mounting your config directory at /configs and naming the component and config file as arguments:

docker run -it \
  -v $(pwd)/docker_config_files/server:/configs \
  ghcr.io/google/grr:latest \
  "-component" "admin_ui" \
  "-config" "/configs/grr.server.yaml"

The Dockerfile also documents the client side. It warns that the Fleetspeak client requires connectivity to the Fleetspeak server and recommends running that client inside the Docker Compose stack, because the stack handles repacking the client templates and installing them into the GRR client container. If you insist on doing it by hand, the documented route is to start a container with an open shell and the client config mounted:

docker run -it \
  -v $(pwd)/docker_config_files/client:/configs \
  --entrypoint /bin/bash \
  ghcr.io/google/grr:latest

Inside that shell you repack the client template and install the resulting Debian package. Read the Dockerfile note carefully before planning around this: the client templates are described as being built only in the GitHub workflow that creates the GRR Docker image, not in a local build. A locally built image will not carry them.

Where GRR Rapid Response stops being the right tool

The client-server design is the limitation as much as the feature. An agent that must reach a Fleetspeak server is an agent that is useless on a host with no route back, which is exactly the situation for an isolated machine or an air-gapped segment. The Dockerfile says this outright: the Fleetspeak client requires connectivity to the Fleetspeak server, and if you run it outside the Compose stack the config needs to be adjusted. That is a real configuration burden, not a footnote. The second constraint is the database. The stack ships MySQL 8.4 with a specific set of server flags, and the healthcheck gates startup on it. If your organisation runs a different database engine, the supplied Compose path does not apply, and the README does not document an alternative. Third, the deployment surface is wide: a database, a Fleetspeak admin service, the admin UI, and repacked client installers all have to line up. That is a reasonable price for fleet-wide live forensics and a poor one for a one-off investigation on a machine you can simply unplug. The README itself is short and defers to the documentation site for anything beyond the architecture sentence, so treat the repository files as the practical reference for deployment details.

GRR vs Velociraptor: two answers to the same question

The most common comparison people search for is GRR vs Velociraptor, and the difference in approach is worth stating precisely. GRR Rapid Response is, per its README, a Python client plus Python server infrastructure that manages and talks to the clients. The architecture is a managed fleet with a central server, a relational database behind it, and Fleetspeak as the transport between server and agent. That shape suits an organisation that wants endpoints enrolled once and then queried repeatedly by a team, with results landing in a shared server rather than on an analyst's laptop. Velociraptor takes a different route: a single agent binary plus its own query language, oriented toward running targeted hunts and collections that the analyst composes at the endpoint and retrieves. If your problem is "I need to ask a question across ten thousand machines right now and keep the answers somewhere central," GRR's server-and-database model is the closer fit. If your problem is "I want to hand one binary to a responder and collect from a host without standing up infrastructure," the server dependency in GRR is friction you will feel on day one. Neither is a drop-in for the other; the deployment model is the decision.

Maintenance, releases, and what the Apache-2.0 licence means here

The repository is not archived, and the last push was on 2026-05-12. The most recent release listed is v.4.0.0.0-release from 2025-12-15, following v3.4.9.1-release in 2025-04-16 and v3.4.9.0 in 2025-02-27. The version.ini file at the repository root is where the version is tracked, and the release tags follow a four-part numbering scheme, so an upgrade is a deliberate act rather than something that happens quietly. The practical upgrade cost sits in the database and client templates. Because the Compose stack pins mysql:8.4 and passes specific InnoDB and packet-size flags, a database version change is a migration you plan for, not a tag bump. And because client installers are produced by repacking templates inside the server image, an upgrade means re-repacking and redistributing the agent to your fleet. The Dockerfile states the image is rebuilt on every push, so ghcr.io/google/grr:latest moves; pinning a digest rather than tracking latest is the safer default for anything you depend on. On licensing: the project is Apache-2.0, which permits commercial and internal use and requires that you preserve the licence and notice files. It also includes an explicit patent grant. That is a permissive arrangement, but it is not legal advice, and if you redistribute repacked client installers to third parties you should have your own counsel review the notice requirements.

Editorial conclusion

Adopt google/grr if you need to query live endpoints at fleet scale and you have the operational appetite for a server, a MySQL 8.4 database, and a Fleetspeak admin service in the same Compose network. Do not adopt it if you want a single static binary you can hand to a responder and run with no server at all; the client exists to talk to the server. Before committing, verify that the client templates in the ghcr.io/google/grr:latest image repack cleanly in your environment, because the Dockerfile states those templates are built in the GitHub workflow that creates the image and not in a local build. If your repack step depends on a local build, the install path in compose.yaml will not carry you.

Frequently asked questions

Official sources

1. google/grr on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases