Skip to main content

Configuration Reference

This reference covers all Tevis configuration options, environment variables, and file formats.

Configuration Files​

Global Configuration​

Location: ~/.tevis/config.yaml

Main configuration file for Tevis settings.

# ~/.tevis/config.yaml

# Version (required)
version: "1.0"

# Default account
default_account: personal

# Accounts configuration
accounts:
  personal:
    name: "Personal"
    projects: {}
  work:
    name: "Work"
    projects: {}

# Service ports
ports:
  core: 8081           # Tevis Core API
  local: 8082          # Tevis Local API
  mission_control: 8083 # Mission Control UI
  ground_control: 8084  # Internal admin UI (staff only)
  docs: 8086           # Documentation site

# Local service settings
local:
  host: localhost
  port: 8082
  auth:
    enabled: false
    token: null

# Execution settings
execution:
  max_parallel_tpus: 4        # Max concurrent TPU containers
  timeout_minutes: 30          # Default task timeout
  auto_retry: true            # Retry failed tasks
  retry_count: 2              # Number of retries
  workspace_root: ~/.tevis-runtime

# Docker settings
docker:
  network: tevis-network
  image: tevis/tpu:latest
  pull_policy: if-not-present  # always, never, if-not-present
  resource_limits:
    memory: 4g
    cpus: 2

# LPU (AI) settings
lpu:
  model: claude-sonnet-4-20250514
  context:
    max_tokens: 100000
    include_memory: true
    include_planning: true
    memory_limit: 50
    min_relevance: 0.3
  instructions: |
    # Custom instructions for all LPU calls
    - Prefer TypeScript over JavaScript
    - Use functional patterns where appropriate

# Memory system settings
memory:
  auto_extract: true           # Automatically extract memories
  min_confidence: 0.5          # Minimum confidence to store
  decay_rate: 0.02            # Monthly confidence decay
  max_memories: 1000          # Max memories per project

# Git settings
git:
  default_remote: origin
  auto_push: false             # Auto-push after commit
  commit_format: "[Tevis {nanocycle}] {task}: {message}"

# Logging
logging:
  level: info                  # debug, info, warn, error
  format: text                 # text, json
  file: ~/.tevis/logs/tevis.log

Project Configuration​

Location: ~/.tevis/accounts/{account}/projects/{project}/config.yaml

Project-specific configuration.

# Project configuration
name: My SaaS App
slug: my-saas-app
description: A SaaS application

# Repository
repository:
  url: git@github.com:user/repo.git
  default_branch: main
  protected_branches:
    - main
    - production

# Technology stack (helps LPU)
stack:
  language: typescript
  framework: nextjs
  database: postgresql
  testing: jest

# Code conventions
conventions:
  style_guide: airbnb
  formatter: prettier
  linter: eslint

# Custom LPU instructions for this project
lpu:
  instructions: |
    - This is a Next.js 14 app router project
    - Use server components by default
    - API routes in app/api/

# Project-specific memory settings
memory:
  min_confidence: 0.6         # Higher threshold for this project

Environment Variables​

Tevis Core​

VariableDescriptionDefault
TEVIS_CORE_URLCore API URLhttps://api.tevis.ai
TEVIS_API_KEYAPI authentication key-
TEVIS_JWT_SECRETJWT signing secret-
DATABASE_URLPostgreSQL connection string-
REDIS_URLRedis connection string-

Tevis Local​

VariableDescriptionDefault
TEVIS_LOCAL_PORTLocal API port8082
TEVIS_LOCAL_HOSTLocal API hostlocalhost
TEVIS_RUNTIME_DIRRuntime directory~/.tevis-runtime
TEVIS_CONFIG_PATHConfig file path~/.tevis/config.yaml

TPU Containers​

VariableDescriptionDefault
CLAUDE_CREDENTIALS_JSONClaude OAuth credentials-
WORKSPACE_PATHWorkspace mount path/workspace
TASK_TIMEOUTTask timeout in seconds1800

Mission Control​

VariableDescriptionDefault
VITE_API_URLTevis Core API URLhttp://localhost:8081
VITE_LOCAL_URLTevis Local API URLhttp://localhost:8082

File Formats​

cycle.json​

Machine-readable nanocycle definition.

{
  "nanocycle_id": "NC-007",
  "title": "User Authentication",
  "status": "ready",
  "created_at": "2026-02-06T10:00:00Z",
  "features": [
    {
      "name": "auth-backend",
      "slug": "auth-backend",
      "tasks": [
        {
          "id": "T001",
          "subject": "Create User model",
          "description": "Define User SQLAlchemy model",
          "status": "pending",
          "depends_on": []
        },
        {
          "id": "T002",
          "subject": "Add password hashing",
          "description": "Implement bcrypt password hashing",
          "status": "pending",
          "depends_on": ["T001"]
        }
      ]
    }
  ],
  "constraints": [
    "Use bcrypt for password hashing",
    "JWT tokens with 15-minute expiry"
  ]
}

PLAN.md​

Human-readable nanocycle plan.

# NC-007: User Authentication

## Overview
Add user authentication with email/password login and JWT tokens.

## Features

### Feature 1: auth-backend
Backend authentication logic.

**Tasks:**
- T001: Create User model
- T002: Add password hashing
- T003: Implement login endpoint
- T004: Implement JWT token generation

### Feature 2: auth-frontend
Frontend authentication UI.

**Tasks:**
- T005: Create login page
- T006: Add form validation
- T007: Handle auth state

## Constraints
- Use bcrypt for password hashing
- JWT access tokens: 15 minutes
- JWT refresh tokens: 7 days

## Dependencies
- bcrypt
- pyjwt

progress.txt​

Task execution progress log.

--- Session Start: 2026-02-06 10:00:00 ---

[10:00:15] TASK_STARTED T001
[10:00:18] Creating User model in src/models/user.py
[10:00:25] Adding fields: id, email, password_hash, created_at
[10:00:32] Model created and registered
[10:00:35] TASK_COMPLETE T001 | Duration: 20s

[10:00:40] TASK_STARTED T002
[10:00:45] Implementing bcrypt password hashing
[10:01:02] Added hash_password and verify_password utilities
[10:01:10] TASK_COMPLETE T002 | Duration: 30s

[10:01:15] FEATURE_COMPLETE auth-backend | Total Duration: 1m 15s

memories.json​

Memory storage format.

{
  "memories": [
    {
      "id": "mem_abc123",
      "type": "decision",
      "content": "Use JWT tokens for authentication",
      "context": "Architecture decision during NC-003",
      "rationale": "Stateless, scalable, industry standard",
      "confidence": 0.95,
      "created_at": "2026-01-15T10:00:00Z",
      "last_used": "2026-02-06T10:00:00Z",
      "references": ["NC-003", "NC-007"]
    }
  ]
}

Configuration Precedence​

Configuration is loaded in this order (later overrides earlier):

  1. Built-in defaults — Sensible defaults in code
  2. Global config — ~/.tevis/config.yaml
  3. Project config — ~/.tevis/accounts/{acct}/projects/{proj}/config.yaml
  4. Environment variables — TEVIS_* env vars
  5. Command-line flags — --port, --config, etc.

Example:

# Global config says port 8082
# ENV says TEVIS_LOCAL_PORT=8092
# CLI flag says --port 8099

# Result: port 8099 (CLI wins)
tevis-local serve --port 8099

CLI Configuration​

View Configuration​

# Show all config
tevis config show

# Show specific key
tevis config get execution.max_parallel_tpus

# Show effective config (merged from all sources)
tevis config show --effective

Set Configuration​

# Set global config
tevis config set execution.max_parallel_tpus 6

# Set project config
tevis config set --project my-project lpu.model claude-opus-4-5-20251101

# Unset (use default)
tevis config unset execution.timeout_minutes

Configuration Validation​

# Validate config file
tevis config validate

# Validate specific file
tevis config validate ~/.tevis/config.yaml

Profiles​

Define named configuration profiles for different scenarios.

# ~/.tevis/profiles.yaml
profiles:
  development:
    execution:
      max_parallel_tpus: 2
      timeout_minutes: 15
    lpu:
      model: claude-sonnet-4-20250514

  production:
    execution:
      max_parallel_tpus: 8
      timeout_minutes: 60
    lpu:
      model: claude-opus-4-5-20251101

  minimal:
    execution:
      max_parallel_tpus: 1
    docker:
      resource_limits:
        memory: 2g
        cpus: 1

Use profiles:

# Use specific profile
tevis --profile development nanocycle create ...

# Or set default
tevis config set default_profile development

Troubleshooting Configuration​

Config Not Loading​

# Check config path
echo $TEVIS_CONFIG_PATH

# Validate config syntax
tevis config validate

# Show loaded config sources
tevis config show --sources

Environment Not Applied​

# List environment variables
env | grep TEVIS

# Check if overridden by config file
tevis config show --effective | grep your_setting

Reset to Defaults​

# Backup current config
cp ~/.tevis/config.yaml ~/.tevis/config.yaml.backup

# Reset to defaults
tevis config reset

# Or delete and recreate
rm ~/.tevis/config.yaml
tevis init