Sensor: Air-Gapped Environments

Telovix is designed to run without any external network connectivity after initial setup. The operational path (sensor heartbeats, policy delivery, alert collection, and compliance reporting) requires only that sensors can reach the Console on your internal network. No traffic leaves the deployment boundary during normal operation.

The air-gap challenge is purely an artifact-transfer and trust-distribution problem: how to get binaries, the license bundle, and CA material into the protected environment before operations start.

Prerequisites

Telovix self-hosted deployment already running (Console installed and setup wizard completed)
Console binary obtained from the Portal Downloads page before network isolation begins
Signed license bundle obtained from the Portal Licenses page before network isolation begins
Sensor binaries for all required architectures and flavors downloaded before network isolation begins
Sensor install script downloaded or accessible from the internal Console before network isolation begins
No internet access from the target environment during and after deployment
Transfer workstation with connectivity to both the external Portal and the internal protected network (for initial artifact staging only)

What does and does not require external connectivity

Operation	External network required	Notes
Sensor heartbeat	No	Sensors connect only to the Console
License validation	No	The verification key is compiled into the Console binary
Console startup	No	All validation is local
Sensor enrollment	No	Sensors connect only to the Console
Policy pack delivery	No	Packs are served by the Console from local disk
SBOM scanning	No	The supported Trivy binary is bundled with the Console package and runs locally
Console self-update check	Optional	Connects to `portal.telovix.com` only when you trigger it from Settings
Sensor binary upgrade	Optional	Download from Portal and stage manually in the Console UI or on disk
Alert notifications (email)	Only if SMTP is external	SMTP server can be internal
SIEM forwarding	Only if SIEM is external	Can point at an internal SIEM

The only Console feature that contacts an external server at runtime is the self-update check, triggered from Settings > Updates. It does nothing automatically. It is only available in Telovix self-hosted deployments. (Telovix self-hosted only) For air-gapped environments, leave this unused and manage updates manually (see Manage updates in air-gapped environments).

Artifacts that must cross the gap

Before installation, transfer the following from a connected transfer workstation into the protected environment:

Artifact	Source	Purpose
Console binary	Portal Downloads page	Console installation
Sensor binaries (`amd64` and/or `arm64`, standard and/or telecom flavor)	Portal Downloads page	Served by the Console to enrolling sensors
Signed license bundle (`.json`)	Portal Licenses page for your deployment	Imported into the Console during setup wizard

The Telovix Console does not require any CA or TLS material to be provided at install time. If the configured cert paths do not exist, the Console auto-generates a self-signed CA and server certificate on first startup (see TLS in air-gapped environments). You can also bring your own PKI material if your organization has one.

No separate Trivy transfer is required. The supported scanner is bundled with the Console package and is updated only through the Telovix vendor-controlled update flow.

Recommended transfer staging layout:

airgap-transfer/
  console/
    telovix-console-amd64          # or arm64
    license-bundle.json
  sensor/
    amd64/
      telovix-sensor                # standard flavor
      telovix-sensor-telecom        # telecom flavor (if needed)
    arm64/
      telovix-sensor                # standard flavor
      telovix-sensor-telecom        # telecom flavor (if needed)

Verify checksums of every binary against the values published in the Portal catalog before transferring. After transfer, verify again inside the protected environment before installation.

License validation is fully offline

The Console validates license bundles using an Ed25519 public key that is compiled into the Console binary at build time. No network call is made during license import or validation. Once the signed bundle is imported and passes verification, the Console never contacts the Portal again for license purposes.

The license has two phases after the validity window:

Phase	Behavior
`active`	License is within its validity window
`grace`	License has passed `valid_until` but is within `grace_until`; the Console continues operating but shows renewal warnings

Past grace_until, protected operations stop. Plan license renewal transfers into your air-gap change-management process the same way you would plan binary updates.

TLS in air-gapped environments

Auto-generated self-signed CA (default for air-gapped setups)

If the TLS cert paths configured in the environment file do not exist when the Console starts, it automatically generates a self-signed CA and server certificate. The SANs on the generated certificate include:

localhost, 127.0.0.1, ::1
All non-loopback IPv4 and IPv6 addresses detected on the Console host at startup
The public hostname or IP configured during the setup wizard

This means the auto-generated certificate works for sensors connecting by IP without any manual cert management. The Console regenerates the certificate automatically if the existing cert expires within 30 days.

The generated CA certificate is served by the Console's trust bootstrap endpoint (requires a valid enrollment token or an operator session). The sensor install script downloads this CA automatically during enrollment and stores it at /etc/telovix-sensor/console-ca.cert.pem. Subsequent sensor communication uses mTLS with this CA as the trust anchor.

Bringing your own CA

If your organization has an internal PKI, place the following files at the paths configured in the Console environment file before starting the service:

File	Notes
Server TLS certificate	Must include the Console hostname/IP as a SAN
Server TLS private key	Mode `600`
CA cert used to verify sensor client certs	Same as issuer cert in most deployments
CA cert used to sign sensor client certs	Used during enrollment to issue client certs
CA signing key	Mode `600`

When using a custom CA, sensors download the CA cert automatically during enrollment via the install script. You do not need to distribute it to sensor hosts manually; the install script handles that.

Stage sensor binaries on the Console

The Console serves sensor binaries for deployment to enrolling sensors, so the Console must have the binaries staged before any sensor can enroll.

Place downloaded binaries at the configured path (default: /opt/telovix/console/sensor-binaries in the standard install layout):

sensor-binaries/
  amd64/
    telovix-sensor              # standard flavor, x86-64
    telovix-sensor-telecom      # telecom flavor, x86-64
  arm64/
    telovix-sensor              # standard flavor, ARM64
    telovix-sensor-telecom      # telecom flavor, ARM64

Permissions: 755, owner root:root.

You can also stage sensor binaries from Settings > Sensor Binaries after the Console is running.

Sensor binary staging is handled through the Console UI.

The upload limit is 200 MB per binary.

Installing sensors without direct internet access

Sensor installation in an air-gapped environment uses the same install script served by the Console. Sensor hosts need no internet access; they only need to reach the Console on port 15483 (Telovix self-hosted default).

The install script downloads the sensor binary and the bootstrap CA directly from the Console's internal address. No connection to the internet is made during sensor installation.

bash

# Standard enrollment (sensor downloads everything from the Console)
sudo bash <(curl -fsSL https://<internal-console-host>:15483/api/v1/sensor/install.sh) \
  --token "<token>"

Expected output after successful enrollment:

[telovix-install] downloading sensor binary... done
[telovix-install] downloading console CA certificate... done
[telovix-install] installing systemd service... done
[telovix] enrolled successfully, sensor_id=tlvs_...
[telovix] heartbeat sent

If the Console uses a self-signed CA and the sensor host does not yet trust it (only relevant before the install script runs), transfer the CA cert manually to the node first, then pass it via the --cacert flag when fetching the install script:

bash

# If you have pre-distributed the Console CA cert to sensor hosts:
sudo bash <(curl -fsSL --cacert /path/to/console-ca.pem \
    https://<internal-console-host>:15483/api/v1/sensor/install.sh) \
  --token "<token>" \
  --bootstrap-ca /etc/telovix-sensor/console-ca.cert.pem

Manage updates in air-gapped environments

The Console self-update feature (Settings > Updates) connects to portal.telovix.com by default to check for new binary versions. In an air-gapped environment, this check will time out. You can either:

Option 1: Leave the update check unused

Do not use the update check in Settings > Updates. Update the Console binary manually by placing the new binary on the host and restarting the service.

Option 2: Point the update check at an internal mirror

The update portal base URL is configurable from Settings > Updates in the Console. Change portal_base_url to an internal server that mirrors the Portal catalog API responses and binary files. The Console fetches the manifest and binary from the configured base URL. Replicate those endpoints on the internal mirror.

HTTP/HTTPS proxy settings are also configurable from Settings > Updates if the Console reaches the internet through a proxy.

The SBOM scanner follows the same vendor-controlled lifecycle. In air-gapped deployments, use the refreshed Console package from Telovix to update the bundled Trivy version. There is no standalone Trivy upload path.

Manual Console binary update

bash

# Stop the service
sudo systemctl stop telovix-console-api

# Replace the binary
sudo install -o root -g root -m 755 telovix-console-amd64-new \
  /opt/telovix/console/bin/telovix-console-api

# Start the service
sudo systemctl start telovix-console-api
sudo journalctl -u telovix-console-api -f

Expected output after restart:

telovix-console-api[...]: starting console version=1.3.0
telovix-console-api[...]: database migrations applied
telovix-console-api[...]: listening on 0.0.0.0:15483

Verify the Console is healthy:

bash

curl -sf http://127.0.0.1:15483/readyz && echo "Ready"

Expected output:

Ready

Manual sensor binary update

In the Console, navigate to Settings > Sensor Binaries and click Upload Binary. Select the architecture (amd64 or arm64), the flavor (standard or telecom), and the binary file. After upload, use the upgrade plan workflow in Sensors > Upgrade Plan to schedule and execute the rollout to enrolled sensors, or update sensors individually from Sensors.

Pre-deployment checklist

[ ] Console binary transferred and checksum verified
[ ] Sensor binaries (all needed architectures and flavors) transferred and staged at sensor-binaries/{arch}/
[ ] Signed license bundle transferred
[ ] Console installed and setup wizard completed (license, storage, admin account)
[ ] Console public URL set to the internal hostname or IP during the setup wizard (needed for correct TLS cert SANs and for the sensor install script URL)
[ ] TLS verified: browser connects without untrusted cert warnings, or custom CA deployed to operator workstations
[ ] Test enrollment: one sensor enrolled from inside the protected network using the internal Console address
[ ] License renewal process documented and scheduled before valid_until
[ ] Self-update check disabled or pointed at an internal mirror

Sensor: Air-Gapped Environments ​

Prerequisites ​

What does and does not require external connectivity ​

Artifacts that must cross the gap ​

License validation is fully offline ​

TLS in air-gapped environments ​

Auto-generated self-signed CA (default for air-gapped setups) ​

Bringing your own CA ​

Stage sensor binaries on the Console ​

Installing sensors without direct internet access ​

Manage updates in air-gapped environments ​

Manual Console binary update ​

Manual sensor binary update ​

Pre-deployment checklist ​

Further reading ​

Sensor: Air-Gapped Environments

Prerequisites

What does and does not require external connectivity

Artifacts that must cross the gap

License validation is fully offline

TLS in air-gapped environments

Auto-generated self-signed CA (default for air-gapped setups)

Bringing your own CA

Stage sensor binaries on the Console

Installing sensors without direct internet access

Manage updates in air-gapped environments

Manual Console binary update

Manual sensor binary update

Pre-deployment checklist

Further reading