Documentation

How entAI routes requests, and how to configure it by MDM.

Overview

entAI brings your organization's OpenAI-compatible AI service to the Mac. Every request runs on the on-device model first; only what it can't handle goes to the company AI, and only as your MDM policy allows. Two surfaces: a menu bar chat (window + a Spotlight-style Quick Chat opened by double-pressing ⌥) and right-click Services actions on selected text and files.

Requirements

• macOS 26 or later, Apple Silicon only
• 8 GB RAM minimum — the bundled on-device model needs about 2.7 GB free
• An OpenAI-compatible endpoint for cloud escalation (optional — entAI works local-only without one)

Installation & Deployment

1. Install EntAI-1.0.0.pkg — signed and notarized, installs /Applications/EntAI.app (~2.6 GB, including the on-device model).
2. Configure with a profile for domain com.spectrechen.entai, starting from the example profile below. Without a profile, entAI works device-only, and the user can still enter a server themselves in Settings.
3. (Recommended) grant Accessibility via PPPC — see PPPC & Accessibility.
4. Company AI credentials: Entra ID needs no secret; API keys go in the user's keychain — see API Keys.
5. (Optional) add Scripts/ea-entai-usage.sh as a Jamf Extension Attribute or Intune custom attribute — see Usage Statistics.

entAI starts at login with a menu bar icon and no Dock icon. It ships without keyboard shortcuts for its Services entries, so it never overrides shortcuts you already use — users assign their own under System Settings → Keyboard → Keyboard Shortcuts → Services.

How Configuration Works

Every setting is optional. A key set by a configuration profile is locked in Settings (shown with a lock badge); any key you don't set stays user-editable. Booleans accept either <true/> or the string "true". Changes are picked up the next time entAI becomes active — macOS doesn't notify running apps when a new profile lands.

How Routing Works

The local model is chosen per request from the most capable installed model that fits into free memory at that moment — the model itself never decides where it runs, the router does, deterministically. On 8 GB Macs under memory pressure, expect more frequent cloud escalation. The local model loads on first use and unloads after 5 idle minutes.

Company AI (Cloud) Keys

On-Device Model

Larger models can be deployed to /Library/Application Support/entAI/Models/<model-id>. The bundled model is Gemma 4 E2B (text-only, Apache 2.0 licensed).

Chat Settings

Settings → Privacy & Chat — the same CloudPolicy choice and chat history controls, in the UI.

Actions & Custom Actions

Built-in actions, in Services-menu order: summarize, translate, rephrase, improve, fixGrammar, rewriteFormal, rewriteCasual, rewriteConcise, explain, keyPoints, actionItems, draftReply.

The Services menu itself is fixed (Summarize, Translate, Rephrase, Fix Spelling & Grammar, Explain, More Actions…, Ask in Chat; for files: Summarize File, Ask About File, File Actions…) — everything beyond those lives under "More Actions…" / "File Actions…". Disabling a fixed entry still shows it, but tells the user it's disabled rather than just disappearing silently.

Microsoft Entra ID — Setup Steps

entAI authenticates as a public client — OAuth 2.0 authorization code + PKCE via ASWebAuthenticationSession, no client secret, no MSAL. After the first sign-in, tokens refresh silently from the keychain; with the Microsoft Enterprise SSO plug-in and entAI allow-listed, the sign-in sheet completes without a password at all.

1. In the Entra admin center: App registrations → New registration — name it entAI, single tenant.
2. Authentication → Add a platform → Mobile and desktop applications — custom redirect URI msauth.com.spectrechen.entai://auth.
3. Authentication → Advanced settings — set Allow public client flows: Yes.
4. API permissions — for Azure OpenAI directly, add Azure Cognitive Services → user_impersonation and grant admin consent. For your own gateway (e.g. APIM), add the gateway API's own scope instead and set EntraScope accordingly.
5. Note the Application (client) ID and Directory (tenant) ID for the profile below.

For Azure OpenAI, the signed-in user or group also needs the Cognitive Services OpenAI User role on the Azure OpenAI resource itself.

<key>CloudAuthMode</key><string>entraID</string>
<key>EntraTenantID</key><string>contoso.onmicrosoft.com</string>
<key>EntraClientID</key><string>...client id...</string>
<!-- only when routing through a gateway rather than Azure OpenAI directly: -->
<key>EntraScope</key><string>api://.../.default</string>

For silent sign-in via the Microsoft Enterprise SSO plug-in, add entAI to its allow list in the Extensible Single Sign-On payload:

<key>AppPrefixAllowList</key>
<string>com.microsoft.,com.apple.,com.spectrechen.entai</string>

Entra Error Codes

Errors surface with their exact Entra code in both Settings → Company AI and directly in chat. Signing out from Settings → Company AI removes the stored refresh token.

Data & Privacy

PPPC & Accessibility

Recommended: allow Accessibility for com.spectrechen.entai, needed for double-press ⌥ to work in other apps and for Replace to work in text actions. Without it, ⌥⌥ only works inside entAI itself, and Replace falls back to just copying.

anchor apple generic and identifier "com.spectrechen.entai" and certificate leaf[subject.OU] = "23VFRTF5KC"

API Keys

API keys are never stored in configuration profiles — they live in the user's login keychain, service com.spectrechen.entai, account apiKey. A user can paste one into Settings directly, or a script can provision it (run as the user):

security add-generic-password -U -s com.spectrechen.entai -a apiKey \
  -T "/Applications/EntAI.app" -w "$KEY"

Example Profile

The distribution's example profile (Azure OpenAI + Entra ID) demonstrates most of the config surface in one file:

• Company AI: CloudBaseURL, CloudAuthMode=entraID, CloudDefaultModel, CloudModels, CloudDisplayName, CloudPolicy=ask, CloudCostPer1KTokens, plus the matching EntraTenantID/EntraClientID.
• Routing: LocalMaxInputTokens=6000, an ActionRouting entry forcing fixGrammar local.
• Chat: history enabled, 30-day retention, attachments on.
• Custom actions: a "Customer Reply" action tuned to a house tone, and a "Check Contract Wording" action forced to the cloud.

Usage Statistics

Settings → Usage — the same counts the Jamf EA / Intune script reports, right in the app.

Scripts/ea-entai-usage.sh reports, for the console user, from ~/Library/Application Support/entAI/UsageStats.plist — counts only, never content:

<result>local=120 cloud=30 refused=2 localShare=80% localTokens=412000 cloudTokens=98000 since=2026-09-28</result>

Disable collection entirely with UsageStatsEnabled = false.

Troubleshooting

Logs: log show --predicate 'subsystem == "com.spectrechen.entai"' --last 1h --info — routing decisions with token estimates, never content.

Uninstall: sudo Scripts/uninstall.sh (add --purge to also remove each user's history, stats and keychain items).