Headless Operations

Operate Thoth without a dashboard using thothctl, the Thoth Control Plane API, and your existing CI/CD workflows.

Use this guide when you want to run Thoth with a code-first operating model and no dashboard dependency.

Operating model

Git repo

policy + deployment config

↓

CI/CD

thothctl + API automation

↓

Thoth Control Plane

settings + integrations

↓

Managed endpoints

thoth runtime + MCP traffic

↓

Security stack

SIEM/SOAR + approval systems

1) Configure control-plane auth for automation

export THOTH_TENANT_ID="<tenant>"
export THOTH_APEX_DOMAIN="<apex-domain>"
export THOTH_API_KEY="<org-level-api-key>"

THOTH_API_KEY is the recommended CI/CD auth path.

For interactive admin sessions, you can still bootstrap a bearer session:

export THOTH_TENANT_ID="<tenant>"
 
thothctl auth login \
  --tenant-id "$THOTH_TENANT_ID" \
  --admin-email "<admin@company.com>"

2) Bootstrap baseline governance

thothctl bootstrap \
  --tenant-id "$THOTH_TENANT_ID" \
  --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 "./mdm-provider.json" \
  --start-sync \
  --json

3) Enable strict Secrets Broker for MCP/API tools

Use strict fail-closed mode so runtime credentials are resolved at request time from managed secret backends, not persisted in local endpoint tool config.

thothctl bootstrap \
  --tenant-id "$THOTH_TENANT_ID" \
  --secret-broker-provider custom \
  --secret-broker-enabled true \
  --secret-broker-strict-endpoint-mode \
  --secret-broker-fail-on-missing-secret \
  --secret-broker-allowed-host api.figma.com \
  --secret-broker-allowed-host api.notion.com \
  --secret-broker-allowed-host <stitch-host> \
  --secret-broker-auth-binding "api.figma.com:Authorization:op://design/figma/token:Bearer " \
  --secret-broker-auth-binding "api.notion.com:Authorization:vault://kv/data/notion#token:Bearer " \
  --secret-broker-auth-binding "<stitch-host>:Authorization:aws-sm://prod/stitch/token:Bearer " \
  --json

Replace <stitch-host> with your Stitch API hostname.

4) Manage browser governance as code

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

5) Run endpoint-side policy sync

# Preview
thothctl browser sync \
  --tenant-id "$THOTH_TENANT_ID" \
  --device-id "<device-id>" \
  --user-id "<user@company.com>" \
  --dry-run \
  --json
 
# Apply
sudo thothctl browser sync \
  --tenant-id "$THOTH_TENANT_ID" \
  --device-id "<device-id>" \
  --user-id "<user@company.com>" \
  --json

6) Verification checklist

thothctl bootstrap --json returns success flags.
thothctl settings get --json returns expected baseline configuration.
thothctl mdm list --json shows enabled provider records.
thothctl endpoints list --json shows enrolled endpoints.
thoth health --json on endpoints returns healthy status.
SIEM webhook test succeeds and evidence events are visible in your monitoring pipeline.

7) Evidence quality checks

Run these checks after rollout and periodically in CI:

thothctl evidence slos \
  --tenant-id "$THOTH_TENANT_ID" \
  --window-hours 24 \
  --json
 
thothctl evidence decision-backfill \
  --tenant-id "$THOTH_TENANT_ID" \
  --window-hours 720 \
  --dry-run \
  --json

Use thothctl evidence backfill only when you need to materialize missing governance evidence records for older events.

Rollout guidance

Use staged rollout in automation:

Canary endpoints
Pilot group
Broad production rollout

Use your existing incident and rollback playbooks for any regression during rollout.

Headless Operations

On this page