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.What Gets Created
*.cpln.app URL is on by default and every request needs a sign-in.
Prerequisites
Create the keys secret
keys.secretName to this name. Never change or delete it afterwards.Create the admin secret
., _, @ or -, starting with a letter; the password is 8 characters or more:admin.secretName to this name.Create the optional secrets
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:Installation
The required values are the names of the two secrets from Prerequisites:UI
CLI
Terraform
Pulumi
Configuration
Keys and Admin Account
Chat Model
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 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
engine at ollama or generic-openai.
MCP Tool Servers
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
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:
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:
Access
Storage and Backup
capacity does not resize an existing volume; see Growing the Volume.
Server
Connecting
{"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 thebackup schedule (daily at 03:00 UTC, kept 7 days by default) and need no bucket or cloud account. List them:
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.Growing the Volume
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
The deployment never becomes ready and logs are empty
The deployment never becomes ready and logs are empty
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.The container restarts and logs anythingllm-bootstrap: FATAL
The container restarts and logs anythingllm-bootstrap: FATAL
., _, @ 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.Chats or vector search fail with No OpenAI API key was set
Chats or vector search fail with No OpenAI API key was set
llm.provider and llm.model, or choose a model in Settings → AI Providers → LLM.The agent does not know your documents
The agent does not know your documents
The cpln MCP server is not running
The cpln MCP server is not running
cpln-mcp: log line (see 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.The embed widget shows Could not respond to message
The embed widget shows Could not respond to message
Important Notes
- Never change or delete the keys secret:
SIG_KEYandSIG_SALTencrypt stored data, and a newJWT_SECRETsigns everyone out. - The admin secret is read on first start only; change the password in the UI afterwards.
- Values set in
llmandembeddingwin over the UI on every restart; withllm.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
embeddingin 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.