Claude Desktop Fleet Configuration

This guide is the headless path for fleet rollout.

Use it when you want policy and endpoint operations driven by CLI/API/GitOps instead of a UI workflow.

For full automation orchestration patterns (CI/CD + API workflows), see GitOps Headless Control Plane.

Choose the right guide

Browser-first architecture

Prerequisites

• Approved release source and trust artifacts (Release Channels + Verification).
• thoth binary available for endpoint runtime.
• thothctl available for control-plane bootstrap.
• admin auth session for the Thoth Control Plane API.
• Chrome Browser Cloud Management in Google Workspace (for managed Chrome rollout).
• MDM delivery path in place (Jamf or Intune).
• Tenant DNS routes reachable (enforce, grid, and control-plane host).

Step 0 — Sign in for admin operations

export THOTH_TENANT_ID="<tenant>"
export THOTH_APEX_DOMAIN="<apex-domain>"
export THOTH_AUTH_SESSION_FILE="$HOME/.thoth/admin-token.jwt"
 
thothctl auth login \
  --tenant-id "$THOTH_TENANT_ID" \
  --admin-email "<admin@company.com>"

--apex-domain and --auth-token-file are optional overrides. For CI/CD automation, you can use org API key auth via THOTH_API_KEY (or --org-api-key).

Step 1 — Bootstrap control-plane settings (headless)

Run this from a secure CI runner or admin workstation:

thothctl bootstrap \
  --tenant-id "$THOTH_TENANT_ID" \
  --compliance-profile soc2 \
  --webhook-url "https://siem.company.com/thoth/events" \
  --test-webhook \
  --mdm-provider jamf \
  --mdm-config-file ./jamf-provider.json \
  --start-sync

For Intune, switch --mdm-provider intune and pass an Intune config JSON.

This command can:

• update tenant policy settings,
• test webhook delivery,
• upsert MDM provider config,
• start MDM inventory sync.

Step 2 — Configure browser control-plane policy (headless)

Use thothctl to manage browser providers, policy bundles, and enrollments:

thothctl browser providers upsert \
  --tenant-id "$THOTH_TENANT_ID" \
  --provider chrome \
  --name "Chrome Enterprise" \
  --config-file ./browser/chrome-provider.json \
  --json
 
thothctl browser policies upsert \
  --tenant-id "$THOTH_TENANT_ID" \
  --provider chrome \
  --name "chrome-baseline-v1" \
  --enforcement-mode enforce \
  --policy-file ./browser/chrome-policy.json \
  --json

For Firefox/Safari/Island, switch --provider and use the matching policy JSON shape.

Step 2A — Sync and apply browser policy on endpoints

Once provider, policy, and enrollment records exist, run endpoint sync:

# Preview (no filesystem writes)
thothctl browser sync \
  --tenant-id "$THOTH_TENANT_ID" \
  --device-id "tim-mac-01" \
  --user-id "tim@example.com" \
  --dry-run \
  --json
 
# Apply managed policy files
sudo thothctl browser sync \
  --tenant-id "$THOTH_TENANT_ID" \
  --device-id "tim-mac-01" \
  --user-id "tim@example.com" \
  --json

browser sync resolves active enrollments for this endpoint, picks the effective active policy per provider, and writes policy artifacts to managed browser policy locations.

Step 3 — Generate governed Claude config artifact

Create a governed claude_desktop_config.json artifact from your base config:

thoth wrap-config \
  --tenant-id "<tenant>" \
  --enforcement-mode block \
  --env THOTH_USER_ID="managed-user@company.com" \
  --env THOTH_APEX_DOMAIN="<apex-domain>" \
  --output governed_claude_config.json \
  base_claude_config.json

Use your normal review process for this file in Git (PR + approvals).

Step 4 — Distribute through Jamf or Intune

Deploy three artifacts through MDM:

1. thoth binary
2. governed_claude_config.json
3. scheduled thothctl browser sync task (LaunchDaemon / Scheduled Task / systemd timer)

Target paths:

Keep tenant/runtime values in managed secrets or profile variables, not in repo plaintext.

Google Workspace admin model (automatic Chrome + cross-browser)

Use Google Workspace Admin for Chrome-managed devices, and MDM for all other browsers.

1. In Google Admin Console, configure Chrome Browser Cloud Management and scope by OU/group.
2. Push Chrome extension policy (ExtensionSettings) and force-install rules for managed Chrome users.
3. Continue using Thoth browser policy records as source-of-truth and run thothctl browser sync in endpoint jobs for Firefox/Safari/Island.
4. For mixed fleets, treat Workspace Admin as Chrome-native control and Jamf/Intune as the cross-browser control plane.

This is the recommended production split:

• Chrome: Google Workspace Admin
• Firefox/Safari/Island: Jamf/Intune/Kandji + thothctl browser sync

Step 5 — Manual enrollment for unmanaged endpoints

For sandboxes or unmanaged hosts:

curl -fsSL https://install.atensecurity.com/thoth | sh
 
export THOTH_TENANT_ID="<tenant>"
export THOTH_USER_ID="analyst@company.com"
export THOTH_APEX_DOMAIN="<apex-domain>"
export THOTH_ENV="prod"
 
CONFIG_PATH="$HOME/Library/Application Support/Claude/claude_desktop_config.json"
 
thoth wrap-config \
  --tenant-id "$THOTH_TENANT_ID" \
  --enforcement-mode block \
  --env THOTH_USER_ID="$THOTH_USER_ID" \
  --env THOTH_APEX_DOMAIN="$THOTH_APEX_DOMAIN" \
  --output "$CONFIG_PATH" \
  "$CONFIG_PATH"

The proxy registers the endpoint and continues periodic check-ins automatically.

Step 6 — Validate health and policy coverage

On endpoint:

thoth health --json
thoth status

Control-plane checks:

# List MDM providers
AUTH="Authorization: Bearer $(cat "$THOTH_AUTH_SESSION_FILE")"
BASE="https://grid.${THOTH_TENANT_ID}.${THOTH_APEX_DOMAIN}/${THOTH_TENANT_ID}/thoth"
 
curl -sS -H "$AUTH" \
  "${BASE}/mdm/providers"
 
# List endpoints
curl -sS -H "$AUTH" \
  "${BASE}/endpoints"

Expected outcomes:

• endpoint registration is healthy,
• governed MCP servers are visible in thoth status,
• policy decisions are consistent with configured mode,
• check-ins continue on schedule.

Native SIEM/PAM integration (no UI dependency)

Use control-plane integration APIs to register and sync platform integrations in automation pipelines.

• Integration create/list/sync routes live under /:tenant-id/governance/integrations.
• MDM providers and sync routes live under /:tenant-id/thoth/mdm/*.
• Browser provider, policy, and enrollment routes live under /:tenant-id/thoth/browser/*.

This lets operations run from CI/CD and existing security tooling instead of a standalone console.

Rollout strategy

Use staged rollout:

1. Canary (1-5 endpoints)
2. Pilot (5-15% of fleet)
3. Full deployment

If behavior regresses, use existing ops playbooks:

• Rollback
• Incident Response