Terraphim AI Release System Map

Overview

This document provides a comprehensive mapping of the Terraphim AI release system, including all components, platforms, package formats, and distribution channels.

Release Components Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Terraphim AI Release System                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐   │
│  │   Server    │  │     TUI     │  │      Desktop App        │   │
│  │ Component   │  │ Component   │  │    (Tauri-based)       │   │
│  │             │  │             │  │                         │   │
│  │ • Core API   │  │ • CLI       │  │ • GUI Interface        │   │
│  │ • Indexing   │  │ • Terminal  │  │ • Auto-updater         │   │
│  │ • Search     │  │ • Sessions  │  │ • System Integration   │   │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘   │
│         │                │                      │              │
│         └────────────────┼──────────────────────┘              │
│                          │                                     │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              Docker Container Images                    │   │
│  │                                                         │   │
│  │ • Multi-architecture (amd64, arm64, arm/v7)            │   │
│  │ • Ubuntu base variants (20.04, 22.04)                  │   │
│  │ • Registry: GHCR, Docker Hub                           │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Platform Distribution Matrix

Linux Platform Support

Linux
├── x86_64 (Intel/AMD)
│   ├── Server Binary
│   ├── TUI Binary
│   ├── Desktop App (AppImage)
│   ├── Debian Package (.deb)
│   ├── RPM Package (.rpm)
│   └── Docker Image (amd64)
├── aarch64 (ARM64)
│   ├── Server Binary
│   ├── TUI Binary
│   ├── Debian Package (.deb)
│   ├── Arch Package (.tar.zst)
│   └── Docker Image (arm64)
└── armv7 (ARM32)
    ├── Server Binary
    ├── TUI Binary
    ├── Debian Package (.deb)
    └── Docker Image (arm/v7)

macOS Platform Support

macOS
├── x86_64 (Intel)
│   ├── Server Binary
│   ├── TUI Binary
│   ├── Desktop App (.dmg)
│   ├── Archive Package (.tar.gz)
│   └── Docker Image (amd64)
└── aarch64 (Apple Silicon)
    ├── Server Binary
    ├── TUI Binary
    ├── Desktop App (.dmg)
    ├── Archive Package (.tar.gz)
    └── Docker Image (arm64)

Windows Platform Support

Windows x86_64
├── Server Binary (.exe)
├── TUI Binary (.exe)
├── Desktop App (.msi/.exe)
└── Installer (.exe)

Package Format Mapping

Binary Distributions

System Package Distributions

| Component | Format | Linux x86_64 | Linux aarch64 | Linux armv7 | macOS x86_64 | macOS aarch64 | Windows | |-----------|--------|--------------|---------------|-------------|--------------|---------------|----------| | Server | .deb | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | Server | .rpm | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | Server | .tar.zst| ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | | Server | .tar.gz| ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | | TUI | .deb | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | TUI | .rpm | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | TUI | .tar.zst| ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | | TUI | .tar.gz| ❌ | ❌ | ❌ | ✅ | ✅ | ❌ |

Desktop Application Distributions

| Platform | Format | Status | Notes | |----------|--------|--------|-------| | Linux x86_64 | AppImage | ✅ | Portable, no installation required | | Linux x86_64 | .deb | ✅ | Integration with package managers | | macOS x86_64 | .dmg | ✅ | Standard macOS installer | | macOS aarch64 | .dmg | ✅ | Universal binary support | | Windows x86_64 | .msi | ✅ | Windows Installer | | Windows x86_64 | .exe | ✅ | NSIS installer |

Distribution Channels

Primary Distribution

GitHub Releases (https://github.com/terraphim/terraphim-ai/releases)
├── Versioned Releases
│   ├── Source Code (tarball)
│   ├── Server Binaries (all platforms)
│   ├── TUI Binaries (all platforms)
│   ├── Desktop Applications (all platforms)
│   ├── System Packages (.deb, .rpm, .tar.zst)
│   ├── Docker Images (multi-arch)
│   ├── Installation Scripts
│   ├── Checksums (SHA256)
│   └── Release Notes
└── Latest Release
    └── Same structure as versioned releases

Package Manager Distribution

Homebrew (macOS/Linux)
├── terraphim/terraphim-ai/terraphim-ai tap
├── Automatic formula updates
└── Dependency management

APT Repositories (Debian/Ubuntu)
├── Server package
├── TUI package
└── Desktop package (future)

YUM Repositories (RHEL/CentOS/Fedora)
├── Server package
├── TUI package
└── Desktop package (future)

AUR (Arch Linux)
├── terraphim-server package
├── terraphim-agent package
└── terraphim-desktop package (future)

Container Registry Distribution

GitHub Container Registry (ghcr.io/terraphim)
├── terraphim-server:latest
├── terraphim-server:v{version}
├── terraphim-server:ubuntu-20.04
├── terraphim-server:ubuntu-22.04
└── Multi-architecture manifests
    ├── amd64
    ├── arm64
    └── arm/v7

Docker Hub (docker.io/terraphim)
├── terraphim-server:latest
├── terraphim-server:v{version}
└── Same multi-architecture support

Build and Release Flow

GitHub Actions Workflow

Tag Push (v*, component-v*)
├── Build Binaries (Matrix)
│   ├── Linux (x86_64, aarch64, armv7)
│   ├── macOS (x86_64, aarch64)
│   └── Windows (x86_64)
├── Build System Packages
│   ├── Debian (.deb)
│   ├── RPM (.rpm)
│   └── Arch (.tar.zst)
├── Build Desktop Applications
│   ├── Linux (AppImage, .deb)
│   ├── macOS (.dmg)
│   └── Windows (.msi, .exe)
├── Build Docker Images
│   ├── Multi-architecture builds
│   └── Push to registries
├── Create GitHub Release
│   ├── Upload all artifacts
│   ├── Generate checksums
│   └── Publish release notes
└── Update Package Managers
    ├── Homebrew formula
    ├── AUR packages
    └── Repository metadata

Installation Methods

Quick Installation

# One-line installation (curl | bash)
curl -fsSL https://github.com/terraphim/terraphim-ai/releases/latest/download/install.sh | sh

# Docker run
docker run -d --name terraphim ghcr.io/terraphim/terraphim-server:latest

# Homebrew
brew install terraphim/terraphim-ai/terraphim-ai

Platform-Specific Installation

Ubuntu/Debian
├── sudo dpkg -i terraphim-server_*.deb
├── sudo apt-get install -f  # Fix dependencies
└── sudo systemctl enable terraphim-server

RHEL/CentOS/Fedora
├── sudo rpm -i terraphim-server-*.rpm
└── sudo systemctl enable terraphim-server

Arch Linux
├── yay -S terraphim-server
├── pacman -U terraphim-server-*.pkg.tar.zst
└── sudo systemctl enable terraphim-server

macOS
├── brew install terraphim/terraphim-ai/terraphim-ai
├── Download and open .dmg file
└── Drag to Applications folder

Windows
├── Download and run .msi installer
├── Follow installation wizard
└── Auto-start option available

File Structure and Naming Conventions

Binary Naming

terraphim_server-{target}
├── terraphim_server-x86_64-unknown-linux-gnu
├── terraphim_server-x86_64-unknown-linux-musl
├── terraphim_server-aarch64-unknown-linux-musl
├── terraphim_server-armv7-unknown-linux-musleabihf
├── terraphim_server-x86_64-apple-darwin
├── terraphim_server-aarch64-apple-darwin
└── terraphim_server-x86_64-pc-windows-msvc.exe

terraphim-agent-{target}
├── Same target variants as server
└── Binary name includes .exe on Windows

Package Naming

Debian Packages (.deb)
├── terraphim-server_{version}-1_amd64.deb
├── terraphim-server_{version}-1_arm64.deb
├── terraphim-agent_{version}-1_amd64.deb
├── terraphim-agent_{version}-1_arm64.deb
├── terraphim-ai-desktop_{version}-1_amd64.deb
└── terraphim-ai-desktop_{version}-1_arm64.deb

RPM Packages (.rpm)
├── terraphim-server-{version}-1.x86_64.rpm
├── terraphim-agent-{version}-1.x86_64.rpm
└── terraphim-ai-desktop-{version}-1.x86_64.rpm

Arch Packages (.tar.zst)
├── terraphim-server-{version}-1-x86_64.pkg.tar.zst
├── terraphim-server-{version}-1-aarch64.pkg.tar.zst
├── terraphim-agent-{version}-1-x86_64.pkg.tar.zst
└── terraphim-agent-{version}-1-aarch64.pkg.tar.zst

Validation Checkpoints

Pre-Release Validation

Build Success: All matrix builds complete successfully
Binary Verification: Executables are valid for target platforms
Package Integrity: System packages install without conflicts
Desktop Functionality: GUI applications launch and function
Container Testing: Docker images run on all architectures

Post-Release Validation

Download Availability: All artifacts accessible from GitHub
Checksum Verification: SHA256 hashes match published values
Installation Testing: Clean installations work on all platforms
Update Testing: In-place updates preserve user data
Integration Testing: Components communicate correctly

This system map provides the foundation for understanding the complexity of the Terraphim AI release process and identifying critical validation points across the entire distribution ecosystem.

Runtime Validation Hooks Documentation## OverviewTerraphim AI implements a **two-stage runtime validation system** that provides safety and knowledge-graph enhancement for AI-assisted development workflows. This system operates through pre/post hooks around LLM generation and tool execution.## Two-Stage Hook Flow### Stage 1: Guard Stage (Security & Bypass Protection)**Purpose**: Prevent dangerous operations and enforce safety invariants before any processing occurs.**Location**: `~/.claude/hooks/pre_tool_use.sh`**Implementation**:```bash#!/bin/bash# Extract command from JSON inputCOMMAND=$(echo "$1" | jq -r '.tool_input.command // empty')# Strip quoted strings to avoid false positivesCLEAN_COMMAND=$(echo "$COMMAND" | sed 's/"[^"]*"//g')# Check for dangerous bypass flagsif [[ "$CLEAN_COMMAND" =~ (--no-verify|-n)(?=.*\bgit\s+(commit|push)) ]]; then # Return deny decision echo '{"decision": "deny", "reason": "Git bypass flags detected"}' exit 0fi# Continue to replacement stagecd ~/.config/terraphimterraphim-agent hook "$1"```**Guard Actions**:- **Block**: `--no-verify` or `-n` flags in `git commit/push` commands- **Allow**: All other commands proceed to replacement stage- **Log**: All guard decisions with reasons### Stage 2: Replacement Stage (Knowledge Graph Enhancement)**Purpose**: Replace text using knowledge graph patterns and connectivity validation.**Location**: `terraphim-agent hook` command in Terraphim agent**Implementation**:```rust// terraphim_agent/src/commands/hook.rspub async fn execute_hook( input: HookInput, agent: &TerraphimAgent,) -> Result { // Apply knowledge graph replacements let enhanced_text = agent .rolegraph .apply_replacements(&input.text)?; // Validate connectivity agent .automata .validate_connectivity(&enhanced_text)?; Ok(HookOutput { modified_text: enhanced_text, was_modified: enhanced_text != input.text, })}```**Replacement Actions**:- **Enhance**: Apply role-based knowledge graph patterns- **Validate**: Ensure semantic connectivity and coherence- **Transform**: Use thesaurus and autocomplete for consistency## Runtime LLM/Tool Hooks### Pre-LLM Hooks**Purpose**: Validate LLM inputs before generation.**Context**:```rustPreLlmContext { prompt: String, // Command type + description agent_id: String, // Agent identifier conversation_history: Vec, // Previous messages token_count: usize, // Estimated tokens}```**Hook Decisions**:- **Allow**: Proceed with LLM generation- **Block**: Stop with reason (security, policy, etc.)- **Modify**: Transform prompt (not recommended for LLM)- **AskUser**: Require human confirmation### Post-LLM Hooks**Purpose**: Validate and potentially modify LLM outputs.**Context**:```rustPostLlmContext { prompt: String, // Original prompt response: String, // Generated response agent_id: String, // Agent identifier token_count: usize, // Total tokens used model: String, // LLM model used}```**Hook Decisions**:- **Allow**: Return original response unchanged- **Block**: Prevent response delivery (harmful content, policy violations)- **Modify**: Transform response (formatting, style, safety fixes)- **AskUser**: Require human review before delivery### Pre-Tool Hooks**Purpose**: Validate code and commands before execution.**Context**:```rustPreToolContext { code: String, // Code to execute language: String, // Programming language agent_id: String, // Agent identifier vm_id: String, // VM execution environment metadata: HashMap, // Additional context}```**Security Validations**:- **Dangerous Patterns**: `rm -rf /`, `sudo`, `chmod 777`, etc.- **Language Restrictions**: Block execution in disallowed languages- **Resource Limits**: Validate memory, CPU, and file access- **Injection Prevention**: Command injection and shell escape detection### Post-Tool Hooks**Purpose**: Monitor and analyze execution results.**Context**:```rustPostToolContext { original_code: String, // Original code executed output: String, // Execution output exit_code: i32, // Process exit code duration_ms: u64, // Execution time agent_id: String, // Agent identifier vm_id: String, // VM identifier}```**Monitoring Actions**:- **Success/Failure Tracking**: Learn patterns of successful executions- **Performance Analysis**: Track execution times and resource usage- **Security Logging**: Record blocked or suspicious activities- **Knowledge Graph Learning**: Update successful patterns for future reference## Configuration### Runtime Validation Config**Location**: `~/.config/terraphim/runtime-validation.toml````toml[hooks]enabled = truefail_open = true # Allow execution if hooks fail (development mode)[guard]strict_mode = false # Block on any suspicion vs. specific patternslog_all_decisions = true # Log allow/block decisions[llm_hooks]enabled = truerequire_human_review = false # Only for high-stakes operations[tool_hooks]enabled = truevm_isolation = trueresource_limits = true[replacement]knowledge_graph_enhancement = trueconnectivity_validation = true```### Environment Variables```bash# Enable/disable specific hook categoriesTERRAPHIM_RUNTIME_VALIDATION_HOOKS=trueTERRAPHIM_GUARD_STAGE=trueTERRAPHIM_REPLACEMENT_STAGE=true# Hook behavior overridesTERRAPHIM_FAIL_OPEN=false # Production mode: fail closedTERRAPHIM_HOOK_TIMEOUT_MS=5000 # Hook execution timeout```## Hook Development### Creating Custom Hooks```rustuse crate::vm_execution::{hooks::*, VmExecutionError};#[derive(Debug)]pub struct SecurityHook { blocked_patterns: Vec,}#[async_trait]impl Hook for SecurityHook { fn name(&self) -> &str { "security-hook" } async fn pre_tool(&self, context: &PreToolContext) -> Result { for pattern in &self.blocked_patterns { if pattern.is_match(&context.code) { return Ok(HookDecision::Block { reason: format!("Blocked pattern: {}", pattern.as_str()), }); } } Ok(HookDecision::Allow) } async fn post_tool(&self, context: &PostToolContext) -> Result { // Log execution for learning if context.exit_code != 0 { log::warn!("Tool execution failed: {:?}", context); } Ok(HookDecision::Allow) }}```### Registering Hooks```rust// In agent initializationlet mut agent = TerraphimAgent::new(config).await?;// Add custom hooksagent.hook_manager.add_hook(Arc::new(SecurityHook::new()));agent.hook_manager.add_hook(Arc::new(PerformanceHook::new()));agent.hook_manager.add_hook(Arc::new(LearningHook::new()));```## Troubleshooting### Hook Not Invoked**Symptoms**: LLM/tool execution without hook validation**Causes**:- HookManager not initialized in agent- Hooks not registered with manager- Hook execution disabled in config**Resolution**:```bash# Check configcat ~/.config/terraphim/runtime-validation.toml# Verify agent initializationgrep -r "hook_manager" src/agent.rs# Check registrationgrep -r "add_hook" src/```### Hook Blocking Too Much**Symptoms**: Many operations blocked as "dangerous"**Causes**: Overly strict regex patterns, false positives**Resolution**:- Review `blocked_patterns` in security hooks- Enable debug logging to see exact matches- Adjust patterns to be more specific### Performance Issues**Symptoms**: Slow LLM/tool response times**Causes**: Hook timeout, expensive operations, network calls**Resolution**:- Increase `TERRAPHIM_HOOK_TIMEOUT_MS`- Profile hook execution with `tokio-console`- Move expensive operations to background threads## Best Practices1. **Fail-Open Development**: Use `fail_open = true` during development to avoid blocking2. **Specific Patterns**: Use targeted regex patterns instead of broad blocks3. **Async Operations**: Keep hook implementations fast and non-blocking4. **Comprehensive Logging**: Log all decisions for debugging and learning5. **Knowledge Graph Integration**: Leverage existing rolegraph and automata for intelligence6. **Security First**: Always implement security validation before functionality7. **Testing**: Test both success and failure scenarios for all hooks## Integration Points- **Claude Code**: `pre_tool_use.sh` → Guard → Replacement → Tool execution- **Terraphim Agent**: CommandExecutor with HookManager integration- **VM Execution**: Pre/post tool hooks around Firecracker execution- **LLM Generation**: Pre/post LLM hooks in all agent types- **Knowledge Graph**: Replacement service using rolegraph connectivityThis two-stage validation system ensures both security (guard stage) and intelligence enhancement (replacement stage) while maintaining clear separation of concerns and comprehensive audit trails.

Terraphim AI Test Scenarios