# macOS Deployment Reference (Jamf)

> Jamf-focused deployment reference for installing, configuring, and validating Thoth MCP Proxy on managed macOS fleets.

Source: https://docs.atensecurity.com/docs/deployments/macos-jamf

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

**Start with Jamf onboarding:**
  For policy sequencing, parameter setup, and rollout workflow, start with
  [Jamf Onboarding Overview](https://docs.atensecurity.com/docs/deployments/jamf-overview) and
  [Jamf macOS Runbook](https://docs.atensecurity.com/docs/deployments/jamf-macos).

**Looking for Intune onboarding?:**
  Use [Intune Onboarding Overview](https://docs.atensecurity.com/docs/deployments/intune-overview) and platform runbooks under Deployments for Intune workflows.

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

```bash
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

| Purpose | URL pattern | Env var |
| --- | --- | --- |
| Control-plane host + API key management | `https://<tenant>.<apex-domain>` | — |
| Endpoint proxy policy checks | `https://enforce.<tenant>.<apex-domain>` | Auto-derived from `THOTH_TENANT_ID` + `THOTH_APEX_DOMAIN` |
| Endpoint registration + check-ins | `https://grid.<tenant>.<apex-domain>` | Auto-derived from `THOTH_TENANT_ID` + `THOTH_APEX_DOMAIN` |

### Runtime Configuration

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

```bash
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.

```bash
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.

```bash
/usr/local/bin/thoth --version
```

7. Validate LaunchDaemon state and install log.

```bash
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:

```bash
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.

```bash
#!/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](https://docs.atensecurity.com/docs/operations/key-rotation)
- [Rollback](https://docs.atensecurity.com/docs/operations/rollback)
- [Incident Response](https://docs.atensecurity.com/docs/operations/incidents)

## What gets installed on your system

| Path | Purpose |
| --- | --- |
| `/usr/local/bin/thoth` | Primary Thoth MCP Proxy executable |
| `/Library/LaunchDaemons/com.atensecurity.thoth.plist` | LaunchDaemon service definition |
| `/Library/Application Support/Thoth/` | Runtime state and policy files |
| `/etc/thoth/` | Configuration directory |
| `/var/log/thoth-install.log` | Installer and postinstall log |

## Verify Deployment

```bash
thoth health --json
```