Claude Code + Agents UI Stack

A self-hosted Docker stack that combines the claude-code-agents-ui frontend with the Claude Code CLI runtime, designed for TrueNAS SCALE deployment.

---

What's Included

File	Purpose
claude-agents-ui-Dockerfile	Multi-stage image: builds the Nuxt 3 UI + installs Claude Code CLI
claude-code-stack-docker-compose.yml	Orchestrates all services (UI, runtime, Postgres, Redis, Nginx)
claude-code-stack.env	Environment variable template — copy to .env before deploying
nginx.conf	Reverse-proxy config (SSL-ready)
deploy-ssh.sh	One-command SSH deployment to TrueNAS ⭐ recommended
deploy-mcp.py	MCP-based deployment (advanced)
QUICKSTART.md	5-minute setup guide
DEPLOYMENT_GUIDE.md	Full reference
CHECKLIST.md	Pre/post-deployment checklist

---

Quick Start

# 1. Set your Anthropic API key (get one at https://console.anthropic.com/)
export ANTHROPIC_API_KEY="sk-ant-..."

# 2. Deploy to TrueNAS
chmod +x deploy-ssh.sh
./deploy-ssh.sh 192.168.1.100 root tank

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

---

Authentication

Claude Code requires authentication to execute prompts. This stack implements non-interactive auth so no manual claude auth login step is needed.

How it works

1. You provide your ANTHROPIC_API_KEY in .env (or via environment variable).
2. The agents-ui container entrypoint writes ~/.claude/.credentials.json containing your API key on first start.
3. The Claude Code CLI reads this file and is ready to execute without any interactive login step.
4. The claude-code-backend container uses ANTHROPIC_API_KEY directly at runtime.

Manual auth (optional)

If you prefer OAuth-based login (tied to a Claude.ai subscription rather than pay-per-token API):

# SSH into TrueNAS
ssh root@192.168.1.100

# Run interactive login inside the container
cd /mnt/tank/docker/claude-code-stack
docker-compose exec agents-ui claude auth login

The credentials are stored in the claude-config Docker volume and persist across restarts.

Auth status check

docker-compose exec agents-ui claude auth status

---

Architecture

Your Browser
     │
     ▼
  Nginx :80/:443
     │
     ├──► Agents UI (Nuxt 3)  :3000  ──► ~/.claude/ volume
     │         │
     │         └──► Claude Code Backend  :5000
     │
     ├──► PostgreSQL  :5432
     └──► Redis       :6379

All services share two Docker volumes:

• claude-config — Claude credentials, agents, commands, skills, workflows
• workspace — Project files for agent execution

---

Configuration

Copy the env template and fill in your values:

cp claude-code-stack.env .env
nano .env  # Set ANTHROPIC_API_KEY and change POSTGRES_PASSWORD / SESSION_SECRET

Key variables

Variable	Required	Description
ANTHROPIC_API_KEY	Yes	Your Anthropic API key
CLAUDE_MODEL	No	Model to use (default: claude-sonnet-4-6)
POSTGRES_PASSWORD	Yes	Change from default before production
SESSION_SECRET	Yes	Random string — run openssl rand -base64 32

Available models: claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5-20251001

---

Deployment Methods

Method 1: SSH (recommended)

export ANTHROPIC_API_KEY="sk-ant-..."
./deploy-ssh.sh 192.168.1.100 root tank

The script:

• Validates prerequisites
• Tests SSH connectivity
• Creates project directory on TrueNAS
• Uploads all files
• Writes .env with auto-generated secrets
• Builds and starts all services
• Verifies Claude auth inside containers

Method 2: Manual

# SSH into TrueNAS
ssh root@192.168.1.100

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

# Upload files, then:
cp claude-code-stack.env .env
cp claude-code-stack-docker-compose.yml docker-compose.yml
cp claude-agents-ui-Dockerfile Dockerfile
nano .env  # Set your API key

docker-compose build
docker-compose up -d

Method 3: MCP

pip install httpx
python deploy-mcp.py --mcp-url https://mcp.wilddragon.net/mcp --pool tank

---

Useful Commands

# View all logs
docker-compose logs -f

# View just the UI logs
docker-compose logs -f agents-ui

# Check auth status
docker-compose exec agents-ui claude auth status

# Re-authenticate (interactive OAuth)
docker-compose exec agents-ui claude auth login

# Restart a service
docker-compose restart agents-ui

# Pull latest images
docker-compose pull && docker-compose up -d

# Stop everything
docker-compose down

# Stop and remove volumes (WARNING: deletes all data)
docker-compose down -v

---

Resource Requirements

Tier	RAM	CPU	Disk
Minimum	2 GB	2 cores	10 GB
Recommended	4 GB	4 cores	20 GB
Optimal	8 GB+	8+ cores	50 GB+

---

Security Notes

• Change POSTGRES_PASSWORD from the default before production
• Generate a proper SESSION_SECRET: openssl rand -base64 32
• The .env file is chmod 600 — never commit it to version control
• The claude-config volume contains your API credentials — back it up securely
• Consider restricting Nginx to internal network access only

---

Links

• Agents UI source
• Claude Code docs
• Anthropic console

---

Version: 1.1.0 | Updated: 2026-04-04 | Compatibility: TrueNAS SCALE, Docker Compose 3.8+