> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Harness

> Connect Harness to inspect delivery health and cloud costs, diagnose failures, and author resources behind approval

[Alex](/guide/agents/alex) can inspect Harness delivery health, diagnose failed executions, review Cloud Cost Management data, and author resources. CloudThinker requires approval before every create, update, or delete and cannot run, retry, or interrupt a pipeline.

## Prerequisites

* A Harness account with access to the organizations, projects, and Cloud Cost Management data you want CloudThinker to inspect.
* A Harness personal access token (PAT) or service account token (SAT).
* Permission to create a service account and role bindings if you use the recommended service-account setup.

<Info>
  Use an account-level service account when CloudThinker needs both project delivery data and account-level cost data. Limit its role bindings to the resource groups and actions you want agents to reach.
</Info>

## Setup

<Steps>
  <Step title="Create a Harness service account">
    In Harness, open **Account Settings → Access Control → Service Accounts**. Create a service account for CloudThinker, then assign role bindings for the organizations, projects, and account resources it should access.

    For personal testing, you can instead open your user profile and use **My API Keys**. A personal token inherits your own permissions.
  </Step>

  <Step title="Generate a token">
    Open the service account, select **API Keys → API Key**, and save a new key. Select **Token** under that key, set an expiration date, then select **Generate Token**.

    Copy the `sat.` token immediately. Harness displays it only once. A personal API key produces a `pat.` token through the same key-and-token flow.
  </Step>

  <Step title="Add the connection in CloudThinker">
    Navigate to **Connections → Harness** and enter:

    * **API key**: the PAT or SAT you generated.
    * **Harness URL**: keep `https://app.harness.io` unless your account uses another cluster or a self-managed installation.
    * **Default organization**: optional organization identifier applied to scoped requests.
    * **Default project**: optional project identifier. Set it only with a default organization.

    Click **Connect**. CloudThinker saves the connection and shows a **Connected** status.
  </Step>
</Steps>

<Warning>
  Harness displays a generated token only once. Store it securely and create a replacement if it is lost.
</Warning>

## Connection details

| Field                    | Description                                                                 | Default                  |
| ------------------------ | --------------------------------------------------------------------------- | ------------------------ |
| **API key**              | Harness PAT or SAT; CloudThinker detects the Harness account for this token | —                        |
| **Harness URL**          | Base URL for Harness SaaS or a self-managed installation                    | `https://app.harness.io` |
| **Default organization** | Optional organization identifier added to scoped calls                      | none                     |
| **Default project**      | Optional project identifier used with the default organization              | none                     |

<Note>
  Harness identifiers are not display names. Use the identifier shown in the Harness resource settings.
</Note>

## Required permissions

Harness tokens inherit permissions from their user or service account. Grant view permissions for every delivery or cost resource CloudThinker should inspect.

| Access                                             | Enables                                                              |
| -------------------------------------------------- | -------------------------------------------------------------------- |
| Organization and project view                      | Discovery across the selected Harness hierarchy                      |
| Pipeline, service, environment, and execution view | Delivery inventory, health summaries, and failed-execution diagnosis |
| Cloud Cost Management view                         | Spend, recommendations, anomalies, and budgets at account scope      |
| Create, edit, or delete on selected resources      | Approval-gated authoring through CloudThinker                        |

<Tip>
  Start with view permissions. Add create, edit, or delete permissions only for resource groups where you want CloudThinker to author definitions.
</Tip>

## Agent capabilities

Once connected, agents read live Harness state for each request.

| Capability             | Description                                                                                    |
| ---------------------- | ---------------------------------------------------------------------------------------------- |
| **Discovery**          | Inventory organizations, projects, pipelines, services, environments, connectors, and triggers |
| **Delivery health**    | Calculate pass rate and failure streaks, and identify failed or stuck executions               |
| **Failure diagnosis**  | Read an execution's failure details and failed-step logs                                       |
| **Cloud costs**        | Review account spend, recommendations, anomalies, and budget coverage                          |
| **Resource authoring** | Create, update, or delete a supported Harness resource after approval                          |

CloudThinker deliberately excludes pipeline execution controls. An agent cannot run, retry, or interrupt an execution, toggle a feature flag, sync a GitOps application, or approve a Harness approval step.

### Verify the connection

```text theme={null}
@alex #report list my Harness organizations and projects, then summarize delivery health for one project
```

### Example prompts

```text theme={null}
@alex #report show failed and stuck Harness executions in the payments project
@alex #recommend rank Harness Cloud Cost Management recommendations by monthly savings
@alex #report diagnose the latest failed Harness execution and name the failed step
```

## Troubleshooting

<Accordion title="Connected status, then 401 Unauthorized">
  The initial connection step does not validate the token. A revoked, expired, or incorrect token can therefore connect and fail on the first read. Generate a new token and reconnect.
</Accordion>

<Accordion title="403 or not authorized">
  The user or service account lacks a role binding for the requested scope. Check its Harness roles and resource groups, then narrow the request or grant the missing view permission.
</Accordion>

<Accordion title="A request says project scope is required">
  The resource needs both an organization identifier and a project identifier. Set **Default organization** and **Default project**, or ask Alex to discover the identifiers before repeating the request.
</Accordion>

<Accordion title="A project or organization is not found">
  Check that you supplied the resource identifier rather than its display name. Copy the identifier exactly as Harness shows it in the resource settings.
</Accordion>

<Accordion title="The agent will not run or retry a pipeline">
  This is an intentional connection boundary. Open the pipeline in Harness to run, retry, or interrupt it. CloudThinker can inspect the execution and diagnose a failure without starting one.
</Accordion>

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Dedicated identity** — prefer a service account so the connection does not inherit a person's changing access.
- **Bounded role bindings** — grant access only to the resource groups and operations agents need.
- **Token rotation** — set an expiration date and replace the token before it expires.

## Related

<CardGroup cols={2}>
  <Card title="CircleCI Connection" icon="https://mintcdn.com/cloudthinker/wCGuHK6EQ4nmA6Df/images/icons/circleci.svg?fit=max&auto=format&n=wCGuHK6EQ4nmA6Df&q=85&s=27a01c2abfb0b9b0dba6eef1585e938c" href="/guide/connections/circleci" width="24" height="24" data-path="images/icons/circleci.svg">
    Pipeline status, workflow analysis, and gated controls
  </Card>

  <Card title="Approval" icon="shield-check" href="/guide/approval">
    How CloudThinker gates agent write actions
  </Card>
</CardGroup>