Deployment Modes: UNIHOST and SWARM

DECNET's deploy command takes a --mode flag that selects how the fleet of deckies is laid out across real hardware. Two modes are defined:

unihost — a single real host runs all deckies as containers.
swarm — multiple real hosts each run a subset of deckies (multi-host).

The mode is validated in decnet/cli.py (deploy --mode) and stored on the DecnetConfig object consumed by decnet/engine/deployer.py. The orchestrator in decnet/composer.py emits the Docker Compose file used by either mode.

When to use which

Criterion	UNIHOST	SWARM
Hosts involved	1	N
Setup complexity	low	higher (needs fleet orchestration)
Deckies per host	all of them	split across hosts
Fits home lab / single server	yes	overkill
Fits multi-subnet / multi-site	no	yes
Failure blast radius	whole fleet on one box	isolated per host
Recommended for first runs	yes	no

UNIHOST is the default (--mode unihost) and what the README's quickstart assumes. SWARM is the deployment posture for a real honeynet spanning multiple boxes.

UNIHOST

                 attacker LAN 192.168.1.0/24
  +---------------------------------------------------+
  |                                                   |
  | [host]  eth0   decnet_lan (MACVLAN / IPvlan L2)   |
  |   |- decky-01 .10                                 |
  |   |- decky-02 .11                                 |
  |   |- decky-03 .12                                 |
  |   |- decky-04 .13                                 |
  |   '- decky-05 .14                                 |
  +---------------------------------------------------+
                         |
              (isolated mgmt path)
                         v
                logging / SIEM network

One host, one MACVLAN or IPvlan L2 network, N deckies. The host also runs the collector/API and forwards logs out-of-band to the isolated logging network.

CLI

# Dry-run: generate compose, no containers
decnet deploy --mode unihost --deckies 3 --randomize-services --dry-run

# Full deploy (root required for MACVLAN)
sudo decnet deploy \
     --mode unihost \
     --deckies 5 \
     --interface eth0 \
     --randomize-services

Flags worth knowing (full table in CLI reference):

--deckies / -n — number of deckies on this host.
--interface / -i — parent NIC. Auto-detected via detect_interface().
--ipvlan — switch to IPvlan L2. Required on WiFi.
--services, --randomize-services, --archetype — service selection.
--distro, --randomize-distros — OS heterogeneity.
--mutate-interval — rotate services every N minutes.
--dry-run — write the compose file under deploy/ without starting.

INI

The same deployment can be expressed declaratively via --config:

decnet deploy --mode unihost --config ./my-fleet.ini

See INI format for the full schema; cli.py's config path calls load_ini and build_deckies_from_ini.

SWARM (multihost)

           attacker network(s)
     ------------------------------
       |              |          |
   [host-A]       [host-B]   [host-C]
    decky-01       decky-04   decky-07
    decky-02       decky-05   decky-08
    decky-03       decky-06   decky-09

     \__________________|__________________/
                        |
               isolated mgmt / SIEM
                        |
                 [master] — swarmctl, listener, ingester, CA

SWARM has a dedicated page: SWARM Mode. That page is the authoritative reference for setup, enrollment, the log pipeline, and troubleshooting.

In brief: DECNET ships a master (decnet swarmctl + decnet listener) that orchestrates workers (decnet agent + decnet forwarder) over HTTP+mTLS on port 8770/8765 and syslog-over-TLS (RFC 5425) on port 6514. A self-managed CA at ~/.decnet/ca/ signs every worker cert at enrollment.

Typical first-time flow:

# On the master:
decnet swarmctl --daemon
decnet listener --daemon
decnet swarm enroll --name decky-vm --address 192.168.1.13 \
     --out-dir /tmp/decky-vm-bundle

# Ship the bundle to the worker, then on the worker:
sudo decnet agent --daemon --agent-dir ~/.decnet/agent
decnet forwarder --daemon --master-host <master-ip>

# Back on the master:
decnet swarm check
decnet swarm list
decnet deploy --mode swarm --deckies 6 --services ssh,smb

deploy --mode swarm round-robins deckies across all enrolled workers, shards the compose config, and dispatches each shard to the matching agent. See SWARM Mode for the full walkthrough, command reference, security posture, and troubleshooting matrix.

What is common to both modes

Compose generation in decnet/composer.py is mode-agnostic; the mode field is recorded on DecnetConfig for state/telemetry but the compose shape (base container + service containers sharing its network namespace via network_mode: service:<base>) is identical.
Network driver selection (MACVLAN vs IPvlan L2) is per-host, controlled by --ipvlan. See Networking: MACVLAN and IPvlan.
Teardown is per-host: run sudo decnet teardown --all on each host in the swarm. See Teardown.

Quick checklist

Single box, one LAN -> UNIHOST.
Multiple boxes across one or more LANs -> SWARM, driven by external orchestration, with non-overlapping --ip-start per host.
Not sure -> start with UNIHOST and a small --deckies count.

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