OpenDeepWiki: self-hosted repository docs, chat and MCP from AIDotNet

The problem OpenDeepWiki solves for teams that cannot ship code to a hosted docs service

Hosted repository documentation services work well until a repository cannot leave your network. OpenDeepWiki is the open-source version of the DeepWiki project, per its README, and it targets exactly that case: repositories that must be indexed where they already live. It accepts three source types, Git URLs, uploaded ZIP archives, and approved local directories, and turns them into a knowledge base rather than a one-off document dump. The audience is narrow but real. Platform teams running an internal Git host, engineers who want an MCP server that answers questions about a private codebase, and documentation groups that need the same generated content reused across a public site, a chat widget and tool calls. The repository is C# and TypeScript, MIT licensed, with the backend on ASP.NET Core and the frontend on Next.js.

One design decision stands out early: the same indexed content feeds four surfaces. The README lists public docs routes such as /{owner}/{repo}, /{owner}/{repo}/mindmap and /{owner}/{repo}/graphify, plus repository-scoped MCP endpoints, a built-in chat assistant, embedded chat APIs and share links. That reuse is the actual product. A team that only wants a static README generator is paying for a pipeline it will not use.

How the repository processing pipeline actually flows

The README gives a Mermaid diagram and a five-step description of the runtime path. Normalize the source and prepare a workspace under REPOSITORIES_DIRECTORY. Build or refresh repository metadata, branch and language state, and processing logs. Generate documentation catalogs and document content using the configured provider and model bindings. Queue follow-up work: translation, mind map generation, Graphify artifacts, incremental updates. Serve the result through the public web app, admin tooling, chat APIs and MCP endpoints.

The architecture table names the pieces. Backend is ASP.NET Core on .NET 10 with MiniApis and background workers. AI orchestration uses Microsoft.Agents.AI, with prompt assets under src/OpenDeepWiki/prompts. Repository processing uses LibGit2Sharp plus ZIP and local-directory ingestion. Visualization is Mermaid mind maps with optional graphifyy artifacts. Persistence is SQLite or PostgreSQL.

Two details matter more than the diagram. First, catalog generation and content generation are separate model bindings (WIKI_CATALOG_* and WIKI_CONTENT_*), so you can spend a stronger model on structure and a cheaper one on prose. Second, the pipeline is queue-based: the request that imports a repository returns before translation, mind maps and Graphify artifacts finish. That is reasonable, but it means a freshly imported repository can look incomplete for a while, and the README does not document a rollback path for a failed generation run.

Installing OpenDeepWiki with Docker Compose and importing a first repository

The documented path is Docker with Compose support, plus at least one LLM API key compatible with your chosen provider. Clone the repository first.

git clone https://github.com/AIDotNet/OpenDeepWiki.git
cd OpenDeepWiki

Then edit compose.yaml. The README says to set a real JWT secret and your AI credentials at minimum. The shipped file uses environment variable substitution with defaults, so you can either edit the values or export them before starting.

services:
  opendeepwiki:
    environment:
      - JWT_SECRET_KEY=replace-this-in-production
      - CHAT_API_KEY=your-chat-api-key
      - ENDPOINT=https://api.openai.com/v1
      - CHAT_REQUEST_TYPE=OpenAI
      - WIKI_CATALOG_MODEL=gpt-4o
      - WIKI_CONTENT_MODEL=gpt-4o
      - WIKI_LANGUAGES=en,zh,zh-tw,ja,ko,es,fr,de,pt-br,pl,ru,ar
      - WIKI_PARALLEL_COUNT=5

The README notes that CHAT_*, WIKI_CATALOG_* and WIKI_CONTENT_* can point at the same provider, and that translation is optional: if WIKI_TRANSLATION_* is unset it falls back to the content-generation provider and model. WIKI_PARALLEL_COUNT controls how many generation tasks run at once, which directly affects how hard you hit your provider rate limit.

Start the stack, either directly or through the Makefile shortcuts make build and make up.

docker compose up -d --build

The README lists the web UI at http://localhost:3000 and the backend health check at http://localhost:8080/health. The compose.yaml in the repository maps port 18081 on the host to 8080 in the container, so the port you reach depends on whether you use the shipped file or the README's quick start. Check the health endpoint before opening the UI. On a fresh database the seeded admin account is admin@routin.ai with password Admin@123, and the README states plainly that both the JWT secret and that password must be changed before any real deployment.

For PostgreSQL, the README offers a bundled stack and two equivalent configuration pairs.

docker compose -f compose.pgsql.yaml up -d --build

- Database__Type=postgresql
- ConnectionStrings__Default=Host=your-host;Port=5432;Database=opendeepwiki;Username=postgres;Password=secret

Once the admin console is reachable, import a repository from a Git URL, an uploaded ZIP or a local directory. Local imports are gated: compose.yaml sets RepositoryAnalyzer__AllowedLocalPathRoots__0 from LOCAL_IMPORT_ROOT, and the .env.example default points at a specific host path. Point that at your own root or local import will be rejected. After import, the public docs appear at /{owner}/{repo} once generation finishes.

Wiring OpenDeepWiki into an MCP client

The README states that OpenDeepWiki registers official MCP endpoints at /api/mcp and /api/mcp/{owner}/{repo}, and that you can scope the repository by path or by query string. The documented client configuration is a URL entry.

{
  "mcpServers": {
    "OpenDeepWiki": {
      "url": "http://localhost:8080/api/mcp/AIDotNet/OpenDeepWiki"
    }
  }
}

The query-based form is http://localhost:8080/api/mcp?owner=AIDotNet&name=OpenDeepWiki. The README also mentions MCP_ENABLED, with the truncated example showing MCP_ENABLED=false as a way to turn the surface off. If your MCP client expects a stdio command rather than an HTTP URL, this is the wrong shape and you will need a bridge; the README documents only the HTTP endpoints.

Where OpenDeepWiki gets expensive or simply does not fit

The cost model is the first limitation. Every catalog, document page, translation, mind map and Graphify artifact is produced by a model you configure and pay for. WIKI_PARALLEL_COUNT=5 multiplies concurrent requests against that provider, and WIKI_LANGUAGES ships with twelve locales enabled. A repository with many files and twelve target languages is not a small bill, and the README gives no token estimate, no cost calculator and no dry-run mode for previewing generation scope.

Operational gaps matter too. The README does not document rollback for a failed generation run, and it does not describe how to purge a repository's generated content and start over. Local directory import is restricted by an allow-list root, which is correct for safety but means the feature is unusable until an administrator edits that setting and restarts. The seeded admin credentials are published in the README, so an instance exposed before the password is changed is trivially compromised. Graphify artifacts are optional and depend on a separate backend and model (GRAPHIFY_BACKEND, GRAPHIFY_MODEL), which the README does not explain beyond the environment variables.

It is also the wrong tool for a single small repository. If you want one README regenerated occasionally, a script calling a model API is less work than running ASP.NET Core, Next.js, a database, background workers and an admin console. OpenDeepWiki earns its complexity when several repositories need the same treatment and the output must be reachable by both humans and tools.

OpenDeepWiki compared with hosted DeepWiki and with plain static site generators

The obvious comparison is hosted DeepWiki, which OpenDeepWiki describes itself as the open-source version of. The difference is where the repository and the index live. A hosted service indexes public repositories on its own infrastructure; OpenDeepWiki runs on yours, reads from your Git host, ZIP uploads or allow-listed local paths, and writes to SQLite or PostgreSQL that you control. That is the whole reason to pick it. The price is that you own model selection, key management, database backups and upgrades.

The second comparison is a static documentation generator such as MkDocs or Docusaurus. Those render Markdown you write; OpenDeepWiki generates the Markdown from the code and then keeps serving it through chat and MCP. If your team already writes documentation by hand and only needs a publishing pipeline, a static generator is cheaper and more predictable. If the goal is answering questions about code nobody has documented, generation is the point, and a static generator has nothing to offer.

Maintenance cadence, upgrade cost and what the MIT licence leaves to you

The repository is not archived, and the last push was on 2026-09-08, the same day as the v2.0.6 release. Recent releases are close together: v2.0.4 and v2.0.5 both landed on 2026-08-12, and v2.0.6 followed on 2026-09-08. That is a fast release rhythm for a project at version 2.x, and it cuts both ways. Fixes arrive quickly, but schema and configuration changes can arrive with them. The README does not document a migration procedure between versions, so the practical upgrade path is the one the project ships: docker compose up -d --build against the same database, with a backup taken first. The Makefile includes make test, make logs and make down, which cover the operational loop but not migration.

Licensing is MIT, which is permissive and places few conditions on commercial use or modification. The licence text is in the repository root. What MIT does not cover is the third-party model providers you connect: your provider's terms, data retention policy and pricing apply to every repository you index, and the README does not discuss data handling. If your code cannot be sent to a hosted model, the relevant setting is not in OpenDeepWiki; it is whether your provider runs on-premises. The README mentions OLLAMA_BASE_UR in the truncated environment list, which suggests a local provider path exists, but the documentation does not spell it out.

Editorial conclusion

Adopt OpenDeepWiki if you already run Docker, have an OpenAI-compatible endpoint or another supported provider, and want repository docs plus MCP tools inside your own network. Do not adopt it if you expect a fully managed product: you must set JWT_SECRET_KEY, replace the seeded admin password, and accept that every catalog and content page is generated by a model you pay for. Verify first that your provider answers the CHAT_*, WIKI_CATALOG_* and WIKI_CONTENT_* bindings, that the health endpoint at /health returns before you point users at port 3000, and that the MCP endpoint /api/mcp/{owner}/{repo} resolves for a repository you actually imported.

Frequently asked questions

Official sources

1. AIDotNet/OpenDeepWiki on GitHub
2. License: MIT
3. Project website
4. README
5. Releases