Core vs Local Architecture

Tevis uses a distributed architecture with two primary API services: Tevis Core (cloud) and Tevis Local (your machine). Understanding this split is key to using Tevis effectively.

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                         YOUR MACHINE                                 │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌─────────────────┐    ┌──────────────────┐    ┌────────────────┐ │
│  │ Mission Control │────│   Tevis Local    │────│   Workspaces   │ │
│  │    (UI :8083)   │    │   (API :8082)    │    │   (Git Clones) │ │
│  └─────────────────┘    └──────────────────┘    └────────────────┘ │
│           │                      │                      │           │
│           │                      │                      │           │
│           │              ┌───────┴───────┐              │           │
│           │              │ TPU Containers │              │           │
│           │              │   (Docker)     │◄─────────────┘           │
│           │              └───────────────┘                          │
│           │                                                          │
└───────────┼──────────────────────────────────────────────────────────┘
            │
            │ Internet
            │
┌───────────▼──────────────────────────────────────────────────────────┐
│                           TEVIS CLOUD                                │
├──────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌─────────────────┐    ┌──────────────────┐    ┌────────────────┐  │
│  │   Tevis Core    │────│     Tevis AI     │────│    Database    │  │
│  │   (API :8081)   │    │ (Intelligence)   │    │ (Account Data) │  │
│  └─────────────────┘    └──────────────────┘    └────────────────┘  │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

Tevis Core (Cloud)

What It Does

Tevis Core is the brain of the system:

Responsibility	Description
Account management	Users, authentication, billing
Project registry	Cross-device project sync
Intelligence (LPU)	Plan generation, context understanding
Orchestration	Nanocycle coordination
Analytics	Usage tracking, optimization

API Endpoints

https://api.tevis.ai/v1/

Authentication:
  POST   /auth/login
  POST   /auth/signup
  POST   /auth/refresh

Projects:
  GET    /projects
  POST   /projects
  GET    /projects/{id}
  PUT    /projects/{id}

Nanocycles:
  POST   /nanocycles/plan     # Generate plan
  POST   /nanocycles/execute  # Start execution

Intelligence:
  POST   /lpu/generate        # LPU planning
  POST   /lpu/analyze         # Context analysis

Data Stored

• User accounts and credentials
• Project metadata (not code)
• Nanocycle plans and status
• Aggregated analytics
• Memory summaries (not raw data)

When Core is Used

• Login/authentication
• Plan generation (LPU calls)
• Nanocycle status sync
• Cross-device coordination
• Billing and limits

Tevis Local (Your Machine)

What It Does

Tevis Local is the hands of the system:

Responsibility	Description
Code execution	TPU containers
File access	Read/write repository files
Knowledge base	Local project context
Git operations	Clone, branch, commit, push
Secrets	Credentials never leave machine

API Endpoints

http://localhost:8082/

Health:
  GET    /health

Sessions:
  GET    /sessions
  POST   /sessions
  GET    /sessions/{id}

Execution:
  POST   /execute/nanocycle
  GET    /execute/status/{id}
  POST   /execute/hold-point/{id}/respond

Knowledge Base:
  GET    /kb/context
  GET    /kb/memory
  POST   /kb/memory

Workspaces:
  GET    /workspaces
  POST   /workspaces
  DELETE /workspaces/{id}

Data Stored

• Repository clones (workspaces)
• Knowledge base files
• Planning context documents
• Execution logs
• Claude OAuth credentials

When Local is Used

• File operations
• Code execution
• Git operations
• Context building
• Credential access

Why This Split?

Privacy

Your code never leaves your machine:

✅ Code stays local
✅ Secrets stay local
✅ Git credentials stay local
✅ Full repository only on your machine

☁️  Only metadata synced to cloud
☁️  Plans (requirements, not code)
☁️  Status updates
☁️  Memory summaries

Performance

Local execution is faster:

File read:
  Local:  ~1ms (disk)
  Cloud:  ~100ms (network round trip)

Git clone:
  Local:  ~2s (direct to GitHub)
  Cloud:  ~5s (proxy through servers)

Execution:
  Local:  Immediate container start
  Cloud:  Network latency on every operation

Reliability

Works offline (partially):

Online:  Full functionality
Offline: Plan approval paused, but:
         - View local knowledge base
         - Browse existing workspaces
         - Review past nanocycles
         - Run local tests

Cost

Execution happens on your hardware:

You provide:        Tevis provides:
- CPU              - Intelligence (LPU)
- RAM              - Orchestration
- Storage          - Coordination
- Docker           - Analytics

Communication Flow

Nanocycle Execution

1. Mission Control → Core: "Create nanocycle with this description"
2. Core → LPU: "Generate plan for this description"
3. LPU → Core: Returns structured plan
4. Core → Mission Control: Shows plan for approval
5. Mission Control → Core: "Plan approved, execute"
6. Core → Local: "Execute this plan"
7. Local → TPUs: Spawns containers with tasks
8. TPUs → Local: Report progress, request files
9. Local → Core: Sync status updates
10. Core → Mission Control: Stream updates
11. TPUs → Local: Task complete
12. Local → Core: Execution complete
13. Core → Mission Control: Show results

Key Points

• Code never goes to Core — Only descriptions and plans
• Intelligence comes from Core — LPU generates plans
• Execution happens locally — TPUs run on your machine
• Status syncs both ways — Real-time updates

Service Configuration

Tevis Core

Configured via environment or Tevis account:

# Environment (for self-hosted)
TEVIS_CORE_URL=https://api.tevis.ai
TEVIS_API_KEY=your_api_key

# Or via config
tevis config set core.url https://api.tevis.ai

Tevis Local

Configured via ~/.tevis/config.yaml:

local:
  port: 8082
  host: localhost

execution:
  max_parallel_tpus: 4
  workspace_root: ~/.tevis-runtime

docker:
  network: tevis-network
  image: tevis/tpu:latest

Deployment Options

Standard (Recommended)

• Core: Tevis cloud (api.tevis.ai)
• Local: Your machine

# Default setup
tevis-local serve
mc start

Self-Hosted Core

Run everything on your infrastructure:

# Deploy Core
docker-compose -f tevis-core.yml up -d

# Configure Local to use self-hosted
tevis config set core.url http://your-server:8081

Air-Gapped

Fully offline (limited functionality):

# Local-only mode
tevis-local serve --offline

# No LPU planning, but:
# - Manual plan creation
# - Execution works
# - Knowledge base works

Troubleshooting

Core Not Reachable

# Check connectivity
curl https://api.tevis.ai/health

# Check authentication
tevis auth status

# Re-authenticate if needed
tevis auth login

Local Not Running

# Check status
tevis-local status

# Start service
tevis-local serve

# Check logs
tevis-local logs

Sync Issues

# Force sync
tevis sync --force

# Check pending changes
tevis sync status

Summary

Aspect	Tevis Core	Tevis Local
Location	Cloud	Your machine
Role	Brain	Hands
Data	Metadata	Code + secrets
Internet	Required	For sync only
Port	8081	8082
Scaling	Managed	Your resources