# Kandji macOS Runbook

> Step-by-step Kandji runbook for deploying notarized thoth packages, managed config, and governed Claude Desktop runtime.

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

Use this runbook to deploy Thoth governance to managed macOS endpoints with Kandji.

## 1. Choose release source

Use [Release Channels + Verification](https://docs.atensecurity.com/docs/deployments/release-channels) and select one:

- notarized PKG (`thoth-macos-universal.pkg`) for Kandji package deployment (recommended)
- Homebrew tap for admin bootstrap/testing only

Validate trust artifacts before rollout:

- `checksums.sha256`
- `sigstore-metadata.json` + `*.sigstore.json`
- `sbom.cdx.json` + `sbom.spdx.json`
- `provenance.json`

## 2. Upload package to Kandji

In Kandji:

1. Create/update a Custom App for `thoth-macos-universal.pkg`.
2. Configure auto-update policy tied to your approved release channel.
3. Scope to test devices first.

## 3. Deploy managed runtime config

Deploy `thoth-config.json` to:

`/Library/Application Support/Thoth/thoth-config.json`

Include onboarding values:

- `tenant_id`
- `apex_domain`
- `environment`

Do not hardcode customer values in scripts committed to source control.

## 4. Deploy setup script

Create a Kandji Script item to:

- validate `thoth` and `thothctl` are installed
- wrap `~/Library/Application Support/Claude/claude_desktop_config.json`
- restart Claude Desktop if config changed

Use recurring enforcement to heal drift.

## 5. Optional Santa alignment

If Santa is enabled, apply trust rules from:

- `santa-metadata.json`
- `signing-metadata.json`

See [Santa macOS Trust Policy](https://docs.atensecurity.com/docs/deployments/santa-macos).

## 6. Validate on pilot endpoints

```bash
thoth --version
thothctl --version
thoth health --json
thoth status
```

Also verify:

- `/Library/Application Support/Thoth/thoth-config.json` exists
- Claude config is wrapped and governed
- logs show successful policy checks

## 7. Rollout pattern

1. Test group
2. Pilot group
3. Production scope

Hold rollback package assignment ready before widening scope.

## Troubleshooting

| Symptom | Likely cause | What to check |
|---|---|---|
| `thoth` missing after assignment | Package deployment failed or stale assignment | Kandji Custom App install logs and version pin |
| `registration_ok=false` | Wrong onboarding values or blocked network path | `tenant_id`, `apex_domain`, endpoint egress |
| Claude remains ungoverned | Wrap script did not run or failed | Kandji script logs and Claude config path |
| Drift reappears after reboot | Script is one-shot only | Make script recurring and idempotent |

## Related docs

- [Release Channels + Verification](https://docs.atensecurity.com/docs/deployments/release-channels)
- [Intune Onboarding Overview](https://docs.atensecurity.com/docs/deployments/intune-overview)
- [Jamf Onboarding Overview](https://docs.atensecurity.com/docs/deployments/jamf-overview)
- [Deployment Validation Matrix](https://docs.atensecurity.com/docs/deployments/validation-matrix)