# Install the Conduit connector

> Install the Conduit connector for Private Access on Linux, macOS or Windows with your admin's one-time token, run it as a service and keep it current.

Source: https://docs.trustaige.com/manage/conduit

Replace these placeholders with your organization's own values:

- `<your-conduit-token>`: Conduit token, a secret. From the hub, when an admin adds a connector. It works once, within an hour.

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](#run-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

```sh title="Linux x86-64"
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>
```

```sh title="Linux ARM64"
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:

```txt title="Output"
✓ 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](#check-it-connected).

## Install on macOS

```sh title="macOS on Apple silicon"
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>
```

```sh title="macOS on Intel"
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:

```txt title="Output"
✓ 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](#check-it-connected).

## Install on Windows

Open PowerShell with **Run as administrator**, then:

```powershell title="Windows x86-64"
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:

```txt title="Output"
✓ 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](#check-it-connected).

## Run in the foreground

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

```sh title="Linux and macOS"
./trustaige-conduit -edge https://edge.trustaige.app -token <your-conduit-token>
```

```powershell title="Windows"
.\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.

## 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](#troubleshooting).

To see which version you're running:

```sh title="Linux and macOS"
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.

```sh title="Linux (use trustaige-conduit-linux-arm64 on ARM64)"
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
```

```sh title="macOS (use trustaige-conduit-darwin-amd64 on Intel)"
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
```

```powershell title="Windows, as administrator"
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.

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

```sh title="Linux and macOS"
sudo ./trustaige-conduit uninstall -purge
```

```powershell title="Windows, as administrator"
.\trustaige-conduit.exe uninstall -purge
```

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

```txt title="Output on Linux"
✓ 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.

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

```sh
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.

```sh title="Linux"
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.