> ## Documentation Index
> Fetch the complete documentation index at: https://filetrace.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# How the agent and the command work together

> Filetrace splits into filetrace-agent, which loads the probes and keeps bounded state, and the filetrace command, which queries it over a local socket.

Filetrace consists of two programs with separate jobs. `filetrace-agent` collects: it loads BPF programs into the kernel, turns what they report into records, and keeps those records in memory. `filetrace` asks: every command sends a query to the agent over a local socket and prints the answer. This page explains how the two fit together, which one needs privileges, and how data flows from the kernel to your terminal.

```mermaid theme={null}
flowchart LR
    K["Kernel<br/>BPF probes"] -- "ring buffer:<br/>process and socket lifecycle" --> A["filetrace-agent<br/>bounded tables, event log"]
    K -- "hash map of byte counters,<br/>swapped every 250 ms" --> A
    A -- "local socket<br/>/run/filetrace/agent.sock" --> C["filetrace<br/>command-line interface"]
    A -- "metrics page" --> P["Prometheus"]
    A -- "OTLP over gRPC" --> O["OpenTelemetry Collector"]
    A -- "gRPC API" --> G["Your client"]
```

## The agent

`filetrace-agent` is the only part that needs privileges, because only loading BPF programs does. It runs as a service (systemd, OpenRC or SysV init) or in the foreground with `sudo filetrace agent run`. It reads `/etc/filetrace/config.toml` once when it starts; its command-line options override the file.

Inside the agent, data takes two paths:

* **Lifecycle events** (process exec, fork and exit; socket connect, listen, establish and close) travel from the kernel through a ring buffer, 4 MB by default.
* **Byte counts** never become one event per system call. They accumulate in a kernel hash map keyed by socket, process and file. Every 250 ms the agent swaps that map for an empty one and reads the idle one, so no update is lost while it reads.

The agent folds both into bounded tables of processes, sockets, flows, files and transfers, and into an event log of bounded size. Rates are bytes per second over the last one to two seconds. [Records and identifiers](https://filetrace.mintlify.site/concepts/data-model.md) describes what each table holds.

The exporters are also part of the agent: the Prometheus page, the OTLP exporter and the gRPC API run inside it and are off until the configuration turns them on. They read the same state the commands read and add nothing to what the probes do. See [Integrations](https://filetrace.mintlify.site/integrations/overview.md).

## The command

`filetrace` is the command-line interface. It connects to the agent's socket, `/run/filetrace/agent.sock` by default, sends a query and prints the result as a table, JSON, JSON Lines, CSV or bare identifiers. The command itself loads nothing into the kernel.

The socket admits root and the user the agent runs as. With the agent running as root, as the packaged service does, the commands that query it need `sudo`.

`--socket` or `$FILETRACE_SOCKET` names another socket, and `--config` or `$FILETRACE_CONFIG` names another configuration file. The command takes its default output format and the agent's socket from the configuration file.

## Collection without an agent

Two commands can collect on their own. Without a running agent, `filetrace watch` and `filetrace events --follow` load the probes themselves and collect in the foreground for as long as they run. This needs the same privileges as the agent. Such a collector exports nothing, and what it saw is gone when it exits.

Every other command needs the agent and exits with code `4` when it is not running:

```text theme={null}
The Filetrace agent is not running (/run/filetrace/agent.sock: No such file or directory).

Start it with:
  sudo filetrace agent run

To check what this machine supports:
  sudo filetrace doctor
```

## Modes

The agent runs in one of two modes, set with `[agent] mode` or `--mode`:

| Mode | Records |
| - | - |
| `standard` (default) | Processes, sockets, network byte counts, file identity and file-to-network attribution. |
| `minimal` | Processes, sockets and network byte counts only. Uses a 1 MB event queue and a 256 KB event log by default. |

## Version coupling

The command and the agent speak one protocol version. A package upgrade therefore restarts a running agent together with the new command. See [Installation](https://filetrace.mintlify.site/installation.md#upgrade).

## Related pages

> [card] [Kernel instrumentation](https://filetrace.mintlify.site/concepts/kernel-probes.md)
>
> Which kernel functions are traced, and how.

> [card] [Run the agent as a service](https://filetrace.mintlify.site/guides/run-as-a-service.md)
>
> Service managers, permissions and the systemd hardening.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.