Configuration reference

Every key in config.yaml — types, defaults, validation rules.

MeshHold reads a single YAML file at startup. On Linux the default location is ~/.meshhold/config.yaml; on Windows the per-user installer puts it under %LOCALAPPDATA%\MeshHold\config.yaml. Pass --config /path/to/file.yaml to override.

A minimal config is short — only swarm_key and bootstrap_peers are usually hand-written, everything else has a sensible default:

swarm_key: "/key/swarm/psk/1.0.0/\n/base16/\n<hex...>"
bootstrap_peers:
  - "/ip4/198.51.100.10/udp/7777/quic-v1/p2p/12D3KooW..."
  - "/ip4/198.51.100.10/tcp/7778/p2p/12D3KooW..."

An invalid value is surfaced loudly at startup — the daemon refuses to boot rather than silently downgrade. An unrecognised key is not: it parses, applies nothing, and stays quiet, because failing on one would break every node carrying a key from a different build. Run meshhold config lint to find those, along with any secret still written into this file:

meshhold config lint

Keeping secrets out of this file

Every secret below can come from three places, and resolves in this order:

1. the environment variable, where one exists — MESHHOLD_SWARM_KEY, MESHHOLD_TMDB_API_KEY, MESHHOLD_ACOUSTID_API_KEY
2. a *_file path — swarm_key_file, vaults[].key_file, webhooks[].token_file, node.enrich.*.­*_api_key_file. This is what systemd's LoadCredential=, Docker secrets and Vault's file sink produce.
3. the inline value — still supported, and reported by config lint

Env before file before inline is deliberate: the further down that list, the more copies a secret leaves behind, so the tightest form available wins.

A *_file that is set but unreadable is a startup error, not a fallback to the inline value — otherwise a node could run on a credential you believe you replaced.

On Git Bash / MSYS, a value starting with / (the three-line /key/swarm/psk/1.0.0/ form) gets path-translated when passed as an environment variable. Use the 64-character hex form, or a *_file.

The diagram is a "you are here" key for the tables below — each branch maps to one of the sections on this page.

config.yaml vs the runtime store

The daemon does not write this file. It is yours: template it with Ansible, keep it in git, diff it. There is exactly one exception, and it is structural — meshhold at-rest enable/disable and the Settings → Security button edit at_rest_encryption, because that key decides whether the database can be opened and therefore cannot live inside it.

config.yaml holds static infrastructure: where state lives (node.metadata_dir, node.blocks_dir), how the daemon binds and serves (api, node.listen_addr, TLS, node.obfs) — settings that must exist before, and independently of, the daemon's database.

Runtime state — the saved networks and which one is active, management keys, the node's display name, vaults — lives in the daemon's database (<metadata_dir>/networks.json for networks) and is changed through the Web UI / CLI, not by editing this file.

Blocks that are a seed, not the source of truth

Some blocks are both: what a fresh node deploys with, and something the Web UI can change afterwards. For those, the runtime store wins once it holds anything, and this file answers only until then:

Editing one of these here after the UI has touched it has no effect — same rule swarm_key follows once networks.json exists. A stored empty list means empty, not "fall back to the file": unmounting everything survives a restart.

Split-tunnel routes (vpn.local_routes) and exit-policy rules (vpn.exit_policy) work differently — those merge with their runtime counterparts rather than being replaced, and the UI badges the rows that came from here as config and gives them no delete action.

In particular, network membership is owned by networks.json. The swarm_key + bootstrap_peers below are a one-time seed for a brand-new node (empty store): on first boot they become the node's first saved network. Once the node has any saved network, the store — including its persisted active network — is the single source of truth, and editing swarm_key here afterwards is ignored (it can no longer resurrect or switch networks). Create / join / switch networks with meshhold networks … or the Web UI; the setup wizard appears only on a genuinely fresh node (no saved network and no config swarm key).

Top-level keys

node

<base> is ~/.meshhold/ on Linux, %LOCALAPPDATA%\MeshHold\ on Windows. Inside the official Docker image the daemon runs from WORKDIR /var/lib/meshhold as uid 65532, so <base> is that directory and the equivalent defaults become /var/lib/meshhold/blocks and /var/lib/meshhold/meta. Mount a host path or named volume there to persist state across container restarts.

Running in Docker

The image is gcr.io/distroless/static-debian12:nonroot underneath, so there is no shell, no package manager, and no system service manager inside the container — just the meshhold daemon process holding pid 1. A few container-only knobs that don't apply to the .deb / .rpm install:

The image does not include the systemd unit, the meshhold system user, or the postinstall password-bootstrap script — those are owned by the .deb / .rpm packagers. Inside Docker, the container runtime is your service manager, the named-volume + uid mapping is your file-system permission model, and the MESHHOLD_PASSWORD env is your auth bootstrap.

node.obfs — masquerade transports

The transport with no disguise (meshlink) always listens, on the ports listen_addr and link_tcp_port name; nothing under node.obfs.meshlink changes that. REALITY and SSH masquerades are opt-in. node.obfs.meshlink was called node.obfs.plain until 2026-09-14, and meshhold config lint says when a file still uses the old name.

Inbound and outbound are independent: a peer reaches you via any listener you turn on, and your node can dial every transport whether or not it listens on one — it tries meshlink first, then the masquerades a peer advertises, and keeps the first that answers.

node.relay — removed

serve, nat_service and auto_dial configured libp2p's Circuit Relay v2, AutoNAT and AutoRelay. All three are gone and these keys do nothing. They still parse, so an existing config file keeps loading, and the daemon logs one warning at startup if any of them is set. A config rewritten by the daemon comes back without them.

There is no replacement key, because there is no longer a choice to make. Relaying for a neighbour is what a route is — a node on a path forwards for it, and nothing has to be volunteered or reserved. Reachability for a NAT'd node is announced in the topology beat rather than held as a slot on somebody else.

They were removed after being measured: with all three switched off on every node of a two-NAT test stand, every behaviour was unchanged, including the case where a hole punch cannot work and the traffic has to be relayed. A relay reservation was never once made, because libp2p only reserves after AutoNAT reports the node unreachable, and AutoNAT needs four independent peers to observe an address before it will believe one — a number a small private mesh does not have.

node.upnp — automatic IGD port mapping

UPnP IGD (and the legacy NAT-PMP fallback) lets the daemon install port mappings on the LAN router so peers can dial this node directly instead of being relayed by another node. At startup the daemon SSDPs the LAN for an Internet Gateway Device and maps every port its transports listen on — meshlink's QUIC (UDP) and TCP ports, and any masquerade's — keeping each port number, then advertises the router's WAN address to peers as one of this node's hosts. It renews the leases, re-installs whatever the router drops, and re-announces when the WAN address changes. Per-forward mappings are also driven through this subsystem when an entry has open_via_upnp: true.

CGNAT-aware: the router-reported WAN IP is compared against /api/ipinfo (see node.ipinfo). When they disagree, the daemon keeps the LAN-side mapping (it can still help mesh peers behind the same NAT) but does not announce the WAN address, to avoid sending peers a dead-end IP.

node.ipinfo — external IP + country lookup

At startup (and after any UPnP remap) the daemon does a single GET /api/ipinfo against the MeshHold marketing site to learn its own public IP + country code. The values populate the topology gossip beat (so peers see the IP / flag on their Network page) and gate the CGNAT comparison described above. Operators in air-gapped environments turn this off; everyone else can leave it alone.

node.s3 — S3-compatible listener

Disabled by default. Even when enabled, the admin REST surface (/api/v1/s3/keys, /api/v1/s3/permissions) is available so keys can be pre-provisioned.

node.share — public share links

Disabled by default, and the only listener meant to be reached by people with no credentials — so the defaults lean the other way: off, loopback, and a short link lifetime that has to be overridden deliberately. See Public links.

node.call_media — headless camera/mic

For Raspberry-Pi-class nodes that auto-answer calls and stream from v4l2 + ALSA.

Auto-answer

node.call_media.auto_answer is the fallback default for the auto-answer master switch, not its runtime home — that's a Badger override the Web UI toggle writes, read live by the daemon on every inbound call, exactly like node.reliable sits beneath the node_reliable runtime override (see Reloading). Resolution: the override wins when present; absent, this config value applies; unset here too → off. Toggling it in the UI does not rewrite config.yaml — it writes the override, which then wins until cleared. You set it from config purely to provision a headless node that never opens the Web UI; everywhere else just use the toggle (or PUT /api/v1/settings {"auto_answer": true}).

When on, the daemon accepts an incoming audio/video call automatically — camera + mic enabled — but only when the caller proves possession of one of this node's self management keys that grants the camera capability (an HMAC over the call invite). The HMAC is the real authorisation; auto_answer only opens the gate. Setting it without also issuing a camera-capability mgmt key to the caller does nothing — see step 5 of the walkthrough below for the full checklist.

node:
  call_media:
    auto_answer: true   # headless default: accept HMAC-authenticated calls

Linux setup walkthrough

Headless capture is Linux-only — the daemon shells out to ffmpeg and talks to the kernel's v4l2 + ALSA subsystems directly. A working config has four moving parts: ffmpeg on PATH, real device nodes under /dev, the meshhold user in the right groups, and the companion profile/mgmt-key flags that actually let a peer reach the camera.

1. Install ffmpeg with the right encoders. The daemon hard-codes the encoding pipeline (audio: Opus 32 kbps mono in Ogg; video: libvpx-vp9 1.5 Mbps in IVF, 1280×720 @ 30 fps, keyframe every 2 s). The ffmpeg binary on PATH must therefore be built with --enable-libopus, --enable-libvpx, --enable-libv4l2, and --enable-indev=alsa. The distro packages on Debian / Ubuntu / Raspberry Pi OS (apt install ffmpeg) and on RHEL / Fedora (dnf install ffmpeg, from RPM Fusion) cover all four. There is no ffmpeg_path knob — symlink or wrap your binary if it lives outside PATH.

2. Discover the device nodes. Plug the camera/USB-capture in, then:

# list video capture devices and the /dev/videoN node each exposes
v4l2-ctl --list-devices

# list ALSA capture (microphone) devices and their hw:CARD,DEV names
arecord -L

USB Video Class cameras almost always expose two /dev/videoN nodes — one for capture, one for metadata. v4l2-ctl --list-formats-ext -d /dev/videoN is the quickest way to confirm which one delivers 1280×720 at 30 fps in a pixel format ffmpeg can ingest (YUYV, MJPG, or NV12). Cameras that only offer e.g. 1920×1080 will make ffmpeg exit on the first frame — adjust the camera, not the config.

3. Grant the daemon access to /dev. The .deb / .rpm postinstall creates a meshhold system user and adds it to the video and audio groups (where those groups exist). A daemon running as any other user gets EACCES opening /dev/video0 until that user is in both groups — the same two commands, with its name:

sudo usermod -aG video,audio meshhold
sudo systemctl restart meshhold

The Docker image runs as uid 65532 (nonroot); pass the host device through with --device /dev/video0 --device /dev/snd and add --group-add video --group-add audio (or --group-add with the numeric GID of those groups on the host) so the container user can read them.

4. Wire the YAML. Two-camera, with-mic example:

node:
  call_media:
    enabled: true
    video_devices:
      - "/dev/video0"   # used at call start; SPECIFIC matches by path
      - "/dev/video2"
    audio_device: "default"   # or "hw:1,0" to pin a specific USB mic

audio_device is forwarded verbatim to ffmpeg -f alsa -i <value> — anything arecord -L prints is valid. Leave it empty for a video-only privacy build (e.g. a doorbell with no microphone). At least one of the two fields must be non-empty when enabled: true, otherwise the daemon logs a warning at startup and falls back to disabled.

5. Make the camera actually reachable. YAML on its own only spawns the local pipeline; two other knobs decide whether any peer can use it:

• Auto-answer must be on. Flip the toggle in the Profile page in the Web UI, or PUT /api/v1/settings { "auto_answer": true }, or — on a headless box with no browser — set the fallback default node.call_media.auto_answer: true in config (see the Auto-answer note above). Without it the daemon rings instead of accepting the call, and a headless box has nothing to answer the ring with.
• A management key with the camera capability has to be issued to the calling device (meshhold mgmt-keys add --caps camera, or the Mgmt Keys panel in the Web UI). The HMAC proof on the call invite is the sole authorisation; if no active self-key carries CapCamera, auto-answer is disabled regardless of the other flags.
• On Linux the allow_calls profile flag defaults to false, so peers' Network pages hide the call buttons to this node. Flip it on in the Profile page once the headless pipeline is wired, otherwise the only way to dial in is POST /api/v1/calls.

node.enrich — metadata enrichment

Disabled by default — operators turn this on for one node per LAN so AcoustID / TMDB lookups don't get duplicated.

node.enrich.music

node.enrich.video

api

Leave all three TLS fields empty to fall back to a self-signed certificate generated on first run.

chat

at_rest_encryption

Master-key sourcing for the daemon's at-rest encryption layer (Badger, the node's identity key, networks store — which is where the swarm key lives).

Leaving enabled unset means encrypt — but what that implies depends on what the node already has on disk:

An existing node is not migrated automatically because migrating takes it offline for the duration and commits it to a key store that has to keep working afterwards. Convert it with meshhold at-rest enable (or Settings → Security) and a restart; see at-rest.

An explicit enabled: true or enabled: false overrides all of that, for both kinds of node.

The master key comes from the first source available, in this order:

1. passphrase_file, when set — always wins, so you can opt out of the platform keystore anywhere and feed the secret yourself from systemd-creds, Vault, or a Kubernetes secret mount.
2. The platform keystore: DPAPI (Windows, user scope), Keychain (macOS), Secret Service (Linux desktop), Android Keystore (Android).
3. A host-bound key file (Linux only), when no Secret Service is reachable — see below.

Failure to obtain a key with enabled: true is a hard startup error — the daemon never silently downgrades to plaintext storage.

Headless Linux

Secret Service needs a session D-Bus, which a VPS reached over SSH, a systemd unit and a container all lack. On those hosts the daemon falls back to a host-bound key file at <metadata_dir>/master.key.host: the master key is stored wrapped, under material derived from the host's /etc/machine-id.

Because the machine-id lives outside the metadata dir, a copy of the data volume on its own — a backup, an rsync of the state directory, a detached cloud disk — cannot unwrap it. It does not protect against local root or a full disk image, which get both halves; for that, point passphrase_file at a secret you manage, or rely on LUKS.

If the machine-id changes, the key cannot be unwrapped and the daemon refuses to start rather than mint a new one over an encrypted database. Two consequences worth planning for:

• Containers: mount a stable /etc/machine-id, or use passphrase_file. An image with a per-build machine-id will strand the volume on the first container recreation.
• Re-imaging: restore /etc/machine-id along with the data directory, or run meshhold at-rest disable on the old host first.

Turning this on is close to a one-way door by design: once the state is encrypted, a daemon that cannot obtain the master key refuses to start rather than overwrite it. meshhold at-rest disable --yes is the supported way back, and it needs the master key to work — so it can rescue a node whose config is wrong, not one whose key is genuinely lost. Keep whatever the key derives from (the keyring entry, the passphrase file, /etc/machine-id) backed up alongside the data.

vaults

A list of trusted vaults — the node holds the symmetric key for each entry and decrypts file metadata locally.

webhooks

Inbound webhooks accepted on POST /api/v1/hooks/<token>; an empty body is a plain trigger (curl -X POST). GET triggers nothing and answers 405. The URL token is the only credential, and the access log records the path with it redacted.

Bodies are parsed as Slack-shape JSON, application/x-www-form-urlencoded with payload=<json>, or text/plain. Each hook takes a burst of 10 requests, then one every 2 seconds; past that it answers 429 with Retry-After. Ten wrong tokens from one client address (as api.trusted_proxies resolves it) within ten minutes turn that address away from every hook, 429, for 30 minutes. There is no separate loopback bind — operators put a reverse proxy in front when needed.

outbound_webhooks

Outbound HTTP delivery of mesh events. Bodies are unsigned JSON; operators who want auth put the receiver behind a reverse proxy.

Known event names: file.added, file.updated, file.deleted, chat.message, peer.connected, peer.disconnected, tunnel.opened, tunnel.closed, replication.lag, forward.opened, forward.closed.

The retry schedule is 5s → 30s → 5min → 30min, then capped.

port_forwards

ssh -L / ssh -R / ssh -D style forwards routed over the mesh's tunnels. Inherits multi-hop routing, and relaying by a node on the route when the two ends cannot reach each other directly.

forward and reverse differ only in which side of the tunnel binds the listener and which side dials the actual destination. The two examples below at the bottom of this page show one of each. dynamic is the third shape: this node binds a SOCKS5 listener and each client names its own destination, which the peer dials — so there is no remote_addr at all.

meshlan

The mesh-LAN overlay: a routable virtual network where every member reaches another member's local services by a stable virtual IP. Off by default. Membership and the per-node port ACL live on the meshlan management keys, so this block only turns the overlay on and picks the IPv4 space.

meshlan:
  # No config needed to join: the overlay auto-starts once this node holds
  # a meshlan management key. Set ipv4_range only to move off the default.
  # ipv4_range: 10.0.0.0/8

Create or join a network with a meshlan management key and the overlay comes up automatically — see the Flat Mesh LAN walkthrough.

vpn

The system exit-VPN's routing model — exit selection, boot auto-start, the configurable split-tunnel exclusions, and per-destination multi-exit policy. See Exit routing for the concepts. The route-install layer runs on Windows (vpnhelper), Linux (/dev/net/tun), and Android (VpnService); macOS isn't a client yet (still a fine exit node). The Exit nodes section and the meshhold vpn CLI write this block.

vpn:
  enabled: true
  exit_node_id: "12D3KooW…HOME"
  peer_key_id: "home-tunnel"
  fail_mode: direct          # fail-open if the exit drops (Windows/Linux/Android)
  default_route: exit        # full tunnel; rules below override per-destination
  local_routes:
    - 192.168.50.0/24        # lab subnet stays local
  exit_policy:
    - name: "EU sites via Frankfurt"
      prefixes: ["203.0.113.0/24"]
      exit_node_id: "12D3KooW…FRA"
      peer_key_id: "fra-tunnel"
  qos:
    enabled: true
    uplink_kbits: 18000        # ~90% of a 20-megabit uplink
    downlink_kbits: 95000      # shaped at the exit
    default_class: 1
    classes:
      - name: interactive      # DNS, VoIP, gaming — highest priority
      - name: bulk             # everything else
        max_percent: 50        # cap bulk at half the link
        demote_after_kb: 4096  # a flow that moves >4 MiB drops to bulk
    rules:
      - proto: udp
        dport_lo: 53
        dport_hi: 53
        class: 0               # DNS -> interactive
        direction: both

tunnel

Tunnel egress settings. Today this carries only tunnel.adblock — the seed for the ad blocker: a domain blocklist merged from configurable sources and enforced on the in-app tunnel browser (CONNECT proxy) and/or the system VPN. On the VPN it's applied by the in-mesh resolver, which is the system DNS while the VPN is up — so blocked names get NXDOMAIN'd for every app on the device, not just tunnelled traffic. This block is the headless default; once the Settings dialog or meshhold adblock saves an override it lives in the runtime catalog store and wins over this seed.

A node with no tunnel.adblock block uses the built-in defaults (the embedded list + the StevenBlack adware+malware list + HaGeZi Pro enabled; fake-news, gambling, porn and social listed but off), applied to both targets. HaGeZi Pro is a broad hosts aggregate that adds video-ad and CIS/RU network coverage StevenBlack lacks; overlapping domains dedupe into the shared blocklist at no extra cost.

tunnel:
  adblock:
    js_blocking: true
    apply_browser: true
    apply_tunnels: true
    sources:
      - name: MeshHold built-in list
        url: builtin:meshhold
        enabled: true
      - name: Ads & malware — StevenBlack
        url: https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
        enabled: true
      - name: Ads, trackers & video-ad networks — HaGeZi Pro
        url: https://raw.githubusercontent.com/hagezi/dns-blocklists/main/hosts/pro.txt
        enabled: true
      - name: Gambling & casinos — StevenBlack
        url: https://raw.githubusercontent.com/StevenBlack/hosts/master/alternates/gambling/hosts
        enabled: false

Remote lists are downloaded directly (not through the tunnel), cached under the metadata dir, and refreshed periodically. DNS sinkholing only covers plain UDP/53 queries — clients using DoH/DoT bypass it.

Example: VPS exit node

A public-reachable VPS that serves as a relay and exposes the S3 listener over loopback (for a local Caddy reverse proxy):

# The key lives in a file systemd hands the unit, not in this config:
#   LoadCredential=swarm:/etc/meshhold/swarm.key
swarm_key_file: "/run/credentials/meshhold.service/swarm"
bootstrap_peers: []  # this IS the bootstrap

node:
  name: "exit-fra-01"
  listen_addr: "0.0.0.0:7777"     # QUIC on UDP 7777; the TCP leg takes 7778
  reliable: true
  public_address: "203.0.113.7"   # an IP; each transport adds its own port
  s3:
    enabled: true
    listen_addr: "127.0.0.1:3900"
    base_domain: "s3.example.org"
  enrich:
    music:
      enabled: true
      acoustid_api_key_file: "/run/credentials/meshhold.service/acoustid"
    video:
      enabled: true
      tmdb_api_key: "..."

api:
  listen_addr: "0.0.0.0:8080"
  tls:
    acme_domain: "node.example.org"

chat:
  retention_days: 90

outbound_webhooks:
  - name: "ops-slack"
    url: "https://hooks.slack.com/services/..."
    events: ["replication.lag", "peer.disconnected"]

Example: home gateway with port forwards

Expose a LAN game server to the Internet through a VPS peer:

port_forwards:
  - name: "zomboid-public"
    direction: "reverse"
    proto: "tcp"
    listen_addr: "0.0.0.0:16261"   # VPS-side bind
    remote_addr: "192.168.1.50:16261"  # LAN server
    peer_node_id: "12D3KooW..."
    peer_key_id: "vps-tunnel"
    # Ask the VPS's host network to expose the port through UPnP
    # too. On a cloud VM this is usually a no-op (no IGD), but
    # on a colo / bare-metal exit it can save a manual port-forward
    # configuration step.
    open_via_upnp: true

  - name: "openvpn-into-home"
    direction: "forward"
    proto: "udp"
    listen_addr: "127.0.0.1:1194"      # local bind
    remote_addr: "192.168.1.1:1194"    # remote LAN OpenVPN
    peer_node_id: "12D3KooW..."
    # peer_key_id is optional — the node id above finds the key. Name
    # one only when you hold several different keys for that node.

  - name: "socks-via-vps"
    direction: "dynamic"               # ssh -D: a local SOCKS5 proxy
    listen_addr: "0.0.0.0:3388"        # reachable from the LAN, hence the credentials
    peer_node_id: "12D3KooW..."        # every client names its own destination,
                                       # so there is no remote_addr at all
    socks_username: "alice"
    socks_password: "s3cret"

Reloading

Most fields require a daemon restart. Two sets do not:

Never in this file at all — runtime state, changed through the REST surface:

• Vault membership: POST /api/v1/vaults writes to Badger, not the YAML.
• Management keys: meshhold mgmt-keys / MgmtKeysPanel in the Web UI.
• S3 access keys + per-bucket permissions: /api/v1/s3/keys, /api/v1/s3/permissions.

Seeded here, then owned by the store — see blocks that are a seed. Changing one of these through the UI or CLI takes effect without a restart and does not touch this file; editing it here afterwards has no effect.

When in doubt, edit config.yaml, run meshhold config lint to catch typos and misplaced secrets, then systemctl restart meshhold (or the equivalent on your platform).