Claude Code + Agents UI Stack - Complete Package

📦 What's Included

This package contains everything needed to deploy a complete Claude Code + Agents UI Docker stack to your TrueNAS SCALE instance.

Files Overview

claude-code-stack/
├── QUICKSTART.md                          # Start here!
├── DEPLOYMENT_GUIDE.md                    # Comprehensive guide
├── docker-compose.yml                     # Main Docker Compose configuration
├── claude-agents-ui-Dockerfile            # Custom Docker image combining UI + Claude Code
├── nginx.conf                             # Reverse proxy configuration
├── claude-code-stack.env                  # Environment variables template
├── deploy-ssh.sh                          # Automated SSH deployment script (RECOMMENDED)
├── deploy-mcp.py                          # MCP-based deployment script
└── README.md                              # This file

🚀 Quick Start (30 seconds)

# 1. Set your API key
export ANTHROPIC_API_KEY="sk-ant-your-actual-key-here"

# 2. Run the deployment script
chmod +x deploy-ssh.sh
./deploy-ssh.sh 192.168.1.100 root tank

# 3. Access the UI
# Open: http://192.168.1.100:3000

📋 What Each File Does

QUICKSTART.md

Start here if you're in a hurry!

• 3 deployment methods
• Quick setup instructions
• Troubleshooting tips
• Common commands

DEPLOYMENT_GUIDE.md

Complete reference guide

• Detailed architecture
• Step-by-step setup
• Configuration options
• Monitoring & maintenance
• Security hardening
• Performance tuning

docker-compose.yml

Main orchestration file Includes:

• Claude Code Agents UI (Nuxt 3 frontend)
• Claude Code Runtime (code execution)
• PostgreSQL (data persistence)
• Redis (caching)
• Nginx (reverse proxy)

All services with:

• Health checks
• Volume management
• Network configuration
• Resource limits

claude-agents-ui-Dockerfile

Optional: Combined image Builds a single Docker image containing:

• Agents UI (Nuxt 3)
• Claude Code CLI
• Required dependencies
• Non-root user for security

Use this if you prefer building a custom image instead of using pre-built images.

nginx.conf

Reverse proxy configuration

• Load balancing
• SSL/TLS support
• Rate limiting
• Security headers
• WebSocket support
• Static file caching

claude-code-stack.env

Environment variables template Configure:

• Anthropic API key (REQUIRED)
• Database credentials
• API ports and hosts
• Security settings
• Storage options
• Agent configuration

deploy-ssh.sh

Automated SSH deployment ⭐ RECOMMENDED

• One-command setup
• Validates prerequisites
• Tests SSH connection
• Creates directories
• Uploads files
• Configures environment
• Starts services
• Verifies deployment
• Sets up monitoring

deploy-mcp.py

MCP-based deployment For advanced users with MCP server running:

• Deploys via MCP protocol
• Async/await operation
• Progress indicators
• Error handling

🎯 Deployment Flowchart

Start
  │
  ├─→ Choose Method
  │    ├─→ SSH (recommended) → deploy-ssh.sh
  │    ├─→ MCP (advanced) → deploy-mcp.py
  │    └─→ Manual → Use docker-compose.yml directly
  │
  ├─→ Prerequisites
  │    ├─→ API Key ✓
  │    ├─→ SSH access ✓
  │    └─→ Docker on TrueNAS ✓
  │
  ├─→ Deploy Stack
  │    ├─→ Create directory
  │    ├─→ Upload files
  │    ├─→ Configure .env
  │    ├─→ Pull images
  │    └─→ Start services
  │
  ├─→ Verify
  │    ├─→ Check service status
  │    ├─→ Test port 3000
  │    └─→ View logs
  │
  └─→ Access UI
       └─→ http://your-truenas-ip:3000

🏗️ Architecture

Your Computer
     │
     │ (SSH or MCP)
     ▼
TrueNAS SCALE
     │
     ├─→ docker-compose
     │
     └─→ Services:
         ├─→ Claude Code Agents UI (Port 3000)
         │   └─→ Web interface for agent management
         │
         ├─→ Claude Code Backend (Port 5000)
         │   └─→ Code execution environment
         │
         ├─→ PostgreSQL (Port 5432)
         │   └─→ Agent data persistence
         │
         ├─→ Redis (Port 6379)
         │   └─→ Caching & sessions
         │
         └─→ Nginx (Port 80/443)
             └─→ Reverse proxy

🔐 Security Features

• ✓ Non-root user execution
• ✓ Health checks on all services
• ✓ Security headers via Nginx
• ✓ Rate limiting
• ✓ SSL/TLS support (optional)
• ✓ Environment variable isolation
• ✓ Volume isolation
• ✓ Network isolation

📊 Resource Requirements

Minimum

• RAM: 2GB allocated to Docker
• CPU: 2 cores
• Disk: 10GB free

Recommended

• RAM: 4GB allocated to Docker
• CPU: 4 cores
• Disk: 20GB free

Optimal

• RAM: 8GB+ allocated to Docker
• CPU: 8+ cores
• Disk: 50GB+ free

🚦 Deployment Status

After running deploy-ssh.sh, you'll see:

[INFO] Checking prerequisites...
[INFO] Testing SSH connection...
[INFO] Creating project directory on TrueNAS...
[INFO] Uploading Docker configuration files...
[INFO] Configuring environment variables...
[INFO] Deploying Docker stack...
[INFO] Verifying deployment...
========================================
  Claude Code Stack Deployed!
========================================

Access the Agents UI at:
  http://192.168.1.100:3000

📝 Next Steps

1. Deploy: Run ./deploy-ssh.sh your-truenas-ip
2. Access: Open http://your-truenas-ip:3000
3. Configure: Set up API keys and workspace
4. Create: Build your first agent
5. Test: Execute and monitor agent tasks

🆘 Common Issues

Q: SSH connection fails

A: Check TrueNAS IP, SSH is enabled, and you have correct credentials.

Q: Port 3000 not responding

A: Wait 30 seconds for startup. Check logs: docker-compose logs agents-ui

Q: API key not recognized

A: Verify in .env file and restart: docker-compose restart

Q: PostgreSQL connection fails

A: Check credentials match in .env. Run: docker-compose logs postgres

See DEPLOYMENT_GUIDE.md for more troubleshooting.

📚 Documentation

• QUICKSTART.md - Start here for quick setup
• DEPLOYMENT_GUIDE.md - Complete reference guide
• Claude Code Docs - https://docs.anthropic.com/
• GitHub Repo - https://github.com/Ngxba/claude-code-agents-ui

🎓 Learning Resources

Getting Started with Claude Code

claude --help
claude "What's in the current directory?"

Creating Agents

Use the Agents UI at http://your-truenas-ip:3000 to:

• Create agents
• Configure models
• Set instructions
• Build workflows

Using Agents

# View available agents
claude list-agents

# Run an agent
claude run agent-name "prompt"

# Interactive mode
claude chat agent-name

🔄 Update & Maintenance

Pull Latest Images

docker-compose pull
docker-compose up -d

View Logs

docker-compose logs -f [service]

Backup Data

docker-compose exec claude-code-backend tar czf - -C /root .claude | gzip > backup.tar.gz

Clean Up

docker system prune -a
docker volume prune

📞 Support

For issues or questions:

1. Check DEPLOYMENT_GUIDE.md troubleshooting section
2. Review QUICKSTART.md for common solutions
3. Check Docker logs: docker-compose logs
4. Visit: https://github.com/Ngxba/claude-code-agents-ui/issues
5. See: https://docs.anthropic.com/

📄 License

This deployment package is provided as-is.

• Claude Code - Use your Anthropic API key
• Agents UI - MIT License (https://github.com/Ngxba/claude-code-agents-ui)
• Docker Components - Various open-source licenses

🎉 Success!

Once deployed, you'll have:

• ✓ Web interface for agent management
• ✓ Claude Code execution environment
• ✓ Persistent storage with PostgreSQL
• ✓ Caching layer with Redis
• ✓ Reverse proxy with Nginx
• ✓ All integrated and running on TrueNAS

Happy coding! 🚀

---

Version: 1.0.0 Last Updated: 2026-04-04 Compatibility: TrueNAS SCALE, Docker Compose 3.8+