Agent Setup

Requirements

Linux (any distro with /proc/net/dev)
Python 3.8 or higher
Root access (required for full mode - not needed with --limited)
Network interface with inbound traffic to monitor

Installation

pip install ftagent --break-system-packages
sudo ftagent --setup

Configuration file

The setup wizard creates /etc/ftagent/config.json (chmod 600):

{
  "api_key":    "ft_live_your_key_here",
  "api_base":   "https://flowtriq.com/api/v1",
  "interface":  "eth0",
  "node_id":    42,
  "pcap_path":  "/var/lib/ftagent/pcaps"
}

Systemd service

The setup wizard installs a systemd service. Manage it with:

sudo systemctl enable  ftagent   # start on boot
sudo systemctl start   ftagent   # start now
sudo systemctl status  ftagent   # check status
sudo journalctl -u ftagent -f    # tail logs

Flags

--setup: Interactive setup wizard
--test: Trigger a synthetic detection event
--debug: Verbose output, don't daemonize
--limited: Run without root - no packet capture, PCAP, IOC matching, or TCP flag analysis

Limited mode

By default the agent requires root for Scapy packet capture. If you cannot grant root, use --limited to run the agent without any root-level functionality.

pip install ftagent --break-system-packages
ftagent --setup --limited

Limited mode monitors traffic using /proc/net/dev counters only. It still reports PPS/BPS metrics, heartbeats, and triggers incident detection via baseline deviation - but the following features are unavailable:

PCAP capture and download
Protocol-level classification (TCP flags, UDP vs TCP breakdown)
IOC pattern matching
Source IP analysis and geo-distribution

The --limited flag is stored in the config file so you only need to pass it once during setup. The systemd service does not need root when running in limited mode:

systemctl --user enable  ftagent   # no sudo required
systemctl --user start   ftagent
systemctl --user status  ftagent

Limited mode does not use Scapy at runtime. The agent automatically skips packet capture features when running with --limited.