macOS Deployment Reference (Jamf)

This reference explains how to deploy Thoth MCP Proxy (thoth) to managed macOS endpoints using Jamf Pro.

Quick Start

Use this flow for a pilot rollout in under 10 minutes.

1. Choose install source:
   • curl -fsSL https://install.atensecurity.com/thoth | sh (recommended)
   • Direct release asset from atensecurity/thoth
2. Scope the install policy to a pilot smart group.
3. Deploy a runtime configuration profile with required environment variables.
4. Validate deployment on endpoints.

thoth health --json

Full Deployment Guide

Objectives

• Install Thoth MCP Proxy across managed macOS fleets.
• Start the service automatically at boot with LaunchDaemon.
• Register endpoints and maintain 60-second heartbeat check-ins.
• Push policy updates through managed runtime configuration.
• Maintain auditable operational controls for rotation, rollback, and incidents.

Prerequisites

• Jamf Pro admin access with package/profile/script deployment rights.
• Tenant ID (THOTH_TENANT_ID).
• Fleet-scoped API key material.
• Endpoint labels:
  • THOTH_FLEET_ID
  • THOTH_ENV=prod
  • THOTH_ENROLLMENT_SOURCE=jamf

Endpoint routing contract

Runtime Configuration

Deploy runtime values via managed profiles or managed config files. Do not hardcode runtime values in the LaunchDaemon plist.

THOTH_TENANT_ID=<tenant-id>
THOTH_USER_ID=<user_email_address>
THOTH_API_KEY_FILE=/Library/Application\ Support/Thoth/secrets/proxy_api_key.json
THOTH_API_KEY_ID=<fleet_scoped_key_id>
THOTH_API_KEY_EXPIRES_AT=<ISO8601_UTC>
THOTH_API_KEY_ROTATE_WITHIN_DAYS=7
THOTH_REVOKED_API_KEY_IDS_FILE=/Library/Application\ Support/Thoth/secrets/revoked_key_ids.json
THOTH_APEX_DOMAIN=atensecurity.com
THOTH_GOVAPI_BEARER_TOKEN=<optional_token>
THOTH_GOVAPI_API_KEY_FILE=/Library/Application\ Support/Thoth/secrets/govapi_api_key.json
THOTH_GOVAPI_API_KEY_ID=<optional_govapi_key_id>
THOTH_ENV=prod
THOTH_ENROLLMENT_SOURCE=jamf
THOTH_FLEET_ID=<org>-PROD-PILOT
THOTH_JAMF_COMPUTER_ID=<optional_managed_device_id_override>
THOTH_HEARTBEAT_INTERVAL_SECONDS=60
THOTH_EXPECTED_PROXY_VERSION=<target_release_version>
THOTH_REQUIRE_NON_ROOT=true
THOTH_EXPECTED_PROXY_USER=<dedicated_proxy_user>
THOTH_EXPECTED_PROXY_UID=<dedicated_proxy_uid_optional>
THOTH_POLICY_PROFILE_PATH=/Library/Application\ Support/Thoth/runtime_policy.json
THOTH_POLICY_PROFILE_HMAC_SECRET=<profile_signing_secret>
THOTH_POLICY_PROFILE_ALLOW_UNSIGNED=false
THOTH_ENFORCER_FAILURE_DECISION=step_up

Validation notes:

• Keep THOTH_REQUIRE_NON_ROOT=true in production.
• Use file-backed secrets where possible. If THOTH_API_KEY_FILE is unset, thoth defaults to ~/.thoth/proxy_api_key.json.
• Set THOTH_ENFORCER_FAILURE_DECISION explicitly per environment.
• thoth derives enforcer_url and govapi_url from tenant_id + apex_domain.
• Endpoint identity defaults to managed device ID override (if provided), then OS machine identity, then hostname fallback.
• govapi_url is derived automatically as https://grid.<tenant>.<apex-domain>.

Installation via Jamf

1. Choose install source:
   • Online install script (recommended): curl -fsSL https://install.atensecurity.com/thoth | sh
   • Direct asset from https://github.com/atensecurity/thoth/releases
2. Verify checksum against release checksums.sha256.
3. Ensure final installed binary path is /usr/local/bin/thoth.
4. Scope to pilot devices.
5. Install and validate paths.

ls -l /usr/local/bin/thoth
ls -ld "/Library/Application Support/Thoth" \
  "/Library/Application Support/Thoth/secrets" \
  /etc/thoth
ls -l /Library/LaunchDaemons/com.atensecurity.thoth.plist

6. Validate binary.

/usr/local/bin/thoth --version

7. Validate LaunchDaemon state and install log.

sudo launchctl print system/com.atensecurity.thoth >/dev/null
 
tail -n 50 /var/log/thoth-install.log

Bootstrap + Check-in Validation

On first startup, Thoth MCP Proxy performs endpoint registration and check-in.

Validate endpoint health:

thoth health --json

Expected:

• registration_ok=true or endpoint ok=true
• config_drifted=false
• current_version_ok=true

Fleet SLO:

• Endpoint appears in Fleet view within 60 seconds.

Extension Attributes + Smart Groups

Use a Jamf Extension Attribute script to parse health output and map it to smart groups.

#!/bin/bash
set -euo pipefail
 
HEALTH_JSON="$(/usr/local/bin/thoth health --json 2>/dev/null || echo '{}')"
HEALTHY="$(echo "$HEALTH_JSON" | /usr/bin/python3 -c 'import json,sys; d=json.load(sys.stdin); print(str(d.get("healthy", False)).lower())')"
DRIFTED="$(echo "$HEALTH_JSON" | /usr/bin/python3 -c 'import json,sys; d=json.load(sys.stdin); print(str(d.get("config_drifted", False)).lower())')"
VERSION_OK="$(echo "$HEALTH_JSON" | /usr/bin/python3 -c 'import json,sys; d=json.load(sys.stdin); print(str(d.get("current_version_ok", False)).lower())')"
 
echo "healthy=$HEALTHY drifted=$DRIFTED version_ok=$VERSION_OK"

Suggested smart groups:

• healthy_current_version
• drifted_config
• proxy_unreachable
• outdated_version

Policy Updates (No Repack Required)

Use managed configuration profile updates to push policy changes without rebuilding the package.

• Update enforcement mode inputs, routing tags, and key references.
• Roll out via pilot then progressive waves.
• Validate with thoth health --json before widening scope.
• Runtime policy updates hot-reload from THOTH_POLICY_PROFILE_PATH.
• Enforce signature verification with THOTH_POLICY_PROFILE_HMAC_SECRET.

Operational guides:

• Key Rotation
• Rollback
• Incident Response

What gets installed on your system

Verify Deployment

thoth health --json