# Project pack: AnythingLLM @ 0acf0e8

Facts about **AnythingLLM** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v1.md). This pack is pinned to one version and never changes after publication.

> AnythingLLM lets you drop in PDFs, Word files, web pages and notes, then chat with them and get answers that point back to the source. Each topic gets its own "workspace", so household paperwork, a hobby and a course stay separate. It comes with a built-in local AI and document search, so it can work without any cloud account, or you can plug in ChatGPT, Claude, Gemini or Ollama.

## Version and source
- Repository: https://github.com/Mintplex-Labs/anything-llm
- Pinned commit: `0acf0e896721d214df6a8c50282a6d118666a735`. Use exactly this version.
- Get it: `git clone https://github.com/Mintplex-Labs/anything-llm anythingllm && cd anythingllm && git checkout 0acf0e896721d214df6a8c50282a6d118666a735`
- Or download a zip: https://github.com/Mintplex-Labs/anything-llm/archive/0acf0e896721d214df6a8c50282a6d118666a735.zip
- Official docs: https://docs.anythingllm.com
- Licence: **MIT**. Very permissive. You can use, change and share it, even commercially, as long as you keep the copyright notice. No obligation to publish your changes.

## Running it
- Easiest:

  ```sh
  export STORAGE_LOCATION=$HOME/anythingllm && mkdir -p $STORAGE_LOCATION && touch "$STORAGE_LOCATION/.env" && docker run -d -p 3001:3001 --cap-add SYS_ADMIN -v ${STORAGE_LOCATION}:/app/server/storage -v ${STORAGE_LOCATION}/.env:/app/server/.env -e STORAGE_DIR="/app/server/storage" mintplexlabs/anythingllm # then open http://localhost:3001 and follow the setup screens
  ```

- Needs: Docker (2 GB RAM minimum, 10 GB disk recommended), or the AnythingLLM Desktop app for Mac, Windows and Linux, For development, Node.js 18 (.nvmrc) and yarn
- Develop: `yarn setup   # copies .env files and sets up Prisma; then in three terminals: yarn dev:server, yarn dev:collector, yarn dev:frontend`
- Test: `yarn test`
- Check/lint: `yarn lint`
- Stack: javascript (Node.js, Express, React, Vite, Tailwind CSS, Prisma, LanceDB). Difficulty for a non-developer with an AI: **moderate**. Three Node.js parts (server, document collector and React frontend) in plain JavaScript with Prisma on SQLite. Models, documents, agents, branding and users are all set in the app's own settings. Code changes are approachable but touch two or three folders and need yarn plus the Prisma setup step.

## The project's own AI instructions
Read these in the repository before changing code: `CONTRIBUTING.md`.

## Customisation points (settings → extend → code)
- **models-and-providers** [settings]: Choose the built-in local model, Ollama or a cloud provider, and set one per workspace if you like. → `Settings → AI Providers → LLM / Embedder / Transcription / Voice (frontend/src/pages/GeneralSettings/LLMPreference, EmbeddingPreference)`
- **workspaces** [settings]: One workspace per topic, each with its own documents, system prompt, temperature and "query only" mode that refuses to answer outside your documents. → `Workspace → settings cog → General / Chat Settings / Agent Configuration (frontend/src/pages/WorkspaceSettings/)`
- **branding** [settings]: Your own logo, app name, footer links, welcome messages, theme and language. → `Settings → Customization → Branding & Whitelabeling / UI Preferences (frontend/src/pages/GeneralSettings/Settings/)`
- **users-and-security** [settings]: Add a password, or switch on multi-user mode so each person has their own login and workspaces. → `Settings → Security (frontend/src/pages/GeneralSettings/Security)`
- **agent-skills-and-mcp** [extend]: Turn on web search, file saving and SQL tools, add MCP servers, or write your own JavaScript agent skill. → `Settings → Agent Skills; custom skills loaded by server/utils/agents/imported.js (manifest schema in server/utils/agents/imported-manifest.schema.json); MCP servers`
- **developer-api** [extend]: Send documents and questions from scripts, shortcuts or other apps. → `Settings → Developer API (server/endpoints/api/**, including an OpenAI-compatible endpoint)`
- **embed-and-scheduled** [extend]: Put a chat bubble on your own website, or run a prompt on a schedule (e.g. a weekly summary). → `Settings → Chat Embed and Scheduled Jobs (frontend/src/pages/GeneralSettings/ChatEmbedWidgets, ScheduledJobs)`
- **frontend-pages** [code]: New screens or a simpler chat layout. → `frontend/src/pages/**, frontend/src/components/WorkspaceChat/**, text in frontend/src/locales/en/common.js`
- **server-and-collector** [code]: New data, behaviour or document types. Database changes need a Prisma migration. → `server/endpoints/ → server/models/ (Prisma, server/prisma/schema.prisma); new file types in collector/processSingleFile/convert/`

## Must keep working
- Uploaded documents, workspaces and chat history in the storage folder. Back it up before upgrades or code changes.
- Privacy between users in multi-user mode. One person's private workspaces and chats must stay hidden from others.
- Source citations. Answers should keep pointing back to the document they came from.
- Database changes need a Prisma migration in server/prisma/.

## Staying updatable
Settings, workspaces, custom agent skills, MCP and the developer API cover most personal needs without a fork. Upstream's CONTRIBUTING.md says pull requests with "Claude Code" or similar agent signatures in the commit history, or LLM-generated filler tests, will be closed; new integrations must meet strict criteria. Keep AI-written changes in your own copy.

## Data, costs and safety
- Personal data: **yes**. Stored in: Everything lives in the storage folder you mount (STORAGE_LOCATION): the SQLite database (anythingllm.db), uploaded and processed documents, the LanceDB vector index, downloaded models, and the .env file with settings and keys. Documents you upload are often the most private files you have (bank letters, medical notes, contracts). Back up the whole storage folder while the container is stopped. Workspaces can also be exported from the app.
- Service: Built-in local LLM engine and embedder (optional, free (uses your own computer)): Chat and document search without any outside service. Downloads models from cdn.anythingllm.com on first use.
- Service: Cloud AI providers (OpenAI, Anthropic, Gemini, Mistral, OpenRouter, Groq and many more) (optional, pay-per-use with your own API key): Stronger chat models, image understanding, speech and embeddings.
- Service: Ollama, LM Studio or LocalAI (optional, free (uses your own computer)): Use local models you already run.
- Service: Web search for agents (e.g. SearXNG, Serper, Bing, Tavily) (optional, free (SearXNG) or free tiers / pay-per-use): Lets the @agent look things up online.
- Service: PostHog telemetry (optional, free): Anonymous usage events sent to the makers. On by default; turn off with DISABLE_TELEMETRY=true or Settings → Privacy.
- Setting `STORAGE_DIR`: Where AnythingLLM keeps its database, documents and vectors inside the container (/app/server/storage).
- Setting `SERVER_PORT`: Port the app listens on (3001 by default).
- Setting `LLM_PROVIDER`: Which chat model provider to use, e.g. ollama, openai, anthropic. Usually chosen in the setup screens instead.
- Setting `OLLAMA_BASE_PATH`: Address of your Ollama server, e.g. http://host.docker.internal:11434.
- Setting `OPEN_AI_KEY` (**secret**: the person enters it themselves, never in chat): OpenAI API key, if you use OpenAI. Can also be entered in the settings screens.
- Setting `JWT_SECRET` (**secret**: the person enters it themselves, never in chat): Random string (12+ characters) used to sign logins once a password or multi-user mode is on.
- Setting `SIG_KEY` (**secret**: the person enters it themselves, never in chat): Random passphrase (32+ characters) used to protect stored secrets.
- Setting `SIG_SALT` (**secret**: the person enters it themselves, never in chat): Random salt (32+ characters) that goes with SIG_KEY.
- Setting `DISABLE_TELEMETRY`: Set to true to stop sending anonymous usage events.
- Out of the box the Docker version has no password. Set one (or turn on multi-user mode) in Settings → Security before anyone else can reach it, and use HTTPS before putting it on the internet.
- When you use a cloud model, the parts of your documents that match your question are sent to that provider with each message. Use the built-in model or Ollama to keep everything local.
- Anonymous telemetry is on by default. Turn it off with DISABLE_TELEMETRY=true or in Settings → Privacy.
- API keys are stored in the .env inside your storage folder. Never share that folder or paste it into an AI chat.
- The Docker command needs --cap-add SYS_ADMIN for the built-in web scraper; agents with web browsing or SQL access can reach other systems, so only enable the skills you need.

---

# Customising AnythingLLM

AnythingLLM is three plain-JavaScript apps in one repo: `server` (API, AI and vector search), `collector` (turns files and web pages into text) and `frontend` (React). **Nearly every personal adaptation is a setting in the app.** Exhaust levels 1 and 2 before touching code.

## Level 1: Settings (no code)
- **Models:** Settings → AI Providers. Pick the built-in local model, Ollama, LM Studio or a cloud provider for chat, embeddings, transcription and voice. Each workspace can override the chat model.
- **Workspaces:** one per topic. Each has its own documents, system prompt, temperature, and a *Query* mode that only answers from your documents (with a custom "I don't know" reply).
- **Look and name:** Settings → Customization → *Branding & Whitelabeling* (logo, app name, footer links, support email) and *UI Preferences* (theme, language, chat behaviour).
- **People:** Settings → Security. Add a password, or turn on multi-user mode for separate logins with admin, manager and default roles.
- **Privacy:** Settings → Privacy & Data, or `DISABLE_TELEMETRY=true` in the storage `.env`.
- **Memories:** the AI can remember facts about you or a workspace; review them in the chat settings.

## Level 2: Extend (no fork)
- **Agent Skills** (Settings → Agent Skills): web search, web scraping, saving files, charts, SQL connectors, Gmail/Outlook/Google Calendar skills. Type `@agent` in a chat to use them.
- **Custom agent skills:** small JavaScript plugins with a `plugin.json` manifest, loaded by `server/utils/agents/imported.js` (schema: `server/utils/agents/imported-manifest.schema.json`). They live in your storage folder, not in the code.
- **MCP servers:** connect other tools the agent can use.
- **Scheduled Jobs:** run a prompt on a timetable, with agent tools.
- **Developer API** (Settings → Developer API, code in `server/endpoints/api/`): upload documents, chat with workspaces, and an OpenAI-compatible endpoint for other apps.
- **Chat Embed:** a chat bubble for your own website, tied to one workspace.

## Level 3: Code
Read upstream `CONTRIBUTING.md` first.

| Change | Where |
|---|---|
| Chat screen | `frontend/src/components/WorkspaceChat/**`, `frontend/src/pages/WorkspaceChat/` |
| Settings screens | `frontend/src/pages/GeneralSettings/**`, `frontend/src/pages/WorkspaceSettings/**` |
| Wording | `frontend/src/locales/en/common.js` (then `yarn translations:verify`) |
| Styles | `frontend/src/index.css`, `frontend/tailwind.config.js` |
| API endpoints | `server/endpoints/**` |
| Data | `server/models/*.js` + `server/prisma/schema.prisma` and a Prisma migration |
| New AI provider | `server/utils/AiProviders/<name>/` (upstream only accepts established providers) |
| New file type | `collector/processSingleFile/convert/` |
| Built-in agent tools | `server/utils/agents/aibitat/plugins/` |

## Running locally
- **Just use it:** the Docker command in `docker/HOW_TO_USE_DOCKER.md` (mount a storage folder so updates keep your data), then open http://localhost:3001. Or install the Desktop app from anythingllm.com.
- **Develop:**
  1. Install Node 18 (`.nvmrc`) and yarn.
  2. Run `yarn setup` (installs, copies `.env` files, sets up Prisma).
  3. Fill in `server/.env.development`.
  4. Run `yarn dev:server`, `yarn dev:collector` and `yarn dev:frontend` in three terminals.
- **Check:** `yarn lint` and `yarn test`.

## Pitfalls
- Without a mounted storage folder, all documents and chats vanish when the container is replaced.
- Changing the embedder after adding documents means re-embedding everything. Pick it first.
- From inside Docker, a model server on your own computer is `http://host.docker.internal:<port>`, not `localhost` (on Linux add `--add-host=host.docker.internal:host-gateway`).
- Some features (multi-user, chat embed widgets) are Docker-only, not in the Desktop app.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/anythingllm/0acf0e8/bespoke.yaml) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/anythingllm/0acf0e8/SKILL.md)