# Jamf macOS Runbook

> Step-by-step Jamf Pro runbook for deploying thoth governance to managed macOS endpoints.

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

Use this runbook to deploy governed Claude Desktop configuration to employee Macs through Jamf Pro.

## 1. Before you begin

Confirm:

- onboarding values are available (`tenant_id`, `apex_domain`)
- Claude Desktop is already installed on target Macs
- baseline dependencies (`thoth`, `thothctl`, `node`, `npx`) are available
- package source is approved from [Release Channels + Verification](https://docs.atensecurity.com/docs/deployments/release-channels)

## 2. Upload Jamf scripts

In Jamf Pro, upload your scripts under **Settings → Computer Management → Scripts**.

Recommended naming:

- `Thoth - Prerequisites`
- `Thoth - Deploy Config`
- `Thoth - Setup Claude MCP`

## 3. Configure setup script parameters

Use Jamf Parameters 4-9:

| Parameter | Label | Description | Example | Required |
|---|---|---|---|---|
| 4 | Tenant ID | thoth tenant ID from onboarding | `acme-corp` | Yes |
| 5 | Apex Domain | thoth apex domain from onboarding | `atensecurity.com` | Yes |
| 6 | Agent ID | MCP agent identifier | `filesystem-safe` | No |
| 7 | Allowed Path | Employee filesystem path exposed to MCP server | `/Users/$USERNAME` | No |
| 8 | Environment | Deployment environment | `production` | No |
| 9 | Device ID Override | Optional managed endpoint identity override (`THOTH_JAMF_COMPUTER_ID`) | `corpsec-mbp-001` | No |

**Credential handling:**
  Keep onboarding values in Jamf policy parameters or secure managed files. Do not commit customer values to source control.

## 4. Create policy sequence

Use three policies in order:

1. **Prerequisites**
2. **Deploy Config**
3. **Setup Claude MCP**

Recommended trigger model:

- Enrollment Complete for initial bootstrap
- Recurring Check-in for ongoing drift correction

## 5. Validate on test endpoints

On a scoped test Mac:

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

Also verify:

- Claude config path: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Setup logs: `/var/log/thoth-setup.log`
- Installer logs (if applicable): `/var/log/thoth-install.log`

## 6. Expand rollout

Roll out in phases:

1. Test smart group
2. Pilot smart group
3. Full production smart group

Maintain a rollback policy ready for rapid reassignment if health checks regress.

## Troubleshooting

| Symptom | Likely cause | What to check |
|---|---|---|
| `thoth` not found | Prerequisites policy has not completed | Confirm prerequisites policy execution status in Jamf |
| `registration_ok=false` | Wrong onboarding values or connectivity issue | Validate tenant/apex values and outbound network path |
| Config drift detected | Endpoint config manually changed | Re-run setup policy and verify managed config ownership |
| Setup script exits with non-zero | Missing config or runtime dependency | Check `/var/log/thoth-setup.log` for failing command and path resolution |
| Claude still uses ungoverned tools | Setup policy did not write managed config | Validate target config file and rerun setup policy |

## Related references

- [Jamf Onboarding Overview](https://docs.atensecurity.com/docs/deployments/jamf-overview)
- [macOS Deployment Reference (Jamf)](https://docs.atensecurity.com/docs/deployments/macos-jamf)
- [Claude Desktop Fleet Configuration](https://docs.atensecurity.com/docs/mcp/fleet-deployment)