Installation¶

Requirements¶

Docker 20.10+ (recommended) or Python 3.11+
nmap 7.80+

Docker (Recommended)¶

Why Docker?

Docker is the easiest way to run Argus. It handles all dependencies and provides multi-arch support (amd64, arm64, armv7) for Raspberry Pi and other ARM devices.

Docker Compose¶

mkdir argus && cd argus

# Get config
curl -o config.yaml https://raw.githubusercontent.com/rangulvers/argus/main/config.yaml.example

# Edit subnet - set your network (e.g., 192.168.1.0/24)
nano config.yaml

docker-compose.yml

services:
  argus:
    image: ghcr.io/rangulvers/argus:latest
    network_mode: host
    cap_add:
      - NET_ADMIN
      - NET_RAW
    volumes:
      - ./data:/app/data
      - ./config.yaml:/app/config.yaml:ro
    restart: unless-stopped

docker compose up -d

Web UI: http://localhost:8080

Docker Run¶

docker run -d \
  --name argus \
  --network host \
  --cap-add NET_ADMIN \
  --cap-add NET_RAW \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/config.yaml:/app/config.yaml:ro \
  ghcr.io/rangulvers/argus:latest

Network Mode Required

--network host is required for accurate L2/L3 discovery. Bridge networking will not work correctly for network scanning.

Setup Checklist¶

Docker installed
Create directory and download config
Edit config.yaml with your subnet
Create docker-compose.yml
Run docker compose up -d
Access web UI at http://localhost:8080

Manual Installation¶

For users who prefer to run without Docker.

Debian/UbuntumacOSFedora/RHEL

sudo apt-get update
sudo apt-get install nmap python3 python3-venv

brew install nmap python@3.11

sudo dnf install nmap python3 python3-pip

Clone and Setup¶

# Clone repository
git clone https://github.com/rangulvers/argus.git
cd argus

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure
cp config.yaml.example config.yaml
nano config.yaml

Run the Server¶

# Run with sudo for full nmap features
sudo .venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8080

Why sudo?

nmap requires elevated privileges for OS detection, service version detection, and raw packet operations. Without sudo, some scan features will be limited.

Setup Checklist¶

Updating¶

DockerManual

docker compose pull
docker compose up -d

git pull
pip install -r requirements.txt

Troubleshooting¶

Permission denied errors

Docker: Ensure you have the required capabilities:

docker run --cap-add NET_ADMIN --cap-add NET_RAW ...

Manual: Run with sudo:

sudo .venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8080

No devices found

Check your subnet in config.yaml:

network:
  subnet: "192.168.1.0/24"  # Your actual network

Verify network interface - Docker must use host networking:
```
docker run --network host ...
```
Test nmap directly:
```
sudo nmap -sn 192.168.1.0/24
```

Container won't start

Check logs:

docker logs argus

Common issues:

Missing --network host flag
Missing capabilities (NET_ADMIN, NET_RAW)
Invalid config.yaml syntax
Port 8080 already in use

Database errors

Reset database:

# Stop Argus
docker compose down

# Remove database
rm -f data/argus.db

# Restart
docker compose up -d

Next Steps¶

Configuration

Customize scan profiles, alerts, and integrations

Configure Argus
First Scan

Run your first network scan and explore results

Start Scanning