Quick Start

Enterprise Edition Enterprise

After registering, you will receive a confirmation email from noreply@trapster.cloud (check your spam folder if you don't see any email). Validate your account, reset your password, then log in.

Once logged in:

1. Accept the End User License Agreement (EULA) if prompted
2. Deploy a Trapster : open Trapsters, click the + card, choose your platform in Deploy a new Trapster, then follow the deployment guide:

• Deployment overview : download images and configs from the dashboard
• Proxmox · VMware · Hyper-V · Docker · Kubernetes · Azure

3. Accept registration when the Trapster appears as a pending device in your dashboard
4. Configure networking: the VM uses DHCP by default. To set a static IP, see Network Configuration

See Using the Dashboard for a guided tour of the interface.

Placement advice

Deploy your Trapster VM in segments where attackers are likely to explore: near NAS systems, in the DMZ, or within user VLANs. By default, any interaction triggers an alert.

Community Edition Community

Docker (recommended)

The fastest way to run Trapster Community is with Docker Compose.

Prerequisites: Docker and Docker Compose installed (Get Docker)

git clone https://github.com/0xBallpoint/trapster-community.git
cd trapster-community
docker compose up --build

Trapster starts with the default configuration. To customise services and logging, run the configuration wizard or edit trapster/data/trapster.conf directly.

bash scripts/trapster-wizard.sh
cp trapster.generated.conf trapster/data/trapster.conf
docker compose up --build

The wizard writes ./trapster.generated.conf in the current directory and prints copy/start commands when it finishes.

See Detection Modules for the full configuration reference.

Quick start with AI (HTTP)

Add a .env file for AI responses on the default HTTPS service (port 8081 in the demo config), then restart:

AI_MODEL=o4-mini
AI_BASE_URL=https://api.openai.com/v1/
AI_API_KEY=<YOUR_OPENAI_API_KEY>

docker compose up --build

Other installation methods

• Run as a Python script
• Run as a systemd service

Python

git clone https://github.com/0xBallpoint/trapster-community/
cd trapster-community
python3 -m venv venv
source ./venv/bin/activate
pip install -r requirements.txt
bash scripts/trapster-wizard.sh
python3 main.py -c ./trapster.generated.conf

See Configuration wizard for the full interactive flow (global settings, service catalog, logger).

Or install the package: pip install -e . then trapster -c ./trapster.generated.conf.

Privileged ports

The example config listens on well-known ports. Run as root or use sudo -E python3 main.py (keeps your venv active).

CLI options:

python3 main.py -h
# -i  Show network interfaces
# -c  Specify config file
# -s  Show current config
# -v  Print version

AI support

Install optional AI dependencies:

pip install trapster[ai]
# or from a checkout:
python3 -m pip install ".[ai]"

Copy example.env to .env and configure:

AI_MODEL=
AI_BASE_URL=
AI_API_KEY=
AI_MEMORY_ENABLE=false
# AI_MEMORY_PATH=

AI_MEMORY_ENABLE and AI_MEMORY_PATH optionally persist conversational context between connections from the same client. See example.env for defaults.

Alternatively, set OPENAI_API_KEY alone to use the default o4-mini model:

export OPENAI_API_KEY=... && venv/bin/python3 main.py

SSH AI : add users to an SSH service in trapster.conf to grant an AI-generated shell after login. See SSH honeypot.

HTTP AI : add an ai: prompt on routes in a skin's config.yaml, or use the demo_ai skin. See HTTP Templates.

Systemd Service

Run this script once to install Trapster as a background service that starts on boot:

# Install in /opt/
git clone https://github.com/0xBallpoint/trapster-community/ /opt/trapster-community
cd /opt/trapster-community
python3 -m venv venv
source venv/bin/activate
python3 -m pip install .

# Config directory
mkdir /etc/trapster-community/
cp /opt/trapster-community/trapster/data/trapster.conf /etc/trapster-community/

# Create systemd unit
cat > /etc/systemd/system/trapster-community.service <<'EOF'
[Unit]
Description=Trapster Community
After=network-online.target

[Service]
Type=simple
ExecStart=/opt/trapster-community/venv/bin/python3 /opt/trapster-community/main.py -c /etc/trapster-community/trapster.conf
Restart=always
RestartSec=20
StandardOutput=append:/var/log/trapster.log
StandardError=append:/var/log/trapster.log

[Install]
WantedBy=multi-user.target
EOF

service trapster-community start
service trapster-community status

Manage the service:

service trapster-community start
service trapster-community stop
service trapster-community status