Set up Thoth end to end

This is the full path from a new workspace to an agent whose tool calls are checked before they run and recorded in your workspace. The dashboard follows the same steps under Set up and confirms each one as you go.

Two kinds of key are involved. Keep them separate.

A configuration key can change your governance settings. Never put it in an agent, a repository or a chat. An agent key can only ask Thoth for decisions for its own agent.

1. Create an organization-wide configuration key

In the dashboard, open Settings → Keys (or step 1 of Set up), choose Configuration key, name it after where it will live (for example terraform-ci) and pick how long it lives: 7, 30, 90 or 180 days, or one year. A trial key never outlives the trial.

Review, confirm, and complete the code prompt. The key is shown once: store it in your secret manager or CI secrets straight away. Before it expires, create a replacement and revoke the old key from the same page.

2. Configure your workspace as code

Point the Thoth provider at your workspace with the configuration key, import the existing settings, and review the plan before applying. The dashboard's Set up page fills in your tenant ID and configuration API URL.

terraform {
  required_version = ">= 1.5"
  required_providers {
    thoth = {
      source  = "atensecurity/thoth"
      version = "~> 0.1.16"
    }
  }
}
 
provider "thoth" {
  tenant_id        = var.tenant_id
  api_base_url     = var.govapi_base_url
  org_api_key_file = var.configuration_key_file
}
 
variable "tenant_id" { type = string }
variable "govapi_base_url" { type = string }
variable "configuration_key_file" { type = string }
 
resource "thoth_governance_settings" "workspace" {
  shadow_high     = "block"
  shadow_critical = "block"
}

export TF_VAR_tenant_id="<your-tenant-id>"
export TF_VAR_govapi_base_url="<your-govapi-url>"
export TF_VAR_configuration_key_file="/absolute/private/path/thoth-configuration-key"
terraform init
terraform import thoth_governance_settings.workspace "$TF_VAR_tenant_id"
terraform plan -out=thoth.plan
terraform apply thoth.plan

Keep state, plans and the key file out of source control. See Configure trial settings as code for importing and restoring prior values.

3. Write policies for your tools

Thoth decides from what each tool does. Declare each tool's classes — read, write, delete, external_call, export, execute, bulk_operation, credential_access, sensitive_data_access — in code, and add a declaration whenever your agent gains a tool.

resource "thoth_tool_classification" "orders_list" {
  tool_name = "orders.list"
  classes   = ["read"]
}
 
resource "thoth_tool_classification" "orders_refund" {
  tool_name = "orders.refund"
  classes   = ["write", "external_call"]
}

Descriptions and classes an agent reports about its own tools are untrusted until an administrator confirms them, in code or on the dashboard's Workspace page. Custom OPA and Cedar policy bundles (thoth_policy_bundle) are available on paid plans.

4. Select the safe-default profile

A profile turns tool classes into decisions. safe-default lets confirmed reads run and sends anything that changes data to a person for approval. It is the right place to start until you have reviewed your tools.

On a trial, the profile applies to every agent in the workspace and is chosen once: use Preview safe-default in step 4 of Set up, review the preview and confirm it. In code, assign it per agent:

resource "thoth_pack_assignment" "my_first_agent" {
  agent_id = "my-first-agent"
  pack_id  = "safe-default"
}

See Profiles for what each profile allows.

5. Create a key for your agent

In Settings → Keys (or step 5 of Set up), choose Agent key, enter the exact agent ID your code will use, and pick an expiry. If the agent has not reported yet, it is registered first; on a trial this uses one of your agent slots. The key can only request decisions (execute) for that one agent ID.

To manage agent keys as code instead, use thoth_agent_api_key with permissions = ["execute"] and scope_target_id set to a registered agent.

6. Connect your agent

Set the connection details in the environment the agent runs in. The dashboard shows your tenant ID and tenant API URL.

export THOTH_TENANT_ID="<your-tenant-id>"
export THOTH_API_URL="<your-tenant-api-url>"
export THOTH_API_KEY="$(cat /absolute/private/path/thoth-agent-key)"
export THOTH_FAIL_OPEN=false

Then wrap the agent's tools with the SDK, using the same agent ID as the key. Every call is checked before it runs. Follow Your first governed agent for complete Python, TypeScript and Go programs, and Instrument your own agent to put real tools behind Thoth.

The Set up page waits for the agent's first decision and links to it in Activity, where each decision shows the tool, outcome, reason and actor.

Key lifecycle

Every key has an expiry you choose when you create it, and Thoth enforces it everywhere the key is checked: the configuration API refuses an expired or revoked configuration key, and the enforcer refuses an expired or revoked agent key on the next call.

Settings → Keys lists every key with its state and scope:

Each key is also marked Org-wide (configuration or runtime access across the workspace) or Agent-specific (one agent ID), with its permissions.

Keep it running

• Create a replacement key before one expires, then revoke the old one. Expiring keys appear in the dashboard's notifications a week ahead.
• Change policies in code and review the plan; the dashboard shows the result, not a second source of truth.
• Approvals for actions that need a person appear under Approvals and in notifications.