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

# AnythingLLM

> AnythingLLM document workspaces with chat, built-in retrieval, a website chat widget, a developer API and MCP agents. One replica on a snapshotted volume, sign-in always required. Deploys into an existing GVC; a keys secret and an admin secret must exist first.

## Overview

AnythingLLM organizes documents into workspaces. Each workspace is a set of files plus a chat that answers from them with citations. Retrieval is built in (a CPU embedding model and an embedded LanceDB vector store), so no extra services are needed. It also serves a website chat widget, a developer API and agents that call MCP tools. This template runs it as one workload on a snapshotted volume; the admin account comes from a secret, so a sign-in is required from the first start.

> [!NOTE]
>
> This template does not create a GVC. It deploys into an existing GVC that you already have, and that GVC should have exactly one location: the workload is a single replica that owns its volume.

### What Gets Created

| Resource | Name | Purpose | Optional |
| - | - | - | - |
| Workload | `RELEASE_NAME-anythingllm` | UI, API, chat widget and document collector on port `3001` (stateful, 1 replica) | — |
| Volume set | `RELEASE_NAME-anythingllm-storage` | Database, vectors, documents, embedding model, MCP config and UI settings (10 GiB) | — |
| Identity | `RELEASE_NAME-anythingllm-identity` | Workload identity for AnythingLLM | — |
| Policy | `RELEASE_NAME-anythingllm-policy` | Grants the identity `reveal` on exactly the secrets you name | — |

The template creates no secrets or credentials. The public `*.cpln.app` URL is on by default and every request needs a sign-in.

## Prerequisites

**1. Create the keys secret**

A **dictionary** secret holding the keys that sign sessions and encrypt stored data. None may be empty:

```bash theme={null}
cpln secret create-dictionary --name KEYS_SECRET_NAME \
  --entry JWT_SECRET="$(openssl rand -hex 32)" \
  --entry SIG_KEY="$(openssl rand -hex 32)" \
  --entry SIG_SALT="$(openssl rand -hex 32)" \
  --entry AUTH_TOKEN="$(openssl rand -hex 32)"
```

Set `keys.secretName` to this name. Never change or delete it afterwards.

**2. Create the admin secret**

A **dictionary** secret with the admin account created on first start. The username is 2-64 lowercase letters, digits, `.`, `_`, `@` or `-`, starting with a letter; the password is 8 characters or more:

```bash theme={null}
cpln secret create-dictionary --name ADMIN_SECRET_NAME \
  --entry username=admin \
  --entry password="$(openssl rand -base64 24)"
```

Set `admin.secretName` to this name.

**3. Create the optional secrets**

A chat model API key (`llm.apiKeySecretName`, required for `openai` and `anthropic`), an embedding API key (`embedding.apiKeySecretName`) and a bearer token per HTTP MCP server (`bearerTokenSecretName`) are each an **opaque** secret:

```bash theme={null}
printf '%s' "$OPENAI_API_KEY" | cpln secret create-opaque --name API_KEY_SECRET_NAME --encoding plain -f -
```

The Control Plane MCP server needs a service-account key, see [Control Plane MCP Server](#control-plane-mcp-server).

Secret names are org-wide, so give each release its own secrets.

> [!WARNING]
>
> Every secret your release names must exist **before** you install. If one does not, the deployment waits silently: `cpln logs` returns nothing, and the only place the missing secret is named is `status.versions[].message` in `cpln workload get-deployments RELEASE_NAME-anythingllm --gvc GVC_NAME -o yaml`. Create the secret and the deployment recovers on its own within about 12 minutes, or run `cpln workload force-redeployment RELEASE_NAME-anythingllm --gvc GVC_NAME` to recover at once. Run the same command after changing any secret the release uses.

## Installation

The required values are the names of the two secrets from [Prerequisites](#prerequisites):

```bash theme={null}
cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/anythingllm \
  --version 1.0.0 --gvc GVC_NAME \
  --set keys.secretName=KEYS_SECRET_NAME \
  --set admin.secretName=ADMIN_SECRET_NAME
```

To install with the CLI, UI, Terraform or Pulumi, follow the instructions for your preferred method:

> [card] [UI](https://docs.controlplane.com/template-catalog/install-manage/ui.md)
>
> Browse, install, and manage templates visually

> [card] [CLI](https://docs.controlplane.com/template-catalog/install-manage/cli.md)
>
> Manage templates from your terminal

> [card] [Terraform](https://docs.controlplane.com/template-catalog/install-manage/terraform.md)
>
> Declare templates in your Terraform configurations

> [card] [Pulumi](https://docs.controlplane.com/template-catalog/install-manage/pulumi.md)
>
> Declare templates in your Pulumi programs

## Configuration

### Keys and Admin Account

```yaml theme={null}
keys:
  secretName: my-anythingllm-keys     # REQUIRED: JWT_SECRET, SIG_KEY, SIG_SALT, AUTH_TOKEN; never change it
admin:
  secretName: my-anythingllm-admin    # REQUIRED: username, password; read on first start only, then change it in the UI
```

### Chat Model

```yaml theme={null}
llm:
  provider: ""          # "" | openai | anthropic | ollama | generic-openai | litellm
  model: ""             # required when provider is set, e.g. gpt-4.1-mini, llama3.2
  baseUrl: ""           # ollama / generic-openai / litellm, e.g. http://my-ollama-ollama.GVC_NAME.cpln.local:11434
  contextWindow: 8192   # the model's token limit (ollama / generic-openai / litellm)
  apiKeySecretName: ""  # opaque secret with the API key; required for openai and anthropic
```

With `provider: ""`, choose the model in Settings → AI Providers → LLM after signing in; the choice is kept on the volume. Until a model is chosen, chats and the developer API's vector search fail. For a model served in the same GVC, such as the [ollama](https://docs.controlplane.com/template-catalog/templates/ollama.md) template, set `baseUrl` to `http://WORKLOAD_NAME.GVC_NAME.cpln.local:PORT`, always fully qualified. Use `generic-openai` for vLLM or any other OpenAI-compatible server, with `baseUrl` ending in `/v1`.

### Embedding Model

```yaml theme={null}
embedding:
  engine: native        # native (built in, CPU, no key; slow for large uploads) | ollama | generic-openai
  model: ""             # required unless native, e.g. nomic-embed-text, text-embedding-3-small
  baseUrl: ""           # e.g. http://my-ollama-ollama.GVC_NAME.cpln.local:11434 or https://api.openai.com/v1
  maxChunkLength: 8192  # characters per chunk sent to the embedder (ollama / generic-openai)
  apiKeySecretName: ""  # opaque secret; generic-openai only, optional
```

The built-in embedder runs on the CPU inside the same container, needs no key and suits small document sets. For large uploads, point `engine` at `ollama` or `generic-openai`.

### MCP Tool Servers

```yaml theme={null}
mcp:
  servers: {}
  # time:                       # stdio: runs inside the container
  #   command: uvx
  #   args: [mcp-server-time]
  # my-tools:                   # HTTP
  #   type: streamable          # streamable | sse
  #   url: http://my-mcp.GVC_NAME.cpln.local:8000/mcp
  #   bearerTokenSecretName: "" # opaque secret sent as "Authorization: Bearer <value>"
```

A stdio server runs inside the AnythingLLM container with its environment, which includes the provider keys and `JWT_SECRET`; add only servers you trust. An HTTP server is reached at its `url`, `streamable` or `sse`, with an optional bearer token.

AnythingLLM has no screen for adding an MCP server; Settings → Agent Skills only turns servers on or off and removes them. With the default `servers: {}`, add servers by editing `/app/server/storage/plugins/anythingllm_mcp_servers.json` through `cpln workload exec`; the chart leaves that file alone. With any server listed here, or `cplnMcp.keySecretName` set, the chart rewrites the whole file on every start, so hand edits are lost.

With any MCP server configured, a workspace in the default Automatic chat mode can route ordinary chats through the agent, and a small model that does not call tools reliably then answers from the tools instead of your documents. Set such a workspace to Chat or Query mode so answers come from its documents. Start an agent run with `@agent` in a workspace chat.

### Control Plane MCP Server

```yaml theme={null}
cplnMcp:
  keySecretName: ""             # opaque: a service-account key; "" = no Control Plane MCP server
  url: https://mcp.cpln.io/mcp?toolsets=readonly  # read-only tools (no create, update or delete); https://mcp.cpln.io/mcp = every tool
```

Setting `keySecretName` adds an MCP server named `cpln` so agents can work with your org. AnythingLLM's MCP client cannot sign in with OAuth, so it authenticates with a service-account key, and **every agent run that uses the server acts as that service account**. Give the account only what your agents need. This example lets it view one GVC; add a policy for each further resource kind, such as `workload` with `view`:

```bash theme={null}
cpln serviceaccount create --name SERVICE_ACCOUNT_NAME
cpln policy create --name POLICY_NAME --target-kind gvc --resource GVC_NAME
cpln policy add-binding POLICY_NAME --permission view --serviceaccount SERVICE_ACCOUNT_NAME
cpln serviceaccount add-key SERVICE_ACCOUNT_NAME --description anythingllm -o json | jq -j .key | \
  cpln secret create-opaque --name CPLN_MCP_KEY_SECRET_NAME --encoding plain -f -
```

Set `cplnMcp.keySecretName` to `CPLN_MCP_KEY_SECRET_NAME`. The default `url` exposes read-only tools; change it to `https://mcp.cpln.io/mcp` only if agents must create, update or delete resources. The key is sent to `url`, so point it only at the Control Plane MCP server. At each start a log line beginning `cpln-mcp:` says whether the server accepted the key:

```bash theme={null}
cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-anythingllm"} |= "cpln-mcp:"' --limit 50 --since 10m
```

### Access

```yaml theme={null}
publicAccess:
  enabled: true         # UI, chat widget and API on the canonical *.cpln.app URL; a sign-in is always required
internalAccess:
  type: none            # none | same-gvc | same-org | workload-list
  workloads: []         # used only with workload-list
```

### Storage and Backup

```yaml theme={null}
volumeset:
  capacity: 10          # GiB (minimum 10); grow a live volume with cpln volumeset expand (below)
backup:
  enabled: true         # platform volume snapshots, no bucket needed
  schedule: "0 3 * * *" # cron in UTC with a single fixed minute; at most hourly
  retention: 7d
```

Changing `capacity` does not resize an existing volume; see [Growing the Volume](#growing-the-volume).

### Server

```yaml theme={null}
image: mintplexlabs/anythingllm:1.19.0
resources:
  minCpu: 500m
  maxCpu: 2000m
  minMemory: 1Gi
  maxMemory: 3Gi        # the built-in embedder and document parsing run in this container
telemetry:
  enabled: false        # true = send anonymous usage events to AnythingLLM
```

## Connecting

| What | Where |
| - | - |
| UI and API (public) | `status.canonicalEndpoint` of `cpln workload get RELEASE_NAME-anythingllm --gvc GVC_NAME -o yaml`; sign in with the admin secret (`cpln secret reveal ADMIN_SECRET_NAME -o yaml`) |
| From your machine (private install) | `cpln port-forward RELEASE_NAME-anythingllm 3001:3001 --gvc GVC_NAME`, then `http://localhost:3001` |
| Internal API | `http://RELEASE_NAME-anythingllm.GVC_NAME.cpln.local:3001` (allow the caller in `internalAccess`) |
| Developer API | `/api/v1/...` with the header `Authorization: Bearer API_KEY`; create keys in Settings → Developer API; reference at `/api/docs` |
| Chat widget | Settings → Chat Embed (see [Embed Widget](#embed-widget)) |
| Control Plane MCP server | In a workspace chat, start an agent with `@agent`; the `cpln` server's tools act as the service account in `cplnMcp.keySecretName` |

Verify the server is up:

```bash theme={null}
cpln port-forward RELEASE_NAME-anythingllm 3001:3001 --gvc GVC_NAME
curl -s http://localhost:3001/api/ping
```

The reply is `{"online":true}`.

### Embed Widget

In Settings → Chat Embed, create an embed for a workspace, list the website's address under allowed domains, and paste the script tag it shows into your site. An embed with no allowed domains refuses every chat, and a page on a domain that is not listed is refused too.

## Operations

### Backing Up

Platform snapshots of the whole volume run on the `backup` schedule (daily at 03:00 UTC, kept 7 days by default) and need no bucket or cloud account. List them:

```bash theme={null}
cpln volumeset snapshot get RELEASE_NAME-anythingllm-storage --gvc GVC_NAME
```

The volume and its snapshots hold provider keys entered in the UI in plain text, alongside every document, so treat snapshots as sensitive.

### Restoring a Backup

Restoring replaces the volume with the snapshot; everything written after the snapshot is lost, and the workload restarts onto the restored volume.

```bash theme={null}
cpln volumeset snapshot restore RELEASE_NAME-anythingllm-storage --gvc GVC_NAME --snapshot-name SNAPSHOT_NAME --location LOCATION_NAME --volume-index 0
```

### Growing the Volume

```bash theme={null}
cpln volumeset expand RELEASE_NAME-anythingllm-storage --gvc GVC_NAME --new-size NEW_SIZE_GIB --location LOCATION_NAME --volume-index 0
```

### Scaling and Availability

AnythingLLM runs as a single replica: its database, vector store and job scheduler belong to one process, and upstream has no multi-instance mode. A restart or upgrade makes it unavailable for a few minutes. Use a single-location GVC.

### Troubleshooting

> [accordion] The deployment never becomes ready and logs are empty
>
> A secret the release names does not exist. Read `status.versions[].message` with `cpln workload get-deployments RELEASE_NAME-anythingllm --gvc GVC_NAME -o yaml`, create the secret, then run `cpln workload force-redeployment RELEASE_NAME-anythingllm --gvc GVC_NAME` to skip the wait.

> [accordion] The container restarts and logs anythingllm-bootstrap: FATAL
>
> The admin secret is invalid (username not 2-64 lowercase letters, digits, `.`, `_`, `@` or `-` starting with a letter, or a password under 8 characters), or a key in the keys secret is empty. Fix the secret and run `cpln workload force-redeployment RELEASE_NAME-anythingllm --gvc GVC_NAME`. The release never serves without a sign-in.

> [accordion] Chats or vector search fail with No OpenAI API key was set
>
> No chat model is configured. Set `llm.provider` and `llm.model`, or choose a model in Settings → AI Providers → LLM.

> [accordion] The agent does not know your documents
>
> MCP servers are configured and the workspace is on Automatic chat mode. Set the workspace to Chat or Query mode.

> [accordion] The cpln MCP server is not running
>
> Read the `cpln-mcp:` log line (see [Control Plane MCP Server](#control-plane-mcp-server)). A line reporting HTTP 401 means the key in `cplnMcp.keySecretName` was refused; create a new service-account key, update the secret and run `cpln workload force-redeployment RELEASE_NAME-anythingllm --gvc GVC_NAME`.

> [accordion] The embed widget shows Could not respond to message
>
> The page's domain is not under the embed's allowed domains in Settings → Chat Embed (HTTP 401 on the request).

> [accordion] The UI is slow or briefly unavailable while a large document embeds
>
> The built-in embedder and document parsing share the container's CPU and memory. Use an `ollama` or `generic-openai` embedder for large document sets, or raise `resources`.

## Important Notes

* Never change or delete the keys secret: `SIG_KEY` and `SIG_SALT` encrypt stored data, and a new `JWT_SECRET` signs everyone out.
* The admin secret is read on first start only; change the password in the UI afterwards.
* Values set in `llm` and `embedding` win over the UI on every restart; with `llm.provider: ""` the chat model chosen in the UI stays.
* Changing the embedding engine or model in the UI deletes every workspace's vectors and document links. Changing `embedding` in the values deletes nothing, but documents already embedded stay unsearchable until they are added again.
* Every agent run that uses the Control Plane MCP server acts as its service account: keep that account's policy narrow.
* Uninstalling deletes the volume after a final snapshot, and with it every workspace, document and account.

## External References

* [AnythingLLM documentation](https://docs.anythingllm.com)
* [Configuration through environment variables](https://docs.anythingllm.com/configuration)
* [Chat embed widget](https://docs.anythingllm.com/features/chat-widgets)
* [MCP in AnythingLLM](https://docs.anythingllm.com/mcp-compatibility/overview)
* [AnythingLLM on GitHub](https://github.com/Mintplex-Labs/anything-llm)
