DEV Community

Cover image for RAGClaw: A Shared Agent Platform for Private Deployment, Where Your Org Sets the Capability Boundary
Adam
Adam

Posted on Originally published at github.com

RAGClaw: A Shared Agent Platform for Private Deployment, Where Your Org Sets the Capability Boundary

#agents #rag #mcp #docker

🌟 Repo: github.com/adam-andel/ragclaw-lite

Most "AI for my team" stories end in one of two places:

  • A SaaS product. It works great, until someone pastes the Q3 financials into a prompt and you realize the data now lives on someone else's servers.
  • A weekend hack. langchain + a vector DB on your laptop. Cool demo, zero auth, no sandbox, and good luck onboarding the other nine people on your team.

RAGClaw is the middle path that's usually missing: a shared agent platform you deploy privately, on one machine, behind your own auth, with the guardrails (sandbox isolation, key management, admin controls) that an actual organization needs, not the ones a prototype gets away with.

A shared agent platform for private deployment in small & mid-sized organizations.

In this post I'll show you what it is, the five features that make it interesting, how the architecture holds up under scrutiny, and how to get it running in about five minutes.

Why RAGClaw exists

Three traits define it:

  • Ease of use. With Docker installed, a single menu script deploys the whole platform on one machine. No Kubernetes, no cloud bill.
  • Security. Data and keys stay fully private. API keys are centrally managed and encrypted at rest; they never land on disk in plaintext and never leak to the frontend.
  • Controllability. LLM access, SKILLs, MCP servers, and the sandbox network policy are all governed by a super administrator. The capability boundary is set by your organization, not by a vendor's defaults.

That last point matters. In a real team you don't want every user spinning up arbitrary outbound network calls or installing whatever skill they found. RAGClaw puts one admin in charge of the blast radius.

The five features worth your attention

1. Fine-grained context management

Long conversations are where most RAG chatbots fall apart. Context overflows, the model "forgets" what you said 20 messages ago, and first-token latency (TTFT) balloons.

RAGClaw attacks this from three angles:

  • Multi-level compaction. A rolling summary feeds a RAG archive chain, so more of a long conversation stays retrievable instead of being evicted.
  • Async compaction. Summarization happens off the critical path, so it never blocks answer generation. Lower TTFT, no awkward pauses.
  • Hybrid memory recall. Remembered context is fetched via vector + BM25 hybrid retrieval, and you can still manually edit or delete any memory. You stay in control.

2. A hardened execution sandbox ("the Claw")

This is the part I'd want to see in a security review. The agent's code execution doesn't run in your app process or on the host. It runs in a separate mcp-repl container on an internal-only network:

  • Per-user UID isolation. Every execution drops privileges to an unprivileged user_u<uid> via setuid, with chown'd workdirs.
  • Brokered network egress. The sandbox has no direct internet route. Every outbound connection is forced through ragclaw-egress, which enforces the policy you pick: deny (default: everything blocked), allowlist (only configured domains), or allow (debugging only). The sandbox is never silently online.
  • Container hardening. read_only rootfs, tmpfs /tmp, no-new-privileges, a custom seccomp.json blocking dangerous syscalls, cap_drop: ALL (only SETUID/SETGID/CHOWN re-added for isolation), plus memory and PID limits. No host port is published. The MCP server is internal-only.

System settings: where network policy and LLM keys are governed

In short, you can finally let the agent "act" without holding your breath.

3. A shared, co-managed workspace

Most agents hand you a download link and call it a day. RAGClaw gives you a real workspace, a file browser that feels like your OS file manager, and it's the same workspace the agent writes to.

The workspace: breadcrumb nav, list/grid views, drag-drop upload, batch zip

  • Breadcrumb navigation, list and grid (card) views, type filters, and eight sort options.
  • Recursive filename search that reaches into subfolders.
  • Create folders, drag-and-drop upload with a concurrent pool (per-file progress, pause/resume/cancel), download as a single ZIP, rename, move, batch delete.

Because it's backed by the same volume the sandbox uses, what you drop in is instantly available to the agent, and what the agent generates shows up in your folder, ready to grab, tweak, or ship. No export-and-import dance.

4. A shared SKILL system that's both efficient and safe

Skills (third-party capability packs) are uploaded as whole folders or zips from the admin page, so everything lands at once.

Skill management: upload, enable, and configure skills

Two details make it production-friendly:

  • A configurable .ragclaw/ adapter boosts script-invocation efficiency while leaving the third-party source untouched. You don't fork the skill to make it work, you adapt around it.
  • Skills that need an API key route through an injection proxy (:9090 inside the egress container). The key lives in process memory on the proxy and is injected at request time, so a skill can be shared across multiple users without ever exposing the key to them or to the frontend.

5. RAG + BM25 hybrid retrieval (with coreference resolution)

Retrieval runs vector search and BM25 in parallel and fuses the results. Better still, the LLM can proactively invoke the hybrid_search meta-tool on demand, topping up a sparse first-pass recall when it knows more context is needed.

Document management: the knowledge base the hybrid retriever searches

And for the "these meetings" / "them" problem: when a query contains a reference, RAGClaw resolves it against conversation history (coreference resolution) and rewrites the query into a self-contained form before searching. No more "which meetings are you talking about" dead ends.

A look at the admin surface

RAGClaw ships a proper enterprise admin UI, not just a chat box. A few highlights:

  • MCP servers. Register and manage external tool servers (HTTP + stdio).

MCP server management

  • Scheduled jobs. Let agents run on a cron, owner-scoped.

Cron job management

  • User management. Multi-user, admin-governed.

User management

  • Profile & personalization. Per-user settings.

Personal profile

The login page keeps the whole thing behind your own auth:

Login page

And the answer view, once the agent is done planning:

Conversation page: the agent plans, calls tools, and streams an answer

Conversation page: answer generation

Under the hood

Layer Tech Notes
Backend FastAPI Async-native, auto OpenAPI
Agent orchestration LangGraph Declarative state graph, conditional routing + multi-turn tool calls
Execution engine REPL sandbox (Python / Shell / Node.js) Multi-language exec + workspace file management: the agent's "hands"
Vector DB ChromaDB Embedded, zero-config
Meta DB SQLite + SQLAlchemy ORM models are the schema source of truth; auto-create on startup
Embedding Not bundled by default (install on demand) Six options: large/medium/small × Chinese/English, pick what you need
LLM Any vendor on the OpenAI protocol Fill in your own API Base URL and Key; tool-calling supported
Memory Custom archive on ChromaDB Persists MemoryChunks, recalled via hybrid search: no external memory service
Tool protocol MCP (HTTP + stdio) External tool integration
Frontend Vue 3 + TS + NaiveUI Enterprise admin UI
Deploy Docker Compose + nginx nginx is the single entry point (optional TLS, hot-reload on cert change)

A couple of things worth calling out:

  • The agent graph is real LangGraph, not a single prompt loop. The path is entry → branch → skill-route → tool-decision → tool-exec → context-build, with conditional routing.
  • Secrets are taken seriously. API keys are AES-256-GCM encrypted into config.enc (format RAGC1 + version + key fingerprint + nonce + ciphertext), set only via the Settings UI, and never exposed to the frontend. The KEK (ragclaw_config_key) is a gitignored host file, mode 600, so keys survive container rebuilds. repl_auth_secret and jwt_secret are DB-backed and rotatable from the UI with no restart. Skill API keys follow the same principle: skills that need a key route through the injection proxy (:9090 inside the egress container), where the key lives only in the proxy's process memory and is injected at request time, so it is never exposed to users or the frontend and a single skill can be shared safely across users.
  • Tests run in container mode, with explicit focus on security/ cases (auth, RBAC, isolation, injection, IDOR).

Quick start

Prerequisites: Docker Engine 20.10+ (or Docker Desktop with the WSL2 backend on Windows/macOS) and the docker compose v2 plugin.

git clone https://github.com/adam-andel/ragclaw-lite ragclaw-lite
cd ragclaw-lite

# Optional: pin host ports / COMPOSE_PROJECT_NAME
cp .env.example .env

# Production: launch the interactive control menu
bash bin/sh/menu.sh

# Windows (CMD):
#   bin\psl\menu.bat
Enter fullscreen mode Exit fullscreen mode

On first boot the stack generates secrets/ragclaw_config_key (the AES-256 KEK for config.enc, mode 600, gitignored), prints the entry URL (random host port unless pinned), and serves Swagger at /docs. Complete super-admin setup, then open Settings → LLM and paste your provider API key. It is encrypted into config.enc (AES-256-GCM) and never exposed to the frontend.

For daily development, use the hot-reload dev mode, where source changes take effect without rebuilding images. On Windows, keep the checkout inside a WSL2 distro rather than a C:\ path: bind mounts forwarded via 9P/gRPC-FUSE add noticeable file-I/O latency and break inotify-based hot reload.

Who is this for?

  • A small team or department that wants ChatGPT-style RAG + agents but can't send data to a third party.
  • A self-hoster who's tired of glue-code prototypes and wants real auth, roles, and a sandbox.
  • An org with compliance needs where "the admin decides the capability boundary" is a requirement, not a nice-to-have.

If you're a solo dev just playing with prompts, this may be more than you need. If you're responsible for other people using an agent with your company's data, it's exactly the shape you want.

Try it, break it, improve it

RAGClaw is Apache License 2.0 and welcoming contributions.

If this solved a problem you've been chewing on, drop a ⭐ and let me know in the comments what you'd build on top of it. What's the first skill or workflow you'd wire in?

Built for teams that want agents they can actually trust with their data.

Top comments (0)