Quick Start

6 steps, 5 minutes from zero to your first detection

Step 1: Create your account

Step 2: Add a node in the dashboard

Go to your dashboard and click Nodes in the sidebar, then Add Node. Enter your server's name and IP address.

Important: After you create the node, the dashboard shows your API key exactly once. Copy it immediately and save it somewhere safe. You will need it in the next step. If you lose it, you will need to delete the node and create a new one.

Step 3: Install the agent

SSH into your server and run the following. The agent runs on any Linux with Python 3.8+.

Option A: One-liner (recommended)

# Install and configure in one step
curl -sSL https://flowtriq.com/install.sh | sudo bash

The install script installs ftagent from PyPI, handles PEP 668 automatically, and launches the setup wizard.

Option A2: Manual pip

# Install from PyPI pip install ftagent --break-system-packages # Run the setup wizard (paste your API key when prompted) sudo ftagent --setup

Option B: Docker

# Pull from Docker Hub docker run -d --name ftagent --network host \ --cap-add NET_ADMIN --cap-add SYS_PTRACE \ -v /etc/ftagent:/etc/ftagent \ -v /var/lib/ftagent:/var/lib/ftagent \ --restart unless-stopped flowtriq/ftagent:latest # Then run setup inside the container docker exec -it ftagent ftagent --setup

Option C: From source

# Clone from GitHub git clone https://github.com/Flowtriq/ftagent.git cd ftagent && pip install . --break-system-packages sudo ftagent --setup

Note: On Ubuntu 23.04+, Debian 12+, and other newer distros, the --break-system-packages flag is required for global pip installs. The one-liner (curl -sSL https://flowtriq.com/install.sh | sudo bash) handles this automatically. Alternatively, use a virtualenv.

The setup wizard prompts for your API key and Node UUID (both from step 2), asks about PCAP capture and monitoring mode, auto-detects your network interface, and starts the agent as a systemd service. The node appears online in your dashboard within 30 seconds.

For servers where root is not available, use limited mode (PPS/BPS monitoring only, no PCAP):

ftagent --setup --limited

Step 4: Verify it's running

# Check agent status
sudo systemctl status ftagent

# Or run in debug mode
sudo ftagent --debug

You should see the agent send its first heartbeat and load IOC patterns from the remote config. After 5 minutes your node's baseline will be established.

Step 5: Configure alerts

Go to your workspace Console → Alert Channels and add at least one alert channel. Discord and Slack webhooks take about 30 seconds to configure.

Tip: Add a Discord channel first. It's the fastest to set up and you can test the connection with one click.

Step 6: Test detection

Use the --test flag to trigger a synthetic attack event:

sudo ftagent --test

This fires a simulated threshold crossing, opens a test incident, and sends alerts to all configured channels.