Installation

• Installation
  • Option A: Docker (recommended for a quick try)
  • Option B: Native
    • Prerequisites
    • Clone and Setup
    • Environment Variables
  • Rails Credentials
  • Install MCP Servers
  • Start the Server
  • Seed Data (Development)

Option A: Docker (recommended for a quick try)

git clone git@github.com:pipihosting/themis.git
cd themis
cp .env.example .env   # fill in RAILS_MASTER_KEY and ANTHROPIC_API_KEY
docker compose up

Visit http://localhost:3000 and sign in with the seeded admin: admin@themis.local / password123.

docker compose up runs two services — db (Postgres 16) and app (Rails dev image). The app container bind-mounts the repo, so code changes reload live; gems and Postgres data persist in named volumes across restarts. MCP servers (GitHub, Sentry, Google Workspace) aren’t bundled — the agent works for non-MCP flows, install them separately below if you need them.

Option B: Native

Prerequisites

• Ruby 3.4.11 (use mise or rbenv)
• PostgreSQL 14+
• Node.js 20+ (for MCP servers and asset pipeline)
• libvips (for Active Storage image variants) — brew install vips on macOS, apt-get install libvips42 on Debian/Ubuntu. The ruby-vips gem binds to this native library, so bundle install succeeds without it and the failure only surfaces later, when an image upload is processed.

Clone and Setup

git clone git@github.com:pipihosting/themis.git
cd themis
bin/setup

bin/setup automatically installs gems, creates databases, runs migrations, and starts the dev server.

Environment Variables

Copy .env.example to .env (or .env.local) and fill in:

POSTGRES_HOST=localhost
POSTGRES_USERNAME=postgres
POSTGRES_PASSWORD=your_password

See .env.example for the full list, including optional bot-identity overrides and Anthropic proxy settings.

Rails Credentials

Themis stores API keys in Rails encrypted credentials:

bin/rails credentials:edit

Add your Anthropic API key (required) and optional integrations:

themis:
  anthropic_api_key: sk-ant-xxx

  # Optional — for Google OAuth sign-in
  google_oauth:
    client_id: xxx
    client_secret: xxx

  # Optional — for Tier 1 lightweight agent
  openai_api_key: sk-xxx

Install MCP Servers

Themis uses MCP (Model Context Protocol) servers to connect agents with external services:

# Sentry (optional)
npm install -g @sentry/mcp-server

# Python MCP servers (optional). pipx gives each its own virtualenv: they need
# incompatible `mcp` versions, so a shared `pip install` breaks whichever came first.
pipx install "analytics-mcp==0.7.0"   # Google Analytics
pipx install "flights[mcp]==0.8.4"    # Flights
pipx install "workspace-mcp @ git+https://github.com/pipihosting/google_workspace_mcp.git@main"  # Google Workspace
pipx ensurepath                        # puts ~/.local/bin on PATH

GitHub access uses a dedicated GitHub App instead of an MCP server — see admin/github-app.md for registration and installation.

Linear MCP is hosted by Linear at https://mcp.linear.app/mcp — no local install needed.

Start the Server

bin/dev

This starts:

Process	Port	Description
Rails	3000	Web application
Tailwind	—	CSS watcher
Solid Queue	—	Background jobs
Google Workspace MCP	10299	Drive + Calendar + Gmail. Off unless WORKSPACE_MCP_ENABLED=1
Jekyll docs	4000	Documentation site

Visit http://localhost:3000 to get started.

Seed Data (Development)

Both bin/setup and docker compose up run db:prepare, which seeds a single admin user on first boot:

Email	Password	Role
admin@themis.local	password123	admin, owner of the shared “Default” space

The email/password login form appears on the sign-in page when ALLOW_PASSWORD_LOGIN=true (the default in docker-compose.yml). For native dev, set it in .env if you want to sign in without configuring Google OAuth. See db/seeds/default.rb for the seed source.