Ragtime

UI Walkthrough Video | Contributing Guide

Table of Contents

• Overview
• Quick Start
• Post-Install Setup
• Concepts
• Integrations
• Operations
• Contributing
• License

Overview

What Ragtime provides and how the main pieces fit together.

Features

• Chat UI built in, with tool visualization, interactive charts, DataTables, and sandboxed HTML components: no external client required
• Model providers: hosted APIs, subscription auth (OpenAI Codex, Claude Code), and local runtimes, all configurable in Settings
• 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 (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, 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)
• Tool 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.

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 to .env. The expanded block below is CI-checked against .env.example, so future edits should go there instead of the README snippet:

2. Edit .env with your actual values.

3. Create docker-compose.yml if you want the standalone self-hosted compose setup shown below:

4. Start the application:

   docker compose up -d
   

5. Access the application:

   • Web UI: http://localhost:8000
   • API docs: http://localhost:8000/docs (available when DEBUG_MODE=true)

   Default credentials: admin / (set via LOCAL_ADMIN_PASSWORD in .env)

Post-Install Setup

After the stack is running, configure the capabilities Ragtime will expose.

Tool Configuration

Configure tools in the Ragtime web UI before connecting MCP clients. Enabled tools are available to chat; MCP exposure additionally applies heartbeat health filtering.

1. Open the web UI at http://localhost:8000 and log in with your admin account.
2. Navigate to the Tools tab.
3. Click Add Tool and select the tool type (PostgreSQL, Odoo, SSH, filesystem indexer, etc.).
4. Fill in connection details (hostnames, credentials, database names, paths) for each tool.
5. Use the built-in test button to verify each tool connection.

Once the required tools are healthy, continue with MCP Integration.

Creating Indexes

The Indexer UI (http://localhost:8000, Indexes tab) supports multiple index types (see Vector Store Abstraction for backend details):

Jobs run async with progress streaming to the UI.

Preview DNS Setup (Reverse Proxy Deployments)

This step configures the wildcard DNS and proxy routing required for workspace live previews (see Workspaces for conceptual details).

1. Choose a preview base domain: Ragtime defaults to prepending the workspace name to its public origin (e.g., https://ragtime.example.com -> https://.ragtime.example.com). To use a separate wildcard domain, set USERSPACE_PREVIEW_BASE_DOMAIN=example-userspaces.com.
2. Add a wildcard DNS record for the chosen domain pointing to your Ragtime entrypoint.
3. Configure your reverse proxy to route these wildcard requests to Ragtime and ensure TLS certificates cover them.
4. Update .env (only if needed):

EXTERNAL_BASE_URL=https://ragtime.example.com
USERSPACE_PREVIEW_BASE_DOMAIN=example-userspaces.com

Notes:

• Set EXTERNAL_BASE_URL only if Ragtime sees a different origin than users do (e.g., behind TLS termination), or to pin public URLs to a canonical host.
• Keep SESSION_COOKIE_SECURE=true when traffic is HTTPS at the edge.
• Forward Host and X-Forwarded-Proto headers through the proxy.
• In local development (DEBUG_MODE=true), previews automatically use userspace-preview.lvh.me.

Concepts

Core concepts that affect how Ragtime is deployed and used.

Workspaces

Workspaces combine files, conversations, selected infrastructure tools, and an isolated runtime preview session in one agentic sandbox. They are Replit-like, but wired into Ragtime’s tools and indexed context so agents can work against live systems.

• Public sharing uses direct routes (/{owner}/{slug} and /shared/{token}) which launch shared previews.
• Password-protected shares are handled server-side with a full-page prompt.
• When the runtime lacks CAP_SYS_ADMIN, previews run in a chroot compatibility mode instead of full pivot_root isolation. Transitioning between chroot and pivot_root can cause loss of snapshot history! It is recommended to take a full backup before transitioning.

External Agent Collaboration

Workspace owners and admins can open Share Workspace, enable External Agent Access, and copy the generated instructions into Claude Cowork, Codex, ChatGPT, or another compatible agent to collaborate on the workspace.

Vector Store Abstraction

Ragtime uses two vector backends: FAISS (in-memory, loaded at startup) and pgvector (PostgreSQL, persistent). Upload, Git, and Filesystem indexes can use either backend.

See Creating Indexes for a detailed breakdown of index types and their storage backends.

FAISS indexes are loaded into memory at startup; pgvector indexes stay in PostgreSQL and use cosine similarity search. Embedding provider (OpenAI, Ollama, llama.cpp, or LM Studio) is configured once in Settings and applies to all index types. Swapping embedding model or dimensions after initial indexing requires a full re-index.

Integrations

How to connect external clients and coding assistants to Ragtime.

Model Context Protocol (MCP) Integration

Ragtime exposes its tools via the Model Context Protocol, allowing AI coding assistants to interact with your databases, execute shell commands, and search your indexed codebases.

By default, MCP is disabled until you enable it in Settings. If disabled, /mcp responds with HTTP 503. For security and authentication rules, see Network & Access.

Available MCP Tools

Tools are dynamically exposed based on what you configure in the UI. The schemas below list the primary fields; several tools also accept optional fields such as timeout.

MCP Server Setup

HTTP Transport (Recommended)

Ragtime exposes an MCP endpoint at /mcp that supports the Streamable HTTP transport. Add this to your MCP client configuration:

{
	"servers": {
		"ragtime": {
			"url": "http://localhost:8000/mcp",
			"type": "http",
      // If you've enabled MCP authentication in the Ragtime Settings UI (Settings > MCP Configuration), add headers for your configured auth method.
      // Password mode supports either `MCP-Password` or `Authorization: Bearer `:
			// "headers": {
      //   "MCP-Password": "your-mcp-password-here"
      //   // or: "Authorization": "Bearer your-mcp-password-here"
			// }
		}
	},
	"inputs": []
}

NOTE: For remote access, replace localhost:8000 with your server URL.

Stdio Transport (Alternative)

For local development or environments where HTTP isn’t preferred, use stdio transport via Docker:

{
  "mcpServers": {
    "ragtime": {
      "command": "docker",
      "args": ["exec", "-i", "ragtime", "python", "-m", "ragtime.mcp"]
    }
  }
}

Replace ragtime with your container name if different (find it with docker ps).

Configuration file locations:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
• VS Code / Copilot: User or workspace MCP settings
• Cursor: .cursor/mcp.json
• Windsurf: ~/.codeium/windsurf/mcp_config.json

Connecting to OpenWebUI

1. In OpenWebUI, go to Settings > Connections > OpenAI API
2. Add a new connection:
   • API Base URL: http://ragtime:8000/v1 (or http://localhost:8000/v1 if running locally)
   • API Key: Your configured API_KEY (see Network & Access) (or any value if not set)
3. Select your server’s model name (default: “ragtime”, configurable in Settings > Server Branding)

Operations

Security, maintenance, and troubleshooting guidance for self-hosted deployments.

Security

Ragtime is designed for self-hosted deployment on trusted networks. Review these recommendations before exposing it beyond localhost:

Pushes to the beta and main branches trigger packaging workflows that build, sign, and publish images. The main-branch images are Cosign-signed and ship with an SPDX SBOM artifact (linked from the badges above and workflow runs) so you can verify what you pull from the registry. Pull requests run validation only and do not publish images.

Network & Access

• Run behind a reverse proxy or firewall. Avoid exposing port 8000 directly to the public internet.
• Set API_KEY to protect the /v1/chat/completions endpoint. When unset (the default), anyone with network access can call the chat API and invoke your configured tools.
• Restrict ALLOWED_ORIGINS to trusted domains. The application default is loopback-only when unset; avoid using * in network-accessible deployments because it is permissive with allow_credentials=True.
• Enable MCP route authentication via Settings UI if /mcp is network-accessible. MCP is disabled by default; when MCP is enabled, the default route is open unless you turn on route authentication.
• MCP authentication supports password-based headers (including MCP-Password and bearer form) and OAuth2/client_credentials route modes.
• Protect workspace external-agent URLs. These URLs contain revocable bearer tokens. Use them only in private sessions with trusted agents, keep them out of generated files and public issue trackers, and rotate or disable a URL when access is no longer needed.
• Set a strong LOCAL_ADMIN_PASSWORD when deploying.
• Review trusted external redirects carefully. OAuth callbacks and other external redirect allowlists should only include destinations you control. Redirecting users to third-party domains can expose authorization codes, tokens, or sensitive workflow context if those destinations are compromised or misconfigured.

Authentication Security

• Encryption key is managed automatically on first startup and stored in the data volume as .encryption_key so sessions and encrypted settings survive restarts. Plain backups do not carry that file. If you need a backup that can restore encrypted API keys and connection passwords, create an encrypted backup with --include-secret so the managed key stays inside ciphertext, or otherwise preserve the .encryption_key file separately.
• Rate limiting protects the login endpoint (5 attempts/minute per IP) to prevent brute-force attacks. In DEBUG_MODE=true, rate limiting is disabled for local testing.

Debug Mode Warning

Do not use DEBUG_MODE=true outside local development. When enabled, the /auth/status endpoint exposes your admin username and password in plaintext (including unauthenticated callers). This is intentional for self-hosted debugging but dangerous if the server is accessible to untrusted users.

SSH Connections

The SSH tool uses Paramiko with AutoAddPolicy, which accepts any host key without verification. This makes SSH connections vulnerable to man-in-the-middle attacks on first connect. Only use the SSH tool on trusted networks or with hosts you have verified out-of-band.

Tool Read-Only Mode

Tool read-only mode is a guardrail, not complete isolation. Validators reduce common write paths, but they cannot make broad database, SSH, shell, or Odoo credentials safe against every bypass or misconfiguration. Use least-privileged credentials, read-only database roles and transactions, OS/container sandboxing, restricted SSH users, timeouts, audit logs, and network/firewall boundaries for any tool reachable by agents.

Docker & Mounts

• The default compose files include mounts for docker.sock and optional privileged flags to support advanced tool features (container exec, SSH tunnels, NFS/SMB mounts).
• If you do not need these features, remove or comment out the corresponding lines in your compose file.
• For NFS/SMB filesystem indexing, the container may require elevated privileges. Consider the security implications before enabling privileged: true or SYS_ADMIN capabilities.
• Filesystem sources attached to User Space workspaces only need to be mounted into the runtime container (the ragtime container does not need to see the source). The runtime container also needs mount authority (privileged: true or cap_add: [SYS_ADMIN]) so it can bind-mount the source into the workspace sandbox without copying or changing source permissions. Filesystem sources used purely for indexing only need to be mounted into the ragtime container; mount them in both services if the same source is used for both indexing and User Space workspaces.
• If a Docker bind source is itself a host-mounted SMB/NFS share, use bind propagation such as :rslave (for example /mnt/Accounting:/mnt/Accounting:rw,rslave) and make sure the host mount is active before starting the container. If the host share is mounted after the container starts, recreate the affected container; otherwise Docker can keep exposing the empty local mountpoint directory into User Space.

Third-Party Data Relay

Queries and tool calls may forward your data to external services you configure (OpenAI, Anthropic, Ollama, llama.cpp, LM Studio, PostgreSQL, MSSQL, SSH hosts). Only connect to services you trust with your data.

Updating

To update to the latest version:

docker compose pull
docker compose up -d

Troubleshooting

SSH Tools Fail from Colima on macOS but Hosts Are Reachable

SSH checks run from inside the Colima VM, so macOS-reachable hosts may still fail if Colima’s user-mode networking is stale. To confirm, test TCP connectivity from each layer:

nc -vz -w 3  22                                                                      # macOS
colima ssh -- bash -lc 'timeout 4 bash -lc "/22" && echo open || echo failed'  # Colima VM
docker exec ragtime-dev bash -lc 'timeout 4 bash -lc "/22" && echo open || echo failed'  # container

If only macOS can connect, restart Colima and the stack:

colima stop && colima start
docker compose -f docker/docker-compose.dev.yml up --build

If the problem persists, kill stale Lima usernet helpers: ps ax | grep 'limactl usernet' and keep only the PID in ~/.colima/_lima/_networks/user-v2/usernet_user-v2.pid.

NumPy CPU Compatibility Error

If you see an error like:

RuntimeError: NumPy was built with baseline optimizations (X86_V2) but your machine doesn't support (X86_V2)

Your CPU lacks the X86_V2 instruction set required by modern NumPy binaries. Use the legacy image instead:

image: hub.docker.visnovsky.us/library/ragtime:legacy

This image pins CPU-sensitive native dependencies, including NumPy and FAISS, to versions compatible with older virtual CPU profiles.

Contributing

See CONTRIBUTING.md for development setup, making changes, and CI/CD details.

License

MIT: see LICENSE.