Register cnspec with Mondoo Platform
Register cnspec with Mondoo Platform to enable policy downloads and scan reporting.
Registering cnspec with Mondoo Platform connects it to the security policies and reporting available in the Mondoo Console. Once registered, cnspec downloads the policies enabled for your space, sends scan results back to the platform, and shows up in the asset inventory.
You can keep using cnspec without registering, but you'll only get Mondoo's open-source community policies and results that stay on the local machine. To unlock platform features, contact Mondoo to start a trial.
Register cnspec
If you installed cnspec with the automated install script and supplied a registration token, you're already registered and can skip ahead to validate registration. Otherwise, register manually:
Registering from automation (CI/CD, immutable images, build agents)? Use a long-lived credentials file instead. Read Register cnspec Using a Credentials File.
-
Log into the Mondoo Console.
-
Navigate to the region, organization, and space the asset should report into.
-
In the left navigation, under Integrations, select Add New Integration.
-
Pick your operating system and copy the registration token.
-
In a terminal on the asset, run:
Register cnspec cnspec login --token "YOUR_REGISTRATION_TOKEN"The token creates a service account so cnspec can report results to Mondoo Platform.
Save the config to the system path
For cnspec to keep reporting after a reboot or service restart, the configuration must live at the
system-wide path. Pass --config when registering:
- Linux and macOS:
cnspec login --token "TOKEN" --config "/etc/opt/mondoo/mondoo.yml" - Windows:
cnspec login --token "TOKEN" --config "C:\ProgramData\Mondoo\mondoo.yml"
Communication with Mondoo Platform is encrypted with HTTPS, and the payload is signed so the platform can verify it has not been tampered with in transit.
Validate registration
cnspec status confirms cnspec is registered and can reach Mondoo Platform. Run it after registering:
cnspec statusA healthy registration ends with these two lines:
→ client is registered
→ client authenticated successfullyA full success looks like this:
→ loaded configuration from /etc/opt/mondoo/mondoo.yml using source default
→ Platform: linux
→ Hostname: webserver-01
→ Time: 2026-02-07T10:58:10-08:00
→ Version: 13.0.0 (API Version: 13)
→ Latest Version: 13.0.0
→ Installed Providers: core | os | mock
→ API ConnectionConfig: https://us.api.mondoo.com
→ API Status: SERVING
→ Owner: //captain.api.mondoo.app/spaces/your-space
→ Service Account: //agents.api.mondoo.app/spaces/your-space/serviceaccounts/...
→ client is registered
→ client authenticated successfullyWhat to do when status fails
If the last line of cnspec status doesn't read client authenticated successfully, match it against this list:
| Final line | Meaning | Fix |
|---|---|---|
x client is not registered | cnspec has no service account credentials yet. | Run the registration steps above. |
x could not connect to mondoo platform error="… Unauthenticated …" | The credentials exist but the service account was revoked or rotated. | Re-register with a fresh token: cnspec login --token "NEW_TOKEN" --config "<path>". |
! possible clock skew detected: <duration> | The system clock is too far from Mondoo's clock for signed requests to work. | Sync the system clock against NTP (sudo timedatectl set-ntp true on systemd; w32tm /resync on Windows) and run cnspec status again. |
Use a proxy server
If your network forces outbound traffic through a proxy, point cnspec at it in mondoo.yml:
-
Open the configuration file:
- Linux and macOS:
/etc/opt/mondoo/mondoo.yml - Windows:
C:\ProgramData\Mondoo\mondoo.yml
- Linux and macOS:
-
Add the proxy URL:
api_proxy: https://1.1.1.1:8080
You can also set the proxy at registration time with --api-proxy:
cnspec login --token "YOUR_TOKEN" --api-proxy "https://1.1.1.1:8080" --config "/etc/opt/mondoo/mondoo.yml"