Animus Installer

Overview

The Animus Installer is a bootstrap script that automates the installation and configuration of the Animus multi-agent system. It sets up a complete environment for running multiple Letta agent instances with shared Animus resources.

What is Animus?

Animus is a multi-agent system that provides:

• Multi-Agent Architecture: Run multiple Letta agent instances with complete isolation
• Shared Resources: Common Python environment and SMCP service
• TUI Interface: Terminal-based user interface (web interface was deprecated)
• MCP Protocol: Model Context Protocol compliance for agent communication

Quick Start

Prerequisites

• Operating System: Ubuntu, WSL, or Raspbian
• Root Access: sudo privileges required
• Internet Connection: Required for package installation and Docker pulls
• Domain: A domain name pointing to your server (for SSL certificates)

Installation

1. Clone the repository:

   git clone https://github.com/AnimusUNO/installer.git
   cd installer

2. Customize the bootstrap script:

   nano kernel-installer/animus_bootstrap.sh

   Required Customizations:

   DOMAIN="your-domain.com"                    # Your actual domain
   EMAIL="your-email@domain.com"               # Your email for SSL
   LETTAPASS="your-secure-password"            # Secure password for Letta
   OPENAI_API_KEY="your-openai-key"            # Your OpenAI API key
   ANTHROPIC_API_KEY="your-anthropic-key"      # Your Anthropic API key

3. Run the installation:

   sudo bash kernel-installer/animus_bootstrap.sh

4. Verify installation:

   # Check if Letta container is running
   docker ps | grep letta
   
   # Check Nginx status
   sudo systemctl status nginx
   
   # Check SSL certificate
   sudo certbot certificates

Project Structure

installer/
├── kernel-installer/
│   └── animus_bootstrap.sh          # Main installation script
├── docs/
│   ├── README.md                     # Documentation overview
│   └── reference/                    # Technical specifications
│       ├── registry_schema.md        # Database schema
│       ├── multi-agent-architecture.md
│       └── letta-api-reference.md
├── requirements.txt                  # Python dependencies
├── .gitignore                       # Git ignore rules
└── README.md                        # This file

Installation Process

The bootstrap script performs the following steps:

1. System Updates: Updates package lists and installs dependencies
2. Python Environment: Creates shared virtual environment
3. Docker Setup: Installs Docker and pulls Letta container
4. Nginx Configuration: Sets up reverse proxy with SSL
5. SSL Certificates: Obtains Letta certificates via Certbot
6. Auto-Start: Configures cron jobs for automatic startup

Configuration

Environment Variables

The bootstrap script uses these configuration variables:

Variable	Description	Example
DOMAIN	Your domain name	example.com
EMAIL	Email for SSL certificates	admin@example.com
LETTAPASS	Letta admin password	secure-password-123
OPENAI_API_KEY	OpenAI API key	sk-...
ANTHROPIC_API_KEY	Anthropic API key	sk-ant-...
OLLAMA_BASE_URL	Ollama service URL	http://host.docker.internal:11434

Post-Installation

After installation, you can access:

• Letta Web Interface: https://your-domain.com
• Letta Admin: https://your-domain.com/admin
• Logs: Check /var/log/nginx/ and Docker logs

Troubleshooting

Common Issues

1. SSL Certificate Issues

# Check certificate status
sudo certbot certificates

# Renew certificates manually
sudo certbot renew --dry-run

2. Docker Container Not Starting

# Check container logs
docker logs letta-container

# Restart container
docker restart letta-container

3. Nginx Configuration Issues

# Test configuration
sudo nginx -t

# Reload configuration
sudo systemctl reload nginx

4. Port Conflicts

# Check if ports are in use
sudo netstat -tlnp | grep :8284
sudo netstat -tlnp | grep :80
sudo netstat -tlnp | grep :443

Log Locations

• Nginx Logs: /var/log/nginx/
• Docker Logs: docker logs letta-container
• System Logs: /var/log/syslog
• Cron Logs: /var/log/cron.log

Development

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Testing

# Test the bootstrap script (dry run)
sudo bash kernel-installer/animus_bootstrap.sh --dry-run

# Verify Python dependencies
pip install -r requirements.txt

Security

Important Security Notes

• Template Values: The bootstrap script contains template values that MUST be customized
• API Keys: Never commit real API keys to the repository
• Passwords: Use strong, unique passwords for production installations
• SSL: Always use HTTPS in production environments

Security Best Practices

1. Customize All Template Values: Never run with default template values
2. Use Strong Passwords: Generate secure passwords for all services
3. Keep Dependencies Updated: Regularly update Python packages and system packages
4. Monitor Logs: Regularly check logs for suspicious activity
5. Backup Configuration: Keep backups of your customized configuration

License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.

Support

• Documentation: Check the docs/ directory for detailed technical specifications
• Issues: Report bugs and feature requests on GitHub Issues
• Discussions: Join community discussions on GitHub Discussions

Changelog

Recent Changes

• 2025-10-12: Added comprehensive documentation and README
• 2025-10-12: Removed deprecated Flask web interface dependencies
• 2025-10-12: Updated dependency versions and added version constraints
• 2025-10-12: Fixed broken documentation references
• 2025-10-12: Renamed bootstrap script for consistency

---

⚠️ Important: This is a bootstrap installation script. Always customize the template values before running in production environments.