WebVM

Questo repository contiene il codice sorgente per https://webvm.io, una macchina virtuale Linux che gira nel tuo browser.

Prova il nuovo ambiente grafico Alpine / Xorg / i3: https://webvm.io/alpine.html

Cos'è WebVM?

WebVM è un ambiente virtuale senza server che gira interamente lato client in HTML5/WebAssembly. È progettato per essere compatibile con l'ABI Linux ed esegue una distribuzione Debian non modificata, inclusi molti toolchain di sviluppo nativi.

WebVM è alimentato dal motore di virtualizzazione CheerpX, che fornisce:

• Compilatore JIT x86-to-WebAssembly
• Filesystem virtuale a blocchi
• Emulatore di syscall Linux
• Esecuzione sicura e sandboxed lato client

Indice dei contenuti

• Rete
• Sviluppo e personalizzazione
  • Distribuisci su GitHub Pages
  • Servizio locale e configurazione dell'immagine
• Integrazione con Claude AI
• Community e supporto
• Scopri di più
• Licenza

[!NOTE] Visita https://webvm.io per iniziare immediatamente nel tuo browser. Nessuna configurazione richiesta.

Per configurazione locale, build personalizzate di immagini e indicazioni su fork/deploy, consulta Sviluppo e personalizzazione.

Rete

WebVM supporta l'integrazione con Tailscale. In questo modo la VM del tuo browser può raggiungere la tua rete privata e, con un nodo di uscita, anche internet pubblico.

[!NOTE] Alcune operazioni di rete di basso livello (in particolare ICMP usato da ping) non sono attualmente disponibili in questo ambiente. Per i controlli di connettività, usa curl o wget.

Rete locale

1. Apri il pannello "Rete" dalla barra laterale
2. Clicca su "Connetti a Tailscale"
3. Accedi (crea un account gratuito su tailscale.com se necessario)
4. Clicca su "Connetti" quando richiesto

WebVM ora ha accesso a tutte le macchine nella tua rete Tailscale!

Suggerimenti per l'uso di Internet

[!TIP] Su connessioni più lente potrebbe esserci un breve ritardo prima dell'inizializzazione. Lo stato della connessione è mostrato come un punto colorato sul pulsante: arancione = rete locale, verde = internet globale. Il testo del pulsante mostra il tuo indirizzo IP Tailscale una volta connesso.

Per accedere a internet pubblico da WebVM, configura un Nodo di uscita su un altro dispositivo nella tua rete Tailscale:

1. Segui la guida rapida per i nodi di uscita di Tailscale (sezioni: "Advertise a device as an exit node")
2. WebVM utilizza automaticamente il nodo di uscita una volta pubblicizzato

Utilizzo di una chiave di autenticazione

In alternativa al login interattivo, aggiungi la tua chiave di autenticazione Tailscale al frammento dell'URL:

https://webvm.io/#authKey=<your-ephemeral-key>

Questo è equivalente all'opzione --login-server di Tailscale.

[!TIP] Se hai anche bisogno di un server di controllo personalizzato, aggiungi controlUrl nello stesso frammento dell'URL e separa i valori con &, ad esempio: #authKey=...&controlUrl=....

Self-Hosting di Tailscale con Headscale

Supportiamo anche headscale, un'implementazione open source self-hosted del server di controllo Tailscale. Poiché Headscale non aggiunge intestazioni CORS per impostazione predefinita, avrai bisogno di un proxy davanti a esso. Vedi la documentazione di Headscale per la configurazione del proxy inverso per un esempio.

Una volta pronto, aggiungi la seguente riga al tuo blocco location / nel file di configurazione nginx.

if ($http_origin = "https://yourdomain.com") {
    add_header 'Access-Control-Allow-Origin' "$http_origin";
    add_header 'Access-Control-Allow-Credentials' 'true' always;
}

Poi accedi a WebVM con:

https://yourdomain.com/#controlUrl=<your-headscale-url>

Sviluppo e personalizzazione

[!NOTE] Gli utenti hanno privilegi di root per impostazione predefinita. sudo non è installato, ma può essere facilmente aggiunto al Dockerfile se necessario.

Distribuisci su GitHub Pages

Questo è un flusso di lavoro semplice e adatto ai principianti. Per l'hosting locale e la personalizzazione, vedi sotto Servizio locale e configurazione dell'immagine.

Forka il repository di WebVM per distribuire la tua versione su GitHub Pages:

1. Forka il repository
2. Abilita GitHub Pages dal repository forked in Impostazioni → Pages usando "GitHub Actions" come sorgente
3. Esegui il workflow Deploy dalle Actions
4. Al termine, apri l'URL mostrato nel job deploy_to_github_pages

Lo stesso workflow Deploy costruisce anche immagini disco .ext2 personalizzate da un Dockerfile. Puoi puntarlo a dockerfiles/debian_mini o a un altro Dockerfile, quindi pubblicare il risultato come asset di Release su GitHub o distribuire la build Pages dal tuo fork.

[!NOTE] dockerfiles/debian_large è un'immagine troppo grande per GitHub Pages.

Servizio locale e configurazione dell'immagine

1. Clona il repository

git clone https://github.com/leaningtech/webvm.git
cd webvm

2. Metti la tua immagine in custom-disk-images/

Questo repository include una directory persistente custom-disk-images/ per file .ext2 locali.

Per usare l'immagine Debian mini ufficiale, scaricala dalle Release:

debian_mini_20230519_5022088024.ext2

Puoi anche copiare un'immagine che hai costruito tu stesso.

3. Punta WebVM alla tua immagine locale

Modifica config_public_terminal.js:

export const diskImageUrl =
  "/custom-disk-images/debian_mini_20230519_5022088024.ext2";
export const diskImageType = "bytes";

4. Installa le dipendenze e costruisci

npm install
npm run build

5. Avvia Nginx e apri WebVM

nginx -p . -c nginx.conf

Poi apri http://127.0.0.1:8081 e goditi la tua WebVM locale!

Per l'ambiente desktop Alpine completo, vedi leaningtech/alpine-image.

Per maggiori dettagli, vedi Documentazione immagini personalizzate CheerpX.

[!TIP] Per un REPL Python3, il workflow Deploy tiene conto del CMD specificato nel Dockerfile.

Per costruire un REPL puoi semplicemente cambiare CMD [ "/bin/bash" ] in CMD [ "/usr/bin/python3" ] e distribuire.

Integrazione con Claude AI

Per accedere a Claude AI, hai bisogno di una chiave API. Segui questi passaggi per iniziare:

1. Crea un account

• Visita Anthropic Console e registrati con la tua email. Riceverai un link di accesso alla Console Anthropic.

2. Ottieni la tua chiave API