yoloai

# yoloAI

**Esecutore in sandbox per agenti di codifica AI. Nessuna stanchezza da permessi, nessuna credenziale nella sandbox, nessuna modifica al tuo progetto finché non le approvi.**

[![CI](https://github.com/kstenerud/yoloai/actions/workflows/ci.yml/badge.svg)](https://github.com/kstenerud/yoloai/actions/workflows/ci.yml)
[![Nightly Audit](https://github.com/kstenerud/yoloai/actions/workflows/audit.yml/badge.svg)](https://github.com/kstenerud/yoloai/actions/workflows/audit.yml)
[![Release](https://img.shields.io/github/v/release/kstenerud/yoloai)](https://github.com/kstenerud/yoloai/releases/latest)
[![Go Reference](https://pkg.go.dev/badge/github.com/kstenerud/yoloai.svg)](https://pkg.go.dev/github.com/kstenerud/yoloai)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Gli agenti di codifica AI funzionano al meglio con i blocchi di sicurezza disattivati, e questo è un modo terribile di eseguirli sulla tua macchina reale. yoloAI offre all'agente una sandbox usa e getta dove può modificare qualsiasi cosa ed eseguire qualsiasi cosa, senza supervisione. Il tuo progetto, le tue credenziali e la tua rete restano sotto il tuo controllo. Quando l'agente ha finito, esamina il diff e applica ciò che vuoi conservare.

```text
Tu                           Sandbox                        Il tuo progetto
 │                              │                                │
 ├─ yoloai new fix-bug .        ├─ copia del progetto in sandbox │
 │                              │                                │
 ├─ << i tuoi prompt >>         ├─ l'agente lavora liberamente   │
 │                              │  (nessuna richiesta di permessi)│
 │                              │                                │
 ├─ yoloai diff fix-bug         ├─ mostra cosa è cambiato         │
 │                              │                                │
 ├─ yoloai apply fix-bug        │                                ├─ patch applicate
 │  (scegli tu quali)           │                                │
 │                              │                                │
 ├─ yoloai destroy fix-bug      ├─ distrugge la sandbox           │
```

## Perché?

Le richieste di permesso esistono perché gli agenti commettono errori. Dopo la centesima approvazione/negazione smetti di leggerle, e `--dangerously-skip-permissions` è a un agente confuso di distanza da una giornata molto brutta. yoloAI riduce il raggio d'esplosione finché le richieste di permesso non sono più necessarie:

- **I tuoi file sono al sicuro.** L'agente lavora su una copia isolata del tuo progetto. `diff` mostra esattamente cosa è cambiato, `apply` applica le patch al tuo progetto reale preservando i singoli commit, e i tuoi originali non cambiano mai finché non applichi.
- **I tuoi segreti sono al sicuro.** La sandbox parte da un ambiente minimale, costruito localmente; le variabili d'ambiente dell'host restano sull'host. Le credenziali arrivano come mount di file in sola lettura, mai come variabili d'ambiente. Dove si applica il broker di credenziali (Claude, Gemini e Codex oggi, attivo di default), la chiave API resta interamente lato host: un proxy locale la inietta sulla strada verso il provider, quindi anche un agente completamente compromesso non ha nulla da esfiltrare.
- **La tua rete è tua.** `--network-isolated` limita il traffico in uscita agli endpoint API dell'agente più i domini che permetti. `--network-none` rimuove la rete completamente.
- **La tua macchina è isolata.** Scegli il tuo livello di comfort, dai namespace Linux attraverso gVisor fino alle VM hardware.

Vedi [Sicurezza](https://github.com/kstenerud/yoloai/blob/main/docs/GUIDE.md#security) per il modello completo, incluse le limitazioni oneste.

## Installazione

### Binario precompilato (consigliato)

Scarica l'archivio per la tua piattaforma dall'[ultima release](https://github.com/kstenerud/yoloai/releases/latest), estrai il binario `yoloai` e mettilo nel tuo `PATH`:

```bash
# Linux x86-64 (sostituisci con linux_arm64 / darwin_amd64 / darwin_arm64 se necessario).
# Imposta VERSION sul tag mostrato nella pagina dell'ultima release linkata sopra, senza
# la "v" iniziale — es. VERSION=1.2.3 per il tag v1.2.3.
VERSION=X.Y.Z
curl -fsSL "https://github.com/kstenerud/yoloai/releases/download/v${VERSION}/yoloai_${VERSION}_linux_amd64.tar.gz" \
  | tar -xz yoloai
sudo install yoloai /usr/local/bin/
```

Ogni archivio include anche i completamenti per la shell, la `LICENSE` e il changelog. Le release sono firmate con cosign (`checksums.txt`) e portano la provenienza di build GitHub (`gh attestation verify yoloai_… --repo kstenerud/yoloai`). Anche i pacchetti Debian/RPM sono allegati a ogni release.

### Homebrew (macOS / Linux)

```bash
brew install --cask kstenerud/tap/yoloai
```

### Usando `go install`

```bash
# Ultima release
go install github.com/kstenerud/yoloai/cmd/yoloai@latest

# Ultima versione di sviluppo (instabile)
go install github.com/kstenerud/yoloai/cmd/yoloai@main
```

Richiede Go 1.26+. Il binario viene posizionato in `$GOPATH/bin` (tipicamente `~/go/bin`).

### Dal sorgente

```bash
git clone https://github.com/kstenerud/yoloai.git
cd yoloai
git checkout "$(git describe --tags --abbrev=0)"   # tag dell'ultima release; oppure resta su main per la versione di sviluppo
make build
sudo install yoloai /usr/local/bin/
```

È un singolo binario Go senza dipendenze runtime oltre al backend che scegli. Al primo avvio, yoloAI costruisce la sua immagine base e crea `~/.yoloai/` (o la directory che indichi con `--data-dir`).

## Avvio rapido

### Non interattivo

```bash
# Autenticazione (yoloAI rileva automaticamente le credenziali esistenti)
export ANTHROPIC_API_KEY=sk-ant-...   # Claude Code
export GEMINI_API_KEY=...             # Gemini CLI
# Oppure lascia che rilevi la tua sessione già autenticata

# 1. Avvia una sandbox. L'agente inizia a lavorare immediatamente quando fornisci un prompt
yoloai new fix-bug ./my-project --prompt "correggi i test che falliscono"

# 2. Vedi cosa ha cambiato l'agente
yoloai diff fix-bug

# 3. Applica le parti buone al tuo progetto reale
yoloai apply fix-bug

# 4. Elimina la sandbox
yoloai destroy fix-bug
```

### Interattivo

```bash
yoloai new exploration ./my-project -a
# Sei dentro l'agente, in esecuzione in tmux nella sandbox.
#   Ctrl-B, D per scollegarti.
#   yoloai attach exploration per ricollegarti.
```

### Iterazione

Per sessioni più lunghe, lavora in un ciclo: di' all'agente di fare commit man mano che procede, ed esegui `yoloai apply` da un altro terminale ogni volta che vuoi portare i commit finiti nel tuo progetto reale. Ogni apply porta solo i nuovi commit dall'ultima volta. Quando sei soddisfatto del risultato, fai push come al solito e distruggi la sandbox. Vedi la [Guida all'uso](https://github.com/kstenerud/yoloai/blob/main/docs/GUIDE.md) per il flusso di lavoro completo.

## Demo

Creazione di una sandbox, invio del prompt all'agente e applicazione dei risultati:

https://github.com/user-attachments/assets/9d6740b4-a34e-4253-82ec-cb0e4c7a8bd9

## Funzionalità

**Sandboxing**

- Sei backend: Docker, Podman, containerd (Kata), Apple Container, Tart e Seatbelt. Funziona su Linux, macOS e Windows (WSL2).
- Forza di isolamento selezionabile per sandbox, da runc attraverso gVisor fino alle VM Kata (QEMU o Firecracker).
- Policy di rete per sandbox: aperta, allowlist o nessuna.
- Ambiente minimale dentro la sandbox. Qualsiasi cosa dall'host è un opt-in esplicito (`--env`, `--dir`).
- Limiti di risorse (`--cpus`, `--memory`) e port forwarding (`--port`).
- Copie economiche della workdir: cloni dell'intero albero su macOS (APFS `clonefile`), reflink per file su filesystem Linux che li supportano (btrfs, XFS). I filesystem senza reflink (ext4) ricevono una copia normale.
- `.gitignore` rispettato: qualsiasi cosa ignorata **NON** viene copiata nella sandbox (pratica di sicurezza per le credenziali di sviluppo su disco).

**Credenziali**

- Rileva automaticamente i tuoi login agent esistenti: chiavi API, credenziali di abbonamento, macOS Keychain.
- Il broker di credenziali mantiene la chiave API lato host (Claude, Gemini e Codex oggi); le credenziali di Aider e OpenCode vengono consegnate come mount di file in sola lettura.

**Flusso di lavoro**

- Copy/diff/apply con git eseguito lato sandbox, così i repository con filtri e hook si comportano correttamente.
- Applica a modo tuo: riproduci i commit (default), squash in una singola patch, esporta file `.patch`, seleziona commit per ref, oppure `--dry-run` prima.
- Ciclo di vita completo: create, attach, stop, restart, wait, clone, reset, destroy. Lo stato dell'agente sopravvive a stop e restart.
- One-shot headless per script e CI: `yoloai run --prompt ... --rm`, con output `--json` su ogni comando.
- Quando l'agente esce, il suo pannello tmux cade in una shell così puoi ispezionare la sandbox.

**Integrazione**

- Claude Code, Codex, Gemini CLI, Aider e OpenCode integrati, più una modalità `shell` per qualsiasi altra cosa.
- VS Code: collegati al container, oppure apri un Remote Tunnel dall'interno della sandbox (`--vscode-tunnel`).
- MCP in entrambe le direzioni: `yoloai mcp serve` permette a un agente esterno di pilotare le sandbox come strumenti; `yoloai mcp proxy` esegue server MCP dentro una sandbox.
- Profili: immagini e default per progetto (Dockerfile + config, con ereditarietà).
- Estensioni: aggiungi i tuoi sottocomandi come script shell avvolti in YAML (`yoloai x`).
- Incorporabile: la CLI è un sottile strato sopra una [API Go](https://pkg.go.dev/github.com/kstenerud/yoloai) pubblica.
- Singolo binario statico. Lo stato vive in `~/.yoloai/` (spostabile con `--data-dir`).

## Infrastruttura supportata

### Backend sandbox

| Backend    | Host supportati              | Dipendenze                                                       |
|------------|------------------------------|--------------------------------------------------------------------|
| docker     | Linux, macOS, Windows (WSL2) | [Docker Engine](https://docs.docker.com/engine/install), [Docker Desktop](https://docs.docker.com/get-docker), o [OrbStack](https://orbstack.dev) |
| podman     | Linux, macOS                 | [Podman](https://podman.io/get-started) (`brew install podman` su macOS) |
| containerd | Linux                        | [Kata Containers](https://katacontainers.io) |
| apple      | macOS (Apple Silicon)        | [Apple Container](https://github.com/apple/container) |
| tart       | macOS (Apple Silicon)        | [Tart](https://github.com/cirruslabs/tart) (`brew install cirruslabs/cli/tart`) |
| seatbelt   | macOS (qualsiasi)            | Nessuna (usa `sandbox-exec` integrato)                                |

**Nota**: Tart fornisce una VM macOS completa, permettendoti di eseguire simulatori dentro la sandbox.

### Modalità di isolamento

Opzionalmente aggiorna il runtime OCI per un isolamento più forte. Le modalità gVisor sono disponibili su docker e podman; le modalità VM arrivano con il backend containerd.

| Modalità | Descrizione |
|------|-------------|
| `container` | `runc` di default: namespace Linux standard e cgroups |
| `container-enhanced` | Kernel in userspace (gVisor/runsc): intercettazione delle syscall, nessun KVM necessario |
| `container-privileged` | Tutte le capability, seccomp/AppArmor non confinati. Usa per Docker-in-Docker e Compose |
| `vm` | Kata Containers (QEMU): isolamento con VM hardware |
| `vm-enhanced` | Kata + Firecracker microVM: isolamento con VM leggera |

```bash
# Usa gVisor per tutte le nuove sandbox
yoloai config set isolation container-enhanced

# Oppure per sandbox
yoloai new task . --isolation container-enhanced
```

### Agenti

| Modalità   | Descrizione |
|------------|-------------|
| `claude`   | Esegue [Claude Code](https://github.com/anthropics/claude-code) tramite chiave API o credenziali di abbonamento (default) |
| `codex`    | Esegue [Codex](https://github.com/openai/codex) tramite chiave API o credenziali di abbonamento |
| `gemini`   | Esegue [Gemini CLI](https://github.com/google-gemini/gemini-cli) tramite chiave API o credenziali di abbonamento |
| `aider`    | Esegue [Aider](https://github.com/Aider-AI/aider) (la tua configurazione viene copiata dentro) |
| `opencode` | Esegue [OpenCode](https://github.com/anomalyco/opencode) (la tua configurazione viene copiata dentro) |
| `shell`    | Esegue una shell tmux con tutte le credenziali dell'agente pre-caricate |
| `idle`     | Esegue un processo inattivo per consentire il proxying MCP |

Usa `yoloai system agents` per elencare gli agenti disponibili.

## Scopri di più

- **[Guida all'uso](https://github.com/kstenerud/yoloai/blob/main/docs/GUIDE.md)**: comandi, flag, modalità workdir, configurazione, sicurezza
- **[Roadmap](https://github.com/kstenerud/yoloai/blob/main/docs/ROADMAP.md)**: funzionalità in arrivo
- **[Architettura](https://github.com/kstenerud/yoloai/blob/main/docs/contributors/architecture/README.md)**: navigazione del codice per i contributori

## Stato

Beta pubblica. Il flusso di lavoro principale è stabile e usato quotidianamente; le interfacce possono ancora cambiare tra le release 0.x, e ogni modifica che rompe la compatibilità è documentata in [BREAKING-CHANGES](https://github.com/kstenerud/yoloai/blob/main/docs/BREAKING-CHANGES.md). [Il feedback è benvenuto.](https://github.com/kstenerud/yoloai/issues)

## Licenza

[MIT](https://github.com/kstenerud/yoloai/blob/main/LICENSE)