# Ragtime > Self-hosted, OpenAI-compatible RAG API + MCP server that plugs local knowledge into existing LLM clients. - **Type:** MCP server - **Install:** `agentstack add mcp-mattv8-ragtime` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [mattv8](https://agentstack.voostack.com/s/mattv8) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [mattv8](https://github.com/mattv8) - **Source:** https://github.com/mattv8/ragtime ## Install ```sh agentstack add mcp-mattv8-ragtime ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Ragtime All your tools. All your context. In one place. Self-hosted, OpenAI-compatible RAG API + MCP server that plugs local knowledge into existing LLM clients. UI Walkthrough Video | Contributing Guide ## Table of Contents - [Overview](#overview) - [Quick Start](#quick-start) - [Post-Install Setup](#post-install-setup) - [Concepts](#concepts) - [Integrations](#integrations) - [Operations](#operations) - [Contributing](#contributing) - [License](#license) ## Overview What Ragtime provides and how the main pieces fit together. ### Features - **Chat UI** built in, with tool visualization, interactive charts, and DataTables: no external client required - **[Model providers](#model-providers)**: hosted APIs, subscription auth (OpenAI Codex, Claude Code), and local runtimes, all configurable in Settings - **[Workspaces](#workspaces)** with live previews run in isolated runtime sessions; shared links use clean public URLs (`/{owner}/{slug}`), with optional password-protected full-page access - **[MCP server](#model-context-protocol-mcp-integration)** (HTTP Streamable + stdio transports) exposing tools to Claude Desktop, VS Code Copilot, Cursor, and JetBrains IDEs with auth - **OpenAI-compatible API** `/v1/chat/completions` endpoint with streaming: works with [OpenWebUI](#connecting-to-openwebui), Continue, and any OpenAI client - **Dual vector store**: Choose FAISS or pgvector for Upload/Git indexes; pgvector for schema/PDM and optional filesystem indexing ([details](#vector-store-abstraction)) - **[Tool security](#security)**: SQL injection prevention via allowlist patterns, LIMIT enforcement, Odoo code validation, optional write-ops flag ### Model Providers Configure LLM and embedding providers in the Settings UI. Chat (LLM) and embedding models can use different providers. Models are discovered live from each provider, and overlapping families (for example Anthropic API key vs Claude Code subscription) stay labeled by the provider serving them so token spend is clear. | Provider | Auth | Chat (LLM) | Embeddings | |----------|------|:----------:|:----------:| | **OpenAI** | API key | Yes | Yes | | **OpenAI Codex** | ChatGPT subscription (OAuth device flow) | Yes | Yes | | **Anthropic** | API key | Yes | - | | **Claude Code** | Claude Pro/Max subscription (CLI/OAuth) | Yes | - | | **OpenRouter** | API key | Yes | Yes | | **GitHub Copilot** | OAuth device flow or PAT | Yes | - | | **Ollama** | Local (self-hosted) | Yes | Yes | | **llama.cpp** | Local (self-hosted) | Yes | Yes | | **LM Studio** | Local (self-hosted) | Yes | Yes | | **oMLX** | Local (self-hosted) | Yes | Yes | Subscription-backed providers (OpenAI Codex, Claude Code) authenticate from the Settings UI without an API key. Claude Code uses the Claude Code CLI subscription and discovers the full Claude model family your plan serves. ### Architecture ```mermaid flowchart LR Tools["Tools(SQL, SSH, Odoo)"] -->|tool runs + results| Ragtime Context["Knowledge Sources(FAISS, pgvector)"] -->|retrieved context| Ragtime LLM["LLM Provider(OpenAI, Anthropic, Ollama, llama.cpp, LM Studio)"] -->|LLM API| Ragtime subgraph Ragtime["Ragtime"] direction TB API["/v1/chat/completions"] MCP["/mcp"] UI["Web UI"] end Ragtime -->|chat responses| Clients["Clients(OpenWebUI, Claude, VS Code)"] Clients -->|chat queries| Ragtime style Ragtime fill:#1a365d,stroke:#3182ce,stroke-width:3px,color:#fff ``` ## Quick Start ### Prerequisites - Docker and Docker Compose - A `.env` file with your configuration ### Setup 1. **Create `.env`:** Copy [.env.example](.env.example) to [.env](.env). The expanded block below is CI-checked against [.env.example](.env.example), so future edits should go there instead of the README snippet: Click to expand .env template ```bash # ============================================================================= # Ragtime RAG API - Environment Configuration # ============================================================================= # Copy this file to .env and fill in your values # ----------------------------------------------------------------------------- # Database Configuration # ----------------------------------------------------------------------------- # PostgreSQL password (used by both database container and ragtime) POSTGRES_PASSWORD=changeme # ----------------------------------------------------------------------------- # Authentication Configuration # ----------------------------------------------------------------------------- # Local admin account credentials LOCAL_ADMIN_USER=admin LOCAL_ADMIN_PASSWORD=changeme_admin # Optional comma-separated OAuth callback URLs to trust in addition to built-in # loopback/IDE callback handling. # OAUTH_TRUSTED_REDIRECT_URIS=https://example-1/oauth/callback,https://example-2/oauth/callback # ----------------------------------------------------------------------------- # Server Configuration # ----------------------------------------------------------------------------- # API port (default: 8000) PORT=8000 # CORS allowed origins (comma-separated) # Leave empty to allow loopback-only origins. # Example: https://ragtime.example.com,https://chat.example.com ALLOWED_ORIGINS= # Canonical public Ragtime origin (scheme + host, no trailing slash), for example: # https://ragtime.example.com # Set it only when Ragtime sees a different origin than users do # (for example behind TLS termination) or public URLs must stay fixed. # EXTERNAL_BASE_URL=https://ragtime.example.com # Optional preview base-domain override for userspace subdomain previews. # Leave unset to derive preview hosts from the current Ragtime origin # (for example https://ragtime.example.com -> https://.ragtime.example.com). # Set this when previews should use a separate wildcard host family such as # example-userspaces.com. Wildcard DNS/TLS must route *.example-userspaces.com # back to Ragtime. # USERSPACE_PREVIEW_BASE_DOMAIN=example-userspaces.com # ----------------------------------------------------------------------------- # Security Configuration # ----------------------------------------------------------------------------- # API Key for OpenAI-compatible endpoint authentication (strongly recommended # for non-local deployments) # Generate with: openssl rand -base64 32 API_KEY= # Ragtime manages its own encryption key at /data/.encryption_key. # Keep that managed file recoverable through your data backups if you need to # restore encrypted API keys and connection passwords later. # Optional GitHub OAuth App client ID for GitHub Copilot device auth flow. # If not set, Ragtime falls back to the built-in default client id. # Create your own OAuth app to control consent screen branding (e.g., app name "Ragtime"). # Note: this is the Client ID only (not the Client Secret). # GITHUB_COPILOT_CLIENT_ID=Ovxxxxxxxxxxxxxxxxxx # Optional OAuth apps for SharePoint/OneDrive and Google Drive userspace mounts. # Microsoft client ID/secret: https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade # Microsoft tenant ID: use the Azure Directory (tenant) ID or primary tenant domain for single-tenant app registrations. # Microsoft Graph delegated permissions for read/write mounts: offline_access, User.Read, Files.ReadWrite.All, Sites.ReadWrite.All. Admin consent may be required. # Google client ID/secret: https://console.cloud.google.com/apis/credentials # Google API library: enable Google Drive API (drive.googleapis.com) for the same project as the OAuth client. # Google OAuth consent screen scopes for read/write mounts: https://www.googleapis.com/auth/drive and https://www.googleapis.com/auth/userinfo.email # CLOUD_MOUNT_MICROSOFT_CLIENT_ID= # CLOUD_MOUNT_MICROSOFT_CLIENT_SECRET= # CLOUD_MOUNT_MICROSOFT_TENANT_ID= # CLOUD_MOUNT_GOOGLE_CLIENT_ID= # CLOUD_MOUNT_GOOGLE_CLIENT_SECRET= # HTTPS: Enable built-in TLS with self-signed certificate (auto-generated on first run) # To use your own certs, place them at ./data/ssl/server.crt and ./data/ssl/server.key # ENABLE_HTTPS=true # Set to true if behind an HTTPS reverse proxy (nginx, Caddy, Traefik) # This marks cookies as Secure. Auto-enabled when ENABLE_HTTPS=true. SESSION_COOKIE_SECURE=false # ----------------------------------------------------------------------------- # Runtime Configuration # ----------------------------------------------------------------------------- # Base URL Ragtime uses for outbound calls to the runtime-manager API that # creates and controls userspace runtime sessions. In the default Docker setup, # this should stay pointed at the internal runtime service. # Set to blank/non-http to force local placeholder runtime mode. # RUNTIME_MANAGER_URL=http://runtime:8090 # Shared bearer token for Ragtime runtime service calls. If unset, User # Space runtime features stay disabled and admins see a security warning in # the UI. Generate with: openssl rand -base64 32 RUNTIME_AUTH_TOKEN= # Maximum concurrent runtime sessions in running/starting state (default: 12) # RUNTIME_MAX_SESSIONS=12 # Optional override for concurrent workspace startup/bootstrap operations per # runtime worker. By default, the worker sizes this automatically from runtime # namespace isolation, CPU, memory, and session capacity. # RUNTIME_STARTUP_CONCURRENCY= # Chat web search uses the bundled internal SearXNG service by default. # Set TAVILY_API_KEY to use Tavily instead (get a key at https://app.tavily.com/home). # TAVILY_API_KEY= ############################################################ # Developer Only - Typically do not modify below this line # ############################################################ # Debug mode (enables verbose logging and hot-reload) DEBUG_MODE=false # Database URL (auto-configured by docker-compose, override for external DB) # DATABASE_URL=postgresql://ragtime:password@hostname:5432/ragtime ``` 2. **Edit `.env`** with your actual values. 3. **Create `docker-compose.yml`** if you want the standalone self-hosted compose setup shown below: Click to expand docker-compose.yml ```yaml # ============================================================================= # Ragtime - Self-Hosted Docker Compose # ============================================================================= # For self-hosted deployment. See README.md for setup instructions. # # Usage: # 1. Create .env file with your configuration # 2. docker compose up -d # 3. Access at http://localhost:${PORT:-8000} services: # PostgreSQL database for Prisma persistence ragtime-db: image: pgvector/pgvector:pg18 container_name: ragtime-db restart: unless-stopped environment: POSTGRES_USER: ragtime POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} POSTGRES_DB: ragtime volumes: - ragtime-db-data:/var/lib/postgresql networks: - ragtime-network healthcheck: test: ["CMD-SHELL", "pg_isready -U ragtime -d ragtime"] interval: 10s timeout: 5s retries: 5 searxng: image: ghcr.io/searxng/searxng:latest container_name: searxng restart: unless-stopped environment: SEARXNG_BASE_URL: http://searxng:8080/ SEARXNG_SECRET: ${SEARXNG_SECRET:-ragtime-internal-searxng} configs: - source: searxng-settings target: /etc/searxng/settings.yml volumes: - searxng-cache:/var/cache/searxng networks: - ragtime-network healthcheck: test: [ "CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8080/healthz', timeout=5).read()", ] interval: 30s timeout: 10s retries: 5 start_period: 10s # Ragtime RAG API ragtime: # For older CPUs without X86_V2 support, use the legacy tag: # image: hub.docker.visnovsky.us/library/ragtime:legacy image: hub.docker.visnovsky.us/library/ragtime:main container_name: ragtime restart: unless-stopped ports: - "${PORT:-8000}:8000" env_file: - .env environment: # Database connection (uses container network) DATABASE_URL: postgresql://ragtime:${POSTGRES_PASSWORD}@ragtime-db:5432/ragtime # Recommended defaults DEBUG_MODE: "false" RUNTIME_MANAGER_URL: ${RUNTIME_MANAGER_URL:-http://runtime:8090} # Shared Ragtime runtime token. If unset, User Space runtime features # stay disabled and admins see a security warning in the UI. RUNTIME_AUTH_TOKEN: ${RUNTIME_AUTH_TOKEN:-} volumes: # Data persistence (indexes, SSL certs, etc.) - ./data:/data # Optional: mount docker.sock only if you need Docker tool execution. # The Docker API can control the host even when the socket is mounted read-only. # - /var/run/docker.sock:/var/run/docker.sock:ro security_opt: - no-new-privileges:true # Uncomment below if using SMB/NFS mounting inside container (consider mounting via docker volume instead) # privileged: true # cap_add: # - SYS_ADMIN networks: - ragtime-network depends_on: ragtime-db: condition: service_healthy runtime: condition: service_started searxng: condition: service_healthy healthcheck: test: ["CMD", "sh", "-c", "if [ \"$ENABLE_HTTPS\" = \"true\" ]; then curl -fsk https://localhost:8000/health; else curl -fs http://localhost:8000/health; fi"] interval: 30s timeout: 10s retries: 3 start_period: 15s runtime: image: hub.docker.visnovsky.us/library/runtime:main container_name: runtime restart: unless-stopped environment: PORT: "8090" RUNTIME_SERVICE_MODE: manager # Shared Ragtime runtime token. If unset, User Space runtime features # stay disabled and admins see a security warning in the UI. RUNTIME_AUTH_TOKEN: ${RUNTIME_AUTH_TOKEN:-} RUNTIME_WORKER_BASE_URL: ${RUNTIME_WORKER_BASE_URL:-http://runtime:8090} RUNTIME_WORKSPACE_ROOT: ${RUNTIME_WORKSPACE_ROOT:-/data/_userspace} RUNTIME_MAX_SESSIONS: ${RUNTIME_MAX_SESSIONS:-12} RUNTIME_STARTUP_CONCURRENCY: ${RUNTIME_STARTUP_CONCURRENCY:-} RUNTIME_LEASE_TTL_SECONDS: ${RUNTIME_LEASE_TTL_SECONDS:-3600} RUNTIME_RECONCILE_INTERVAL_SECONDS: ${RUNTIME_RECONCILE_INTERVAL_SECONDS:-15} volumes: - ./data:/data security_opt: - no-new-privileges:true # Uncomment below to enable full runtime sandbox isolation when the host # permits mount and PID namespaces (otherwise runtime falls back to chroot). # privileged: true # cap_add: # - SYS_ADMIN networks: - ragtime-network healthcheck: test: ["CMD", "curl", "-fs", "http://localhost:8090/health"] interval: 30s timeout: 10s retries: 3 start_period: 5s networks: ragtime-network: driver: bridge configs: searxng-settings: content: | use_default_settings: true search: formats: - html - json volumes: ragtime-db-data: searxng-cache: ``` > **Note:** Ragtime configuration variables are loaded from the … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [mattv8](https://github.com/mattv8) - **Source:** [mattv8/ragtime](https://github.com/mattv8/ragtime) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-mattv8-ragtime - Seller: https://agentstack.voostack.com/s/mattv8 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.