{% extends "base.html" %} {% block title %}Documentation{% endblock %} {% block content %}

๐Ÿ“š Documentation โ€“ LLMWikiNG

Version {{ app_version }} ยท Complete manual for setup, multi-wiki, authentication, and API.

๐Ÿš€ Getting Started

  1. Install dependencies: pip install -r requirements.txt
  2. Start the server: ./start.sh (or python3 run.py --port 8080)
  3. On the first start (setup), you will be redirected automatically to /register to create the initial admin user.
  4. Open in browser: http://localhost:8080/LLMWikiNG/

The original wiki/ folder is migrated to wikis/main/ automatically upon the first startup (no data loss).

๐Ÿ—‚๏ธ Multiple Wikis (Sub-wikis)

Each wiki resides under wikis/<name>/ and has its own display name. Use the WebUI to create new wikis:

The app's base URL path can be changed via the LLMWIKI_BASE_PATH environment variable (default: /LLMWikiNG), e.g. example.com/LLMWikiNG/wiki/<Name>/.

๐Ÿ” Authentication & User Management

โš™๏ธ Settings Panels

The central settings page /LLMWikiNG/settings is divided into tabs:

๐Ÿฆˆ Tailscale & Funnel Integration (Remote Agent Access)

LLMWikiNG includes an integrated same-container Tailscale feature (under Settings โžœ Tailscale). This allows you to serve your instance within a private Tailnet network or expose it via Tailscale Funnel to the public internet for remote AI agents (e.g., Claude, Grok, Cursor, AGY) โ€” without port forwarding, NGINX, or CGNAT issues.

๐Ÿ’พ Server Backups

LLMWikiNG includes a full backup management system under Settings โžœ Backups (Admin only). Backups are created as compressed .tar.xz archives and stored in the data/ directory.

Backups can also be managed programmatically via the API (see API section below).

๐ŸŒ API (JSON, Key-protected)

All actions are available under /LLMWikiNG/api/v1 via the X-API-Key header or session cookie (automatic fallback for the web browser).

โš™๏ธ Antigravity AI-Skill Remote Control

Download the official AI remote control skill (SKILL.md) for your Antigravity Agent to control this wiki.

๐Ÿ“ฅ Download Skill
MethodPathDescription
GET/api/v1/wikisList all wikis
GET/api/v1/wikis/<wiki>/pagesList pages in wiki
GET/api/v1/wikis/<wiki>/pages/<slug>Get single page content
GET/api/v1/wikis/<wiki>/tagsList tags with page counts (optional filter via ?tag=)
POST/api/v1/wikis/<wiki>/pagesCreate new page (scope write required)
POST/api/v1/wikis/<wiki>/pages/<slug>/exportExport page
POST/api/v1/wikis/<wiki>/ingestUpload raw source file (to raw/)
GET/api/v1/wikis/<wiki>/pendingList pending uploads
POST/api/v1/wikis/<wiki>/ingest/processProcess ingest queue
GET/api/v1/search?q=&wiki=Search across wiki (Supports wiki=all for Cross-Wiki search)
GET/api/v1/graph?wiki=Get graph coordinates
GET/api/v1/stats?wiki=Get statistics
GET/api/v1/lint?wiki=Run system linter
GET/api/v1/statusGet basic server status
GET/api/v1/system/healthFull readiness check: sync state, source freshness, quality issues, tools, cache, and aggregate usage
GET/api/v1/wikis/<wiki>/usageLocal aggregate page-read statistics without query or content logging
GET/api/v1/system/statusSystem metrics & traffic logs (Admin only)
POST/api/v1/system/syncSync all wiki indexes (Admin only)
GET/api/v1/system/auditRetrieve audit logs โ€“ filterable by action, user, date range (Admin only)
GET/audit/export?fmt=json|csvExport audit logs in JSON or CSV format (Admin only)
GET/api/v1/system/backupsList server-side backup files (Admin only)
POST/api/v1/system/backupsCreate server-side backup (Admin only)
POST/api/v1/system/backups/<file>/restoreRestore server-side backup (Admin only)
DELETE/api/v1/system/backups/<file>Delete server-side backup (Admin only)
GET/api/v1/system/update/checkCheck if update is available (Admin only)
POST/api/v1/system/update/runRun system update (Admin only)
GET/api/v1/usersList users (Admin only)
POST/api/v1/usersCreate user (Admin only)
DELETE/api/v1/users/<id>Delete user (Admin only)
GET/api/v1/api-keysList API keys (Admin only)
POST/api/v1/api-keysCreate API key (Admin only)
DELETE/api/v1/api-keys/<id>Revoke API key (Admin only)
GET/api/v1/mcp-keysList Per-User MCP keys (Admin only)
POST/api/v1/mcp-keysCreate Per-User MCP key with tool permissions (Admin only)
PUT/api/v1/mcp-keys/<id>Edit Per-User MCP key name, user, allowed tools or status (Admin only)
DELETE/api/v1/mcp-keys/<id>Revoke Per-User MCP key (Admin only)
POST/wiki/<wiki>/api/ingestDirect multi-wiki ingest endpoint (API key authorized)
POST/wiki/<wiki>/api/syncDirect index synchronisation (API key authorized)
GET/mcp/sseMCP SSE channel for AI agents (MCP API key)
POST/mcp/messagesMCP JSON-RPC message channel (MCP API key)

๐Ÿ“‹ cURL examples (Terminal remote control)

Export variables to quickly test these queries:

export API_KEY="llmw_your_key"
export SERVER_URL="http://localhost:8082/LLMWikiNG"
export WIKI="main"
1. List all active wikis:
curl -H "X-API-Key: $API_KEY" "$SERVER_URL/api/v1/wikis"
2. List all pages inside a wiki:
curl -H "X-API-Key: $API_KEY" "$SERVER_URL/api/v1/wikis/$WIKI/pages"
3. Read specific wiki page:
curl -H "X-API-Key: $API_KEY" "$SERVER_URL/api/v1/wikis/$WIKI/pages/llm-wiki"
4. Write a new page (requires valid YAML frontmatter):
curl -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"slug":"api-test","content":"---\ntype: Concept\ntitle: API Test\ntimestamp: 2026-07-14T22:00:00Z\n---\n# API Test\nCreated successfully!"}' \
  "$SERVER_URL/api/v1/wikis/$WIKI/pages"
5. Direct multi-wiki Ingest (File, URL or Raw Text):
# URL Ingest
curl -X POST -H "X-API-Key: $API_KEY" -d "url=https://de.wikipedia.org/wiki/Google" -d "title=Google" "$SERVER_URL/wiki/$WIKI/api/ingest"

# File upload
curl -X POST -H "X-API-Key: $API_KEY" -F "file=@/path/to/file.txt" "$SERVER_URL/wiki/$WIKI/api/ingest"

# Raw text paste
curl -X POST -H "X-API-Key: $API_KEY" -d "text=# Raw Text\nContent..." -d "title=Text-Paste" "$SERVER_URL/wiki/$WIKI/api/ingest"
6. Full-text search:
curl -H "X-API-Key: $API_KEY" "$SERVER_URL/api/v1/search?q=SearchQuery&wiki=$WIKI"
7. Get network graph coords:
curl -H "X-API-Key: $API_KEY" "$SERVER_URL/api/v1/wikis/$WIKI/graph"
8. Create user account (Admin only):
curl -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"username":"new_user","password":"secure_password","role":"editor"}' \
  "$SERVER_URL/api/v1/users"
9. Manage API Keys (Admin only):
# List active keys
curl -H "X-API-Key: $API_KEY" "$SERVER_URL/api/v1/api-keys"

# Generate new key (optional require_password toggle)
curl -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"New Key","require_password":false,"scopes":["read","write"]}' \
  "$SERVER_URL/api/v1/api-keys"
10. Manage MCP Keys (Admin only):
# List MCP keys
curl -H "X-API-Key: $API_KEY" "$SERVER_URL/api/v1/mcp-keys"

# Create new MCP key with tool permissions
curl -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Cursor Agent","user_id":1,"allowed_tools":["okf_list_wikis","okf_read_concept","okf_search"]}' \
  "$SERVER_URL/api/v1/mcp-keys"
11. Check & run system update (Admin only):
# Check if update is available:
curl -H "X-API-Key: $API_KEY" "$SERVER_URL/api/v1/system/update/check"

# Run the update:
curl -X POST -H "X-API-Key: $API_KEY" "$SERVER_URL/api/v1/system/update/run"

๐Ÿค– Model Context Protocol (MCP)

LLMWikiNG provides a native Model Context Protocol (MCP) server over HTTP-SSE. This allows AI assistants (like Cursor, OpenCode, and the Antigravity agy CLI) to access, read, write, and search the wiki via the Open Knowledge Format (OKF v0.2).

๐Ÿ”Œ Endpoint Configuration

Configure the MCP server using environment variables before launching LLMWikiNG:

# Enable MCP (Default: true)
ENABLE_MCP_SERVER=true

# Secure your endpoints (X-API-Key required)
LLMWIKING_MCP_KEY="your_secure_mcp_key_2026"

This exposes the MCP endpoints at:

  • Streamable HTTP Endpoint: http://localhost:8080/LLMWikiNG/mcp
  • SSE Channel: http://localhost:8080/LLMWikiNG/mcp/sse
  • Message Channel: http://localhost:8080/LLMWikiNG/mcp/messages

๐Ÿ’ป Client Setup Examples

1. Cursor IDE

Go to Settings โžœ Features โžœ MCP, click "+ Add New MCP Server":

  • Name: LLMWikiNG-OKF
  • Type: SSE
  • URL: http://localhost:8080/LLMWikiNG/mcp/sse
  • Headers: {"X-MCP-Key": "your_secure_mcp_key_2026", "X-API-Key": "your_database_api_key"}
2. OpenCode

Add the server block to your global (~/.config/opencode/opencode.json) or project-specific (opencode.json) configuration:

{
  "mcp": {
    "llmwiking-okf": {
      "type": "remote",
      "url": "http://localhost:8080/LLMWikiNG/mcp/sse",
      "enabled": true,
      "headers": {
        "X-MCP-Key": "your_secure_mcp_key_2026",
        "X-API-Key": "your_database_api_key"
      }
    }
  }
}
3. Antigravity CLI (agy) & Antigravity IDE

Register the SSE server in your global config file at ~/.gemini/config/mcp_config.json (or in your project workspace under .agents/mcp_config.json):

{
  "mcpServers": {
    "llmwiking-okf": {
      "type": "http",
      "url": "http://localhost:8080/LLMWikiNG/mcp",
      "headers": {
        "X-MCP-Key": "your_secure_mcp_key_2026",
        "X-API-Key": "your_database_api_key"
      }
    }
  }
}

Usage in agy: Simply type / in the chat input. agy will autocomplete all 38 remote slash commands (e.g. /wikis, /search, /read, /write, /status, /update). You can also ask agy in plain language to read or update wiki pages.

๐Ÿ›ก๏ธ Security Recommendation:
It is highly recommended to create a dedicated, low-privilege user account and a specific API key for each AI agent/client (via the web UI under Settings โžœ Users / Keys) instead of reusing your main administrator credentials or a global shared key. Additionally, you can create per-user MCP keys with fine-grained tool permissions under Settings โžœ Keys โžœ MCP Keys. Each MCP key is bound to a specific user and can be restricted to a subset of tools (e.g., read-only access). This ensures clean audit logs and limits the potential impact of any single agent.
โš ๏ธ Troubleshooting: "Decryption failed" for API & MCP Keys:

If you see the message "Decryption failed. The cryptographic system secret differs..." when displaying/decrypting a key, this key was created before a change of the system secret (secret_key in config.json).

Solution:
  1. Go to Settings โžœ API Keys & MCP Keys.
  2. Click the red button "๐Ÿ—‘๏ธ Delete All API Keys" or "๐Ÿ—‘๏ธ Delete All MCP Keys" in the respective section and confirm with your admin password.
  3. Create new keys. These will be encrypted with the current system secret in config.json and remain permanently decryptable.

โšก MCP Prompts & Remote Slash Commands (38 Commands)

Once connected to LLMWikiNG via MCP, typing / in supporting clients (AGY, OpenCode, Cursor, Claude Code) opens the slash command menu:

/update Check for and run system update
/ingest [wiki] Process pending raw sources
/backup Create full server backup
/search <query> [wiki] Search wiki pages
/status Show system status overview
/lint [wiki] Execute wiki health check
/read <slug> [wiki] Read complete wiki page
/sync [wiki] Synchronize Matrix index

The MCP Tool Explorer under Settings โžœ MCP in the WebUI provides a categorized accordion view of all 47 tools with their descriptions, parameters, and ready-to-use prompts. The Interactive Client Configurator in the same panel lets you select a user and their keys to generate a ready-made config snippet for AGY, OpenCode, or Hermes with one click.

๐Ÿ’ฌ Copy-Paste AI Configuration Prompt:

Copy and paste this prompt directly to your AI assistant (e.g., Cursor Chat, Claude Code, OpenCode, or agy) to instruct it to configure itself:

Please configure yourself to connect to the LLMWikiNG MCP server. The server uses SSE (Server-Sent Events) at URL: http://localhost:8080/LLMWikiNG/mcp/sse. You must include the headers 'X-MCP-Key' set to '<YOUR_MCP_SERVER_KEY>' and 'X-API-Key' set to '<YOUR_AGENT_API_KEY>'. In OpenCode, add it under the 'mcp' section in your config file. In Antigravity (agy), add it under the 'mcpServers' object in your ~/.gemini/config/mcp_config.json file.

๐Ÿ”‘ Cryptographic Secret (LLMWIKI_SECRET)

The system uses a central key to sign browser session cookies and encrypt API keys. It is read from the LLMWIKI_SECRET environment variable or dynamically generated and persisted inside config.json (under the key "secret_key") upon the first launch.

โš ๏ธ Warning regarding Secret Rotation:
Rotating the secret key will immediately invalidate all active web sessions (forcing a re-login) and make previously encrypted API keys un-decryptable. After changing the secret, old API keys must be deleted and recreated inside the admin interface.

๐ŸŒ— UI Appearance (Theme)

The appearance theme (Dark/Light) is managed in the settings panel and saved in config.json ("theme": "dark" or "light"). Dark theme is activated by default and loaded server-side. There is no manual theme toggler in the navigation sidebar.

๐Ÿ‹ Docker & UGreen NAS

The Docker configuration is explicitly optimized for UGreen NAS (UGOS) to guarantee out-of-the-box compatibility. The file structure is automatically set up under volume1/docker/llmwiking/.

UGreen NAS (UGOS) Setup:

When importing the image into the UGreen Container Manager, the following volumes are pre-defined:

Local Deployment & Development:

To run the Docker setup locally or on another host without file-over-directory mount conflicts (specifically with config.json), use the DOCKER_VOLUME_BASE environment variable:

  1. Create a local .env file in the project root:
    DOCKER_VOLUME_BASE=.
  2. Start the containers:
    docker compose up --build

๐ŸŽจ Frontend (Tailwind CSS v4)

The styling is built via a CSS-First compiler pipeline (using @theme directives with oklch values, Dark mode media-controls, and responsive parameters):

cd frontend && npm install && npm run build

base.html links to compiled static/css/tailwind-build.css. All active JavaScript logic is written as pure ES modules under static/js/.

โŒจ๏ธ Essential Routes

{% endblock %}