macOS Troubleshooting

Validate and troubleshoot an AI Endpoint Shield installation on macOS — version, LaunchAgents, config, logs, hooks, and the common failure modes.

Overview

This page covers post-installation validation and troubleshooting of AI Endpoint Shield on macOS — checking the version, LaunchAgents and processes, where config lives, the logs the agent writes, verifying IDE hooks, and common fixes. Use it if Akto was installed but is not sending data, or stopped working after a restart.

Everything below is read-only unless a section says otherwise — safe to run at any time without disrupting a working install.

Run the commands as the signed-in user, in Terminal. A few checks note where sudo is needed. If you run them over SSH as root, path checks will look at /var/root instead of the user's home and report false negatives.

30-second health check

Paste this into Terminal:

BIN=/usr/local/bin/akto-endpoint-shield

echo "--- Version ---"
"$BIN" --version 2>&1

echo "--- Config status ---"
"$BIN" check-config --path ~/.akto-endpoint-shield/config 2>&1

echo "--- Services ---"
launchctl list | grep akto-endpoint-shield || echo "(none loaded)"

echo "--- Processes ---"
ps aux | grep -E "akto-endpoint-shield" | grep -v grep || echo "(none running)"

A healthy result looks like:

• A version string (e.g. akto-endpoint-shield version v1.1.134), not an error

• Config status prints provisioned

• Both io.akto.akto-endpoint-shield and io.akto.akto-endpoint-shield-agent listed, each with a PID in the first column — not -

• At least one akto-endpoint-shield process

If any of these don't match, keep reading — the matching section explains what to check, and Common issues and fixes has a symptom → fix table.

Checking the installed version

/usr/local/bin/akto-endpoint-shield --version

This prints immediately, before anything else the agent does, so it works even if config or the network is broken. If it errors instead of printing a version, the binary is missing, quarantined, or the wrong architecture — see Install location and files.

Install location and files

Path	Purpose
/usr/local/bin/akto-endpoint-shield	Main binary
/usr/local/lib/akto-endpoint-shield/	Bundled runtime (includes the mitmproxy virtualenv when the optional system proxy is enabled)
/Library/Application Support/Akto/	Asset bundle installed by the pkg (hooks, scripts, config seed; also where identity.json is staged, see Custom Device Name and Email)
~/.akto-endpoint-shield/	Per-user tree — bin/, hooks/, config/, logs/

Presence and trust check:

BIN=/usr/local/bin/akto-endpoint-shield
ls -l "$BIN"
file "$BIN"                                   # architecture
shasum -a 256 "$BIN"                          # hash, for EDR allowlisting
xattr -p com.apple.quarantine "$BIN" 2>/dev/null && echo "QUARANTINED" || echo "no quarantine attribute"
codesign -dvv "$BIN" 2>&1 | grep -E "Authority=|TeamIdentifier="
spctl -a -vvv "$BIN" 2>&1 | head -3

• Quarantine attribute present — Gatekeeper may refuse to run it. Clear it:

  sudo xattr -dr com.apple.quarantine /usr/local/bin/akto-endpoint-shield

• x86_64 only on an Apple Silicon Mac — the binary needs Rosetta 2:

  softwareupdate --install-rosetta --agree-to-license

  Current Akto builds are universal, so this points at a stale install.

• spctl rejects it — the notarization ticket is missing or a security tool is intercepting. Reinstall from the Akto-provided pkg.

Also confirm the pkg receipt is on the machine:

pkgutil --pkgs | grep -i akto
pkgutil --pkg-info io.akto.akto-endpoint-shield

Provisioning markers

The agent writes marker files after it finishes first-run provisioning. Missing markers mean it never completed setup, which is why hooks aren't installed:

ls -1 ~/.akto-endpoint-shield/.assets-synced-* ~/.akto-endpoint-shield/.hooks-installed-* 2>/dev/null || \
  echo "no provisioning markers — first-run provisioning did not complete"

Root misinstall

If the pkg was installed by hand with sudo installer -pkg ... rather than through MDM, the postinstall runs as root and drops everything into root's home instead of the user's:

sudo ls -d /var/root/.akto-endpoint-shield /var/root/.claude 2>/dev/null && \
  echo "ROOT MISINSTALL — files landed in root's home"

Fix by removing /var/root/.akto-endpoint-shield and re-running the install through your MDM policy, or by launching the pkg as the signed-in user.

LaunchAgents and services

Akto runs as LaunchAgents in the user's GUI session — there are no system daemons for the core services.

Label	What it does
io.akto.akto-endpoint-shield	Local HTTP service the agent and hooks use internally
io.akto.akto-endpoint-shield-agent	Main background agent — heartbeats to the dashboard, applies config/policy changes, keeps IDE hooks up to date
io.akto.akto-endpoint-shield-detector	Detects which AI tools/IDEs are installed
io.akto.akto-endpoint-shield-system-proxy	Optional system-wide HTTPS inspection proxy (LaunchDaemon; only if your organization has it enabled)

Their plists live in ~/Library/LaunchAgents/. Check status:

launchctl list | grep akto-endpoint-shield

The first column is the PID and the second is the last exit status:

Output	Meaning
1234 0 io.akto...	Running normally
- 0 io.akto...	Loaded but not running — most often BTM approval, see below
- 78 io.akto...	Exited with an error — check the logs
(nothing listed)	The plist was never loaded — reinstall, or bootstrap manually

Check the plists themselves:

for p in ~/Library/LaunchAgents/io.akto.akto-endpoint-shield*.plist; do
  echo "--- $p"
  /usr/libexec/PlistBuddy -c "Print :ProgramArguments" "$p" 2>/dev/null
  /usr/libexec/PlistBuddy -c "Print :RunAtLoad" "$p" 2>/dev/null
  grep -q '%USER%' <(grep '<string>' "$p") && echo "  ERROR: %USER% placeholder was never replaced"
done

RunAtLoad must be true, and the referenced binary must exist. A literal %USER% or a /Users/root/ path in a <string> value means the install ran without a console user — re-run it at login.

Restart the services (after a config change, or to force a hook re-check):

launchctl bootout gui/$(id -u)/io.akto.akto-endpoint-shield 2>/dev/null
launchctl bootout gui/$(id -u)/io.akto.akto-endpoint-shield-agent 2>/dev/null
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/io.akto.akto-endpoint-shield.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/io.akto.akto-endpoint-shield-agent.plist
launchctl list | grep akto-endpoint-shield

See why a loaded service isn't running:

launchctl print gui/$(id -u)/io.akto.akto-endpoint-shield-agent 2>/dev/null |
  grep -E "state|pid|last exit|throttle|runs"

Background items (BTM approval)

macOS 13 and later require every LaunchAgent label to be approved as a background item before launchd will start it. This is separate from code signing and notarization: a fully signed, notarized install can sit loaded, never running, with zero logs forever if BTM hasn't approved the label.

This is the most common cause of "installed successfully, but nothing happens" on modern macOS.

# Is Akto registered with BTM, and is it enabled?
sudo sfltool dumpbtm 2>/dev/null | grep -i -A 12 akto

# Same view via system_profiler
system_profiler SPBackgroundTaskManagementDataType 2>/dev/null | grep -i -A 8 akto

# Is an MDM pre-approval profile installed?
sudo profiles show -type configuration 2>/dev/null | grep -i servicemanagement

In sfltool dumpbtm output, look at the Disposition: line. [enabled, allowed, notified] is healthy; [disabled, ...] or a pending/requires-approval state means launchd will not start the service.

Fixes, in order of preference:

1. MDM profile (fleet-wide, no user prompt) — deploy a com.apple.servicemanagement configuration profile from Jamf, Mosyle, or your MDM that pre-approves Akto's Team Identifier. Contact Akto for the Team Identifier and a sample payload.

2. Manual approval (single machine) — open System Settings → General → Login Items & Extensions → Allow in the Background, find the Akto Endpoint Shield entry, and turn the toggle on.

To see what the system logged around install time:

log show --predicate 'subsystem == "com.apple.backgroundtaskmanagement" OR process == "syspolicyd"' \
    --last 1h 2>/dev/null | grep -i "akto\|approv\|denied\|background item"

Running processes

ps aux | grep -E "akto-endpoint-shield|mitmdump" | grep -v grep

You should normally see two or three akto-endpoint-shield processes. If nothing appears:

• Restart the services (command above) and re-check after a few seconds.

• If a process appears and disappears within seconds every time, something is killing it — most commonly an antivirus/EDR tool. See Security software conflicts.

To see the exact startup error, run the binary in the foreground:

/usr/local/bin/akto-endpoint-shield http

Read the first few lines, then press Ctrl+C. Common messages:

Message	Meaning / fix
AKTO_API_TOKEN is not set	Config missing or unreadable — see Config values and location
AKTO_API_BASE_URL is not set	Same as above
address already in use	Another Akto process holds the port — pkill -f akto-endpoint-shield, then restart the services
failed to install mitmproxy	No internet access during install — check network and re-run the installer

Don't use the legacy wrapper (~/.akto-endpoint-shield/bin/akto_endpoint_shield.sh) for this test. It only reads plaintext config and reports a false "config not found" on any device with encrypted config. Run the binary directly.

Listening ports

lsof -nP -iTCP -sTCP:LISTEN | grep -iE "akto|mitmdump"

If nothing is listening but processes exist, the service failed to bind — run the foreground test above to see the bind error.

Config values and location

Akto stores its configuration (your account token, dashboard URL, and feature switches) encrypted on disk, keyed to this Mac's hardware IOPlatformUUID. The file is not human-readable, and only this machine can decrypt it.

Where	Path
Your user profile	~/.akto-endpoint-shield/config/config.env.enc
Root (only if misinstalled)	/var/root/.akto-endpoint-shield/config/config.env.enc

On a device that hasn't been updated in a while you may instead see a plain config.env — same idea, older format, still supported. If both exist, the agent reads the encrypted one; the plaintext copy should have been removed at migration and is safe to delete.

Check whether config is present and valid (does not print any secret values):

/usr/local/bin/akto-endpoint-shield check-config --path ~/.akto-endpoint-shield/config

Output	Exit code	Meaning
provisioned	0	Healthy — token and settings are present and readable
not-provisioned	2	Device was never given credentials — re-run the installer with your Akto token
undecryptable	3	Config exists but can't be decrypted (restored from another Mac's backup, or a logic-board swap) — this device must be reinstalled, it cannot be repaired in place

Read specific non-secret values, e.g. to confirm which dashboard this machine reports to:

/usr/local/bin/akto-endpoint-shield get-config --path ~/.akto-endpoint-shield/config \
    AKTO_API_BASE_URL AGENT_ID DATABASE_ABSTRACTOR_SERVICE_URL

Do not run get-config ... AKTO_API_TOKEN and paste the output anywhere — screenshots, tickets, chat. That value is your account's secret credential. Akto support can verify it against your account without you ever displaying it.

Config keys you may be asked about:

Key	What it is
AKTO_API_TOKEN	Your organization's Akto account credential (secret — never share)
AKTO_API_BASE_URL	Your Akto dashboard's URL for this account
AGENT_ID	This device's unique identifier, shown on the Akto dashboard
ENABLE_PROMPT_HOOKS_* / ENABLE_MCP_HOOKS_*	Per-IDE switches for whether guardrail hooks are installed (on by default)
ENABLE_SYSTEM_PROXY	Whether the optional system-wide HTTPS proxy is on (off by default)
AKTO_TCC_GUARD	Whether the agent skips Desktop/Documents/Downloads to avoid TCC prompts

Permissions should be 600:

ls -la ~/.akto-endpoint-shield/config/

Token mismatch between profiles. If a root misinstall left a second config behind, the two can carry different tokens and produce intermittent 401s:

/usr/local/bin/akto-endpoint-shield check-config --path /var/root/.akto-endpoint-shield/config 2>/dev/null \
  && echo "A root-profile config also exists — see Root misinstall above"

Device identity

Useful when a device is installed and healthy but doesn't show up on the dashboard, or shows up twice.

UUID=$(ioreg -rd1 -c IOPlatformExpertDevice | awk -F'"' '/IOPlatformUUID/{print $4}' | tr -d '-' | tr 'A-Z' 'a-z')
NAME=$(scutil --get ComputerName | tr 'A-Z' 'a-z' | sed 's/[^a-z0-9]/-/g')
echo "${NAME}-${UUID:0:8}"

This should match the device label shown for this machine in the Akto dashboard, unless you've overridden it with an identity.json file (see Custom Device Name and Email). A Mac restored from another machine's image inherits that machine's UUID, which both collides on the dashboard and makes the encrypted config undecryptable — it needs a reinstall.

Logs

All logs below are plain text.

Log	Location	What's in it
Install log (user)	~/.akto-endpoint-shield/logs/install.log	Step-by-step output of the last install/update, including every IDE hook installer's own output
Install log (root context)	/var/log/akto-endpoint-shield-install.log	What the MDM script and pkg postinstall did, before a user profile was detected
Agent	~/.akto-endpoint-shield/logs/agent.log	Main agent runtime — heartbeats, config reloads, hook maintenance
HTTP service	~/.akto-endpoint-shield/logs/proxy-server.log	Local HTTP service runtime
Detector	~/.akto-endpoint-shield/logs/detector.log	AI tool/IDE detection runs
System proxy	/var/log/akto-endpoint-shield/system-proxy.log	Only present if the optional proxy feature is enabled
OpenCode plugin	~/.config/opencode/akto/logs/akto-guardrails.log	OpenCode guardrail plugin activity

View recent activity:

tail -50 ~/.akto-endpoint-shield/logs/agent.log
tail -f ~/.akto-endpoint-shield/logs/*.log

Hook installation output goes into install.log, prefixed with each installer's script name — there is no separate file per IDE:

grep -i "hook" ~/.akto-endpoint-shield/logs/install.log

Hook execution (prompt block/allow) decisions are recorded on the Akto dashboard, not in a local file.

These logs never contain your API token — safe to share with Akto support without redacting anything.

Verifying IDE hooks

Akto installs guardrail hooks into each supported IDE/CLI so it can inspect prompts and tool calls. Check whichever tools you use:

Tool	Check
Claude Code	jq '.hooks | keys' ~/.claude/settings.json
Cursor	jq '.hooks.beforeSubmitPrompt' ~/.cursor/hooks.json
Gemini CLI	grep -i akto ~/.gemini/settings.json
Codex CLI	grep -i akto ~/.codex/config.toml
GitHub Copilot CLI	ls ~/.copilot/hooks/
VS Code Copilot	ls ~/.vscode/copilot/hooks/akto/
Kiro CLI	ls ~/.kiro/hooks/akto/
OpenCode	ls ~/.config/opencode/plugin/akto-guardrails-plugin.js

A JSON block or a matching line means the hook is installed. Nothing means that tool's hooks weren't installed — because the tool wasn't detected on the machine, its feature switch (ENABLE_PROMPT_HOOKS_*, see Config values and location) is off for your account, or first-run provisioning never completed (see Provisioning markers).

Check that registered hook commands actually point at files that exist — a common failure after manual edits to IDE settings:

jq -r '.. | .command? // empty' ~/.claude/settings.json 2>/dev/null | grep -i akto | while read -r cmd; do
  f=$(echo "$cmd" | awk '{for(i=1;i<=NF;i++) if ($i ~ /\.sh$/) {print $i; exit}} END{}')
  f=${f/#\~/$HOME}
  [ -f "$f" ] && echo "OK      $f" || echo "MISSING $f"
done

Hook commands should use absolute paths. A leading ~ is not expanded when bash runs non-interactively, so a ~/-prefixed hook command fails silently.

If hooks worked before and stopped working, the background agent re-checks and restores them automatically — wait for its next check-in cycle (typically a few minutes), or restart the agent service to force it immediately.

System-wide proxy (optional)

Some accounts have an optional feature enabled where Akto routes AI-tool traffic through a local HTTPS-inspecting proxy. This only applies if your organization has turned it on.

ls -l /usr/local/lib/akto-endpoint-shield/venv/bin/mitmdump 2>/dev/null || echo "system proxy not installed"
ls -l /var/lib/mitmproxy/mitmproxy-ca-cert.pem 2>/dev/null
security find-certificate -c mitmproxy /Library/Keychains/System.keychain >/dev/null 2>&1 \
  && echo "mitmproxy CA trusted" || echo "mitmproxy CA NOT in System keychain"

# Which proxy the active network service is pointed at
SVC=$(networksetup -listallhardwareports | awk -v d="$(route get default 2>/dev/null | awk '/interface/{print $2}')" \
  '/^Hardware Port:/{n=substr($0,index($0,":")+2)} $0 ~ ("Device: " d "$"){print n; exit}')
networksetup -getsecurewebproxy "$SVC"

If mitmdump isn't installed and no certificate is listed, the feature is simply not enabled for your account — this is normal and not an error.

If it is enabled but tools warn about an untrusted certificate, re-import the CA:

sudo security add-trusted-cert -d -r trustRoot \
    -k /Library/Keychains/System.keychain /var/lib/mitmproxy/mitmproxy-ca-cert.pem

Security software conflicts

Antivirus and EDR products are a common cause of "installed, but nothing runs". Enumerate what's present:

PAT='crowdstrike|falcon|sentinelone|carbonblack|defender|mdatp|sophos|malwarebytes|trendmicro|cylance|trellix|xagt|netskope|zscaler|umbrella|tanium|forcepoint|santa|littlesnitch|kolide'

ps axo user,pid,comm | grep -iE "$PAT" | grep -v grep | grep -v /System/
ls -1 /Applications | grep -iE "$PAT"
systemextensionsctl list 2>/dev/null | grep -iE "$PAT"
ls -1 /Library/LaunchDaemons /Library/LaunchAgents 2>/dev/null | grep -iE "$PAT"

Also check the OS-level gates:

spctl --status                                                    # Gatekeeper
csrutil status                                                    # SIP
/usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate   # Application Firewall

If a security tool is present and the binary keeps being killed or quarantined, add the exclusions in Allowlist in Security Software and give your security administrator the SHA256 hash from Install location and files.

Folder access (TCC) prompts

macOS may prompt for access to Desktop, Documents, and Downloads. These are optional — the agent works without them, but MCP-related file scanning coverage is reduced.

If the prompts were declined and you want to grant access later, open System Settings → Privacy & Security → Files and Folders and enable the folders for Akto Endpoint Shield. To suppress the prompts entirely fleet-wide, set AKTO_TCC_GUARD=true (the default in MDM deployments) or deploy a PPPC configuration profile from your MDM.

Common issues and fixes

Symptom	Likely cause	Fix
Services show - instead of a PID, no logs at all	macOS 13+ background item not approved	Background items (BTM approval)
Device not appearing on the dashboard	Not provisioned, or the agent isn't running	Run check-config; see Config values and location
Services loaded but exit immediately	Missing token, port conflict, or EDR	Foreground test in Running processes
Binary won't execute at all	Quarantine attribute, or an x86_64-only binary on Apple Silicon	Install location and files
Files ended up in /var/root	Installed manually with sudo installer instead of via MDM	Root misinstall
check-config reports undecryptable	Mac restored from another machine's image, or a logic-board swap	Reinstall — this can't be repaired in place
A specific IDE's hooks aren't showing up	Tool not detected, feature flag off, or provisioning incomplete	Verifying IDE hooks
Hooks registered but silently do nothing	Hook command uses ~ instead of an absolute path	Verifying IDE hooks
Everything worked, then stopped after a restart	RunAtLoad false, or BTM approval revoked	LaunchAgents and services, then BTM
Repeated 401 errors in agent.log	Stale or duplicate config	Config values and location
Device shows up twice, or under the wrong name	Machine cloned from another device's image	Device identity

Full automated diagnostic

For a single comprehensive report covering everything above plus security-software conflicts, BTM state, Jamf staging, and install-time forensics:

1. Get diagnose_mac.sh from Akto support (it is also included in the installer package).

2. Run it and save the output:

   bash diagnose_mac.sh > ~/Desktop/akto-diag.txt 2>&1

3. Send ~/Desktop/akto-diag.txt to Akto support.

The script only reads information from your machine — it makes no changes — and never prints your API token.

Reinstall / uninstall (last resort)

If nothing above resolves the issue:

1. Run the uninstall script provided by Akto (uninstall.sh), or trigger the uninstall policy from your MDM's Self Service.

2. Restart the Mac.

3. Re-run the install through your MDM policy, or the installer package provided by your IT team.

4. Wait 2–3 minutes, then check the dashboard for the device to reappear.

If the problem persists after reinstall, run the diagnostic above and send the report to Akto support along with what you observed.

Related documentation

• Windows Troubleshooting — the same checks for Windows

• Allowlist in Security Software — antivirus and EDR exclusions

• Custom Device Name and Email: override the auto-detected hostname and username

• macOS Standalone Installation — the end-user install walkthrough

• Jamf MDM Deployment / Mosyle MDM Deployment / NinjaOne Deployment (macOS)

Get support

When contacting Akto support, include the diagnostic report, the installed version, and what you observed and when it started. Never include the raw AKTO_API_TOKEN value in a ticket, chat, or screenshot.

1. In-app Intercom in the Akto dashboard

2. Discord community

3. [e-mail]

4. Contact Akto