> ## 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.

# AWX

> Connect Ansible AWX to CloudThinker to launch job templates, monitor jobs, manage inventories, and orchestrate automation workflows

Connect your Ansible AWX server to enable CloudThinker agents to launch job templates, monitor jobs, manage inventories and hosts, sync projects, and orchestrate automation workflows. AWX authenticates with a **user access token** scoped to read or write operations.

***

## Prerequisites

* A **self-hosted AWX or Ansible Automation Platform** (Controller/Tower) instance reachable from CloudThinker over HTTPS.
* An **AWX user** with access to the organizations and inventories CloudThinker should reach.

***

## Setup

<Steps>
  <Step title="Sign in to AWX">
    Sign in to your AWX web interface. Use a dedicated user scoped to only the organizations and inventories CloudThinker needs.
  </Step>

  <Step title="Create an access token">
    Go to **Access → Users**, open your user, select the **Tokens** tab, and click **Add**:

    * **Application**: leave empty
    * **Scope**: **Write** for full operations, or **Read** for monitoring only

    Copy the token — AWX shows it only once.
  </Step>

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

    * **TOWER\_HOST**: your AWX address, e.g. `https://awx.your-domain.com`
    * **TOWER\_OAUTH\_TOKEN**: the token from the previous step

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

***

## Connection details

| Field                   | Description                   | Example                       |
| ----------------------- | ----------------------------- | ----------------------------- |
| **TOWER\_HOST**         | Base URL of your AWX instance | `https://awx.your-domain.com` |
| **TOWER\_OAUTH\_TOKEN** | AWX user access token         | —                             |

***

## Required permissions

What agents can do depends on the token scope.

* **Read** — list jobs, inspect inventories, check project status, review schedules, and view configuration.
* **Write** — all read operations plus launching jobs, running ad-hoc commands, controlling running jobs, syncing projects, and managing hosts, groups, and schedules.

<Tip>
  Use a Read-scoped token for monitoring only; add Write scope when agents need to launch or modify resources, and keep those actions approval-gated in CloudThinker.
</Tip>

***

## Agent capabilities

What agents can do depends on the token's scope.

**Read — monitoring & inspection:**

| Capability                | Description                                                                     |
| ------------------------- | ------------------------------------------------------------------------------- |
| **Monitor jobs**          | List jobs and workflow runs, check status, and read output                      |
| **Inspect inventories**   | View inventories, hosts, and groups; spot unreachable or disabled hosts         |
| **Check project status**  | Review sync status and source-control state                                     |
| **Review schedules**      | List schedules and upcoming runs                                                |
| **Inspect configuration** | View job templates, workflow templates, inventory sources, and credential types |

**Write — adds operations (requires approval):**

| Capability                           | Description                                                            |
| ------------------------------------ | ---------------------------------------------------------------------- |
| **Launch jobs**                      | Run job templates with extra variables and monitor to completion       |
| **Run ad-hoc commands**              | Execute one-off commands against hosts without a template              |
| **Control running jobs**             | Cancel in-flight jobs and relaunch failed ones                         |
| **Sync projects & inventory**        | Pull project updates from source control and refresh dynamic inventory |
| **Manage hosts, groups & schedules** | Add, update, or remove them and toggle host enablement                 |
| **Orchestrate workflows**            | Launch workflow job templates and approve or deny approval nodes       |

Administrative resources (organizations, teams, users, and RBAC) are out of scope for agent operations.

### Verify the connection

```text theme={null}
@alex list all AWX inventories and show any unreachable hosts
```

### Example prompts

```text theme={null}
@kai list failed AWX jobs in the last 24 hours and #report their output
@kai launch the deploy-production job template with version=2.1.0 and monitor it
@alex check all AWX projects for sync failures and #recommend updates
```

***

## Troubleshooting

<Accordion title="Connection or authentication failed">
  Verify the AWX URL is reachable from CloudThinker over HTTPS. Confirm the token has not expired or been revoked — create a new token if needed and reconnect.
</Accordion>

<Accordion title="Permission denied">
  The token's scope does not allow the requested action. Use a Write-scoped token for launch, sync, or management operations, and confirm the user has access to the target organization or inventory.
</Accordion>

<Accordion title="Empty results">
  The token's user lacks visibility into the requested resources. Grant access to the relevant organizations and inventories in AWX, then retry.
</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.

- **Write scope only when needed** — use a Read-scoped token for monitoring; only enable Write scope when agents need to launch or modify resources.
- **HTTPS only** — always use an HTTPS AWX URL; plaintext connections expose the access token.

***

## Related

<CardGroup cols={2}>
  <Card title="ArgoCD Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/argocd.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=34c7a30ed3772de41da3c56cb43396b3" href="/guide/connections/argocd" width="24" height="24" data-path="images/icons/argocd.svg">
    GitOps operations and application management
  </Card>

  <Card title="Jenkins Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/jenkins.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=871f9df2f5553b663f1b5c33f11bf5da" href="/guide/connections/jenkins" width="24" height="24" data-path="images/icons/jenkins.svg">
    CI/CD pipeline monitoring and job operations
  </Card>
</CardGroup>