> ## 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.

# filetrace agent: run, check and stop the agent

> Reference for filetrace agent: run the collector in the foreground, report whether an agent serves the socket and how healthy it is, or stop it.

`filetrace agent` runs or controls the background agent from the command-line interface. `run` collects in the foreground and serves queries, like [`filetrace-agent`](https://filetrace.mintlify.site/cli/filetrace-agent); `status` reports whether an agent is serving the socket; `stop` asks the running agent to stop.

## Usage

```bash theme={null}
filetrace agent run [options]
filetrace agent status
filetrace agent stop
```

## run

`agent run` starts the agent in the foreground: it loads the probes, collects and answers the other commands on the socket until you press Ctrl-C. It runs the same code as `filetrace-agent` and takes the same options. The global options `--socket` and `--config` given before `agent`, and `$FILETRACE_SOCKET`, are passed on to it.

```bash theme={null}
sudo filetrace agent run
```

Service managers should start `filetrace-agent` directly. [Run the agent as a service](https://filetrace.mintlify.site/guides/run-as-a-service.md) shows how.

## status

`agent status` reports whether an agent is serving the socket, with its backend, mode, PID, start time, uptime and health:

```bash theme={null}
sudo filetrace agent status
```

```text theme={null}
Monitoring: RUNNING
Backend:    Linux eBPF (trampolines)
Mode:       standard
PID:        1008
Started:    2026-11-11 20:07:55
Uptime:     0s
Health:     Healthy
```

Health is `Degraded` while the agent has lost events within the last 60 seconds; [`stats`](https://filetrace.mintlify.site/cli/stats) gives the details. When no agent is running, `status` prints `Monitoring: STOPPED` with the command that starts one. Because the exit code carries the answer, `status` suits scripts and health checks:

```bash theme={null}
sudo filetrace agent status >/dev/null; echo $?
```

## stop

`agent stop` asks the running agent to stop. It prints `The agent is stopping.` and returns; the agent closes its socket and removes it as it exits.

```bash theme={null}
sudo filetrace agent stop
```

## Options

`status` and `stop` take no options. The options of `run`:

**--mode** `string` (default: standard)

`minimal` or `standard`. Minimal collects processes, sockets and network byte counts; standard adds file identity and file-to-network attribution.

**--probes** `string` (default: auto)

`auto`, `trampoline` or `kprobe`. Auto uses BPF trampolines where the kernel has them and kprobes otherwise.

**--flush-interval** `string` (default: 250ms)

How often counters are collected from the kernel.

**--queue-size** `string` (default: 4MB)

Kernel event queue size. The default is 1MB in minimal mode.

**--correlation-window** `string` (default: 2s)

Longest read-to-send gap that still associates a file with a send.

**--log-level** `string` (default: info)

`error`, `warn`, `info` or `debug`.

`agent run` also accepts `--event-log-size` and the other options of [`filetrace-agent`](https://filetrace.mintlify.site/cli/filetrace-agent), which lists their accepted ranges, and `filetrace agent run --help` prints the agent's own help.

## Examples

```bash theme={null}
sudo filetrace agent run
sudo filetrace agent run --mode minimal
sudo filetrace agent status
```

## Exit codes

| Command | Code | Meaning |
| - | - | - |
| `status` | 0 | An agent is running and healthy |
| `status` | 4 | No agent is running |
| `status` | 9 | An agent is running but degraded |
| `status`, `stop` | 3 | The agent socket is not accessible to this user |
| `stop` | 0 | The agent was asked to stop |
| `stop` | 4 | No agent is running |
| `run` | 0, 1, 2, 3, 5, 6, 8 | As for [`filetrace-agent`](https://filetrace.mintlify.site/cli/filetrace-agent) |
| any | 2 | Invalid arguments, such as a missing or unknown action |


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