claude-code-stack/QUICKSTART.md

Claude Code + Agents UI Stack - Quick Start Guide

📋 Prerequisites

• TrueNAS SCALE system running
• Docker and Docker Compose installed on TrueNAS
• Anthropic API Key (get from https://console.anthropic.com/)
• SSH access to TrueNAS (for SSH deployment method)

🚀 Deployment Options

Option 1: SSH Deployment (Easiest for TrueNAS)

This is the recommended method for deploying to TrueNAS.

Setup

# 1. Make the deployment script executable
chmod +x deploy-ssh.sh

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

# 3. Deploy to your TrueNAS
./deploy-ssh.sh 192.168.1.100 root tank

# Parameters:
#   192.168.1.100  = Your TrueNAS IP address
#   root           = SSH username (default: root)
#   tank           = Pool name (default: tank)

That's it! The script will:

• ✓ Create the project directory
• ✓ Upload Docker configuration
• ✓ Configure environment variables
• ✓ Start all services
• ✓ Verify deployment

Access the UI

Once deployed, access the Agents UI at:

http://192.168.1.100:3000

---

Option 2: MCP Deployment (For Advanced Users)

If you have the TrueNAS MCP server running at mcp.wilddragon.net:

Setup

# 1. Install dependencies
pip install httpx

# 2. Make the script executable
chmod +x deploy-mcp.py

# 3. Deploy via MCP
export ANTHROPIC_API_KEY="sk-ant-your-actual-key-here"
python deploy-mcp.py --mcp-url https://mcp.wilddragon.net/mcp --pool tank

---

Option 3: Manual Docker Compose Deployment

For complete control:

Step 1: SSH into TrueNAS

ssh root@192.168.1.100

Step 2: Create project directory

mkdir -p /mnt/tank/docker/claude-code-stack
cd /mnt/tank/docker/claude-code-stack

Step 3: Copy docker-compose.yml

Create and edit the file:

cat > docker-compose.yml << 'EOF'
# Paste the content from docker-compose.yml
EOF

Step 4: Configure environment

cat > .env << 'EOF'
ANTHROPIC_API_KEY=sk-ant-your-key-here
POSTGRES_PASSWORD=secure-password
NODE_ENV=production
EOF

Step 5: Start services

docker-compose up -d

Step 6: Verify

docker-compose ps
curl http://localhost:3000

---

📊 Services Overview

What Gets Deployed

Service	Port	Purpose	Required
Agents UI	3000	Web interface for agent management	✓ Yes
Claude Code	5000	Code execution backend	✓ Yes
PostgreSQL	5432	Data persistence	Optional
Redis	6379	Caching & sessions	Optional
Nginx	80/443	Reverse proxy	Optional

---

🎮 Using the Stack

Access the UI

http://your-truenas-ip:3000

View Logs

# SSH into TrueNAS
ssh root@your-truenas-ip

# Navigate to project
cd /mnt/tank/docker/claude-code-stack

# View logs
docker-compose logs -f agents-ui
docker-compose logs -f claude-code-backend

Run Claude Code Directly

# Execute a prompt
docker-compose exec claude-code-backend claude "What files are in the workspace?"

# Access the CLI
docker-compose exec claude-code-backend bash

Stop Services

docker-compose down

Restart Services

docker-compose restart

---

🔧 Configuration

Environment Variables

Edit .env file to customize:

# Your Anthropic API key (REQUIRED)
ANTHROPIC_API_KEY=sk-ant-xxx

# Database password
POSTGRES_PASSWORD=secure-password

# Node environment
NODE_ENV=production

# Claude Code settings
CLAUDE_MODEL=claude-opus-4-1
RUN_CLAUDE_CODE=true

Port Changes

Want different ports? Edit docker-compose.yml:

ports:
  - "8000:3000"  # Access UI at port 8000 instead

Then restart:

docker-compose down && docker-compose up -d

---

🐛 Troubleshooting

Issue: "Connection refused" on port 3000

Solution:

# Check if service is running
docker-compose ps

# View logs
docker-compose logs agents-ui

# Restart
docker-compose restart agents-ui

# Wait a few seconds for startup
sleep 10
curl http://localhost:3000

Issue: API key not recognized

Solution:

# Verify .env file
cat .env | grep ANTHROPIC_API_KEY

# Update if needed
nano .env

# Restart services
docker-compose restart

Issue: Database connection fails

Solution:

# Check PostgreSQL
docker-compose logs postgres

# Verify credentials in .env
grep POSTGRES .env

# Restart database
docker-compose restart postgres

Issue: Cannot SSH to TrueNAS

Solution:

# Check IP address
ping your-truenas-ip

# Test SSH connection
ssh -v root@your-truenas-ip

# Check if SSH is enabled on TrueNAS
# System Settings > Services > SSH > Start Automatically

---

📈 Performance Tips

Increase Memory Allocation

Edit docker-compose.yml:

services:
  agents-ui:
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 1G

Enable Caching with Redis

Redis is included in the stack and automatically started.

Database Optimization

# Increase PostgreSQL connections
docker-compose exec postgres psql -U claude -c "ALTER SYSTEM SET max_connections = 200;"
docker-compose restart postgres

---

🔒 Security Recommendations

1. Change Default Passwords

# Edit .env
nano .env

# Change:
# POSTGRES_PASSWORD=changeMe123!
# SESSION_SECRET=your-random-secret

2. Enable SSL/TLS

Create self-signed certificate:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

Update docker-compose.yml to mount certs.

3. Restrict Network Access

In TrueNAS, configure firewall to allow only trusted IPs.

4. Regular Backups

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

# Backup database
docker-compose exec postgres pg_dump -U claude claude_agents > backup.sql

---

🎯 Next Steps

1. Access the UI: http://your-truenas-ip:3000
2. Configure API key: Check that ANTHROPIC_API_KEY is set
3. Create your first agent: Use the Agents UI to create and test agents
4. Set up workspace: Mount your projects in /workspace
5. Configure SSH keys: For git operations (optional)

---

📚 Resources

• Claude Code Agents UI: https://github.com/Ngxba/claude-code-agents-ui
• Claude Documentation: https://docs.anthropic.com/
• Docker Compose Reference: https://docs.docker.com/compose/compose-file/
• TrueNAS Documentation: https://www.truenas.com/docs/

---

💡 Common Commands

# View running services
docker-compose ps

# Follow logs
docker-compose logs -f

# Stop everything
docker-compose down

# Restart everything
docker-compose restart

# Execute command in container
docker-compose exec agents-ui command

# Access shell in container
docker-compose exec agents-ui sh

# Update and restart
docker-compose pull && docker-compose up -d

# Clean up disk space
docker system prune -a

---

🆘 Getting Help

If you encounter issues:

1. Check the logs: docker-compose logs -f
2. Verify configuration: cat .env
3. Check connectivity: docker-compose exec agents-ui ping -c 1 claude-code-backend
4. Review the full guide: See DEPLOYMENT_GUIDE.md

---

Deployed successfully? 🎉

Next, configure your agents:

1. Open http://your-truenas-ip:3000
2. Create a new agent
3. Set up your workspace
4. Start automating!

Happy coding! 🚀