Configuration

OpenTide ships sensible defaults inside the package. Your repository customises them under .opentide/configurations/. This guide is the practical tour of that directory; the normative merge rules live in the Configuration spec.

How configuration is layered

OpenTide deep-merges configuration from several sources. Later layers win; nested tables merge, scalars replace.

flowchart LR
  bundled["1 · Package defaults<br/>(bundled in the wheel)"] --> platforms["2 · Bundled platform configs"]
  platforms --> client["3 · Your workspace<br/>.opentide/configurations/"]
  client --> parent["4 · Parent instance<br/>(nested workspaces)"]

You only ever edit layer 3 — your workspace. You override just the keys you care about; everything else falls through to the package defaults.

.opentide/configurations/
├── paths.toml              # workspace directory layout
├── deployment.toml         # statuses + promotion
├── schema.toml             # template defaults, vocabulary extensions
├── visibility.toml         # what is exposed/deployed
├── documentation.toml      # `opentide generate docs` settings
└── platforms/
    ├── sentinel.toml
    └── splunk.toml

Enabling a platform

A platform is loaded only when it is enabled in your workspace config. Create one file per platform under platforms/:

# .opentide/configurations/platforms/sentinel.toml
[platform]
enabled = true

Confirm what the engine actually loaded:

opentide info
opentide --json info --platform sentinel

See Platforms for the capability matrix and the exact --platform identifiers.

Credentials

Deploying rules or running live query checks needs platform credentials. Keep secrets out of the repo — reference environment variables from the platform TOML and inject them at runtime (locally via a .env you never commit, in CI via secrets).

# .opentide/configurations/platforms/sentinel.toml
[platform]
enabled = true

[[tenants]]
name = "Primary"
description = "Production Sentinel workspace"
deployment = "ALWAYS"

[tenants.setup]
resource_group = "rg-soc"
workspace_name = "soc-sentinel"
workspace_id = "$AZURE_WORKSPACE_ID"
azure_tenant_id = "$AZURE_TENANT_ID"
azure_subscription_id = "$AZURE_SUBSCRIPTION_ID"
azure_client_id = "$AZURE_CLIENT_ID"
azure_client_secret = "$AZURE_CLIENT_SECRET"

If you sit behind an outbound proxy, configure it in deployment.toml:

[proxy]
proxy_host = "proxy.internal"
proxy_port = 8080
proxy_user = "${PROXY_USER}"          # optional; enables authenticated proxy
proxy_password = "${PROXY_PASSWORD}"

Deployment statuses and strategies

Every rule's status must match a status defined in the merged deployment.toml. That is the only constraint — statuses are a configurable set, not a fixed lifecycle, and OpenTide does not enforce an order between them. OpenTide ships this set out of the box:

The strategy decides how deploy treats a rule: INERT never deploys, PREVIEW targets staging, RELEASE goes to production, DISABLEMENT/DELETION tear down. You can add or rename statuses by overriding deployment.toml:

# .opentide/configurations/deployment.toml
[[statuses]]
name = "PILOT"
description = "Limited rollout to a pilot workspace"
strategy = "PREVIEW"

Full field contract: Deployment spec.

Promotion

Promotion rewrites a rule's status directly to promotion_target — it is a single jump, not a step through intermediate statuses.

# .opentide/configurations/deployment.toml
[promotion]
enabled = true
promotion_target = "PRODUCTION"

There is no separate promote command. Edit a rule's status in YAML for deliberate changes, then run opentide deploy — when promotion is enabled, deploy applies the promotion target to every status whose strategy is not RELEASE, DISABLEMENT, or DELETION. See deploy and the detection-as-code workflow.

Deployment plan

The DEPLOYMENT_PLAN environment variable selects which plan deploy and validate query operate under, letting you keep separate plans (e.g. per environment) without editing config:

export DEPLOYMENT_PLAN=production
opentide deploy --platform sentinel

See CLI global options for how it resolves.

Visibility and documentation

• visibility.toml controls which objects are exposed/deployed in a given context; it is validated by a generated visibility schema.
• documentation.toml tunes opentide generate docs output (which folders, which sections). See generate docs.

Paths

paths.toml overrides the default workspace layout (where objects/, docs/, and .opentide/ live). Most repos never touch it; the defaults are described in the Workspace spec.

Related

• Configuration spec — normative merge order and file contract.
• Repository setup — how opentide setup scaffolds this directory.
• Troubleshooting — "unknown status", "platform not loaded", and other config errors.