Come funziona ElephantPool

1. La forma del sistema

Tre parti, un solo contratto fra loro.

L'host interroga verso l'esterno; nulla si connette verso di lui. Quella sola decisione spiega perché una GPU dietro un router di casa funziona senza alcuna configurazione, e perché un host non espone mai una porta a Internet.

2. Cosa succede a una richiesta

1. La tua chiamata arriva al gateway con una chiave API. Verifichiamo la chiave, stimiamo il costo, e confermiamo che saldo prepagato e tetto di spesa lo coprano.
2. Il job viene accodato per il modello richiesto. Porta i tuoi messaggi e nulla su di te.
3. Un host lo reclama — uno che ha dimostrato, con un benchmark su quella macchina, di poter servire quel modello.
4. La GPU produce token, trasmessi a te attraverso il gateway man mano che nascono.
5. Il job viene liquidato. I token sono contati, il tuo saldo addebitato al micro-centesimo, l'host accreditato dell'80%, e il prompt sparisce dal registro. Restano conteggi e timestamp — niente testo.
6. L'host firma una ricevuta con una chiave che non lascia mai la sua macchina: modello, build esatta, conteggi, tempi.

I prompt vivono in memoria per la durata del job. Non vengono scritti su disco, non registrati e non usati per l'addestramento — né da noi né dagli host.

3. mahout — l'agente sull'host

mahout è un unico binario Rust open source di circa 5 MB, chiamato come la persona che guida l'elefante. Gira come utente normale, non serve root, e fa sei cose:

• Sonda la macchina — CPU, RAM, GPU e la loro VRAM.
• Si registra con un codice monouso dal pannello, generando in locale un'identità ed25519; la chiave privata non lascia mai la macchina.
• Scarica e verifica pesi e motore in una cache indirizzata per contenuto — contro impronte SHA-256 fissate, durante il download e a ogni caricamento.
• Supervisiona il motore: lo avvia, ne controlla la salute, lo riavvia una volta se muore, lo ferma in modo pulito.
• Interroga e serve job, trasmettendo token a lotti.
• Firma una ricevuta per job, aggiunta a un registro locale che puoi riverificare offline con mahout receipts verify.

Si mette in pausa da solo mentre usi la macchina, e mahout uninstall mostra un piano di cancellazione prima di rimuovere qualsiasi cosa. Sorgente e installer sono pubblici.

4. I modelli sono build, non file

Un modello è ciò che un cliente chiede (qwen3.8-27b). Una build è un artefatto concreto: una quantizzazione, un motore, un file esatto di una revisione upstream esatta, con lo SHA-256 pubblicato.

Quella separazione è ciò che permette a un modello di raggiungere ogni classe di GPU. Qwen3.8 27B arriva in cinque build, dal Q5_K_M per una scheda da 24 GB all'IQ2_XXS per una da 8 GB. La richiesta del cliente non cambia mai; l'host sceglie la build che la sua scheda può davvero far girare.

Una build diventa reclamabile su una macchina solo dopo che quella macchina l'ha caricata e misurata. Le stime decidono cosa vale la pena scaricare; le misure decidono cosa vale la pena instradare.

5. I motori — e la questione dei container

mahout non fa i calcoli da solo. Guida un motore di inferenza, e il motore appartiene alla build, non all'host — è ciò che rende un nuovo motore un'aggiunta invece di una riscrittura.

Quindi, quali sono le immagini, esattamente?

Oggi, su una macchina host: nessuna. Niente immagine Docker da tirare, niente daemon da installare, niente root da concedere. Un binario da 5 MB e un file di modello verificato via checksum sono l'intera impronta. Crediamo sia la forma giusta per un PC da gaming in salotto, e non abbiamo voluto fingere altro per suonare cloud-native.

I container contano all'altro capo del mercato. Quando arriverà il livello vLLM, le immagini dei motori saranno immagini upstream riferite per digest — vllm/vllm-openai@sha256:…, non un tag mobile — e l'elenco delle immagini che un host può far girare è compilato nella release stessa di mahout. Il piano di controllo può dire alla tua macchina quale immagine consentita avviare; non può mai introdurne una nuova. Il container non ha uscita di rete e un mount in sola lettura dei pesi verificati.

Tre regole governano quel livello, le stesse che governano i pesi:

• Fissato per digest. Un digest è immutabile e verificato dal runtime; un tag è una promessa che qualcun altro può cambiare.
• In lista bianca nel client. Un host esegue ciò che il suo binario permette, non ciò che chiede un server.
• Opt-in per host. Nessuno si sveglia ospitando un motore nuovo.

E il registry?

Per i motori upstream non ospitiamo immagini — replicare un'immagine pubblica aggiunge terabyte di storage e zero sicurezza, perché il digest prova già cosa hai ricevuto. Gestiamo un registry nostro per esattamente un caso: immagini che noi costruiamo. La prima è il hook di verifica — una build del motore che emette un impegno crittografico sulle proprie attivazioni, così l'output di un job può essere controllato invece che creduto. Quell'immagine deve essere nostra: sarà pubblicata dal nostro registry europeo, firmata e fissata per digest come tutto il resto.

In breve: oggi nessuna immagine sugli host; immagini upstream fissate per digest quando arriverà il livello vLLM; registry nostro solo per le immagini che produciamo noi.

6. Cosa viene verificato, e da chi

Un controllo fallito non è un avviso: l'artefatto viene scartato e il job non gira. Preferiamo che un host non serva nulla piuttosto che qualcosa che non sappiamo nominare con esattezza.

7. I soldi

I clienti pagano per token, in euro, per modello, senza abbonamento e senza minimo: ricarichi un saldo prepagato, e ogni chiave API porta un tetto di spesa perché un loop impazzito non possa svuotarlo. Gli host ricevono l'80% dei ricavi dei job che servono, con bonifico SEPA da 50 €.

Il pannello esprime i guadagni di un host in euro per ora di servizio, calcolati dalla velocità di decodifica misurata dalla sua stessa scheda — mai una proiezione, e mai una cifra mensile, perché significherebbe promettere una domanda che non possiamo promettere.

8. Dove siamo onesti sui limiti

• Il motore gira oggi come processo figlio senza privilegi legato a localhost, non in una sandbox di syscall. L'indurimento (seccomp, Landlock, container senza egress) è pianificato e non ancora fatto.
• Linux e Windows x86_64 sono le sole piattaforme host pubblicate. macOS è portabile in linea di principio e non consegnato in pratica.
• La verifica dell'output (impegni sulle attivazioni) è progettata e non ancora imposta; le garanzie di oggi sono ricevute e reputazione.

La specifica tecnica distingue ovunque ciò che gira oggi da ciò che è progettato. L'AGENTS.md di mahout, nel repository pubblico, fa lo stesso.