Install Trustity TCP On-Prem
Air-gap install of TCP On-Prem 4.0 with DNS, TLS, Trustity-signed licensing, and TAO 3 enrollment.
Install Trustity TCP On-Prem
TCP On-Prem 4.0 runs the Trustity Control Portal on your Linux server. After the install media is inside your network, the portal does not need outbound internet. Endpoints enroll with TAO 3 in On-Premises mode against that server - not against the cloud portal at trustity.io.
This guide is written so your team can install the portal, apply the license, and enroll Windows endpoints without ad-hoc troubleshooting. Read the Portal hostname & TLS and TAO enrollment sections before touching endpoints.
Licensing (do not skip)
- Your server creates
data/license-request.jsonduring install (also available under Deployment). - Send that file to Trustity. A Trustity admin issues a signed license with your agent quota and modules.
- Apply the signed file under Deployment → Apply signed license.
- Copy the organization license key shown after apply. Keys from a previous portal reset or an old license file will not work.
Self-generated keys do not unlock commercial modules.
Get the package
Entitled customers receive Trustity-TCP-OnPrem-4.0.1-airgap.tar.gz from Trustity (secure vault, account team, or trustity.dev/downloads for entitled partners). There is no public self-serve download.
| Package | Where to get it |
|---|---|
Trustity-TCP-OnPrem-4.0.1-airgap.tar.gz | Your Trustity account team after purchase |
| TAO 3 Windows installer | Portal Deployment page (after license apply) or your Trustity account team |
Prepare media on an open network, then transfer by USB / approved sneakernet.
Server prerequisites
Prepare the air-gapped host before install:
| Requirement | Specification |
|---|---|
| OS | Ubuntu 22.04 LTS or compatible Linux, x86_64 (amd64) |
| Docker | Docker Engine 24+ with Compose v2 - install on the host before running the installer |
| Resources | 2+ vCPU, 4 GB RAM minimum (8 GB recommended with VisionX) |
| Network | Endpoints can reach the portal on TCP 443 (HTTPS) and TCP 80 (CA bootstrap during TAO install) |
| Portal hostname | Internal DNS name strongly recommended (see next section) |
The installer loads bundled container images from the package. It does not pull from a registry, but Docker must already be installed on the server.
Portal hostname & TLS (read before install)
Use DNS in production
Plan a stable internal hostname for the portal, for example tcp.corp.local or trustity.company.internal.
| Approach | When to use |
|---|---|
| Internal DNS (recommended) | Production and most customer deployments |
| Fixed IP only | Acceptable for lab; you must regenerate TLS if the IP changes |
hosts file on endpoints | Lab / PoC only - when internal DNS is not ready yet |
Use the same hostname everywhere: DNS (or lab hosts), portal .env, TLS certificate, TAO /server= URL, and TAO_BASE_URL. Mixing IP in one place and DNS in another causes TLS or enrollment failures.
How portal TLS works
TCP On-Prem ships with a private Certificate Authority (CA) and a server certificate signed by that CA. Browsers may show “Not secure” - that is expected for a private CA.
TAO does not use the Windows certificate store. TAO validates HTTPS with its own TLS stack (rustls). Installing the CA into Windows Trusted Root does not enroll or heartbeat the agent. TAO needs the portal CA file (ca.crt) via:
- Recommended: silent install with
/mode=onprem(Setup downloads the CA automatically), or - Manual:
TAO_TLS_CA_FILEpointing at the CA PEM file on disk.
Generate TLS for your hostname
During install, enter the portal URL as https://your-hostname (no :443).
If you change the hostname or IP later, regenerate certificates on the portal server:
cd /opt/Trustity-TCP-OnPrem-4.0.1-airgap
./scripts/regenerate-tls.sh tcp.corp.local
docker compose restart caddy
Then redistribute certs/ca.crt to every endpoint and restart TAO.
What endpoints need on disk
| File | Purpose |
|---|---|
certs/ca.crt from the portal | Trust anchor for TAO → portal HTTPS |
Not server.crt | That is the portal’s leaf cert, not what TAO needs |
Default path on Windows (if you copy manually): C:\ProgramData\Trustity\portal-ca.crt
The portal also serves the CA at http://<portal>/ca.crt (port 80) for bootstrap during On-Prem Setup.
Install the portal
tar xzf Trustity-TCP-OnPrem-4.0.1-airgap.tar.gz
cd Trustity-TCP-OnPrem-4.0.1-airgap
sudo ./install.sh
When prompted:
- Portal URL:
https://tcp.corp.local(your chosen hostname - no trailing slash, no:443) - Organization name and administrator credentials
Save data/license-request.json and send it to Trustity.
Verify from a workstation on the same network:
curl -k -sS -o /dev/null -w "%{http_code}\n" https://tcp.corp.local/
curl -sS http://tcp.corp.local/ca.crt | head -1
The first command should return 200 or 302. The second should print -----BEGIN CERTIFICATE-----.
Apply the Trustity license
- Receive the signed license JSON from Trustity.
- Sign in to
https://your-portal→ Deployment. - Paste or upload the file → Apply signed license.
- Copy the organization license key shown on Deployment (fresh key - not from an old install).
TAO 3 enrollment (Windows)
Recommended - silent install (production)
Run as Administrator on each endpoint. Use the exact portal URL from install (hostname, not a mismatched IP):
Trustity-Agent-Setup.exe /quiet /mode=onprem /server=https://tcp.corp.local /license=YOUR_DEPLOYMENT_KEY
This mode:
- Downloads the portal CA from
http://tcp.corp.local/ca.crt - Saves it and sets machine environment variables (
TAO_BASE_URL,TAO_TLS_CA_FILE) - Enrolls in On-Premises mode and starts the Windows service
Confirm the device under Agents in the portal. Open Trustity TAO - status should show Protected, not Offline.
Manual enrollment (fallback)
If silent install is not an option, run as Administrator:
curl -o C:\ProgramData\Trustity\portal-ca.crt http://tcp.corp.local/ca.crt
setx TAO_BASE_URL "https://tcp.corp.local" /M
setx TAO_TLS_CA_FILE "C:\ProgramData\Trustity\portal-ca.crt" /M
cd /d "C:\Program Files\Trustity\TAO"
tao-agent.exe enroll --license-key YOUR_DEPLOYMENT_KEY --deployment-mode on_prem
net stop TrustityAgent
net start TrustityAgent
Close and reopen TAO GUI after changing machine environment variables.
Do not rely on the TAO GUI Activate button alone after a plain /quiet install without /mode=onprem - the agent may default to the cloud portal until TAO_BASE_URL is set.
Lab / PoC without internal DNS
For a proof-of-concept when DNS is not ready:
-
Pick a lab hostname, e.g.
tcp.lab.local. -
On the portal server, run
./scripts/regenerate-tls.sh tcp.lab.localand restart Caddy. -
On each Windows endpoint, edit
C:\Windows\System32\drivers\etc\hostsas Administrator:192.168.1.50 tcp.lab.local -
Enroll TAO with
https://tcp.lab.localeverywhere - not the raw IP if the cert was issued for the hostname.
This is fine for lab validation. Move to real internal DNS before production.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| “License key not recognized” | Enrolling against cloud (trustity.io) or wrong key | Use /mode=onprem or --deployment-mode on_prem; copy key from Deployment after latest apply |
| TAO Offline, heartbeat error to portal URL | Missing TAO_TLS_CA_FILE for service/GUI | Set machine env vars; ensure portal-ca.crt exists; restart TrustityAgent |
| TLS / certificate errors | Hostname mismatch (IP vs DNS) | Regenerate TLS for the hostname you use in URLs; keep URL consistent |
| Browser “Not secure” | Private CA | Expected; unrelated to TAO if CA file is configured |
| Agent in portal but GUI shows Offline | Enroll worked once; heartbeat lacks CA trust | setx TAO_TLS_CA_FILE + restart service (see above) |
curl https://portal/ca.crt fails on Windows | Windows curl uses cert store | Use http://portal/ca.crt or curl -k for tests; TAO uses TAO_TLS_CA_FILE |
Quick diagnostic (Administrator CMD)
reg query "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v TAO_BASE_URL
reg query "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v TAO_TLS_CA_FILE
dir C:\ProgramData\Trustity\portal-ca.crt
cd /d "C:\Program Files\Trustity\TAO"
tao-agent.exe status
Related
- Product page: /products/tcp-onprem
- Integrator guide: trustity.dev/docs/platform/tcp-onprem-install
- Cloud Deployment center: Deployment