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.7 (use mise or rbenv)
• PostgreSQL 14+
• Node.js 20+ (for MCP servers and asset pipeline)
• Go (for GitHub MCP server)

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

# Google Workspace (optional)
pip install workspace-mcp

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 integration (if installed)
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.