Connect a home with the connector
ingressd-connector is a small program that links your home to all of your nodes over WireGuard. It runs on Linux, macOS, Windows or Docker and needs no port forwarding and no router changes.
At least one node is installed and connected. The connector's machine must be able to reach the services you want to publish, such as 192.168.1.20:8096.
1. Create the home#
In the panel, open Homes, choose Add home and pick Connector. The panel attaches the home to all of your nodes and shows a one-line install command with a join string. The join string carries the node's URL and a one-time token.
2. Install and enrol#
$ curl -fsSL https://app.ingressd.com/install/connector.sh | sudo sh -s -- <join-string>
What the installer does depends on the platform:
| Platform | Result |
|---|---|
| Linux with systemd, as root | Binary in /usr/local/bin, state file, systemd service. |
Linux with Docker (--docker) |
A container with host networking, so LAN discovery sees your subnets. |
| macOS, as root | Binary in /usr/local/bin and a launchd daemon. |
| Anything else | Binary in ~/.local/bin, and the commands to run it. |
On Windows, download ingressd-connector_windows_amd64.exe and run it from an administrator prompt:
$ ingressd-connector enroll <join-string> $ ingressd-connector install-service
The connector generates its WireGuard key on your machine; the private key never leaves it. After enrolling with one node it learns about the home's other nodes and opens a tunnel to each, re-checking the list every 60 seconds.
3. Check it#
$ ingressd-connector status
status shows each node's tunnel, the transport in use and the last handshake. In the panel the home shows one line per node.
Modes#
| Mode | Default when | How it works |
|---|---|---|
tun |
Linux, as root | A real WireGuard interface. Replies are routed; transparent game-server mode needs it. |
netstack |
Everything else, and Docker | WireGuard in user space. No root and no capabilities needed. |
Pick one with --mode tun or --mode netstack on the installer or on enroll.
When UDP is blocked#
If a network blocks outbound UDP, the connector falls back to WireGuard over a WebSocket on port 443 of the node, and keeps retrying UDP in the background. --udp-timeout and --udp-retry on ingressd-connector run change how quickly it falls back and retries.
LAN discovery#
When you add an app, the panel can ask the connector to scan your LAN for web services and suggest origins. Turn this off with --no-discovery when you enrol (it is remembered) or on run.
Installer options#
| Option | Meaning |
|---|---|
--docker |
Install as a Docker container. |
--mode tun|netstack |
Tunnel mode (default: tun as root on Linux, else netstack). |
--edge-addr IP |
Dial this address instead of resolving the node's hostname. |
--no-discovery |
Never scan the LAN for services. |
--no-service |
Install and enrol, but don't install or start a service. |
--reenroll |
Enrol again even if this machine is already enrolled. |
Running the installer again upgrades the connector in place without enrolling again.
Next: publish a web app.