Headmaster Docs

Deployment Guide

This guide covers deploying Headmaster to your organization, including prerequisites, configuration, and best practices for production environments.

Prerequisites

System Requirements

Minimum Specifications

  • 2 CPU cores
  • 4 GB RAM
  • 20 GB storage (grows with agent memory)
  • 100 Mbps network connection

Recommended Production Specifications

  • 8+ CPU cores
  • 32 GB RAM
  • 500 GB+ SSD storage
  • Redundant 1 Gbps+ network connections

Required Infrastructure

Cloud Providers

  • AWS (EC2, RDS, S3)
  • Google Cloud (Compute Engine, Cloud SQL, Cloud Storage)
  • Microsoft Azure (Virtual Machines, SQL Database, Blob Storage)
  • Private data centers with Docker and Kubernetes support

Kubernetes (recommended for production)

  • Kubernetes 1.24 or later
  • Helm 3.x for package management
  • Persistent volume support (EBS, GCE, Azure Disks)
  • Container registry access (ECR, GCR, ACR, or Docker Hub)

Required Accounts & Credentials

  1. LLM Provider (choose one or more)
    • Anthropic API key for Claude models
    • OpenAI API key for GPT models
    • Google AI API credentials
    • Other model providers as needed
  2. Platform Integrations (optional, as needed)
    • Slack workspace admin access
    • Microsoft Teams organization admin
    • Gmail/Microsoft 365 service account
    • Salesforce org credentials
    • AWS/GCP/Azure service accounts
  3. Database
    • PostgreSQL 13+ or managed service (RDS, Cloud SQL, Azure Database)
    • Initial user account with CREATE DATABASE permissions
  4. Email Delivery (optional)
    • SMTP server credentials (or use AWS SES, SendGrid, etc.)
    • Domain verification for email agents

Deployment Steps

1. Prepare Your Environment

Create a deployment directory and clone the Headmaster configuration:

mkdir -p /opt/headmaster cd /opt/headmaster git clone https://github.com/gcaplabs/headmaster-deploy.git cd headmaster-deploy

2. Configure Environment Variables

Create a .env file with your configuration:

# Core Configuration HEADMASTER_ENV=production HEADMASTER_REGION=us-east-1 HEADMASTER_LOG_LEVEL=info # LLM Configuration (choose primary model) LLM_PROVIDER=anthropic ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx # Database Configuration DATABASE_URL=postgresql://headmaster:password@db.example.com:5432/headmaster DATABASE_POOL_SIZE=20 # Storage Configuration STORAGE_TYPE=s3 AWS_REGION=us-east-1 AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE # Security Configuration JWT_SECRET=your-very-long-random-secret-key-here ENCRYPTION_KEY=your-encryption-key-here # Monitoring & Logging DATADOG_API_KEY=xxxxxxxxxxxxx

3. Database Setup

Create and initialize the database:

# Create database and user createdb -h db.example.com -U postgres headmaster # Run migrations npx headmaster db:migrate # Create initial admin user npx headmaster admin:create --email admin@example.com

4. Deploy Using Docker

Build and run the Headmaster container:

# Build image docker build -t headmaster:latest . # Run container docker run -d \ --name headmaster \ --env-file .env \ -p 8080:8080 \ -v /opt/headmaster/data:/app/data \ headmaster:latest # Verify deployment curl http://localhost:8080/health

5. Deploy on Kubernetes

Use the provided Helm chart:

# Add Headmaster Helm repository helm repo add headmaster https://charts.gcaplabs.com helm repo update # Create namespace kubectl create namespace headmaster # Create secrets for sensitive data kubectl create secret generic headmaster-api-keys \ --from-literal=ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \ -n headmaster # Deploy using Helm helm install headmaster headmaster/headmaster \ --namespace headmaster \ --values values.yaml # Verify deployment kubectl get pods -n headmaster

6. Configure Platform Integrations

Slack Integration

Create a Slack app and configure:

  1. Go to https://api.slack.com/apps/new
  2. Select "From scratch"
  3. Copy Bot User OAuth Token
  4. Set SLACK_BOT_TOKEN environment variable
  5. Test connection: npx headmaster slack:test-connection

Email Integration

For Gmail:

  1. Create service account in Google Cloud Console
  2. Download JSON key
  3. Share Google Group with service account email
  4. Test connection: npx headmaster email:test-connection

7. Enable Monitoring & Logging

Datadog

# Install Datadog agent helm repo add datadog https://helm.datadoghq.com helm install datadog datadog/datadog \ --set datadog.apiKey=$DD_API_KEY \ -n headmaster

Post-Deployment Configuration

1. Create Your First Agent

npx headmaster agent:create \ --name "Customer Support Agent" \ --model "claude-3-5-sonnet-20241022" \ --platform slack \ --workspace-id T12345678

2. Configure Approval Gates

npx headmaster approval:configure \ --agent-id agent_123 \ --trigger financial_transaction \ --threshold 5000 \ --approver-group finance_team

3. Set Up Monitoring Dashboards

  • Access web UI: https://headmaster.example.com
  • Create dashboards for:
    • Agent activity and uptime
    • Error rates and performance
    • Model usage and costs
    • Integration health

4. Run Health Checks

# System health npx headmaster health:check # Database connectivity npx headmaster db:check # Integration status npx headmaster integration:status

Production Best Practices

High Availability

  • Run at least 3 replicas for fault tolerance
  • Use load balancer with health checks
  • Database replication (primary/standby)
  • Automated backups every 6 hours
  • Cross-region failover capability

Scaling

  • Horizontal scaling: increase pod replicas
  • Vertical scaling: increase resource requests/limits
  • Cache layer (Redis) for frequently accessed data
  • Database connection pooling
  • Asynchronous job queue for long-running tasks

Security

  • Enable TLS for all communications
  • Use secrets management (Vault, AWS Secrets Manager)
  • Regular security updates and patches
  • Network policies and firewall rules
  • Audit logging for all operations

Disaster Recovery

  • Regular backup testing (monthly)
  • Recovery time objective (RTO): 4 hours
  • Recovery point objective (RPO): 1 hour
  • Documented runbooks for common scenarios
  • Disaster recovery drills quarterly

Troubleshooting

Agent not responding

# Check agent status npx headmaster agent:status --id agent_123 # View recent logs npx headmaster logs:tail --agent-id agent_123 --lines 50 # Restart agent npx headmaster agent:restart --id agent_123

Database connection issues

# Test connection npx headmaster db:test-connection # Check migrations npx headmaster db:status # Run migrations npx headmaster db:migrate

Memory issues

# Check memory usage npx headmaster memory:stats # Archive old conversations npx headmaster memory:archive --days 90

Getting Help

  • Documentation: https://docs.gcaplabs.com
  • Community: https://community.gcaplabs.com
  • Support Email: support@gcaplabs.com
  • Emergency Hotline: +1-415-555-0147
  • Status Page: https://status.gcaplabs.com