claude-code-stack/README.md

# Claude Code + Agents UI Stack

A self-hosted Docker stack that combines the [claude-code-agents-ui](https://github.com/Ngxba/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

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

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

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

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

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

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

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

---

## Useful Commands

```bash
# 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](https://github.com/Ngxba/claude-code-agents-ui)
- [Claude Code docs](https://docs.anthropic.com/en/docs/claude-code)
- [Anthropic console](https://console.anthropic.com/)

---

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