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.
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:
# 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 stopCLI Server Commands
| Command | Description |
|---|---|
tribe server start | Start the tutor server daemon |
tribe server stop | Stop the tutor server daemon |
tribe server status | Show server status and configuration |
tribe server config | Show current configuration |
tribe server config database <url> | Set PostgreSQL database URL |
tribe server config port <port> | Set server port (default: 8080) |
tribe server config reset | Reset configuration to defaults |
tribe server logs | View server logs |
Using with Collector
Once your server is running, authenticate and start collecting:
# 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:
# 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-serverRequirements: 2GB RAM, 10GB storage, Linux/macOS/Windows
🏢 Enterprise: Kubernetes Cluster
Production-ready deployment for large teams (50+ users) with high availability and auto-scaling.
# Deploy tribecode Kubernetes cluster
npx @_xtribe/cli@latest --localhost on
# or
git clone https://github.com/TRIBE-INC/0zen
cd 0zen && ./start.shRequirements: Kubernetes cluster, 4GB+ RAM per node, container registry
🔒 Air-Gapped: Offline Deployment
Complete offline deployment for maximum security environments with no internet access.
# Download release bundle offline
# Transfer to secure network
# Deploy without internet connectivityRequirements: 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:
# 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 startTables are automatically created on first connection.
Option 2: Environment Variables
For manual binary deployments or containerized environments:
# 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-serverDatabase Options Comparison
| Option | Configuration | Use Case |
|---|---|---|
| PostgreSQL | DATABASE_URL or CLI config | Self-hosted, full control, production |
| Supabase | SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY | Managed cloud, easy setup |
| In-Memory | Default (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=requirefor 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.
Web Dashboard
Interactive analytics dashboard for visualizing team insights, usage patterns, and productivity metrics.
Bridge API
Orchestration layer that manages agent lifecycles, task assignment, and coordinates between components.
TaskMaster
Task queue and workflow management system for automated AI agent operations and collaborative coding workflows.
💡 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:
curl -L https://github.com/TRIBE-INC/tutor-server-community-release/releases/latest/download/tutor-server-linux-amd64 -o tutor-servercurl -L https://github.com/TRIBE-INC/tutor-server-community-release/releases/latest/download/tutor-server-darwin-amd64 -o tutor-servercurl -L https://github.com/TRIBE-INC/tutor-server-community-release/releases/latest/download/tutor-server-darwin-arm64 -o tutor-serverStep 2: Configure & Run
# 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-serverThe server starts on http://localhost:8080 with OAuth authentication via tribecode.ai enabled by default.
Step 3: Verify Installation
# Check server health
curl http://localhost:8080/api/health
# View web dashboard
open http://localhost:8080Security 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)
# Server: No configuration needed!
# OAuth is enabled by default
# Clients authenticate via:
tribe loginRecommended for all deployments. Users authenticate via tribecode.ai. Enables user attribution, team management, and usage analytics.
🔒 Air-Gapped Mode (Offline Only)
# Server: Enable anonymous ingest
export ALLOW_ANONYMOUS_INGEST=true
# Clients: Skip authentication
tribe -skip-auth enableOnly for air-gapped networks with no internet connectivity. No user attribution or team features available.
✅ How OAuth Authentication Works
- • Users run
tribe loginto 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
# 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:
# 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-tutorMonitoring & Logging
Health Monitoring
# Add to monitoring system
curl http://localhost:8080/api/health
# Expected response:
{"status":"healthy","uptime":"..."}Log Management
# Configure log rotation
sudo tee /etc/logrotate.d/tribe <<EOF
/var/log/tribe/*.log {
daily
rotate 30
compress
delaycompress
notifempty
}
EOFBackup & Recovery
Data Backup Strategy
# 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).jsonDisaster 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:
| Component | Scaling Method | Bottleneck |
|---|---|---|
| tribecode server | Multiple instances + load balancer | Data ingestion rate |
| Database | Read replicas + sharding | Write throughput |
| Dashboard | CDN + multiple instances | Concurrent users |
Performance Optimization
# 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:
# 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 locallyVersion Upgrades
- Stop the current service:
sudo systemctl stop tribe-tutor - Backup database and configuration files
- Download new binary version
- Run database migrations (if required)
- Update configuration for new features
- Start service:
sudo systemctl start tribe-tutor - Verify functionality with health check
Troubleshooting
Common Issues
Check if port is in use: lsof -i :8080. Set different port: PORT=8081 ./tutor-server
Ensure users have run tribe login to authenticate with tribecode.ai. For air-gapped deployments, set ALLOW_ANONYMOUS_INGEST=true.
Reduce batch sizes in configuration. Consider adding more RAM or horizontal scaling.
Debug Commands
# 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 -hSupport & Community
🤝 Community Support
🚀 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.