spotlight_harness_profile

The spotlight_harness_profile resource, and the API's harness-profile kind: a team's set of permission rules, MCP servers and native harness settings. A station names one in its profile.

See Resource API for the operations, headers and errors every kind shares.

ExampleCopy Anchor Link

resource "spotlight_harness_profile" "core_careful" {
  team_id = spotlight_team.core.id
  key     = "careful"

  permissions = {
    allow = ["read", "edit", "execute(npm test *)"]
    ask   = ["execute(git push *)"]
    deny  = ["read(.env)"]
  }

  mcp_servers = [
    {
      name    = "acme"
      command = "npx"
      args    = ["-y", "acme-mcp"]
      env     = { ACME_API_KEY = "secret.ACME_API_KEY" }
    },
  ]

  native = {
    claude-code = { includeCoAuthoredBy = false }
    codex       = "model_verbosity = \"low\"\n"
  }
}

FieldsCopy Anchor Link

permissions accepts no other keys.

Permission rulesCopy Anchor Link

A rule is a kind, alone or with a pattern in parentheses.

• A pattern may not be empty.
• A rule may appear once, under one of allow, ask and deny.
• For each kind, a bare rule sets what happens to anything no patterned rule matches. A kind has at most one bare rule.
• A kind with no bare rule is allowed.
• A rule with a pattern is an exception to the kind's bare rule.

An ask rule becomes a Spotlight approval. A permission request is put to a person only when its kind has an ask rule, bare or patterned; a request of any other kind, such as a web fetch, is allowed. See Approvals.

MCP serversCopy Anchor Link

An env value is plain text, stored and shown as written, or a reference to a workspace secret written secret.<NAME>, as in secret.ACME_API_KEY.

• A reference must name a secret the workspace holds, or the write is refused with 422.
• The server receives a stand-in, and egress puts the value in place of it, in the server's requests to the host the secret is bound to.
• A secret a profile references cannot be deleted.

Every harness gets the servers when its session starts. Cursor also gets them in cursor/mcp.json.

Native settingsCopy Anchor Link

A key that names no harness, a claude-code or cursor value that is not an object, and a codex value that does not parse as TOML are refused with 422.

How each harness receives itCopy Anchor Link

A run's harness gets the profile's settings as files in the run's state directory, .spotlight/state within the run's workspace. See Inside a sandbox. Spotlight does not remove a repository's own settings files, such as .claude/settings.json or AGENTS.md.

WarningsCopy Anchor Link

Where a harness cannot hold a rule as written, the profile's warnings name the approximation. The write succeeds. Warnings include:

DeleteCopy Anchor Link

A delete is refused with 409 in-use while any station names the profile.

A station that names a profile its team does not hold is not refused when the line is written; its runs are refused.

See Limit what agents may do and Give an MCP server a secret.