{"slug": "ragbox-it-s-rag-in-a-box-as-easy-as-it-gets", "title": "Ragbox: It's RAG in a box, as easy as it gets", "summary": "A project called ragbox packages retrieval-augmented generation into a single Docker container that indexes a mounted read-only folder and exposes the contents to AI agents through a Model Context Protocol (MCP) server with one `search` tool combining vector and keyword search. Ragbox extracts text from supported files, chunks it, generates embeddings via an external provider such as Ollama or any OpenAI-compatible API, and stores chunks and embeddings in PGlite, an embedded PostgreSQL database with the pgvector extension, so no separate database is required. The service watches the folder and re-indexes added, changed, or deleted files after a 10-second default cool-down, and serves a web page on port 8080 for monitoring indexing, viewing errors, running test searches, and changing settings.", "body_md": "It's RAG in a box, as easy as it gets!\n\nragbox is a local retrieval-augmented generation (RAG) service that runs in a single Docker container. It indexes the files in a folder and lets AI agents search them through the Model Context Protocol (MCP).\n\n- Scans a folder that you mount into the container as read-only.\n- Extracts the text from each supported file, splits it into chunks, and creates an embedding for each chunk. Embeddings are created by an external provider, such as Ollama or any OpenAI-compatible API.\n- Stores the chunks and embeddings in [PGlite](https://pglite.dev) , an embedded\nPostgreSQL database with the pgvector extension. No separate database is\nrequired.\n- Watches the folder and re-indexes files that are added, changed, or deleted. After a file changes, ragbox waits for a cool-down period (10 seconds by default) before it re-indexes the file.\n- Runs an MCP server over HTTP with one tool, `search` . The tool combines\nvector search with keyword search.\n- Serves a web page where you can monitor indexing, see errors, run test searches, and change settings.\n\n| Type | Extensions | \n|---|---|\n| Documents | `.pdf` ,`.docx` ,`.docm` ,`.dotx` ,`.pptx` ,`.pptm` ,`.potx` ,`.xlsx` ,`.xlsm` | \n| Text and markup | `.md` ,`.markdown` ,`.mdx` ,`.txt` ,`.text` ,`.log` ,`.rst` ,`.html` ,`.htm` ,`.xhtml` | \n| Data | `.csv` ,`.tsv` ,`.json` ,`.jsonc` ,`.json5` ,`.hujson` ,`.geojson` ,`.webmanifest` ,`.yaml` ,`.yml` ,`.xml` ,`.xsd` ,`.xsl` ,`.xslt` ,`.svg` ,`.plist` ,`.csproj` ,`.pom` ,`.ipynb` | \n| Source code | `.py` ,`.c` ,`.h` ,`.cpp` ,`.cc` ,`.hpp` ,`.js` ,`.jsx` ,`.mjs` ,`.cjs` ,`.ts` ,`.tsx` ,`.mts` ,`.cts` ,`.java` ,`.cs` ,`.go` ,`.rs` ,`.kt` ,`.kts` ,`.swift` ,`.scala` ,`.rb` ,`.php` ,`.lua` ,`.dart` ,`.tf` ,`.cue` ,`.rego` ,`.bzl` ,`.star` ,`.proto` ,`.sql` ,`.sh` ,`.bash` ,`.zsh` ,`.fish` ,`.ps1` ,`.bat` ,`.cmd` ,`.jq` | \n| Files without an extension | `Dockerfile` ,`Containerfile` ,`Makefile` ,`Tiltfile` ,`BUILD` ,`BUILD.bazel` | \n| Images | `.png` ,`.jpg` ,`.jpeg` ,`.jpe` ,`.jfif` ,`.gif` ,`.webp` | \n| Audio | `.wav` ,`.wave` | \n\nMetaTrader files (`.mq4`, `.mqh`) are also supported but are disabled by\ndefault. You can enable or disable any file type on the **Settings** page.\n\nPDF files must contain a text layer. ragbox doesn't run OCR on scanned documents.\n\nBefore you begin, install [Docker](https://docs.docker.com/get-docker/).\n[Ollama](https://ollama.com) is optional: if it isn't installed, ragbox can\nrun Ollama in a container.\n\nThe setup script asks a few questions, starts ragbox, and shows how to connect an MCP client. It works on macOS, Linux, and Windows Subsystem for Linux (WSL).\n\n1. \nClone the repository: \n\n```\ngit clone https://github.com/ferraridavide/ragbox.git\ncd ragbox\n```\n\n2. \nRun the setup script: \n\n```\n./run.sh\n```\n\n Follow the wizard. It asks which folder to index, starts ragbox, and returns the MCP endpoint to add to your client.\n\nOn macOS, Docker containers can't use the GPU, so Ollama in a container is much slower than a native installation. For faster indexing on a Mac, install Ollama before you run the script.\n\nTo start ragbox without the setup script, choose the Compose file that fits\nyour setup. Replace `/path/to/your/documents` with the folder that you want\nto index.\n\n- \nIf Ollama is installed on your computer, download the embedding model and start ragbox: \n\n```\nollama pull embeddinggemma-2\nRAGBOX_DOCS=/path/to/your/documents docker compose up -d --build\n```\n\n- \nIf Ollama isn't installed, start ragbox together with an Ollama container. The container downloads `embeddinggemma-2` on first start:\n\n```\nRAGBOX_DOCS=/path/to/your/documents docker compose -f docker-compose.ollama.yml up -d --build\n```\n\n To use an NVIDIA GPU on Linux, uncomment the `deploy` section in`docker-compose.ollama.yml` .\n\nOpen [http://localhost:8080](http://localhost:8080) to see the indexing progress. To use a different\nport, set `RAGBOX_HOST_PORT`, for example `RAGBOX_HOST_PORT=9090`.\n\n`embeddinggemma-2` also embeds images and audio. For details, see\n[Images and audio](#images-and-audio). To use a different model, change\n`RAGBOX_EMBEDDING_MODEL` in the Compose file.\n\nThe MCP endpoint is `http://localhost:8080/mcp`. It uses the Streamable HTTP\ntransport.\n\nTo add ragbox to Claude Code, run the following command:\n\n```\nclaude mcp add --transport http ragbox http://localhost:8080/mcp\n```\n\nFor clients that use a JSON configuration file, add the following entry:\n\n```\n{\n  \"mcpServers\": {\n    \"ragbox\": { \"type\": \"http\", \"url\": \"http://localhost:8080/mcp\" }\n  }\n}\n```\n\nThe `search` tool accepts the following arguments:\n\n| Argument | Required | Description | \n|---|---|---|\n| `query` | Yes | The text to search for. | \n| `limit` | No | The maximum number of results, from 1 to 50. The default is 8. | \n| `path_prefix` | No | Searches only the files in this folder, for example `projects/acme/` . | \n\nYou can change all settings on the **Settings** page of the web interface.\nTo set initial values, use environment variables in `docker-compose.yml`.\nValues that you save in the web interface take precedence over environment\nvariables.\n\n| Variable | Default | Description | \n|---|---|---|\n| `RAGBOX_EMBEDDING_PROVIDER` | `ollama` | `ollama` or`openai` . Use`openai` for any OpenAI-compatible API. | \n| `RAGBOX_EMBEDDING_URL` | `http://host.docker.internal:11434` | The URL of the embedding provider. For `openai` , include the API version, for example`https://api.openai.com/v1` . | \n| `RAGBOX_EMBEDDING_MODEL` | `embeddinggemma` | The embedding model. | \n| `RAGBOX_EMBEDDING_API_KEY` | None | The API key for the embedding provider. | \n| `RAGBOX_COOLDOWN_SECONDS` | `10` | The number of seconds to wait after a file changes before ragbox re-indexes it. | \n| `RAGBOX_MCP_TOKEN` | None | If set, MCP clients must send the header `Authorization: Bearer <token>` . | \n\nEvery other setting on the **Settings** page can be set in the same way. The\nvariable name is `RAGBOX_` followed by the setting name in upper snake case.\nFor example, `chunkSize` becomes `RAGBOX_CHUNK_SIZE`.\n\nIf you change the embedding model, ragbox rebuilds the index.\n\n- The web interface doesn't have authentication. By default,\n`docker-compose.yml` makes ragbox available only on`127.0.0.1` .\n- Run only one ragbox container for each data volume.\n- On Linux, the container runs as user ID 1000. That user must be able to read the mounted folder.\n- On Linux, a native Ollama installation listens only on `127.0.0.1` by\ndefault, so the ragbox container can't reach it. Set`OLLAMA_HOST=0.0.0.0` for the Ollama service, or use`docker-compose.ollama.yml` .\n\nTo run ragbox without Docker, you need Node.js 22 or later.\n\n```\nnpm install\nRAGBOX_DOCS_DIR=./docs RAGBOX_DATA_DIR=./data RAGBOX_EMBEDDING_URL=http://localhost:11434 npm run dev\nnpm test\n```\n\nragbox is licensed under the MIT License. Parts of the file parsing and\nchunking code are adapted from\n[knowledge-rag](https://github.com/lyonzin/knowledge-rag), which is also\nlicensed under the MIT License. For details, see [LICENSE](https://github.com/ferraridavide/ragbox/blob/main/LICENSE).", "url": "https://wpnews.pro/news/ragbox-it-s-rag-in-a-box-as-easy-as-it-gets", "canonical_source": "https://github.com/ferraridavide/ragbox", "published_at": "2026-10-29 12:34:38+00:00", "updated_at": "2026-10-29 12:47:34.254302+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "agent-protocols", "ai-search", "artificial-intelligence"], "entities": ["ragbox", "Docker", "Model Context Protocol", "Ollama", "PGlite", "pgvector", "embeddinggemma-2", "GitHub"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/ragbox-it-s-rag-in-a-box-as-easy-as-it-gets", "markdown": "https://wpnews.pro/news/ragbox-it-s-rag-in-a-box-as-easy-as-it-gets.md", "text": "https://wpnews.pro/news/ragbox-it-s-rag-in-a-box-as-easy-as-it-gets.txt", "jsonld": "https://wpnews.pro/news/ragbox-it-s-rag-in-a-box-as-easy-as-it-gets.jsonld"}}