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

# Docker Hub

> Connect Docker Hub to CloudThinker to review namespaces, repositories, pull demand, tag metadata, and repository descriptions

Connect your Docker Hub account so agents can inventory accessible namespaces, review repository visibility and lifetime pulls, inspect tag metadata, and update repository descriptions with approval.

Docker Hub authenticates with your account username and a **personal access token (PAT)**.

***

## Prerequisites

* A **Docker account** with access to the personal and organization repositories you want to inspect.
* Your **Docker Hub username**. Use the account name, not an email address or organization name.
* A **personal access token** with the permissions described below.

<Info>
  Use a dedicated, expiring PAT for CloudThinker. A Read-only PAT covers every inventory and tag inspection capability.
</Info>

***

## Setup

<Steps>
  <Step title="Create a personal access token">
    Sign in to Docker Home, then select **your avatar → Account settings → Personal access tokens → Generate new token**. Docker documents this flow in its [personal access token guide](https://docs.docker.com/security/access-tokens/).

    Configure the token:

    * **Description**: `cloudthinker`
    * **Expiration date**: choose a lifetime that matches your security policy
    * **Access permissions**: select **Read-only** for inventory, or **Read, Write & Delete** if you also need repository description updates

    Select **Generate**, then copy the token immediately.
  </Step>

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

    * **Docker Hub username**: the account that created the PAT
    * **Personal access token**: the PAT you just created

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

<Warning>
  Docker shows a new PAT only once. Store it securely before you leave the page, or generate a replacement.
</Warning>

***

## Connection details

| Field                   | Description                                                                              | Example  |
| ----------------------- | ---------------------------------------------------------------------------------------- | -------- |
| **DOCKERHUB\_USERNAME** | Docker Hub account username that owns the PAT; not an email address or organization name | `myuser` |
| **DOCKERHUB\_PAT**      | Personal access token created in Docker account settings                                 | —        |

***

## Required permissions

| PAT permission           | What it enables                                                                                                      |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| **Read-only**            | Namespace discovery, repository inventory, visibility, lifetime pull counts, stars, push recency, and tag inspection |
| **Read, Write & Delete** | All reads plus repository short-description and overview updates                                                     |

Docker Hub rejects repository description updates from a **Read & Write** PAT. Use **Read, Write & Delete** only when you need that capability. The connection cannot delete repositories or images, even with this PAT.

CloudThinker's write permission ships as **Never allow**. To enable description updates, open the connected Docker Hub account, expand **Tool permissions → Write/delete tools**, and select **Needs approval**. Each update then requires [approval](/guide/approval).

<Tip>
  Start with a Read-only PAT. Grant the broader PAT permission and enable the write permission only for workspaces that need repository text updates.
</Tip>

***

## Agent capabilities

| Capability               | Description                                                                                                   |
| ------------------------ | ------------------------------------------------------------------------------------------------------------- |
| **Account discovery**    | Identify the personal namespace and organization namespaces that Docker Hub returns for the credential        |
| **Repository inventory** | Review repositories by namespace with visibility, lifetime pulls, stars, last-push age, and Docker Hub status |
| **Tag inspection**       | Inspect tag counts, compressed image sizes, platforms, push dates, pull dates, and status                     |
| **Repository text**      | Read a repository's short description, then update its short description or overview with approval            |

Pull counts are lifetime totals, not rates. Reported sizes are compressed image sizes, not storage usage or runtime footprint.

### Verify the connection

```text theme={null}
@alex #report discover my Docker Hub account and summarize the returned namespace and repository inventory
```

### Example prompts

```text theme={null}
@alex #report list repositories in the acme namespace by lifetime pulls, including visibility and last-push age
@alex #report inspect tags for acme/api and show compressed size, platforms, and push and pull dates
@alex #recommend propose a clearer short description for acme/api, then ask for approval before updating it
```

***

## Troubleshooting

<Accordion title="Invalid Docker Hub username">
  Enter the Docker Hub account name that created the PAT. Do not enter an email address or an organization namespace.
</Accordion>

<Accordion title="Authentication failed">
  The PAT is wrong, expired, deactivated, or deleted. Generate a new PAT, then reconnect with the same Docker Hub username.
</Accordion>

<Accordion title="An organization namespace is missing">
  Docker Hub may refuse organization listing for a PAT. This does not prove that the account has no organizations. Ask the agent to inspect the known organization namespace directly, and confirm that the PAT's account is a member.
</Accordion>

<Accordion title="A private repository is not found">
  Confirm the namespace and repository name. The account that created the PAT must also have permission to read that private repository.
</Accordion>

<Accordion title="A description update reports insufficient scope">
  The PAT does not have **Read, Write & Delete** permission. Docker Hub also rejects this update from a **Read & Write** PAT. Generate a replacement PAT with the required permission and reconnect.
</Accordion>

<Accordion title="A description update does not run">
  Open the Docker Hub connection and check **Tool permissions → Write/delete tools**. Set the write permission to **Needs approval**, then approve the update when CloudThinker asks.
</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.

- **Prefer Read-only**: use **Read, Write & Delete** only when agents must update repository text. The connection still cannot push, delete, rename, or change repository visibility.
- **Rotate and revoke**: set an expiration, review last-used dates, and deactivate or delete unused PATs under **Account settings → Personal access tokens**.

***

## 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">
    Monitor pipelines, workflows, jobs, and build logs
  </Card>

  <Card title="Approval" icon="shield-check" href="/guide/approval">
    Control actions that require human confirmation
  </Card>
</CardGroup>