# 🖥️ TrueNAS SCALE AI Workspace

> **code-server + OmniRoute + Claude Code** — полноценное AI-окружение разработчика прямо в браузере, развёрнутое на домашнем сервере TrueNAS SCALE.

---

## 📋 Содержание

1. [О проекте](#о-проекте)
2. [Архитектура стека](#архитектура-стека)
3. [Требования](#требования)
4. [Подготовка системы](#1-подготовка-системы-shell-truenas)
5. [Развёртывание контейнеров](#2-развёртывание-custom-app--docker-compose)
6. [Установка Claude Code](#3-установка-claude-code)
7. [Настройка OmniRoute + Kiro AI](#4-настройка-omniroute--kiro-ai)
8. [Решение проблемы Ambiguous model](#5-решение-проблемы-ambiguous-model)
9. [Удобные алиасы](#6-удобные-алиасы)
10. [Полезные команды Claude Code](#7-полезные-команды-claude-code)
11. [Устранение неполадок](#8-устранение-неполадок)

---

## О проекте

Этот проект предоставляет готовую конфигурацию для развёртывания AI-окружения на **TrueNAS SCALE 24.x (Electric Eel) и новее**.

**Что получите в итоге:**
- 🌐 VS Code в браузере (code-server) на порту `18443`
- 🔀 Единый API-шлюз OmniRoute для управления ключами на порту `20128`
- 🤖 Claude Code CLI, работающий через локальный прокси (без прямых трат на Anthropic API)
- 💾 Доступ к файлам всех приложений прямо из редактора

---

## Архитектура стека

```
Браузер
  │
  ▼
code-server (VS Code) :18443
  │  терминал
  ▼
Claude Code CLI
  │  ANTHROPIC_BASE_URL
  ▼
OmniRoute (локальный шлюз) :20128
  │  model mapping
  ▼
Kiro AI / Anthropic API
```

---

## Требования

| Компонент | Версия |
|-----------|--------|
| TrueNAS SCALE | Electric Eel 24.x+ |
| Docker (встроенный) | любая |
| Пул хранилища | `/mnt/ssd` (замените на свой) |
| UID пользователя apps | `568` |

---

## 1. Подготовка системы (Shell TrueNAS)

> ⚠️ **Критично:** Выполняйте из Shell TrueNAS, а не из контейнера. Права `568:568` обязательны — без них контейнеры не смогут писать в тома.

```bash
# Создание директорий на пуле хранилища
mkdir -p /mnt/ssd/apps/vscode/config \
         /mnt/ssd/apps/vscode/workspace \
         /mnt/ssd/apps/omniroute

# Настройка прав доступа (рекурсивно)
chown -R 568:568 /mnt/ssd/apps
chmod -R 775 /mnt/ssd/apps
```

---

## 2. Развёртывание (Custom App / Docker Compose)

Используйте этот YAML при создании **Custom App** в интерфейсе TrueNAS SCALE:

```yaml
services:

  code-server:
    image: lscr.io/linuxserver/code-server:latest
    container_name: code-server
    environment:
      - PUID=568
      - PGID=568
      - TZ=Europe/Moscow
      - PASSWORD=your_password_here       # Пароль для входа в VS Code
    volumes:
      - /mnt/ssd/apps/vscode/config:/config
      - /mnt/ssd/apps/vscode/workspace:/config/workspace
      - /mnt/ssd/apps:/mnt/ssd/apps       # Доступ к конфигам других приложений
    ports:
      - 18443:8443
    restart: unless-stopped

  omniroute:
    image: diegosouzapw/omniroute:latest
    container_name: omniroute
    environment:
      - PUID=568
      - PGID=568
      - PORT=20128
      - GEMINI_OAUTH_CLIENT_SECRET=not_used   # Заглушка (если не используете Gemini)
      - GEMINI_OAUTH_CLIENT_ID=not_used
    volumes:
      - /mnt/ssd/apps/omniroute:/app/data
    ports:
      - 20128:20128
    restart: unless-stopped
```

---

## 3. Установка Claude Code

> 💡 Используем `docker exec -u 0` для установки от root — это надёжнее, чем sudo внутри контейнера.

Выполните из **Shell TrueNAS** (не из терминала VS Code):

```bash
# Установка Node.js и Claude Code
docker exec -u 0 -it code-server bash -c \
  "apt update && apt install -y nodejs npm && npm install -g @anthropic-ai/claude-code"

# Настройка PATH и прокси OmniRoute
docker exec -u 0 -it code-server bash -c \
  "echo 'export PATH=\$PATH:/usr/local/bin' >> /config/.bashrc"

docker exec -u 0 -it code-server bash -c \
  "echo 'export ANTHROPIC_BASE_URL=\"http://192.168.31.100:20128/v1\"' >> /config/.bashrc"

# Создание системной ссылки (чтобы claude был доступен для всех пользователей)
docker exec -u 0 -it code-server \
  ln -s /usr/local/bin/claude /usr/bin/claude
```

Затем в **терминале VS Code** примените настройки:

```bash
source /config/.bashrc
claude   # запуск агента
```

---

## 4. Настройка OmniRoute + Kiro AI

1. Откройте **OmniRoute Dashboard**: `http://<IP_ВАШЕГО_СЕРВЕРА>:20128`
2. Перейдите в раздел **Providers** → добавьте провайдера **Kiro AI** (тип: Custom OpenAI)
3. Укажите Base URL и API-ключ из вашего кабинета Kiro
4. В настройках провайдера добавьте **Model Mapping**:

   | Inbound (что запрашивает Claude) | Outbound (имя в Kiro) |
   |-----------------------------------|-----------------------|
   | `claude-sonnet-4-6`               | `claude-sonnet-4.5`   |
   | `claude-haiku-4-5`                | `claude-haiku-4.5`    |

5. Установите Kiro как **провайдера по умолчанию** для семейства Claude

---

## 5. Решение проблемы "Ambiguous model"

### Симптом

```
API Error: 400 {"error":{"message":"Ambiguous model 'claude-sonnet-4-6'.
Use provider/model prefix (ex: cc/claude-sonnet-4-6 or antigravity/claude-sonnet-4-6)."}}
```

### Причина

OmniRoute видит несколько провайдеров для одной модели и не знает, какой выбрать.

### Решение A — Быстрое (разово, через флаг)

```bash
claude --model kr/claude-sonnet-4-6
# или
claude --model kiro/claude-sonnet-4-6
# (используйте тот префикс, который вы задали провайдеру в Dashboard)
```

### Решение B — Постоянное (через Dashboard OmniRoute)

1. `http://<IP>:20128` → Providers → Kiro AI
2. Раздел **Model Mapping** → добавить правило (см. таблицу выше)
3. Установить Kiro как **Default** для Claude-моделей

### Решение C — Через алиас в `.bashrc`

```bash
echo "alias claude='claude --model kr/claude-sonnet-4.5'" >> /config/.bashrc
source /config/.bashrc
```

---

## 6. Удобные алиасы

Добавьте в терминале VS Code:

```bash
cat >> /config/.bashrc << 'EOF'

# Claude Code — быстрое переключение моделей
alias c4s='claude --model kr/claude-sonnet-4.5'   # Мощная модель (Sonnet)
alias c4h='claude --model kr/claude-haiku-4.5'    # Быстрая модель (Haiku)
alias c='claude --model kr/claude-sonnet-4.5'     # Краткий алиас
EOF

source /config/.bashrc
```

**Использование:**
```bash
c4s   # запустить Claude Sonnet (сложные задачи)
c4h   # запустить Claude Haiku (быстрые вопросы)
```

---

## 7. Полезные команды Claude Code

| Команда | Описание |
|---------|----------|
| `/init` | Индексация текущего проекта |
| `/terminal-setup` | Оптимизация горячих клавиш терминала |
| `/help` | Список всех команд |
| `Shift+Enter` | Перенос строки в промпте |
| `Esc` | Прерывание выполнения |
| `exit` | Выход из агента |

---

## 8. Устранение неполадок

### Claude не находит API

```bash
# Проверьте переменную окружения
echo $ANTHROPIC_BASE_URL
# Должно быть: http://192.168.31.100:20128/v1

# Если пусто — примените профиль
source /config/.bashrc
```

### Проверка логов OmniRoute

```bash
# Из Shell TrueNAS
docker logs omniroute -f --tail=50
```

Или через Dashboard: `http://<IP>:20128` → вкладка **Logs**.

### Права доступа к файлам

```bash
# Из Shell TrueNAS — сброс прав если что-то пошло не так
chown -R 568:568 /mnt/ssd/apps
chmod -R 775 /mnt/ssd/apps
```

### Переустановка Claude Code

```bash
docker exec -u 0 -it code-server bash -c \
  "npm uninstall -g @anthropic-ai/claude-code && npm install -g @anthropic-ai/claude-code"
```

---

## Авторы

Проект подготовлен **Анатолием** на основе реального опыта развёртывания.  
Публикуется для сообщества разработчиков на TrueNAS SCALE.

---

> 💬 Нашли ошибку или есть улучшение? Открывайте Issue или Pull Request!