Install the Conduit connector

You’re setting up the connector for Trustaige Private Access. An administrator in your organization wants an internal web app reachable through Trustaige, signed in with a passkey, without a VPN. Conduit, the connector, runs on a server inside the app’s network and dials out to the Trustaige edge; the edge sends each signed-in person’s requests back down that connection to the app. Nothing opens inbound.

From your admin you should have a one-time registration token from the hub. It starts with tk_, works once, and expires an hour after it was minted. The token already says which organization and site the connector serves, so there’s nothing else to configure. If it has expired, ask for a new one.

Before you begin

You need	Why
The token from your admin	It registers this machine as a connector. Treat it as a secret until it’s used.
A machine inside the app’s network	The connector forwards requests to the app’s internal address (the Internal origin URL your admin entered, such as `http://wiki.internal:3000`), so it must be able to reach it.
Outbound HTTPS to `edge.trustaige.app` on port 443	The connector holds a WebSocket open to `wss://edge.trustaige.app/__trustaige/tunnel`, and the installer downloads `https://edge.trustaige.app/dl/manifest.json` to check itself. Nothing inbound.
Root (Linux and macOS) or an elevated PowerShell (Windows)	To install it as a service.
One of the supported platforms	Linux on x86-64 or ARM64 (systemd, to run as a service); macOS on Apple silicon or Intel; Windows on x86-64.

Install it as a service (below) for anything you want to keep running: it starts on boot and restarts five seconds after it stops. To try it first, run it in the foreground instead, but not both with the same token: the token works once, and the foreground copy keeps its identity in a different place from the service.

Install on Linux

curl -fLo trustaige-conduit https://edge.trustaige.app/dl/trustaige-conduit-linux-amd64
chmod +x trustaige-conduit
sudo ./trustaige-conduit install -edge https://edge.trustaige.app -token <your-conduit-token>

curl -fLo trustaige-conduit https://edge.trustaige.app/dl/trustaige-conduit-linux-arm64
chmod +x trustaige-conduit
sudo ./trustaige-conduit install -edge https://edge.trustaige.app -token <your-conduit-token>

The installer checks its own checksum against the edge’s manifest, copies itself to /usr/local/bin/conduit, writes a systemd unit and starts it:

✓ binary checksum matches the edge manifest
✓ installed /usr/local/bin/conduit
✓ wrote /etc/systemd/system/trustaige-conduit.service
✓ trustaige-conduit enabled and started — it dials out only, no inbound ports


Service	`trustaige-conduit` (`/etc/systemd/system/trustaige-conduit.service`)
Binary	`/usr/local/bin/conduit`
Connector identity	`/var/lib/trustaige-conduit/state.json`, readable by root only
Status and logs	`systemctl status trustaige-conduit`, `journalctl -u trustaige-conduit`

Then check it connected.

curl -fLo trustaige-conduit https://edge.trustaige.app/dl/trustaige-conduit-linux-amd64
chmod +x trustaige-conduit
sudo ./trustaige-conduit install -edge https://edge.trustaige.app -token <your-conduit-token>

curl -fLo trustaige-conduit https://edge.trustaige.app/dl/trustaige-conduit-linux-arm64
chmod +x trustaige-conduit
sudo ./trustaige-conduit install -edge https://edge.trustaige.app -token <your-conduit-token>

✓ binary checksum matches the edge manifest
✓ installed /usr/local/bin/conduit
✓ wrote /etc/systemd/system/trustaige-conduit.service
✓ trustaige-conduit enabled and started — it dials out only, no inbound ports

Install on macOS

curl -fLo trustaige-conduit https://edge.trustaige.app/dl/trustaige-conduit-darwin-arm64
chmod +x trustaige-conduit
sudo ./trustaige-conduit install -edge https://edge.trustaige.app -token <your-conduit-token>

curl -fLo trustaige-conduit https://edge.trustaige.app/dl/trustaige-conduit-darwin-amd64
chmod +x trustaige-conduit
sudo ./trustaige-conduit install -edge https://edge.trustaige.app -token <your-conduit-token>

The installer checks its own checksum against the edge’s manifest, copies itself to /usr/local/bin/conduit, writes a launch daemon and starts it:

✓ binary checksum matches the edge manifest
✓ installed /usr/local/bin/conduit
✓ wrote /Library/LaunchDaemons/com.trustaige.conduit.plist
✓ com.trustaige.conduit bootstrapped and started — it dials out only, no inbound ports


Launch daemon	`com.trustaige.conduit` (`/Library/LaunchDaemons/com.trustaige.conduit.plist`)
Binary	`/usr/local/bin/conduit`
Connector identity	`/Library/Application Support/trustaige-conduit/state.json`, readable by root only
Status	`sudo launchctl print system/com.trustaige.conduit`
Log	`/Library/Logs/trustaige-conduit.log`

Then check it connected.

curl -fLo trustaige-conduit https://edge.trustaige.app/dl/trustaige-conduit-darwin-arm64
chmod +x trustaige-conduit
sudo ./trustaige-conduit install -edge https://edge.trustaige.app -token <your-conduit-token>

curl -fLo trustaige-conduit https://edge.trustaige.app/dl/trustaige-conduit-darwin-amd64
chmod +x trustaige-conduit
sudo ./trustaige-conduit install -edge https://edge.trustaige.app -token <your-conduit-token>

✓ binary checksum matches the edge manifest
✓ installed /usr/local/bin/conduit
✓ wrote /Library/LaunchDaemons/com.trustaige.conduit.plist
✓ com.trustaige.conduit bootstrapped and started — it dials out only, no inbound ports

Install on Windows

Open PowerShell with Run as administrator, then:

Invoke-WebRequest -Uri https://edge.trustaige.app/dl/trustaige-conduit-windows-amd64.exe -OutFile trustaige-conduit.exe
.\trustaige-conduit.exe install -edge https://edge.trustaige.app -token <your-conduit-token>

The installer checks its own checksum against the edge’s manifest, copies itself under Program Files, registers a Windows service that starts automatically and restarts five seconds after a failure, and starts it:

✓ binary checksum matches the edge manifest
✓ installed C:\Program Files\Trustaige\Conduit\conduit.exe
✓ TrustaigeConduit installed and started — it dials out only, no inbound ports


Service	`TrustaigeConduit`, shown as Trustaige Conduit in Services
Binary	`C:\Program Files\Trustaige\Conduit\conduit.exe`
Connector identity	`C:\ProgramData\Trustaige\Conduit\state.json`
Status	`Get-Service TrustaigeConduit`

Then check it connected.

Invoke-WebRequest -Uri https://edge.trustaige.app/dl/trustaige-conduit-windows-amd64.exe -OutFile trustaige-conduit.exe
.\trustaige-conduit.exe install -edge https://edge.trustaige.app -token <your-conduit-token>

✓ binary checksum matches the edge manifest
✓ installed C:\Program Files\Trustaige\Conduit\conduit.exe
✓ TrustaigeConduit installed and started — it dials out only, no inbound ports

Run in the foreground

To try the connector without installing it, run the downloaded file directly. It stays connected until you press Ctrl+C.

./trustaige-conduit -edge https://edge.trustaige.app -token <your-conduit-token>

.\trustaige-conduit.exe -edge https://edge.trustaige.app -token <your-conduit-token>

It saves its identity in your user’s configuration folder (~/.config/trustaige-conduit/state.json on Linux, ~/Library/Application Support/trustaige-conduit/state.json on macOS, %AppData%\trustaige-conduit\state.json on Windows), so the next run needs no token: leave -token off. To keep it running, install the service with a new token from your admin.

./trustaige-conduit -edge https://edge.trustaige.app -token <your-conduit-token>

.\trustaige-conduit.exe -edge https://edge.trustaige.app -token <your-conduit-token>

How the token is used

The first time the connector connects, it hands the token to the edge, which registers the connector with your organization and gives it a long-lived credential in return. The connector saves that credential in its identity file and uses it from then on; the token is spent. The installer leaves the token in the service definition, where it does no harm, since it can’t be used again.

The identity file is what makes this machine the connector: keep it private, and know that deleting it means asking for a new token.

Check it connected

The connector connects as soon as it starts, and your admin sees it in the hub within seconds:

While they’re adding the app or the connector, the status line changes from “Listening for the connector” to “Connector name is online”, with this machine’s operating system, architecture and Conduit version.
On Apps → Connectors, a row appears under the site, named after this machine’s hostname (lower-case, letters, digits and hyphens only), with “seen just now”.

From any browser, open the app’s address (your admin has it; it ends in .trustaige.app). You should be asked to sign in, then see the app. If instead you see This app isn’t connected right now, the connector isn’t online; see Troubleshooting.

To see which version you’re running:

conduit -version

conduit -version

Upgrade the connector

The hub marks a connector update available when it runs an older version than the current one. Upgrading needs no token: the connector keeps its identity and comes back as the same row in the hub.

curl -fLo trustaige-conduit https://edge.trustaige.app/dl/trustaige-conduit-linux-amd64
chmod +x trustaige-conduit
sudo ./trustaige-conduit install -edge https://edge.trustaige.app
sudo systemctl restart trustaige-conduit

curl -fLo trustaige-conduit https://edge.trustaige.app/dl/trustaige-conduit-darwin-arm64
chmod +x trustaige-conduit
sudo ./trustaige-conduit install -edge https://edge.trustaige.app

Stop-Service TrustaigeConduit
Invoke-WebRequest -Uri https://edge.trustaige.app/dl/trustaige-conduit-windows-amd64.exe -OutFile trustaige-conduit.exe
.\trustaige-conduit.exe install -edge https://edge.trustaige.app

On Linux, the installer enables the service but doesn’t restart one that’s already running, hence the last line. On Windows, the running service holds the installed file open, so stop it first; the installer starts it again.

curl -fLo trustaige-conduit https://edge.trustaige.app/dl/trustaige-conduit-linux-amd64
chmod +x trustaige-conduit
sudo ./trustaige-conduit install -edge https://edge.trustaige.app
sudo systemctl restart trustaige-conduit

curl -fLo trustaige-conduit https://edge.trustaige.app/dl/trustaige-conduit-darwin-arm64
chmod +x trustaige-conduit
sudo ./trustaige-conduit install -edge https://edge.trustaige.app

Stop-Service TrustaigeConduit
Invoke-WebRequest -Uri https://edge.trustaige.app/dl/trustaige-conduit-windows-amd64.exe -OutFile trustaige-conduit.exe
.\trustaige-conduit.exe install -edge https://edge.trustaige.app

Remove the connector

On the machine, uninstall the service and its identity with the downloaded file (download it again as in the install steps if you no longer have it):

sudo ./trustaige-conduit uninstall -purge

.\trustaige-conduit.exe uninstall -purge

This stops and removes the service, removes the installed binary and, with -purge, the identity file:

✓ removed /etc/systemd/system/trustaige-conduit.service
✓ removed /usr/local/bin/conduit
✓ removed connector identity — the row in the hub can be deleted too

Then ask your admin to remove the connector in the hub (Apps → Connectors, the bin on its row, Remove connector). Without -purge, the identity stays, and installing again later reconnects as the same connector with no token.

If your admin removes the connector in the hub first, the connector on the machine is refused from then on; uninstall it the same way. To bring a removed connector back, uninstall with -purge and install again with a new token.

sudo ./trustaige-conduit uninstall -purge

.\trustaige-conduit.exe uninstall -purge

✓ removed /etc/systemd/system/trustaige-conduit.service
✓ removed /usr/local/bin/conduit
✓ removed connector identity — the row in the hub can be deleted too

Command reference

trustaige-conduit runs the connector; install and uninstall manage the service. The installed copy is conduit (conduit.exe on Windows) and takes the same commands.

Flag	Used with	What it does
`-edge`	run, `install`	The edge to connect to. Always `https://edge.trustaige.app`.
`-token`	run, `install`	The one-time registration token. Needed only until the connector has an identity.
`-state`	run, `install`, `uninstall`	The identity file. Defaults to the paths above.
`-version`	run	Prints the version and exits.
`-trace`, `-traces`	run	Writes each connection step to a `.trace.jsonl` file in the `-traces` folder, for troubleshooting.
`-bin`	`install`, `uninstall`	Where the binary is installed. Defaults to the paths above.
`-service`	`install`, `uninstall`	The service name. Defaults to the names above.
`-skip-verify`	`install`	Skips the checksum check against the edge’s manifest. Don’t, unless you know why it fails.
`-purge`	`uninstall`	Also removes the identity file.

Troubleshooting

The connector prints nothing while it works. It writes a line only when it stops on an error, and it retries a lost connection on its own, waiting longer each time, up to about 45 seconds between attempts. Where the service writes that line: journalctl -u trustaige-conduit on Linux, /Library/Logs/trustaige-conduit.log on macOS.

“a registration token is required for first install (mint one in the hub)”

This machine has no connector identity yet, so the installer needs -token. Add the token from your admin.

“install writes to … — run with sudo”

Run the install command with sudo.

“opening the service manager (run from an elevated prompt — Run as administrator)”

Open PowerShell with Run as administrator and run the command again.

“binary checksum … does not match the edge's … build — re-download from the edge”

The file you downloaded isn’t the build the edge currently serves: the download was cut short, altered, or a new version came out in between. Download it again and rerun the command. Don’t reach for -skip-verify.

“fetching edge manifest” or “edge manifest unavailable”

The installer couldn’t reach https://edge.trustaige.app. Check this machine can make outbound HTTPS connections to it:

curl -sI https://edge.trustaige.app/dl/manifest.json

“edge rejected connector: invalid_token”

The token was already used, has expired, or was mistyped. A token is spent the first time any connector uses it, including a foreground run. Ask your admin for a new token and install again with it.

“edge rejected connector: invalid_credential”

The connector’s identity is no longer valid, usually because the connector was removed in the hub. Uninstall with -purge, then install again with a new token from your admin.

“conduit state … is corrupt”

The identity file can’t be read. Uninstall with -purge and install again with a new token; ask your admin to remove the old row from Connectors.

The hub keeps “Listening for the connector”, and the connector prints nothing

The connector can’t reach the edge and is retrying. Check outbound HTTPS to edge.trustaige.app on port 443 is allowed, including WebSocket upgrades if your traffic passes through an inspecting proxy. To see each step, stop the service and run the installed copy in the foreground with a trace. Keep -token if the connector has never connected; once it has an identity, the token is ignored.

sudo systemctl stop trustaige-conduit
sudo /usr/local/bin/conduit -edge https://edge.trustaige.app -token <your-conduit-token> -state /var/lib/trustaige-conduit/state.json -trace -traces /tmp/conduit-trace

Each line in /tmp/conduit-trace/conduit-local.*.trace.jsonl is one step: tunnel.dial, then tunnel.ws_open once the edge answers, tunnel.hello and, on a refusal, tunnel.error with its code. Repeated tunnel.reconnect_wait without tunnel.ws_open means the edge can’t be reached. Press Ctrl+C and start the service again with sudo systemctl start trustaige-conduit.

The connector shows offline in the hub

The connector lost its connection to the edge. Check the machine is up and the service is running (systemctl status trustaige-conduit, sudo launchctl print system/com.trustaige.conduit or Get-Service TrustaigeConduit).

People see “This app isn't connected right now”

No connector in the app’s site is online. Check the service is running. If it is, the connector may be registered to a different site from the app’s: your admin can compare them on Connectors, where each site lists its connectors and the apps it serves.

People get an empty 502 page

The connector is online but can’t reach the app at its internal address. From this machine, check the app answers there, for example curl -I http://wiki.internal:3000. If the app uses HTTPS, this machine must trust its certificate: the connector checks it against the system’s trusted certificates.