GitOps Headless Control Plane

Use this section when you want no dashboard dependency for governance operations.

You can run Thoth end to end from CI/CD and platform IaC:

• thothctl for secure bootstrap and updates
• Terraform and Pulumi for declarative rollout
• Argo CD for continuous reconciliation
• GovAPI for programmatic integration workflows

Reference architecture

1) Bootstrap with thothctl

Use thothctl in CI with a file-backed admin bearer token:

thothctl bootstrap \
  --tenant-id "<tenant>" \
  --apex-domain "atensecurity.com" \
  --auth-token-file "/run/secrets/thoth_admin_jwt" \
  --compliance-profile "soc2" \
  --shadow-low allow \
  --shadow-medium step_up \
  --shadow-high block \
  --shadow-critical block \
  --webhook-url "https://siem.company.com/hooks/thoth" \
  --webhook-secret "$THOTH_WEBHOOK_SECRET" \
  --test-webhook \
  --mdm-provider "jamf" \
  --mdm-config-file "./jamf-provider.json" \
  --start-sync \
  --json

Release assets now include both runtime and control-plane binaries:

• thoth (endpoint/browser runtime)
• thothctl (headless admin bootstrap and updates)

2) Terraform-native management

Use public Terraform artifacts only (no private module paths).

Recommended public artifacts:

• Terraform provider repo: atensecurity/terraform-provider-thoth
• Terraform Registry source: atensecurity/thoth

Working path today (GA): use the bootstrap module from the public repo.

module "thoth_bootstrap" {
  source = "github.com/atensecurity/terraform-provider-thoth//modules/bootstrap?ref=v0.1.0"
 
  tenant_id               = var.tenant_id
  govapi_url              = var.govapi_url
  admin_bearer_token_file = "/run/secrets/thoth_admin_jwt"
 
  compliance_profile = "soc2"
  shadow_low         = "allow"
  shadow_medium      = "step_up"
  shadow_high        = "block"
  shadow_critical    = "block"
 
  webhook_url     = var.siem_webhook_url
  webhook_secret  = var.siem_webhook_secret
  webhook_enabled = true
  test_webhook    = true
 
  mdm_provider   = "jamf"
  mdm_name       = "Jamf Pro"
  mdm_enabled    = true
  mdm_config_file = "${path.module}/configs/jamf.json"
  start_mdm_sync = true
}

Recommended pattern:

1. Store non-secret control-plane config in Terraform variables.
2. Pass admin token via secure file path in CI runner secrets.
3. Execute thothctl bootstrap through the module for settings, SIEM webhook, and MDM sync.
4. Keep outputs non-secret and route evidence to SIEM/SOAR.

Provider-native resources (thoth_tenant_settings, thoth_mdm_provider, thoth_mdm_sync, thoth_webhook_test) are maintained in the same public repo and can be adopted when your team is ready.

3) Pulumi-native management

Use public Pulumi artifacts only (no private repo dependencies).

Recommended public artifacts:

• Pulumi provider repo: atensecurity/pulumi-thoth

Working path today (GA): use the bootstrap examples from the public repo.

import * as command from "@pulumi/command";
 
new command.local.Command("thothctl-bootstrap", {
  create: 'bash "../../scripts/thothctl_bootstrap.sh"',
  update: 'bash "../../scripts/thothctl_bootstrap.sh"',
  environment: {
    THOTH_GOVAPI_URL: govapiUrl,
    THOTH_TENANT_ID: tenantId,
    THOTH_ADMIN_BEARER_TOKEN_FILE: "/run/secrets/thoth_admin_jwt",
    THOTH_COMPLIANCE_PROFILE: "soc2",
    THOTH_WEBHOOK_URL: siemWebhookUrl,
    THOTH_WEBHOOK_SECRET: siemWebhookSecret,
    THOTH_TEST_WEBHOOK: "true",
    THOTH_MDM_PROVIDER: "intune",
    THOTH_MDM_START_SYNC: "true",
    THOTH_JSON_OUTPUT: "true",
  },
});

Recommended pattern:

1. Keep Pulumi stack config in Git and secrets in Pulumi secret store / runner secret files.
2. Use thothctl_bootstrap.sh for stable SIEM/SOAR + MDM bootstrap behavior.
3. Trigger reruns with explicit config drift fields (triggerVersion).
4. Export bootstrap stdout and feed verification events into your SIEM pipeline.

4) Argo CD reconciliation path

Argo CD should own:

• Kubernetes manifests / Helm values for proxy runtime surfaces
• tenant-specific app config references
• rollout policy (canary → pilot → full)

Pipeline model:

1. Terraform/Pulumi provisions infra and control-plane settings.
2. Argo CD reconciles runtime manifests.
3. thothctl and GovAPI automation keep governance + MDM + integration state in sync.

5) API-first integrations (SIEM, PAM, browser, endpoint)

Use GovAPI integration endpoints to manage and sync external systems:

• SIEM providers for event ingestion and alert routing
• PAM / approval integrations for privileged action controls
• MDM provider sync (Jamf/Intune) for endpoint inventory and fleet mapping
• Browser/endpoint telemetry flows through proxy check-ins and event pipelines

Runbooks and integration assets should be published in a public repo so customer SecOps teams can adopt without internal code access:

• atensecurity/thoth-runbooks
• SIEM runbooks (Splunk/Sentinel/Elastic)
• PAM runbooks (approval and step-up routing)
• SOAR runbooks (incident workflows + auto-remediation triggers)

Operationally:

• govern by code in Git
• apply in CI
• verify via API + SIEM evidence
• avoid ad hoc dashboard-only operations

6) Verification checklist

• Terraform CI target public-github has completed successfully in .github/workflows/terraform.yml
• Public asset publish workflow has synced latest provider/runbook content (publish-public-platform-assets.yml)
• thothctl bootstrap --json succeeds in CI
• webhook test succeeds to SIEM destination
• SIEM/SOAR runbooks are committed and versioned in atensecurity/thoth-runbooks
• MDM sync reports imported/upserted endpoint counts
• endpoint check-ins are healthy (thoth health --json)
• policy decisions and alerts are visible in SIEM with tenant/fleet/endpoint context

Related docs

• Claude Desktop Proxy
• Claude Desktop Fleet Configuration
• Headless E2E Runbook
• API Reference
• Changelog