# Set up Thoth end to end

> Create your keys, configure the workspace as code, choose a profile and connect your first agent.

Source: https://docs.atensecurity.com/docs/getting-started/setup-guide

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.

**Before you start:**
  You need a workspace administrator account. Creating keys and changing
  configuration require a recent second factor: the first time, the dashboard
  emails you a code and then asks you to add an authenticator app
  (1Password, Google Authenticator, Authy or similar). After that it asks for
  a 6-digit code when a change needs it.

Two kinds of key are involved. Keep them separate.

| Key | Permissions | Scope | Used by |
| --- | --- | --- | --- |
| Configuration key | read, write | Whole organization | Terraform, Pulumi, `thothctl` |
| Agent key | execute | One agent ID | The agent's SDK |

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**

```hcl title="main.tf"
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"
}
```

```bash title="Terminal"
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
```

**Pulumi (Python)**

```python title="__main__.py"
import pulumi
import pulumi_thoth as thoth

config = pulumi.Config()
provider = thoth.Provider(
    "thoth",
    tenant_id=config.require("tenantId"),
    api_base_url=config.require("govapiBaseUrl"),
    org_api_key_file=config.require("configurationKeyFile"),
)
opts = pulumi.ResourceOptions(provider=provider)

thoth.governance.GovernanceSettings(
    "workspace",
    shadow_high="block",
    shadow_critical="block",
    opts=pulumi.ResourceOptions(provider=provider, import_=config.require("tenantId")),
)
```

Install `pulumi>=3.170,<4` and `pulumi-thoth==0.1.16`, set the three config
values, then run `pulumi preview` before `pulumi up`. Remove `import_` after
the first import.

Keep state, plans and the key file out of source control. See
[Configure trial settings as code](https://docs.atensecurity.com/docs/getting-started/trial-settings) 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.

**Terraform**

```hcl title="policies.tf"
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"]
}
```

**Pulumi (Python)**

```python title="__main__.py"
thoth.governance.ToolClassification(
    "orders-list", tool_name="orders.list", classes=["read"], opts=opts
)
thoth.governance.ToolClassification(
    "orders-refund",
    tool_name="orders.refund",
    classes=["write", "external_call"],
    opts=opts,
)
```

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:

**Terraform**

```hcl title="policies.tf"
resource "thoth_pack_assignment" "my_first_agent" {
  agent_id = "my-first-agent"
  pack_id  = "safe-default"
}
```

**Pulumi (Python)**

```python title="__main__.py"
thoth.governance.PackAssignment(
    "my-first-agent", agent_id="my-first-agent", pack_id="safe-default", opts=opts
)
```

See [Profiles](https://docs.atensecurity.com/docs/getting-started/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`](https://docs.atensecurity.com/docs/terraform-provider) 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.

```bash title="Terminal"
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](https://docs.atensecurity.com/docs/getting-started/quickstart) for complete
Python, TypeScript and Go programs, and
[Instrument your own agent](https://docs.atensecurity.com/docs/getting-started/your-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:

| State | Meaning |
| --- | --- |
| Active | Works until its expiry date |
| Expires soon | Active, with less than 7 days left. Create a replacement now |
| Expired | Past its expiry date. It no longer works and cannot be renewed |
| Revoked | Turned off by an administrator before it expired |

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.