Blackhole Docs

Installation

Install on macOS, Windows, Linux, iOS, Android, or Raspberry Pi

Joining the mesh

Register a device and get your 100.64.x.x virtual IP

Connecting two devices

Verify the tunnel is up with ping and MagicDNS

First 5 minutes

End-to-end walkthrough from install to SSH over your mesh

blackhole login

Authenticate via magic link or Google OAuth

blackhole up / down

Start and stop the local agent daemon

blackhole status

Show all peers, virtual IPs, latency, and relay status

blackhole exec

Run a command on any connected device in your mesh

blackhole channel

Create, publish, and subscribe to Agent Bus channels

blackhole acl

Manage access control list rules from the CLI

How WireGuard mesh works

Peer exchange, virtual IPs, direct vs relay paths

MagicDNS

Resolve device hostnames like server.blackhole automatically

NAT traversal

How Blackhole punches through firewalls, CGNAT, and 4G

IP persistence

Your 100.64.x.x address survives reboots and reconnects

What is an exit node?

Route all internet traffic through another device

Enabling exit node mode

Set any Linux device as an exit node with one command

Connecting via exit node

Select an exit node from the CLI or mobile app

Split tunneling

Route only specific subnets through an exit node

Device tags

Label devices: server, mobile, iot, admin

Writing ACL rules

Allow or deny traffic between tags, ports, and protocols

Zero-trust defaults

Understanding the default-deny posture

ACL examples

Common patterns: IoT isolation, admin-only SSH, dev/prod split

Overview

Pub/sub event bus running across your entire mesh

CLI publish & subscribe

blackhole channel publish / subscribe commands

HTTP API

POST /channels/{id}/publish from any process or script

WebSocket streaming

Subscribe to channels in real-time from any language

Hermes bridge

Connect nFlow Hermes agents to Blackhole channels

Running the control plane

Deploy blackhole-server on any VPS or bare metal

PostgreSQL + Redis setup

Database and cache configuration requirements

Environment variables

Full reference for all server configuration options

Docker Compose

One-command self-hosted deployment with Docker

Authentication

Magic link, Google OAuth, and device token flows

Devices API

Register, list, update, and remove devices

Mesh API

Join, get status, list peers, configure exit nodes

Channels API

Create channels, publish events, stream history

ACL API

Manage tags and rules programmatically

Billing API

Checkout, portal, subscription status, webhooks