Installation Guide

Quick Install (Ubuntu / Debian)

curl -fSL https://raw.githubusercontent.com/gen0sec/synapse/refs/heads/main/install.sh | sh

Package Install (GitHub Releases)

Download pre-built packages from GitHub Releases.

Debian / Ubuntu (.deb)

# x86_64
wget https://github.com/gen0sec/synapse/releases/latest/download/synapse_0.5.0-1_amd64.deb
sudo dpkg -i synapse_0.5.0-1_amd64.deb

# ARM64
wget https://github.com/gen0sec/synapse/releases/latest/download/synapse_0.5.0-1_arm64.deb
sudo dpkg -i synapse_0.5.0-1_arm64.deb

RHEL / CentOS / Fedora (.rpm)

# x86_64
wget https://github.com/gen0sec/synapse/releases/latest/download/synapse-0.5.0-1.x86_64.rpm
sudo rpm -i synapse-0.5.0-1.x86_64.rpm

# ARM64
wget https://github.com/gen0sec/synapse/releases/latest/download/synapse-0.5.0-1.aarch64.rpm
sudo rpm -i synapse-0.5.0-1.aarch64.rpm

Binary (tar.gz)

# x86_64
wget https://github.com/gen0sec/synapse/releases/latest/download/synapse-x86_64-unknown-linux-gnu.tar.gz
tar xzf synapse-x86_64-unknown-linux-gnu.tar.gz
sudo mv synapse /usr/local/bin/

# ARM64
wget https://github.com/gen0sec/synapse/releases/latest/download/synapse-aarch64-unknown-linux-gnu.tar.gz
tar xzf synapse-aarch64-unknown-linux-gnu.tar.gz
sudo mv synapse /usr/local/bin/

Ansible

git clone https://github.com/gen0sec/synapse.git
cd synapse/moat/ansible
cp hosts.example hosts
# Edit hosts and add your server details
ansible-playbook playbook.yml -e gen0sec_api_token=your_key_here

Features: Debian/Ubuntu + RedHat/CentOS/Fedora, optional ClamAV/Redis/Fail2Ban.

Ansible Variables

Variable	Default	Description
synapse_version	latest	Version of Synapse to install
synapse_branch	main	GitHub branch for configuration files
gen0sec_api_token	""	Gen0Sec API token
clamav_enabled	true	Enable ClamAV installation
redis_enabled	true	Enable Redis installation
fail2ban_enabled	false	Enable Fail2Ban integration
synapse_config_mode	"agent"	Operating mode: "agent" or "proxy"

Kubernetes (Helm)

helm repo add gen0sec https://helm.gen0sec.com
helm install synapse-stack

Killercoda Playground

Try Synapse without installing anything:

curl -sSL https://raw.githubusercontent.com/gen0sec/synapse/main/scenarios/synapse-operator/synapse.sh | bash -s -- --api-key <YOUR_API_KEY>

Docker

docker run \
  --cap-add=SYS_ADMIN --cap-add=BPF --cap-add=NET_ADMIN \
  -e API_KEY="your-api-key" \
  -e MODE="proxy" \
  -p 80:80 -p 443:443 \
  synapse -c /etc/synapse/config.yaml

Required Capabilities

Docker containers need SYS_ADMIN, BPF, and NET_ADMIN capabilities for XDP/eBPF support.

Running Synapse

# Run with config file
synapse -c /etc/synapse/config.yaml

# Set mode via environment variable (default: agent)
export MODE="proxy"  # or "agent"

CLI Options

Flag	Description	Default
-c, --config <PATH>	Path to configuration file (YAML)	-
--security-rules-config <PATH>	Security rules file (fallback without API key)	security_rules.yaml
-i, --iface <NAME>	Network interface for XDP	eth0
--ifaces <LIST>	Additional interfaces (comma-separated)	-
--log-level <LEVEL>	Log level (error, warn, info, debug, trace)	info
--disable-xdp	Disable XDP packet filtering	false
--redis-url <URL>	Redis connection URL	redis://127.0.0.1/0
--redis-prefix <PREFIX>	Redis namespace prefix	ax:synapse
--captcha-site-key <KEY>	CAPTCHA site key	-
--captcha-secret-key <KEY>	CAPTCHA secret key	-
--captcha-jwt-secret <KEY>	JWT secret for CAPTCHA tokens	-
--captcha-provider <PROVIDER>	CAPTCHA provider (hcaptcha, recaptcha, turnstile)	-
--captcha-token-ttl <SECS>	CAPTCHA token TTL	7200
--captcha-cache-ttl <SECS>	CAPTCHA cache TTL	300
--proxy-protocol-enabled	Enable PROXY protocol	false
--proxy-protocol-timeout <MS>	PROXY protocol timeout	1000
-d, --daemon	Run as daemon	false
--daemon-pid-file <PATH>	PID file path	/var/run/synapse.pid
--daemon-working-dir <PATH>	Daemon working directory	/
--daemon-stdout <PATH>	Daemon stdout log	/var/log/synapse.out
--daemon-stderr <PATH>	Daemon stderr log	/var/log/synapse.err
--daemon-user <USER>	Run daemon as user	-
--daemon-group <GROUP>	Run daemon as group	-
--clear-certificate <DOMAIN>	Clear certificate from filesystem and Redis	-

System Requirements

Requirement	Minimum	Recommended	Notes
Kernel	4.18+	5.4+	XDP support required
glibc	2.31+	2.35+	For binary releases
Architecture	x86_64	x86_64, aarch64	ARM64 supported
Memory	128 MB	512 MB+	Depends on traffic
Disk	100 MB	500 MB+	For logs and MMDB files

Dependency	Required	Purpose
libbpf	Yes	eBPF program loading
Redis	Yes (Proxy)	Caching, certificate store
ClamAV	Optional	Content scanning

Kernel Feature Requirements

Feature	Required For	Check Command
XDP	Packet filtering	grep XDP /boot/config-$(uname -r)
BPF	eBPF programs	grep BPF /boot/config-$(uname -r)
BTF	BPF Type Format	ls /sys/kernel/btf/vmlinux

Verification

After installation, verify Synapse is running:

# Check service status
sudo systemctl status synapse

# Check logs
sudo journalctl -u synapse -f

Next Steps

• Configuration Reference - Complete configuration options
• Daemon Mode - Run as a background service
• Testing Guide - Validate your installation