Connect an origin with the connector
ingressd-connector is a small program that links your origin 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 origin#
An origin is the network your services run on: a home lab, an office or a rack in a datacentre. Run the connector on any always-on machine on that network.
In the panel, open Origins, choose Add origin and pick Connector. The panel attaches the origin 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 origin'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 origin 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 service URLs. 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.