EmiBrain — Architettura e Stato Deploy

Overview

EmiBrain gira su un server Hetzner CAX21 (ARM64, 8GB RAM, 80GB SSD, Debian 12). Tutto in Docker CE 29.3 + Compose 5.1. Ogni utente ha il suo container workspace isolato.

┌─────────────────────────────────────────────────────────┐
│  Server Hetzner (178.104.48.34 / Tailscale 100.70.197.28) │
│                                                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │ emibrain-    │  │ emibrain-    │  │ emibrain-    │   │
│  │ nginx        │  │ php          │  │ admin        │   │
│  │ :80 → proxy  │  │ FPM :9000    │  │ :3100 webssh │   │
│  └──────┬───────┘  └──────────────┘  │ :8080 api    │   │
│         │                             └──────────────┘   │
│         │  ┌─────────────────────────────────────────┐   │
│         │  │         Workspace Containers             │   │
│         │  │  ws-giobi  ws-puddu  ws-bodini          │   │
│         │  │  ws-ricci  ws-franzini  ws-stagista     │   │
│         │  │  (Claude Code + tmux + brain)            │   │
│         │  └─────────────────────────────────────────┘   │
│         │                                                 │
│  ┌──────┴──────────────────────────────────────────────┐ │
│  │  /var/emibrain/                                      │ │
│  │  ├── brains/{slug}/     ← volume mount (rw)          │ │
│  │  ├── repos/{slug}.git   ← bare repos (backup)        │ │
│  │  ├── shared/            ← volume mount (ro)           │ │
│  │  ├── database.sqlite    ← Laravel DB                  │ │
│  │  └── docker/            ← build context               │ │
│  └──────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────┘

Container

Volume Mount

Dockerfile.workspace

L'immagine workspace include:

• Debian bookworm-slim + Python3, Node.js, git, tmux, curl, sqlite3
• Claude Code installato globalmente via npm
• SSH server (per accesso diretto via ssh brain@container)
• Brain template baked in /opt/emibrain/brain-template/
• Entrypoint che fa auto-bootstrap al primo avvio: crea boot/, wiki/, diary/, git init, primo commit

Architettura

Un server Node.js nel container emibrain-admin che fa da ponte tra il browser e i container workspace. Gestisce sessioni tmux via docker exec, serve file, e fornisce le API per il brain explorer.

Browser (xterm.js)
    │ WebSocket
    ▼
Nginx (:80)
    │ proxy_pass
    ▼
emibrain-admin:3100 (server.js)
    │ docker exec -it
    ▼
emibrain-ws-{slug} → tmux -L webssh attach-session

Endpoint HTTP

WebSocket

Il terminale nel browser usa xterm.js che si connette via WebSocket al server admin. Il server fa docker exec -it nel container workspace e attacca la sessione tmux. Il resize del terminale viene propagato via messaggio JSON {type: "resize", cols, rows}.

Auth: JWT

Ogni richiesta porta un JWT firmato con WEBSSH_SECRET. Il JWT contiene:

• user_id — ID utente Laravel
• workspace_uid — UUID del brain
• brain_slug — slug leggibile (usato per path filesystem)
• provider — docker, claude, gemini

Durata: 12 ore. Il frontend fa auto-refresh via endpoint Laravel /webssh/{brain}/refresh-token.

Auto-title sessioni

Quando l'endpoint /sessions viene chiamato, il server legge i file .claude/projects/-home-brain-workspace/*.jsonl nel container via docker exec python3, estrae il primo messaggio user come titolo. Mapping per ordine cronologico (sessione tmux piu recente = jsonl piu recente).

Il frontend fa polling ogni 30 secondi per aggiornare i titoli nella sidebar.

Tmux lockdown

La config tmux (webssh/tmux-webssh.conf) disabilita tutti i binding pericolosi:

• No split pane (unbind ", %)
• No nuove finestre (unbind c, n, p)
• No detach (unbind d, D)
• No right-click menu (unbind MouseDown3Pane)
• Mouse ON per scroll (scrollback tmux con rotella)

Routing

Public files

Ogni brain ha la cartella public/ servita via public.emibrain.it:

Architettura

Container workspace          Host (emibrain)              (futuro)
/home/brain/workspace/       /var/emibrain/repos/         GitHub
    git commit          ──→  {slug}.git (bare repo)  ──→  deploy key
                             cron ogni 5 min              (non ancora)

I container fanno solo git commit. Il push al bare repo avviene dall'host via cron ogni 5 minuti (/var/emibrain/scripts/brain-git-sync.sh). I container non vedono la directory /var/emibrain/repos/ — il push e esterno.

Stato bare repos

Cron script

/var/emibrain/scripts/brain-git-sync.sh — gira come root ogni 5 minuti. Per ogni brain:

• Compara HEAD del brain con il bare repo
• Se diversi, fa sudo -u emibrain git push local {branch}
• Log in /var/log/emibrain/git-sync.log

Flusso login

• Utente inserisce email su emibrain.it/login
• Laravel genera magic link (token SHA-256, scade 1h)
• Email inviata via [email protected] (Purelymail SMTP)
• Click sul link → sessione Laravel attiva
• Dashboard mostra i brain dell'utente
• Click su brain → genera JWT → apre WebSSH/Dchat

Whitelist

Solo email @emisfera.it possono registrarsi. [email protected] ha accesso admin a tutti i brain.

Template nel Docker image

L'immagine workspace contiene /opt/emibrain/brain-template/ con:

Auto-bootstrap (entrypoint)

Al primo avvio del container, workspace-entrypoint.sh:

• Crea directory structure: boot/, wiki/, diary/, todo/, inbox/, public/, storage/
• Copia template da /opt/emibrain/brain-template/
• Interpola local.yaml con BRAIN_USER e BRAIN_ROLE (env vars dal compose)
• Symlink domain.md → shared
• git init + primo commit automatico

local.yaml

Ogni brain ha un boot/local.yaml con:

• platform: container
• realm: emibrain
• role: user|admin|root
• public_url: https://public.emibrain.it/{slug}
• git.push: cron — il brain sa che non deve pushare

domain.md (shared)

File unico in /var/emibrain/shared/domain.md, montato read-only in tutti i container. Descrive:

• Cos'e EmiBrain e Emisfera
• Ruoli (admin/user)
• Che sei in un container Docker
• Come funziona public/ e git
• Cosa NON fare (sudo, apt-get, docker, file fuori workspace)

Funzionante

Da fare

D1: Brain su host, non in container

I dati del brain vivono su /var/emibrain/brains/{slug}/ e vengono montati nei container. Se il container muore, il brain sopravvive. Backup con strumenti standard (git, rsync, tar).

D2: WebSSH via docker exec, non SSH

Il server admin fa docker exec nei container workspace per attaccare le sessioni tmux. Non usa SSH tra container — meno overhead, meno config, meno superficie d'attacco.

D3: Git push esterno al container

I container non hanno credenziali git. Fanno solo commit. Un cron sull'host pusha ai bare repos ogni 5 minuti. Zero auth dentro i container, zero rischio di leak credenziali.

D4: Server webssh ibrido (312 → 608 righe)

Il server originale (312 righe, nell'immagine Docker del 18 marzo) gestiva solo sessioni tmux via docker exec. E stato esteso a 608 righe aggiungendo gli endpoint brain explorer e file explorer che leggono direttamente dal filesystem host (montato in /var/emibrain). Non usa il server ABChat da 1263 righe perche quello gestisce tmux sull'host, non via docker exec.

D5: Un branch per EmiBrain

EmiBrain usa il branch emibrain/docker-sessions del repo giobi/abchat. ABChat e Generations restano su main. Le modifiche specifiche EmiBrain (Docker mode, slug paths, tmux lockdown) non impattano gli altri realm.

Repo: giobi/abchat

Branch emibrain/docker-sessions

Sul server EmiBrain