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

# OpenSearch

> Connect OpenSearch to CloudThinker for read-only index, query, cluster health, and search relevance investigation

Connect your OpenSearch cluster to let CloudThinker agents review indices, mappings, shards, cluster health, documents, queries, and relevance explanations.

OpenSearch authenticates with the **cluster URL and a basic-auth user**. The connection is **read-only by design** — agents can list, search, count, and explain, and your search environment stays unchanged during investigation.

## Prerequisites

* An **OpenSearch cluster** reachable from the internet over HTTPS, or from wherever your CloudThinker deployment runs.
* A **basic-auth user** scoped to the indices this workspace should reach — not the cluster admin.

## Setup

<Steps>
  <Step title="Create a dedicated user">
    In your cluster's security settings, create a user with read access to the indices agents should investigate.
  </Step>

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

    * **Cluster URL**: the cluster endpoint, such as `https://opensearch.internal:9200`
    * **Username** and **Password**: the dedicated user's credentials
    * **Connection timeout (seconds)**: a value such as `15` — without it, an unreachable cluster stalls the conversation turn instead of failing

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

## Connection details

| Field                            | Description                                                                              | Example                            |
| -------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------- |
| **Cluster URL**                  | Endpoint of the OpenSearch cluster                                                       | `https://opensearch.internal:9200` |
| **Username**                     | Basic-auth user scoped to the indices this workspace should reach                        | —                                  |
| **Password**                     | Password for that user                                                                   | —                                  |
| **Verify TLS certificate**       | Leave empty to verify the certificate; set to `false` only for a self-signed certificate | —                                  |
| **Connection timeout (seconds)** | Bounds how long a call waits for the cluster; empty means no timeout                     | `15`                               |

<Note>
  A TLS verification failure surfaces as a hung call rather than an error, so set **Connection timeout (seconds)** whenever you change **Verify TLS certificate**.
</Note>

## Required permissions

Grant the user **read** access to the target indices and cluster health. The connection exposes only read operations — list indices, read mappings, search, count, multi-search, shard and cluster health checks, and query explanations — so write permissions on the user are wasted surface.

<Tip>
  Scope the user to the indices agents actually need. A cluster-admin credential grants nothing extra here and widens the blast radius if it leaks.
</Tip>

## Agent capabilities

Once connected, agents have read access to your cluster:

| Capability                | Description                                                          |
| ------------------------- | -------------------------------------------------------------------- |
| **Index inventory**       | List indices and read their mappings                                 |
| **Search and count**      | Run search, count, and multi-search queries against selected indices |
| **Cluster health**        | Check cluster health and shard allocation                            |
| **Relevance explanation** | Explain why a document matched or scored the way it did              |

### Verify the connection

```text theme={null}
@oliver check the OpenSearch cluster health and list the largest indices
```

### Example prompts

```text theme={null}
@oliver #report the pattern of authentication failures in the logs-app index over the last 24 hours
@oliver #report why the products search returns irrelevant results for "wireless charger", explaining the top hit's score
@oliver #recommend what to rebalance in the OpenSearch cluster's shard allocation
```

## Troubleshooting

<Accordion title="401 Unauthorized">
  The username or password is wrong, or the user was removed. Update the credentials on the connection.
</Accordion>

<Accordion title="Calls hang instead of failing">
  The cluster is unreachable, or TLS verification is failing against a self-signed certificate. Set **Connection timeout (seconds)**, and set **Verify TLS certificate** to `false` only if the cluster genuinely serves a self-signed certificate.
</Accordion>

<Accordion title="Agent cannot see an index">
  The basic-auth user lacks read access to that index. Widen the user's index permissions in the cluster's security settings.
</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.

- **Read-only surface** — the connection cannot write, delete, or change cluster settings, whatever the user's permissions allow.
- **TLS verification on** — keep certificate verification enabled unless the cluster serves a self-signed certificate you trust.

## Related

<CardGroup cols={2}>
  <Card title="Elasticsearch Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/elasticsearch.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=c7389cfcd0bc8d303aeeb68bd19199ca" href="/guide/connections/elasticsearch" width="24" height="24" data-path="images/icons/elasticsearch.svg">
    Search and log analytics
  </Card>

  <Card title="Graylog Connection" icon="https://mintcdn.com/cloudthinker/PAPf7dQXz6G9xwkG/images/icons/graylog.svg?fit=max&auto=format&n=PAPf7dQXz6G9xwkG&q=85&s=11bac41a029ed27ed4c8a6a988847722" href="/guide/connections/graylog" width="256" height="256" data-path="images/icons/graylog.svg">
    Centralized log management
  </Card>
</CardGroup>