SuperHQ

Cos'è SuperHQ?

SuperHQ esegue agenti di codifica AI all'interno di “sandbox reali” isolate, così gli agenti possono lavorare in un ambiente controllato invece che direttamente sulla tua macchina locale. Orchestra Claude Code, OpenAI Codex e agenti personalizzati, ciascuno nella propria microVM.

Lo scopo principale è aiutarti a eseguire in sicurezza modifiche al codice guidate da agenti: il tuo progetto viene montato nella sandbox (in /workspace), le modifiche sono catturate in un overlay fino alla tua approvazione, e puoi ispezionare una revisione di diff unificato prima che tocchi i file locali.

Caratteristiche Principali

• Isolamento microVM per agente: Ogni agente Claude Code, Codex e personalizzato gira nella propria microVM, mantenendo il workspace contenuto.
• Completo userland Linux tramite VM Debian: La sandbox è una VM Debian con tool di pacchetti come apt, più npm e pip, così l'agente ha ciò che serve per installare e eseguire dipendenze.
• Workspace progetto montato in /workspace: Il tuo progetto è montato nella sandbox; le modifiche dell'agente puntano a questo percorso montato.
• Modifiche overlay con gate di approvazione: Le modifiche fatte nella VM rimangono in un overlay fino all'approvazione nel pannello di revisione.
• Revisione diff unificato prima dell'applicazione locale: Puoi vedere un diff unificato di ciò che ha cambiato l'agente e scegliere cosa tenere o scartare.
• Port forwarding opt-in: Le porte possono essere inoltrate dalla sandbox all'host solo quando le abiliti (utile per server dev, database e API).
• Checkpoint e rewind: Puoi fermare e fare checkpoint dello stato VM e riprendere dopo; puoi anche forkare un checkpoint per creare un nuovo branch.

Come Usare SuperHQ

1. Installa SuperHQ su macOS usando i comandi Homebrew forniti (brew tap superhq-ai/tap e brew install --cask superhq).
2. Crea un nuovo workspace per il tuo progetto (l'UI indica la creazione del workspace e il rapido switch tramite shortcut da tastiera).
3. Avvia un agente (l'interfaccia elenca Claude Code, OpenAI Codex e supporto per agenti personalizzati) per eseguire task di codifica nella sandbox.
4. Rivedi le modifiche nel pannello di revisione: ispeziona il diff unificato e approva o scarta le modifiche prima che vengano applicate ai tuoi file locali.
5. Usa i controlli sandbox di supporto se necessario: abilita il port forwarding solo quando hai bisogno di accedere a un servizio in esecuzione nella VM, e fai checkpoint se vuoi mettere in pausa/riprendere o forkare un branch pulito.

Casi d'Uso

• Refactor sicuri guidati da agenti per un repo locale: Esegui un agente per modificare codice in una VM Debian isolata, rivedi il diff unificato e approva solo le parti che vuoi applicare al tuo progetto locale.
• Task con dipendenze pesanti senza inquinare la tua macchina: Lascia che l'agente installi ed esegua tool usando l'userland Debian della sandbox (apt, npm, pip) invece di installare pacchetti direttamente sull'host.
• Debug con server dev temporanei: Abilita il port forwarding opt-in per accedere a servizi (ad esempio, un server dev o API) in esecuzione nella sandbox mentre ispezioni il comportamento.
• Esperimenti iterativi con checkpoint: Fai checkpoint di uno stato workspace, prova un approccio, poi rewind o fork del checkpoint per creare un nuovo branch per una direzione diversa.
• Esecuzione workflow personalizzati con agenti custom: Usa l'opzione “custom agents” quando hai un setup agente oltre Claude Code o Codex, mantenendo comunque l'esecuzione in sandbox microVM per agente.

FAQ

• Cosa isola SuperHQ? Ogni esecuzione agente (Claude Code, Codex o agente personalizzato) avviene nella propria sandbox microVM.

• Dove risiede il mio progetto durante le esecuzioni agente? Il tuo progetto è montato nella sandbox in /workspace.

• Come vengono applicate le modifiche ai miei file locali? Le modifiche dell'agente sono tenute in un overlay fino all'approvazione nel pannello di revisione. Viene mostrato un diff unificato così puoi tenere o scartare le modifiche prima che tocchino i file locali.

• La sandbox può esporre servizi all'host? Sì, ma il port forwarding è opt-in, abilitato solo quando scegli di esporre porte dalla sandbox all'host.

• Come funzionano i checkpoint? Puoi fermare un workspace e fare checkpoint dello stato completo VM, riprendere dopo in secondi, e forkare un checkpoint per iniziare un branch fresco.

Alternative

• Workflow locali degli agenti (esecuzione diretta degli agenti sulla tua macchina): Sono più semplici ma generalmente mancano dell'isolamento microVM descritto, del gating di approvazione e del modello overlay sandbox.
• Ambienti di sviluppo containerizzati (es. setup agenti basati su Docker): I container possono isolare dipendenze e tooling, ma il flusso overlay-approval specifico e il comportamento checkpoint/rewind microVM potrebbero differire.
• Sandbox remoti o piattaforme di esecuzione codice hosted: Possono fornire isolamento, ma workflow e modalità di revisione/applicazione cambiamenti codice possono variare rispetto al mount progetto locale di SuperHQ su /workspace con approvazione diff unificata.
• Assistenti AI coding integrati in IDE senza sandboxing: Si concentrano sull'assistenza coding in-editor; potrebbero non fornire isolamento VM per agente, revisione diff prima dell'applicazione su file locali o port forwarding opt-in legato a runtime sandbox.