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 Booster (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-booster-<version>.pkg              # macOS, agent + AI Booster app
cortega-ai-booster-<version>-windows.zip      # Windows, agent + AI Booster app

Pick the endpoint-guard package for headless fleet deployment, and the ai-booster 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. Browsers and desktop AI clients read the system proxy and the trusted CA once at launch.

Route AI assistants through AIBG

Endpoint Guard has two separate paths: Apps policies govern intercepted traffic to its original destination, while AI Assistants configures supported local tools to send their inference requests through AI Border Gateway.

1. Install and enroll Endpoint Guard on the user's device, and keep its native app running so it can apply the per-user assistant configuration.
2. Configure the user's team and its model routing in AIBG. For private inference, select self-hosted models and keep fallback routes private too.
3. Open Endpoint Guard → AI Assistants and enable Route AI assistant traffic through AIBG.
4. Select Default team for AI assistant keys. This is used when the enrolling user has no assigned team; otherwise the user's team takes precedence.
5. Check the assistants to configure. Endpoint Guard detects installed tools and applies the gateway URL and a Cortega API key through their local settings. One key per device is shared across its enabled assistants.
6. Let the device receive the updated runtime configuration. Restart the assistant if needed to reload its settings; quit and reopen Cursor after its configuration changes. Run a real request and confirm the caller, team, and private model in AIBG observability.

Supported assistants are Claude Code, Codex CLI, OpenCode, Pi, Cursor, Goose, Aider, and Continue (VS Code). The console lists the files and settings changed for each tool. Codex Desktop shares the CLI's configuration file.

Continue: start the extension once so ~/.continue exists (Windows: %USERPROFILE%\.continue). Endpoint Guard saves the original config.yaml in .cortega-config-backup.json, then manages config.yaml with a Cortega local profile for chat, edit, apply, and autocomplete. Select that local profile in Continue; reload the extension if it has not refreshed. While enabled, remote changes update the gateway, key, and routed model, and local edits to this file are overwritten. Unchecking Continue restores the original file byte for byte (or removes the generated file if none existed). Existing rules and other settings in the saved original are inactive while the managed profile is used. Cloud-selected configs, workspace overrides, embeddings, reranking, and other VS Code extensions are not managed. This is configuration management, not a lock against choosing another profile. The selected model must support streaming and tool calls; test autocomplete compatibility separately.

Microsoft Copilot: there is no supported local model endpoint/API-key setting for this integration to redirect its Microsoft-hosted inference to AIBG. Use Endpoint Guard → Apps for supported interception/policy coverage; interception does not replace Microsoft's models. GitHub Copilot Chat, Windsurf, Cline, and Gemini CLI are not automatically configured. VS Code extensions need individual integrations; Continue is the supported extension here.

Configuration is reapplied as settings change. Unchecking an assistant removes Cortega's managed configuration for that tool when the native app applies the updated selection. Turning off the master switch immediately revokes the existing device assistant keys for the tenant; turning it back on reactivates the same keys. This is not just a setting for future enrollments.

Routing setup does not guarantee model compatibility. Test the selected model with the assistant's required API, streaming, and tool calls. In particular, Codex uses streaming tool calls on the Responses API, which not every self-hosted endpoint supports. External SaaS assistants and browser traffic remain governed separately through Endpoint Guard → Apps.

Collect AI assistant usage

Collect AI assistant usage is a second checkbox on Endpoint Guard → AI Assistants. It reports how each developer uses Claude Code and Codex. It does not send their requests through AI Border Gateway. Each developer keeps their own Claude or ChatGPT subscription and signs in as before.

What is sent: session counts, active time, token totals, models used, an estimated cost, lines changed, and edits accepted or rejected. Prompt text, response text and tool arguments and output are dropped by the collector unless the second checkbox, Collect prompts, responses and tool use, is ticked. See that section below.

The two checkboxes work on their own. Route-only keeps today's behavior. Collect-only is the setup for a team that wants to keep its subscriptions. With both on, requests are routed and the usage numbers add what the gateway cannot see, such as lines changed.

The collector

The collector is a core service. Every AWS install runs it, behind a small ingest service that is the only part developers reach. The installer creates the install secret and sets the address, so there is nothing to set by hand.

• With a load balancer, developers reach the collector at telemetry.<gateway suffix>. After the install finishes, create a DNS record for that name that points to the load balancer. Cloudflare terminates TLS.
• Without a load balancer, developers reach the collector at http://<core public IP>:4320. Port 4320 opens to the same network as the app's public port: AWS_ALLOWED_HTTP_CIDR in the AWS installer, or app_ingress_cidr in Terraform.

The management backend reads the collector address and secret when it starts. If you change either one, restart the management backend and the ingest service. Changing the secret invalidates every device credential until each device syncs again.

Local Docker Desktop installs do not start the collector. To run it locally, add --profile client-telemetry to the compose command and set a token in .env.

Turn it on

1. Open Endpoint Guard → AI Assistants and tick Collect AI assistant usage. The page warns you if the install has no collector address and token.
2. Check Claude Code and Codex CLI in the assistant list. These are the two tools that can send usage. The other assistants are route-only.
3. Endpoint Guard and the VS Code extension write the settings for each checked tool on their next sync: Claude Code's ~/.claude/settings.json (the env block) and Codex's ~/.codex/config.toml (an [otel] section). Existing settings in those files are kept. If config.toml already has its own [otel] section, Cortega leaves it alone and reports that usage was not written. Restart the tool if it was running.
4. Unticking the box, or unchecking a tool, removes only what Cortega wrote.

Collect prompts, responses and tool use

Collect prompts, responses and tool use sits under the usage checkbox and needs it ticked. It makes Claude Code and Codex send the text of the work, not only the counts. This can include source code, commands, file contents and anything a developer types, so tell developers before you turn it on.

Tool	What is collected	Setting Cortega writes
Claude Code	Prompt text, assistant response text, and tool arguments (commands, file paths, search patterns)	OTEL_LOG_USER_PROMPTS=1, OTEL_LOG_ASSISTANT_RESPONSES=1, OTEL_LOG_TOOL_DETAILS=1 in ~/.claude/settings.json
Codex	Prompt text, tool arguments and tool output. Codex does not export response text.	log_user_prompt = true in the [otel] section of ~/.codex/config.toml

The ingest service sets a content flag for the collector from the tenant's setting, and the collector keeps the text fields only when that flag is set. Without it, the collector deletes prompt, prompt_text, response, tool_parameters, tool_input, command_name, arguments, output and body from every log record before it is stored. Codex sends tool arguments and tool output with every tool result, so this deletion is what keeps them out of storage when the box is off.

Claude Code truncates text over 60 KB. Claude Code tool output is not collected, because it is only available in traces, which the client collector does not take. Devices pick up a change at their next sync, and a tool that is already running keeps its old settings until it is restarted. Neither tool offers scrubbing of secrets in this text.

Read the text

Endpoint Guard → AI Assistant Conversations lists each developer's Claude Code and Codex sessions, newest first. Pick one to read its prompts, the assistant's responses and the tool calls in time order. Filter by time window, tool or developer email. A tool call opens to show its arguments and output.

The page needs the data:pii:view permission, which the admin role has and the other roles do not, plus the observability screen. Every list and every conversation opened is written to the audit log with who opened it. A tenant sees only its own developers' sessions.

A record shows "Text was not collected" with the length the tool declared when the developer's tenant had the box off at the time, or the tool had not yet restarted with the new settings. Codex sends no response text, so its sessions show prompts and tool calls only. Claude Code tool output is not collected.

If routing is off, the VS Code extension configures usage only and leaves the tool's own login in place. Unticking Collect AI assistant usage while routing is off makes the extension remove the settings it wrote at its next sync. It never switches the tools onto the gateway. The extension fetches its settings every 30 minutes and when you run Sync AI tools, so a change can take up to 30 minutes to reach a developer's files, and a tool that is already running may keep sending until it is restarted. If the extension is signed in to a tenant that has never set Collect AI assistant usage, it behaves as before and routes through the gateway.

Collect repository inventory

Collect repository inventory is a checkbox on Endpoint Guard → AI Assistants. It is off by default. When on, Cortega AI Booster Pack reports the Git repositories in the signed-in editor and scans that user's home directory. The AI Booster app scans the same home from the signed-in user session. The Endpoint Guard agent also scans when it can read local profiles. Cortega stores the local path, remotes, organization, branch, Git identity, and working-tree state. Source code is not uploaded. Public or private visibility is not classified.

1. Open Endpoint Guard → AI Assistants and tick Collect repository inventory.
2. In VS Code or Cursor, sign in to Cortega AI Booster Pack and run Sync AI tools. Sync uploads open workspaces, then walks the home directory for other Git checkouts.
3. If AI Booster is installed, keep the app signed in. Settings shows Repository inventory under Telemetry when the checkbox is on. The app uploads after the next refresh, about every 15 minutes.
4. Open Endpoint Guard → Developer repositories. The page needs Observability and PII view. Click a row for the full local path, remotes, and Git identity. AI Booster Pack rows are labeled AI Pack. Rows from the AI Booster app or the Endpoint Guard agent are labeled Endpoint Guard.

A change can take up to 30 minutes to reach Cortega AI Booster Pack unless you run Sync. The AI Booster app and Endpoint Guard upload after the next scan (first scan shortly after the setting is on, then a refresh about every 15 minutes).

Read the report

Open Endpoint Guard → AI Assistant Usage. Each developer row includes combined session, estimated cost, and token totals for Claude Code and Codex. Totals with unpriced Codex models carry an asterisk and exclude those models from estimated cost. It lists each developer with Claude Code and Codex usage for the last 7, 30 or 90 days. A developer whose email is not a Cortega user in the tenant is marked. A table splits usage by model, and each developer row opens to show that developer's models. Claude Code reports its own cost estimate. Codex reports none, so Cortega computes one from its token counts and the lowest list price for the model in the rate catalog. Both are API-equivalent estimates and neither is a charge on a subscription. A model with no catalog price shows "no price", not $0. Cursor is not included.

The same data is available to scripts at GET /api/v1/analytics/coding-tools/usage with an API key that has the analytics:read scope.

Each device sends its own credential, minted for the developer's email (the one they enrolled or signed in with) and their tenant. The ingest service reads the tenant and the person from that credential and sets them on every record. The tools send no identity headers, and any X-Cortega-* header a tool sends is discarded. A credential works only for its own person and tenant, and only while the tenant has usage collection on. The install secret that signs credentials is never given to a device. A credential stolen from one laptop can send data as that one developer and no one else.

How traffic reaches the agent

The agent does not attach to Chrome, ChatGPT, or Claude. Packaged install starts it with --system-proxy, which:

• Points OS HTTP and HTTPS proxies at 127.0.0.1:8888.
• Turns PAC / Auto Proxy off so a leftover PAC URL cannot override that.
• Does not turn on the OS SOCKS checkbox. A SOCKS5 listener still listens on 127.0.0.1:1080 for clients you point at it yourself.

Anything that honors those HTTP(S) settings then opens TCP to loopback and sends CONNECT to the destination host. The agent decrypts only Apps Observe / Police hosts. Unlisted hosts still reach the agent and are tunneled (encrypted, no capture). Block hosts are dropped.

System-proxy coverage: clients such as curl and Claude Code may ignore OS proxy settings. Use Endpoint Guard → AI Assistants for automatic AIBG configuration of supported tools (including Claude Code), or configure their gateway endpoint and key manually. On macOS, Endpoint Guard does not set HTTP_PROXY / HTTPS_PROXY. Assistant configuration is separate from proxy interception.

AI Query Log: Target is the HTTP host of that request, not a guess from the prompt. App undetected plus kind other means the classifier did not treat the call as a chat/MCP send — PID labeling is skipped for other. The UI hides the URL path; dump GET http://127.0.0.1:7878/api/captures to see url, host, kind, app. ChatGPT.app on macOS uses the HTTP proxy (:8888), not SOCKS. The bundled codex app-server ignores the OS proxy unless ~/.codex/config.toml has [features] respect_system_proxy = true (singular). Fully quit and reopen ChatGPT.app after that change. Edge does not write that file yet.

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 Booster 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.

Bulk enrollment via the Edge API

The Enrollment and Seats screens are also a REST API, so a provisioning, MDM, or asset-management system can enroll a fleet without the console. The full reference is the Edge API.

Issue a key under System → API Access with the edge:write scope, or edge:read for a key that only lists CAs and devices. Send it as a bearer token: Authorization: Bearer crt_....

Headless Endpoint Guard:

1. Create one enrollment CA:

   curl -X POST -H "Authorization: Bearer $CORTEGA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name":"Fleet CA","generate_cortega_ca":true}' \
     "https://$CORTEGA_HOST/api/v1/edge/enrollment/cas"

2. Mint one identity per device:

   curl -X POST -H "Authorization: Bearer $CORTEGA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"device_id":"LT-0423","email":"[email protected]","name":"Alice MBP"}' \
     "https://$CORTEGA_HOST/api/v1/edge/enrollment/cas/$CA_ID/client-certs"

   Write the response's identity_pem to the machine and set cortega_url in the local config. The service registers itself on startup. No console step per device.

Adding a device in the console

In Endpoint Guard → Seats → Add Device, Tenant 0 administrators with cross-tenant management permission choose the target Tenant by name from a dropdown. Other tenants do not see this field: enrollment stays in their own tenant, and the backend rejects cross-tenant requests even if a platform permission was accidentally granted to that caller. For certificates, the Enrollment CA list is filtered to the target tenant; the certificate's tenant must match its CA.

Cortega URL is pre-filled from the install's CORTEGA_APP_ORIGIN when set, including a public Cloudflare hostname or load-balancer address. AWS deployment scripts carry the resolved app origin into the runtime environment for both single-node and multi-node installs. If no origin is configured, the form uses the browser's current origin. The public app proxy supports the SSO enrollment routes, so invitations may use that address. The field remains editable: confirm the address is reachable from the device, and override it for a separate enrollment ingress or local testing. A localhost URL reaches the device's own machine, so use a reachable hostname or IP for remote devices. Certificate enrollment additionally needs a TLS ingress that forwards the client identity.

AI Booster is tied to a person, so mint one invitation per user and distribute the links:

curl -X POST -H "Authorization: Bearer $CORTEGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","cortega_base_url":"https://cortega.company.internal"}' \
  "https://$CORTEGA_HOST/api/v1/edge/sso/invitations"

The user pastes the invite_url into the app's Enterprise Sign in tab and completes SSO. Domain-matched SSO needs no API call.

To reconcile, list devices with GET /api/v1/edge/agents and remove one with DELETE /api/v1/edge/agents/{id}. Listing needs only edge:read. A certificate-enrolled device can re-enroll after deletion unless you also disable its CA with PUT /api/v1/edge/enrollment/cas/{id}/trust.

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 → Seats.

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 → Seats.

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 → Seats, 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 → Seats 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 Seats 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 → AI Assistants	Detects local AI assistants (Claude Code, Codex CLI, OpenCode, Pi, Cursor, Goose, Aider, Continue) on enrolled devices and points the checked ones at AIBG with a per-device Cortega API key.
Endpoint Guard → Apps	Catalog apps (Claude, ChatGPT, …) with action observe, police, or block. Cortega expands each app to its surface domains. Observe/Police hosts are decrypted; block is dropped. Hosts not in Apps still reach the local HTTP proxy and are tunneled (no decrypt, no capture).
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 Booster 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 Seats 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.
Codex CLI: model metadata for a team name not found	An earlier Endpoint Guard build wrote the team name or a catalog model id as Codex model. Current Endpoint Guard leaves the user's Codex model in place and strips leftover catalog ids. Restart Endpoint Guard after this agent update, then quit and reopen Codex.
Codex CLI still uses a leftover catalog model after unchecking Codex	Unchecking Codex CLI removes the Cortega provider table. An earlier build could leave a catalog model line behind, so Codex kept sending that id to OpenAI. Restart Endpoint Guard after this agent update so the next tick deletes that leftover line.
Codex CLI: this model doesn't support tool use in streaming mode	Codex always streams tool calls on the Responses API. Point the coding-assistant identity's team router at a model whose provider accepts tools on a streaming Responses request (typically OpenAI GPT). Qwen and many Bedrock / OpenAI-compat models reject that combination even when Codex model is a GPT id, because the gateway still team-routes the request.
(Windows) Install/activate fails with an access-denied error	The install/activate/import-identity/uninstall scripts all need an elevated (Administrator) PowerShell session.

Seats on shared machines

Each Seats row is one person on one machine. Several people may enroll the same Mac or Windows machine; each takes a seat and has a separate registration and refresh credential. A reinstall reuses the person's hardware-serial registration. Deleting one row frees only that person's seat; the other people's registrations on that machine remain. Deleting a user removes that user's seats. The license's Edge seats limit counts these person-device pairs.

Disabled or purged tenants cannot enroll, mint or refresh tokens, poll config, or read Edge usage/research. These calls return 403 tenant_inactive with "your organization's account is not active". Already-issued short-lived Edge tokens expire normally; contact the organization’s administrator for help. A disabled tenant's domain remains claimed until tenant purge.

VS Code registrations

AI Booster Pack sign-in registers the computer in Seats, labeled VS. It uses VS Code's computer ID and the signed-in user's identity, so signing in again on the same computer reuses the seat. Another person on that computer, or the same person on another computer, uses another seat. These registrations count against Endpoint Guard / AI Booster tenant capacity and installation Edge seat limits. Deleting a registration allows the next sign-in or sync to recreate it. Disable the account to block further registrations.

VS Code configures supported AI tools. Machine-wide TLS inspection and proxy enforcement require the native Endpoint Guard agent. VS registrations do not show CA trust prompts. If the extension shows needs repair, click its status bar and choose Show status and repair details, or open the Cortega AI Booster Pack Output channel. Use Sync AI tools with Cortega to restore settings. Claude Code and Codex configuration files are shared by editor windows and native clients under the same OS user; a different account's sync can replace them.

Endpoint Guard navigation starts with Getting Started, Seats, and Enrollment. Agent groups Apps, Observability, and Guardrails. Routing groups AI Assistants, AI Assistant Usage, and AI Assistant Conversations. AI Assistants opens assistant configuration.

On-prem multi-tenant deployments

Multi-tenancy is supported on customer infrastructure. Enable CORTEGA_MULTI_TENANCY_ENABLED=true, provision active tenants and their product/seat entitlements, then configure tenant IdPs, registration domains, invitations or Enrollment CAs. Existing users resolve to their assigned tenant before domain matching. Use explicit users/invitations/certificates when tenants share a domain.

AI Booster's native app is the successor to the AI Verifier desktop product. Enter your app origin or invitation in Enterprise sign-in. The VS Code AI Booster Pack also registers a seat, labelled VS, and may consume an additional registration on the same workstation. See On-prem multi-tenant setup for the .env, DNS/TLS, nginx routes, callback URLs and capacity checks needed before enrollment.