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

```bash
# 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

```bash
# 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

```bash
ssh root@192.168.1.100
```

#### Step 2: Create project directory

```bash
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:
```bash
cat > docker-compose.yml << 'EOF'
# Paste the content from docker-compose.yml
EOF
```

#### Step 4: Configure environment

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

#### Step 5: Start services

```bash
docker-compose up -d
```

#### Step 6: Verify

```bash
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

```bash
# 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

```bash
# 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

```bash
docker-compose down
```

### Restart Services

```bash
docker-compose restart
```

---

## 🔧 Configuration

### Environment Variables

Edit `.env` file to customize:

```bash
# 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`:

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

Then restart:
```bash
docker-compose down && docker-compose up -d
```

---

## 🐛 Troubleshooting

### Issue: "Connection refused" on port 3000

**Solution:**
```bash
# 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:**
```bash
# Verify .env file
cat .env | grep ANTHROPIC_API_KEY

# Update if needed
nano .env

# Restart services
docker-compose restart
```

### Issue: Database connection fails

**Solution:**
```bash
# 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:**
```bash
# 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`:

```yaml
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

```bash
# 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

```bash
# Edit .env
nano .env

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

### 2. Enable SSL/TLS

Create self-signed certificate:
```bash
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

```bash
# 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

```bash
# 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! 🚀