Installation

Full install walkthrough. For the two-minute version see Quick Start. For interpreter support see Requirements and Python Versions.

OS prerequisites

DECNET is Linux-only. It talks directly to the kernel for MACVLAN / IPvlan setup and to the Docker daemon for container orchestration.

Requirement	Why
Linux kernel with MACVLAN or IPvlan	Each decky gets its own MAC (MACVLAN) or unique IP on the shared host MAC (IPvlan).
Docker Engine 24+	Compose v2 plugin, BuildKit, MACVLAN driver stability.
`iproute2` (`ip` command)	Used for interface/subnet detection and hairpin interface creation.
Root / `sudo`	Required for MACVLAN/IPvlan network creation and sysctl injection.
NIC in promiscuous mode or `--ipvlan` on WiFi	MACVLAN needs the NIC to accept frames for MACs it does not own; WiFi upstreams typically filter those, so IPvlan L2 is used instead.

WSL has MACVLAN limitations. Use bare metal or a VM for honest testing.

Python virtualenv (recommended)

Always install into a virtualenv. ANTI's house rule: activate .venv before every pip / pytest call in this project.

cd DECNET
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

Install DECNET

Editable install is the supported path — the CLI is under active development and -e keeps it tracking your checkout.

pip install -e .

This installs the decnet console script (a Typer app at decnet/cli.py) plus the FastAPI dashboard under decnet/web/.

Optional extras

DECNET ships several optional feature groups. Install only what you need.

pip install -e ".[tracing]"      # OpenTelemetry exporters for the ingest pipeline
pip install -e ".[profiling]"    # py-spy / scalene hooks for the web API
pip install -e ".[dev]"          # pytest, ruff, mypy

If an extra is not declared in pyproject.toml, pip will error out — check decnet services and the Development and Testing page for the current set.

Verifying the install

decnet --help
decnet services
decnet archetypes
decnet distros

decnet --help should list the top-level commands: deploy, status, teardown, services, archetypes, distros, correlate, web, api.
decnet services should print 25 service rows.

Dry-run a deploy to confirm end-to-end wiring without touching the network:

decnet deploy --mode unihost --deckies 2 --randomize-services --dry-run

Run the test suite (if you installed the dev extra):

python -m pytest

Configuration

Runtime configuration can live in .env.local (preferred) or .env at the project root. Copy .env.example and edit:

cp .env.example .env.local

Details in Environment Variables.

Uninstall

pip uninstall decnet
sudo decnet teardown --all      # before uninstalling, remove any live deckies

If teardown is unavailable (e.g. the package is already gone), remove the MACVLAN network manually:

docker network ls | grep decnet
docker network rm decnet_macvlan
ip link del decnet_macvlan0 2>/dev/null || true

DECNET

Home

User docs

Developer docs

Project meta

DECNET — honeypot deception-network framework. Pre-1.0, active development — use with caution. See Sponsors to support the project. Contact: samuel@securejump.cl