Endpoint Guard deployment guide

How to try Cortega Endpoint Guard on one machine, then enroll licensed devices with MDM or administrator-provided certificates.

The product is Cortega Endpoint Guard (the headless agent) and Cortega AI Verifier (the same agent plus a native desktop app). This guide calls the running software "the agent" and the product "Endpoint Guard."

Quick reference

The Endpoint Guard agent is a native agent that captures AI traffic from desktop apps, browsers, and local MCP tools, the traffic Cortega's gateway never sees because it isn't pointed at the gateway. It installs as a system-level service (macOS: a LaunchDaemon; Windows: an SCM service) and runs before login, with no per-user setup, available for macOS and Windows.

System requirements:

• macOS: 11.0 Big Sur or later. One universal package installs on both Apple Silicon and Intel Macs. Admin/root access is required to install.
• Windows: a current, supported Windows 10/11 release. Administrator access is required to install.

Packages:

cortega-endpoint-guard-<version>.pkg           # macOS, agent only
cortega-endpoint-guard-<version>-windows.zip   # Windows, agent only
cortega-ai-verifier-<version>.pkg              # macOS, agent + AI Verifier app
cortega-ai-verifier-<version>-windows.zip      # Windows, agent + AI Verifier app

Pick the endpoint-guard package for headless fleet deployment, and the ai-verifier package when users need the desktop app. A machine runs one or the other, never both. See Install for where to get these packages.

Before testing any mode, restart AI apps such as Claude Desktop, ChatGPT, and other agent clients so existing provider connections close and reconnect through Endpoint Guard.

Deployment modes

Endpoint Guard supports a local trial mode and licensed enrollment modes. The trial mode never talks to Cortega. New licensed deployments should prove device identity with a per-device client certificate; a shared enrollment key remains available as a test-only path.

Mode	Who uses it	Identity proof	Security	Manageability
MDM rollout	Enterprise fleet deployment	MDM-issued per-device client cert	Highest; unique device cert, MDM lifecycle, optional non-exportable key	Best for fleets; MDM owns install, cert, config, removal
Self rollout	Admin-managed pilots	Cortega-generated per-device client cert	High; unique cert per device, no shared secret	Good for pilots; secure distribution required
Shared key-based activation	Internal installs/testing	Shared enrollment key	Lowest	Simple and familiar

Recommended default: use MDM rollout or self rollout without MDM, and use key-based activation only as a test path while certificate enrollment is adopted.

The modes above cover the headless Endpoint Guard service. The AI Verifier desktop app enrolls differently: it signs the user in through SSO or an invitation link, and an unknown user is routed to a Cortega admin for approval rather than being auto-provisioned.

Certificate model

Licensed Endpoint Guard enrollment uses one trusted enrollment authority and one client certificate per device. Do not share one client certificate across machines; a shared cert would behave like a shared enrollment key.

The client certificate identifies the device and the assigned user. The Cortega URL is part of configuration, and it must be the public Endpoint-Guard-facing HTTPS origin (the nginx, load balancer, or app URL the device can reach). The Endpoint Guard → Enrollment screen prefills this from the browser origin. Since the certificate includes the user email, the activation command does not need a separate email argument.

Administrator setup: TLS, nginx, and client-cert headers

Certificate enrollment needs a TLS terminator that can see the agent's client certificate. Cortega then verifies that cert against the trusted enrollment CAs and mints a short-lived token.

There are two supported topologies:

• Direct HTTPS to management-backend. Use this only for a lab or a dedicated listener. The backend requests a client certificate on the TLS handshake and verifies it against trusted enrollment CAs directly. Do not publish this port to the internet if the public console already sits on another origin.
• TLS-terminating proxy or load balancer (normal production path). The public console and the agent share one HTTPS origin. The proxy terminates TLS, optionally requests a client certificate, and forwards the verified leaf cert in one HTTP header. management-backend never sees the TLS client cert directly.

For the proxy topology, four properties matter: the proxy must overwrite the identity header (clearing any client-supplied value before setting it from the TLS handshake, otherwise a caller could paste a stolen certificate and impersonate that device); management-backend and webapp-backend must not be reachable from the internet directly, only the TLS terminator; client certs must be optional at the TLS layer, since browsers loading the console have no client cert, though Cortega still rejects certificate-mode calls that arrive without a valid one; and the enrollment CA must be exported to the terminator and kept in sync with what's uploaded in Endpoint Guard → Enrollment.

Supported terminators, and what to send Cortega:

Terminator	What to send Cortega
nginx	The URL-encoded PEM of the client cert, forwarded in a custom header
AWS ALB passthrough	X-Amzn-Mtls-Clientcert (built-in, URL-encoded PEM)
GCP HTTPS LB	Needs a custom header with URL-encoded PEM; its built-in header format isn't one Cortega parses. Put nginx behind the GCP LB, or configure a matching custom header.
Azure Application Gateway	Rewrite the client-certificate variable (PEM) into the configured header; URL-encode it if the rewrite leaves raw newlines

Always configure the exact header name the terminator sends.

Security notes for certificate mode: one client cert per device, since a shared fleet cert is the shared enrollment key with extra steps; trusting the forwarded header trusts that header, not possession of the private key, so the terminator must have already proven possession during the TLS handshake; and rotating or disabling a CA from Endpoint Guard → Enrollment must be matched by updating the terminator's trusted CA file, since Cortega rejecting a cert does not by itself stop the terminator from accepting the handshake.

1. Local trial without Cortega

Use this when an admin wants to download the package and try Endpoint Guard on one machine without a Cortega backend.

Install the package for your platform. It installs and starts the system service with no Cortega URL and no enrollment identity, and captures locally against a built-in list of common AI domains such as ChatGPT, Claude, Gemini, Copilot, DeepSeek, and Kimi.

Open http://127.0.0.1:7878 and generate traffic to an AI site. You should see local captures on the diagnostic page. The table shows only Time and App columns until the agent is registered with Cortega, since nothing is sent to Cortega while no backend is configured.

Trial behavior: works for 15 minutes per service start. After 15 minutes without Cortega connectivity, Endpoint Guard enters passthrough mode: no interception, no capture, no guardrails, no budget checks, the same behavior a real network outage produces. Restarting the service starts a new 15-minute local trial window. This mode is not licensed, not enrolled, and not connected to a Cortega backend.

2. MDM rollout with MDM-issued certificates

Use this for production fleet rollout with Jamf, Kandji, Intune, Mosyle, or a similar MDM.

Admin workflow in Cortega: open Endpoint Guard → Enrollment, choose MDM-issued certificates, upload the MDM/SCEP/ACME issuing CA certificate or select an existing trusted enrollment CA, download the CA PEM and install it as the client CA on the TLS terminator, configure the expected certificate identity fields (tenant ID, device ID, user email, serial number, or MDM device ID), and copy the public HTTPS Cortega URL for the deployment.

MDM workflow: deploy the endpoint-guard package, deploy a per-device client certificate through SCEP, ACME, or an MDM certificate payload (non-exportable private key when the MDM supports it), and deploy a configuration profile or file with the Cortega URL and the client certificate/key paths. Start or restart the service.

Expected device behavior: the agent finds the installed client certificate, registers with Cortega using mutual TLS or an equivalent certificate-backed request, and Cortega verifies the cert chains to a trusted enrollment CA, is not expired, has Client Authentication usage, and maps to an allowed tenant/device identity. Cortega then creates or updates the device record, mints a short-lived token, and returns runtime policy. The device appears in Endpoint Guard → Devices.

MDM installs must be noninteractive; MDM supplies the certificate and config separately rather than relying on package prompts.

3. Self rollout with Cortega-generated certificates

Use this for pilots, small fleets, or customers without MDM. Cortega acts as the enrollment CA and generates unique per-device client certificates.

Admin workflow in Cortega: open Endpoint Guard → Enrollment, choose Cortega-generated certificates, create or select the Cortega enrollment CA and install its downloaded PEM on the TLS terminator if not already done, generate one client certificate per device or user/device assignment, leaving Cortega URL as the public HTTPS origin the device will call, choose a finite certificate lifetime (usually 90 days to 1 year for pilots, up to 3 years for managed fleets with a rotation process), download the certificate/key or full identity bundle, and send the package, identity material, and Cortega URL to the target user through a secure channel.

User/admin install workflow: install the package, then install the per-device identity using the platform's import-identity helper with the Cortega URL and either the separate certificate/key files or the full identity bundle. The helper copies the certificate/private key into the Cortega identity directory, writes the Cortega URL and PEM paths, clears any shared enrollment key, and restarts the service. The device then registers with Cortega and appears in Endpoint Guard → Devices.

Certificate import runs as an explicit, elevated/root-run helper for manual/self rollout; package install scripts cannot safely prompt during MDM installs, which is why MDM deployment uses mode 2 instead.

4. Key-based activation

Use this for existing deployments that already rely on the shared enrollment key. This is a compatibility path, less secure than certificate enrollment because the same secret can be reused across many devices.

Admin workflow in Cortega: configure the enrollment key on the Cortega backend, share the Cortega URL and enrollment key only through an approved secret channel, and rotate the key if it's exposed or if a deployment cohort should no longer be able to enroll.

Device workflow: run the platform's activation script with the Cortega URL, enrollment key, and user email. The script writes the Cortega URL, agent key, and email into the local Endpoint Guard config (clearing any leftover client-cert identity from a prior certificate enrollment) and restarts the service. On startup, the agent registers with Cortega by presenting the shared key plus the claimed email; Cortega compares the key to its configured enrollment key, validates the email/domain, records the device, and returns a short-lived token plus runtime policy.

Security notes: the key proves access to the enrollment secret, not possession of a specific managed device; any holder of the shared key can attempt to register a device and claim an allowed email; the key is stored in the device's Endpoint Guard config and must be protected as a secret; prefer per-device certificate enrollment for new production deployments.

Verify

For local trial: restart AI apps, browse to an AI site such as chatgpt.com or claude.ai, open http://127.0.0.1:7878, and confirm local captures appear (and that nothing appears in Cortega, since the device is not enrolled).

For licensed enrollment: confirm the device appears in Endpoint Guard → Devices, confirm http://127.0.0.1:7878 shows the device as registered, restart AI apps, generate AI traffic, and confirm Endpoint Guard → Observability shows captured LLM or MCP activity.

Managing devices

Endpoint Guard → Devices lists enrolled devices. The Identity column shows how Cortega last verified the device: Enrollment key (shared enrollment secret), Client certificate · {CA name} (mTLS or forwarded client cert chained to that trusted enrollment CA), or Unknown (registered before identity was recorded; the next successful register updates it).

Serial is the hardware serial the agent reads from the device. Certificate enrollment uses the cert's device identity as Device ID. The Devices table's Device column and the drawer title are the OS hostname, which is not the Device ID.

Intercept CA is separate: it is whether the device trusts Cortega's local TLS inspection certificate, not the enrollment CA.

Active Clients lists AI apps currently running on the device (ChatGPT, Claude Desktop, Cursor, and similar). The agent reports this on register and on each config poll.

Delete a device to free a license seat. The device must re-enroll to appear again.

Other Endpoint Guard screens

Screen	What it does
Endpoint Guard → Apps	Allow/deny rules for AI domains. A rule can cover all Endpoint Guard AI domains or one exact domain, and can turn request/response content capture off for that domain. Cortega returns the resolved rules in each device's runtime config; the agent blocks any domain whose action resolves to deny.
Endpoint Guard → Guardrails	Guardrails scoped to Endpoint Guard traffic, the same guardrail types as AI Border Gateway (see the Guardrails guide), applied to what the agent captures.
Endpoint Guard → Observability	The Endpoint Guard LLM/MCP query tables, every captured exchange, in the same telemetry pipeline as gateway traffic.

Device notifications from Cortega Agents

If the Cortega Agents product is licensed and the Legal Agent (AI Verifier) is enabled, a false or unverified verdict on an Endpoint Guard-captured response is pushed back to the originating device on its next config poll and shown as a native OS notification. Delivery is best-effort and at-most-once; there is no acknowledgement. Gateway traffic (no device) never triggers this.

Uninstall

Uninstalling stops the service, removes Endpoint Guard files, removes the trusted local interception certificate, and reverts system proxy settings the agent changed.

For certificate-based licensed installs, uninstall should not automatically delete an MDM-issued identity certificate unless Cortega installed it during self rollout. MDM-owned certificates should be removed by MDM.

Troubleshooting

Symptom	Likely cause
Diagnostic page shows no traffic	Restart the AI app and confirm the domain is in the Endpoint Guard app policy.
Trial stops capturing after 15 minutes	Expected local-trial timeout; restart the service for another local trial window.
Device never appears in Cortega	Missing Cortega URL, missing client certificate, untrusted CA, expired cert, or certificate identity mismatch.
Certificate import fails	User lacks root/admin access, the PEM files are missing or malformed, or the cert lacks Client Authentication usage.
Sign in with SSO returns "account pending" / a "request submitted" screen	Working as intended: the email's domain isn't on any tenant's SSO-enrollment list and there's no invitation, so the request went to Users & Access → Pending Approval for a Cortega admin. Add the domain to the tenant, issue an invitation link, or provision the user from the pending row.
Sign in with SSO returns "seats full"	The tenant's AI Verifier seat count is exhausted. Raise the seat count on the tenant or remove an inactive device.
SSO tries to reach the public Cortega domain instead of your instance	The Cortega URL field was left blank; it defaults to the public instance. Type your full instance URL.
Client certificate is required, through the proxy	The proxy isn't configured to trust client certificates, isn't setting the expected header, or a component in front of Cortega isn't forwarding it.
Invalid client certificate	The proxy forwarded a cert that does not chain to a trusted enrollment CA, is expired, or lacks Client Authentication. Download the CA PEM again and confirm it matches the proxy's trusted CA configuration.
Agent fails TLS to a local test URL	The OS trust store doesn't trust the local test CA; the agent uses system roots, not a custom CA file.
Browser console breaks after enabling mTLS	The terminator required a client cert instead of making it optional. Browsers connect without a cert and need that to succeed.
Registered locally, but no Endpoint Guard Observability rows	Check network access from the device to the Cortega gateway/observability URL and widen the time selector.
MDM install hangs waiting for input	A package prompt was used in MDM mode; move cert/config delivery into MDM payloads and keep install noninteractive.
Device never appears in Cortega's Devices page (key-based)	Re-run the activation script and check its output for errors; confirm the agent key matches what's configured on your Cortega instance.
(Windows) Install/activate fails with an access-denied error	The install/activate/import-identity/uninstall scripts all need an elevated (Administrator) PowerShell session.