Ragtime

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

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 LOCALADMINUSER=admin LOCALADMINPASSWORD=changeme_admin

# Optional comma-separated OAuth callback URLs to trust in addition to built-in # loopback/IDE callback handling. # OAUTHTRUSTEDREDIRECT_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. # EXTERNALBASEURL=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. # USERSPACEPREVIEWBASE_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). # GITHUBCOPILOTCLIENT_ID=Ovxxxxxxxxxxxxxxxxxx

# Optional OAuth apps for SharePoint/OneDrive and Google Drive userspace mounts. # Microsoft client ID/secret: https://portal.azure.com/#view/MicrosoftAADRegisteredApps/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: offlineaccess, 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 # CLOUDMOUNTMICROSOFTCLIENTID= # CLOUDMOUNTMICROSOFTCLIENTSECRET= # CLOUDMOUNTMICROSOFTTENANTID= # CLOUDMOUNTGOOGLECLIENTID= # CLOUDMOUNTGOOGLECLIENT_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 ENABLEHTTPS=true. SESSIONCOOKIE_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. # RUNTIMEMANAGERURL=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 RUNTIMEAUTHTOKEN=

# Maximum concurrent runtime sessions in running/starting state (default: 12) # RUNTIMEMAXSESSIONS=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. # RUNTIMESTARTUPCONCURRENCY=

# Chat web search uses the bundled internal SearXNG service by default. # Set TAVILYAPIKEY to use Tavily instead (get a key at https://app.tavily.com/home). # TAVILYAPIKEY=

############################################################ # 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 ```

1. Edit .env with your actual values.

1. 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 containername: ragtime-db restart: unless-stopped environment: POSTGRESUSER: ragtime POSTGRESPASSWORD: ${POSTGRESPASSWORD} 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 containername: searxng restart: unless-stopped environment: SEARXNGBASEURL: http://searxng:8080/ SEARXNGSECRET: ${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 X86V2 support, use the legacy tag: # image: hub.docker.visnovsky.us/library/ragtime:legacy image: hub.docker.visnovsky.us/library/ragtime:main containername: ragtime restart: unless-stopped ports:

• "${PORT:-8000}:8000"

env_file:

• .env

environment: # Database connection (uses container network) DATABASEURL: postgresql://ragtime:${POSTGRESPASSWORD}@ragtime-db:5432/ragtime # Recommended defaults DEBUGMODE: "false" RUNTIMEMANAGERURL: ${RUNTIMEMANAGERURL:-http://runtime:8090} # Shared Ragtime runtime token. If unset, User Space runtime features # stay disabled and admins see a security warning in the UI. RUNTIMEAUTHTOKEN: ${RUNTIMEAUTH_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 # capadd: # - SYSADMIN networks:

• ragtime-network

dependson: ragtime-db: condition: servicehealthy runtime: condition: servicestarted searxng: condition: servicehealthy healthcheck: test: ["CMD", "sh", "-c", "if [ \"$ENABLEHTTPS\" = \"true\" ]; then curl -fsk https://localhost:8000/health; else curl -fs http://localhost:8000/health; fi"] interval: 30s timeout: 10s retries: 3 startperiod: 15s

runtime: image: hub.docker.visnovsky.us/library/runtime:main containername: runtime restart: unless-stopped environment: PORT: "8090" RUNTIMESERVICEMODE: manager # Shared Ragtime runtime token. If unset, User Space runtime features # stay disabled and admins see a security warning in the UI. RUNTIMEAUTHTOKEN: ${RUNTIMEAUTHTOKEN:-} RUNTIMEWORKERBASEURL: ${RUNTIMEWORKERBASEURL:-http://runtime:8090} RUNTIMEWORKSPACEROOT: ${RUNTIMEWORKSPACEROOT:-/data/userspace} RUNTIMEMAXSESSIONS: ${RUNTIMEMAXSESSIONS:-12} RUNTIMESTARTUPCONCURRENCY: ${RUNTIMESTARTUPCONCURRENCY:-} RUNTIMELEASETTLSECONDS: ${RUNTIMELEASETTLSECONDS:-3600} RUNTIMERECONCILEINTERVALSECONDS: ${RUNTIMERECONCILEINTERVALSECONDS:-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 # capadd: # - SYSADMIN 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: | usedefaultsettings: 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
• Source: mattv8/ragtime
• License: MIT

Install and usage instructions live in the source repository linked above.