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/tcp/7777/p2p/12D3KooW..."

Missing or invalid keys are surfaced loudly at startup — the daemon refuses to boot rather than silently downgrade.

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

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 plain TCP listener is on by default. REALITY and SSH masquerades are opt-in.

Inbound and outbound are independent: a peer reaches you via any listener you turn on, and your own outbound dialer walks node.obfs.order in sequence to pick a transport per peer.

node.relay — libp2p Circuit Relay v2 / AutoNAT

Defaults match the "client behind home NAT" profile. Public-reachable nodes flip serve (and usually nat_service) on.

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 relying on a public relay. At startup the daemon SSDPs the LAN for an Internet Gateway Device, maps each libp2p listen port, and injects /ip4/<wan>/tcp/<port> into the multiaddrs Identify advertises to peers. 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 suppresses the external-multiaddr announcement 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.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 but does not add it to the video or audio groups. Out of the box the daemon will get EACCES opening /dev/video0. Run once, then restart the service:

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, libp2p identity, networks store). The zero value (enabled: false) is the safe default for headless installs without a platform keystore.

passphrase_file always wins when set, so you can opt out of the platform keystore on a desktop install if you'd rather feed the secret yourself. Failure to obtain a key with enabled: true is a hard startup error — the daemon never silently downgrades to plaintext storage.

Mobile / desktop builds flip enabled: true and rely on the platform keystore (Keychain / Credential Manager / libsecret).

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> (and GET for trigger-style integrations). The URL token is the only credential.

Bodies are parsed as Slack-shape JSON, application/x-www-form-urlencoded with payload=<json>, or text/plain. There is no rate-limit and no 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 style TCP/UDP forwards routed over the libp2p tunnel mesh. Inherits multi-hop routing and libp2p Circuit Relay v2.

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.

telemetry

Anonymous, low-volume usage reporting. Enabled by default — collects a once-a-day beat containing your country, a hash of your swarm key, and counters for vault/chat/call/tunnel usage. The full field list and the rationale live in privacy-telemetry; this section only covers the YAML knobs.

The two convenience CLI commands meshhold telemetry enable / meshhold telemetry disable rewrite this block in place; calling them is equivalent to setting enabled by hand and saves you the file edit.

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:
  enabled: true

After enabling, create or join a network with a meshlan management key — 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) and Android (VpnService); a Linux node has no daemon-owned exit TUN yet (it's 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/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

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):

swarm_key: "/key/swarm/psk/1.0.0/\n/base16/\n<hex...>"
bootstrap_peers: []  # this IS the bootstrap

node:
  name: "exit-fra-01"
  listen_addr: "0.0.0.0:7777"
  reliable: true
  public_address: "exit.example.org:7777"
  relay:
    serve: true
  s3:
    enabled: true
    listen_addr: "127.0.0.1:3900"
    base_domain: "s3.example.org"
  enrich:
    music:
      enabled: true
      acoustid_api_key: "..."
    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: "home-tunnel"

Reloading

Most fields require a daemon restart. The exceptions are managed through the REST surface and intentionally not in config.yaml:

• 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.
• TMDB API key, when set via the Web UI Settings page, lives in the catalog settings keystore and overrides node.enrich.video.tmdb_api_key.

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