tribecodetribecode
    DocsPricingLogin
    Documentation

    Documentation

    • Getting Started
    • CLI Commands
    • TRIBE API UsageBeta
    • MUSENew
    • CIRCUITNew
    • Self-Hosting
      • Quick Start
      • Team Setup
    • API Reference
    • Analytics Dashboard
    • Privacy & Security
    • Troubleshooting
    1. Docs
    2. Self-Hosting

    Self-Hosting tribecode

    Deploy tribecode on your own infrastructure for maximum privacy, security, and complete data control.

    🛡️ Maximum Privacy & Security

    Self-hosting tribecode gives you complete control over your AI analytics data. Your telemetry never leaves your infrastructure, and you maintain full ownership of all collected insights.

    Setting Up Your Team?

    Learn how to configure multiple team members to use your self-hosted server securely.

    Team Setup Guide →

    Why Self-Host tribecode?

    🔒 Privacy Benefits

    • Data never leaves your network
    • No third-party cloud dependencies
    • Complete audit trail control
    • Custom retention policies
    • GDPR/HIPAA compliance friendly
    • Air-gapped deployment support

    ⚡ Enterprise Benefits

    • Custom authentication systems
    • Integration with existing infrastructure
    • Unlimited team size and usage
    • Custom analytics and reporting
    • No per-seat licensing costs
    • Full API customization

    Quick Start with CLI (Recommended)

    The easiest way to run a self-hosted server is using the tribecode CLI:

    Click to copy
    # Install the CLI (includes server binary)
    npx @_xtribe/cli@latest
    
    # Configure database (optional - uses in-memory by default)
    tribe server config database postgresql://user:pass@host:5432/db
    
    # Start the server
    tribe server start
    
    # Check status
    tribe server status
    
    # View logs
    tribe server logs
    
    # Stop the server
    tribe server stop

    CLI Server Commands

    CommandDescription
    tribe server startStart the tutor server daemon
    tribe server stopStop the tutor server daemon
    tribe server statusShow server status and configuration
    tribe server configShow current configuration
    tribe server config database <url>Set PostgreSQL database URL
    tribe server config port <port>Set server port (default: 8080)
    tribe server config resetReset configuration to defaults
    tribe server logsView server logs

    Using with Collector

    Once your server is running, authenticate and start collecting:

    Click to copy
    # Step 1: Login to tribecode.ai (required for authentication)
    tribe login
    
    # Step 2: Point collector to your local server
    tribe -tutor-local enable
    
    # Alternative: Set server URL via environment variable
    export TRIBE_TUTOR_SERVER=http://localhost:8080
    tribe enable

    🔐 OAuth Required: Your self-hosted server uses tribecode.ai for authentication. All users must run tribe login before collecting telemetry. This ensures user attribution and team management work correctly.


    Alternative Deployment Options

    📦 Manual Binary Download

    If you prefer to run the server binary directly without the CLI:

    Click to copy
    # Download and run the tutor server
    curl -L https://github.com/TRIBE-INC/tutor-server-community-release/releases/latest/download/tutor-server-linux-amd64 -o tutor-server
    chmod +x tutor-server
    ./tutor-server

    Requirements: 2GB RAM, 10GB storage, Linux/macOS/Windows

    🏢 Enterprise: Kubernetes Cluster

    Production-ready deployment for large teams (50+ users) with high availability and auto-scaling.

    Click to copy
    # Deploy tribecode Kubernetes cluster
    npx @_xtribe/cli@latest --localhost on
    # or
    git clone https://github.com/TRIBE-INC/0zen
    cd 0zen && ./start.sh

    Requirements: Kubernetes cluster, 4GB+ RAM per node, container registry

    🔒 Air-Gapped: Offline Deployment

    Complete offline deployment for maximum security environments with no internet access.

    Click to copy
    # Download release bundle offline
    # Transfer to secure network
    # Deploy without internet connectivity

    Requirements: Offline package transfer, local container registry

    Database Setup

    By default, the server uses in-memory storage (data lost on restart). For production use, configure a PostgreSQL database for persistent storage.

    Option 1: CLI Configuration (Recommended)

    The simplest way to configure a database:

    Click to copy
    # Configure PostgreSQL database
    tribe server config database postgresql://user:password@host:5432/dbname
    
    # Verify configuration
    tribe server status
    
    # Restart server to apply
    tribe server stop && tribe server start

    Tables are automatically created on first connection.

    Option 2: Environment Variables

    For manual binary deployments or containerized environments:

    Click to copy
    # PostgreSQL (self-hosted or cloud)
    export DATABASE_URL="postgresql://user:password@host:5432/dbname?sslmode=require"
    
    # OR Supabase (managed cloud)
    export SUPABASE_URL="https://your-project.supabase.co"
    export SUPABASE_SERVICE_ROLE_KEY="your-service-role-key"
    
    # Start server
    ./tutor-server

    Database Options Comparison

    OptionConfigurationUse Case
    PostgreSQLDATABASE_URL or CLI configSelf-hosted, full control, production
    SupabaseSUPABASE_URL + SUPABASE_SERVICE_ROLE_KEYManaged cloud, easy setup
    In-MemoryDefault (no config needed)Development, testing only

    Supported PostgreSQL providers: Self-hosted PostgreSQL 12+, NeonDB, Supabase, Railway, or any PostgreSQL-compatible database.

    Security Recommendations

    • • Always use sslmode=require for PostgreSQL connections
    • • Use strong, unique passwords for database access
    • • Restrict database network access to your server IP only
    • • Keep OAuth authentication enabled (default) - only disable for air-gapped deployments

    Component Architecture

    tribecode consists of several microservices that work together to provide comprehensive AI analytics:

    tribecode server

    Core telemetry collection and processing engine. Handles data ingestion, privacy scrubbing, and analytics generation.

    Essential

    Web Dashboard

    Interactive analytics dashboard for visualizing team insights, usage patterns, and productivity metrics.

    Recommended

    Bridge API

    Orchestration layer that manages agent lifecycles, task assignment, and coordinates between components.

    Advanced

    TaskMaster

    Task queue and workflow management system for automated AI agent operations and collaborative coding workflows.

    Advanced

    💡 Modular Deployment

    Start with just the tribecode server for basic analytics, then add components as your needs grow. Each component can be deployed independently and scaled separately.

    Quick Start Guide

    Step 1: Download the Server

    Get the latest pre-built binary for your platform:

    Linux (recommended for servers):
    Click to copy
    curl -L https://github.com/TRIBE-INC/tutor-server-community-release/releases/latest/download/tutor-server-linux-amd64 -o tutor-server
    macOS (Intel):
    Click to copy
    curl -L https://github.com/TRIBE-INC/tutor-server-community-release/releases/latest/download/tutor-server-darwin-amd64 -o tutor-server
    macOS (Apple Silicon):
    Click to copy
    curl -L https://github.com/TRIBE-INC/tutor-server-community-release/releases/latest/download/tutor-server-darwin-arm64 -o tutor-server

    Step 2: Configure & Run

    Click to copy
    # Make executable
    chmod +x tutor-server
    
    # Optional: Configure port (default: 8080)
    export PORT=8080
    
    # Run the server (OAuth via tribecode.ai enabled by default)
    ./tutor-server

    The server starts on http://localhost:8080 with OAuth authentication via tribecode.ai enabled by default.

    Step 3: Verify Installation

    Click to copy
    # Check server health
    curl http://localhost:8080/api/health
    
    # View web dashboard
    open http://localhost:8080

    Security Configuration

    Authentication Setup

    Self-hosted servers authenticate users via tribecode.ai OAuth by default. This provides user attribution, team management, and secure access control without any additional configuration.

    🔐 OAuth via tribecode.ai (Default)

    Click to copy
    # Server: No configuration needed!
    # OAuth is enabled by default
    
    # Clients authenticate via:
    tribe login

    Recommended for all deployments. Users authenticate via tribecode.ai. Enables user attribution, team management, and usage analytics.

    🔒 Air-Gapped Mode (Offline Only)

    Click to copy
    # Server: Enable anonymous ingest
    export ALLOW_ANONYMOUS_INGEST=true
    
    # Clients: Skip authentication
    tribe -skip-auth enable

    Only for air-gapped networks with no internet connectivity. No user attribution or team features available.

    ✅ How OAuth Authentication Works

    • • Users run tribe login to authenticate with tribecode.ai
    • • Collector sends OAuth token with each telemetry request
    • • Your server validates tokens via tribecode.ai/api/account/info
    • • Valid tokens return user ID, email, and team for proper attribution
    • • Token validation is cached for 5 minutes for performance
    • • Your data stays on your server - only tokens are validated externally

    Network Security

    TLS/HTTPS Setup

    Click to copy
    # Use reverse proxy (recommended)
    nginx/apache → https://your-domain.com → http://localhost:8080
    
    # Or configure TLS directly
    export TLS_CERT_PATH="/path/to/cert.pem"
    export TLS_KEY_PATH="/path/to/key.pem"

    Firewall Configuration

    • • Only expose port 8080 internally (use reverse proxy for external access)
    • • Restrict database access to application servers only
    • • Use VPN or private networks for admin access
    • • Enable fail2ban or similar intrusion prevention

    Production Configuration

    Data Storage

    The tutor server currently uses in-memory storage for simplicity and performance:

    ⚠️ In-Memory Storage

    • • Data is stored in memory and will be lost when server restarts
    • • Suitable for development and testing environments
    • • For production use, consider regular exports or contact support for persistence options
    • • Performance is excellent for real-time analytics

    💡 Data Persistence Tips

    • • Use scheduled exports for backup: curl localhost:8080/api/telemetry/stats > backup.json
    • • Keep server running continuously for persistent analytics
    • • Consider load balancing multiple instances for high availability

    Process Management

    Use systemd for automatic startup and process management:

    Click to copy
    # Create systemd service
    sudo tee /etc/systemd/system/tribe-tutor.service <<EOF
    [Unit]
    Description=tribecode Server
    After=network.target
    
    [Service]
    Type=simple
    User=tribe
    ExecStart=/opt/tribe/tutor-server
    Environment=PORT=8080
    # OAuth via tribecode.ai is enabled by default
    # For air-gapped deployments only:
    # Environment=ALLOW_ANONYMOUS_INGEST=true
    Restart=always
    
    [Install]
    WantedBy=multi-user.target
    EOF
    
    # Enable and start
    sudo systemctl enable tribe-tutor
    sudo systemctl start tribe-tutor

    Monitoring & Logging

    Health Monitoring

    Click to copy
    # Add to monitoring system
    curl http://localhost:8080/api/health
    
    # Expected response:
    {"status":"healthy","uptime":"..."}

    Log Management

    Click to copy
    # Configure log rotation
    sudo tee /etc/logrotate.d/tribe <<EOF
    /var/log/tribe/*.log {
      daily
      rotate 30
      compress
      delaycompress
      notifempty
    }
    EOF

    Backup & Recovery

    Data Backup Strategy

    Click to copy
    # Export current analytics data
    curl http://localhost:8080/api/telemetry/stats > analytics_$(date +%Y%m%d).json
    
    # Backup server binary and configuration
    tar -czf tutor_backup_$(date +%Y%m%d).tar.gz ./tutor-server .env
    
    # Backup authentication data (if using OAuth)
    cp ~/.tribe/tutor/auth.json auth_backup_$(date +%Y%m%d).json

    Disaster Recovery

    • Store backups in separate geographic location
    • Test restore procedures monthly
    • Document recovery time objectives (RTO)
    • Maintain infrastructure-as-code for rapid redeployment
    • Keep encrypted copies of authentication secrets

    Compliance & Governance

    Data Governance

    • • Custom data retention policies
    • • Automated PII scrubbing with custom rules
    • • Audit logging for all data access
    • • Role-based access controls
    • • Data export in standard formats
    • • Configurable anonymization

    Compliance Features

    • • GDPR: Right to access, rectify, erase
    • • HIPAA: Encryption at rest and in transit
    • • SOC 2: Audit trails and access controls
    • • PCI DSS: Secure credential handling
    • • ISO 27001: Security management systems
    • • Custom compliance reporting

    Scaling & Performance

    Horizontal Scaling

    Scale TRIBE components independently based on your needs:

    ComponentScaling MethodBottleneck
    tribecode serverMultiple instances + load balancerData ingestion rate
    DatabaseRead replicas + shardingWrite throughput
    DashboardCDN + multiple instancesConcurrent users

    Performance Optimization

    Click to copy
    # Optimize server performance
    export MAX_BATCH_SIZE=1000     # Larger batches for high throughput
    export PORT=8080               # Use fast port
    
    # System-level optimizations
    # Increase file descriptor limits
    ulimit -n 65536
    
    # Use more CPU cores (run multiple instances with load balancer)
    # Start on different ports: 8080, 8081, 8082, etc.

    Migration & Upgrades

    From Cloud to Self-Hosted

    Migrate existing data from TRIBE cloud to your self-hosted instance:

    Click to copy
    # Export from cloud instance (contact support for data export)
    # Data migration currently requires manual assistance
    
    # Alternative: Start fresh with self-hosted instance
    # Your new telemetry data will be collected locally

    Version Upgrades

    1. Stop the current service: sudo systemctl stop tribe-tutor
    2. Backup database and configuration files
    3. Download new binary version
    4. Run database migrations (if required)
    5. Update configuration for new features
    6. Start service: sudo systemctl start tribe-tutor
    7. Verify functionality with health check

    Troubleshooting

    Common Issues

    Server won't start on port 8080

    Check if port is in use: lsof -i :8080. Set different port: PORT=8081 ./tutor-server

    Authentication issues

    Ensure users have run tribe login to authenticate with tribecode.ai. For air-gapped deployments, set ALLOW_ANONYMOUS_INGEST=true.

    High memory usage

    Reduce batch sizes in configuration. Consider adding more RAM or horizontal scaling.

    Debug Commands

    Click to copy
    # Check server status
    curl http://localhost:8080/api/health
    
    # View logs
    journalctl -u tribe-tutor -f
    
    # Test API endpoints
    curl http://localhost:8080/api/telemetry/stats
    
    # Check resource usage
    htop
    df -h

    Support & Community

    📚 Documentation

    • Getting Started Guide
    • API Reference
    • Troubleshooting Guide
    • CLI Commands

    🤝 Community Support

    • GitHub Issues
    • Discord Community
    • Email Support
    • Contributing Guide

    🚀 Ready to Deploy?

    Start with our single-server deployment and scale up as your team grows. Self-hosting tribecode gives you complete control over your AI analytics while maintaining maximum privacy.

    Download Latest ReleaseView Setup Guide
    tribecodetribecode

    Not another agent—a telemetry vault + API you can trust.

    Product

    • Pricing
    • Support

    Developers

    • Documentation
    • API Reference
    • GitHub

    © 2026 tribecode. All rights reserved.

    Privacy PolicyTerms of Service