Skip to main content

Installation

This guide covers the complete installation and configuration of Tevis for your development environment.

System Requirements​

Hardware​

ComponentMinimumRecommended
CPU4 cores8+ cores
RAM8 GB16+ GB
Storage20 GB free50+ GB SSD
NetworkBroadbandLow latency

Software Prerequisites​

DependencyVersionPurpose
Python3.11+Tevis Local runtime
Docker20.10+TPU container execution
Node.js18+Mission Control UI
pnpm8+Package management
Git2.30+Version control
Claude CLILatestAI agent execution

Installation Steps​

Step 1: Install Python Dependencies​

# Create a virtual environment (recommended)
python3 -m venv ~/.tevis-env
source ~/.tevis-env/bin/activate

# Install Tevis Local
pip install tevis-local

# Verify installation
tevis-local --version

Step 2: Install Docker​

macOS​

# Using Homebrew
brew install --cask docker

# Start Docker Desktop
open -a Docker

Linux (Ubuntu/Debian)​

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Start Docker
sudo systemctl start docker
sudo systemctl enable docker

Verify Docker​

docker --version
docker info
docker run hello-world

Step 3: Install Claude CLI​

# Install Claude CLI
npm install -g @anthropic-ai/claude-cli

# Authenticate
claude login

# Verify
claude --version

Step 4: Clone the Repository​

# Clone Tevis
git clone https://github.com/teaboratory/tevis.git
cd tevis

# Install dependencies (use pnpm, not npm)
npx pnpm install
Package Manager

Tevis uses pnpm for package management. Running npm install will fail due to workspace protocol dependencies.

Step 5: Configure Tevis​

Create Config Directory​

mkdir -p ~/.tevis

Set Up Claude Credentials​

# Copy Claude credentials for TPU execution
cp ~/.claude/.credentials.json ~/.tevis/claude_oauth_credentials.json

Configure Environment​

Create ~/.tevis/config.yaml:

# Tevis Configuration
version: "1.0"

# Default account settings
default_account: personal

# Accounts
accounts:
  personal:
    name: "Personal"
    projects: {}

# Service ports (optional overrides)
ports:
  core: 8081
  local: 8082
  mission_control: 8083
  ground_control: 8084
  docs: 8086

# LLM settings
llm:
  provider: anthropic
  model: claude-sonnet-4-20250514

# Execution settings
execution:
  max_parallel_tpus: 4
  timeout_minutes: 30
  auto_retry: true

Starting Services​

Option 1: Development Mode (All Services)​

# From the tevis directory
./scripts/start.sh

# This starts:
# - Tevis Core API (8081)
# - Tevis Local API (8082)
# - Mission Control (8083)
# - Internal admin UI (8084)

Option 2: Individual Services​

# Terminal 1: Tevis Core API
./scripts/services/tevis-core-api start

# Terminal 2: Tevis Local API
./scripts/services/tevis-local-api start

# Terminal 3: Mission Control
./scripts/services/mission-control start

Option 3: Using the Service Manager​

# Start all services
./scripts/tevis start

# Check status
./scripts/tevis status

# Stop all services
./scripts/tevis stop

Verify Installation​

Check Service Health​

# Tevis Local health
curl http://localhost:8082/health

# Mission Control
curl http://localhost:8083

# Check all services
tevis-local status

Run Diagnostics​

# Full system check
tevis diagnostics

# Expected output:
# ✓ Python 3.11.4
# ✓ Docker 24.0.6
# ✓ Claude CLI 1.2.0
# ✓ Tevis Local 2.1.3
# ✓ Services healthy

Project Configuration​

Initialize a Project​

# Create a new Tevis project
tevis init my-project

# Or link an existing repository
tevis init my-project --repo git@github.com:user/repo.git

This creates:

~/.tevis/accounts/personal/projects/my-project/
├── kb/                    # Knowledge base
│   ├── MACROCYCLE.md     # Strategic planning
│   ├── MESOCYCLE.md      # Feature themes
│   └── MICROCYCLE.md     # Tactical focus
├── nanocycles/           # Nanocycle artifacts
└── config.yaml           # Project config

Knowledge Base Setup​

Create your planning context files:

# MACROCYCLE.md - Strategic vision (months)
cat > ~/.tevis/accounts/personal/projects/my-project/kb/MACROCYCLE.md << 'EOF'
# Macrocycle: Q1 2026

## Vision
Build a world-class developer experience.

## Milestones
- [ ] Core platform MVP
- [ ] Public beta launch
- [ ] 1000 active users
EOF

# MESOCYCLE.md - Feature themes (weeks)
cat > ~/.tevis/accounts/personal/projects/my-project/kb/MESOCYCLE.md << 'EOF'
# Mesocycle: January 2026

## Theme: Foundation

### Objectives
- Authentication system
- Project management
- Real-time updates
EOF

# MICROCYCLE.md - Tactical focus (days)
cat > ~/.tevis/accounts/personal/projects/my-project/kb/MICROCYCLE.md << 'EOF'
# Microcycle: Week 1

## Focus
- User signup flow
- Dashboard polish
- API documentation
EOF

Updating Tevis​

Update Tevis Local​

pip install --upgrade tevis-local

Update UI Components​

cd tevis
git pull
npx pnpm install

Refresh Claude Credentials​

OAuth tokens expire periodically. Refresh them:

# Re-authenticate
claude login

# Update Tevis credentials
cp ~/.claude/.credentials.json ~/.tevis/claude_oauth_credentials.json

Uninstallation​

Remove Tevis Local​

pip uninstall tevis-local

Remove Configuration​

# Backup first if needed
cp -r ~/.tevis ~/.tevis-backup

# Remove config
rm -rf ~/.tevis

Remove Docker Images​

# List Tevis images
docker images | grep tevis

# Remove images
docker rmi tevis/tpu:latest

Next Steps​

Troubleshooting​

If you encounter issues during installation, check the error messages carefully and ensure all prerequisites are met. For additional help, open an issue on GitHub.