SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor

Browser headless per agenti AI su un VPS

Chromium headless su un VPS può fallire per /dev/shm ridotto, flag sandbox, font mancanti e processi residui. Imposta i limiti prima dell'agente.

Cosa state eseguendo

Un browser headless su un VPS è Chromium senza interfaccia grafica, controllato dal vostro codice invece che da una persona. Su un server è un albero di processi persistente con cui il vostro agent comunica tramite un socket locale. L'installazione richiede un solo comando. Il lavoro consiste in tutto ciò che viene dopo. Dovete limitare le risorse che il browser può consumare dalla macchina e mantenere il suo endpoint di controllo non accessibile da Internet.

Questa guida presuppone che la scelta dello strumento sia già stata effettuata e che ora dobbiate gestirlo. Se state ancora confrontando crawler ed estrattori, iniziate dalle alternative self-hosted a Firecrawl e tornate qui. Tutto ciò che segue usa Chromium tramite Playwright, perché Playwright distribuisce una propria build del browser e un proprio installer delle dipendenze. Gli stessi comandi funzionano quindi su un VPS Ubuntu senza componenti preinstallati e all'interno di un container. I comandi fissano Playwright alla versione 1.62.

Installa Chromium senza indovinare le dipendenze

npm i -D playwright@1.62.0
npx playwright install --with-deps chromium

--with-deps esegue apt per le librerie condivise e i font necessari a Chromium e richiede l'accesso a root quando necessario. La build del browser viene scaricata in ~/.cache/ms-playwright per l'utente che ha eseguito il comando. Questo è importante su un server, perché l'utente del servizio di solito non coincide con l'utente con cui effettui il login. Installa una volta i pacchetti di sistema come amministratore usando sudo npx playwright install-deps chromium, quindi imposta PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers sia nel comando di installazione sia nell'unità del servizio, in modo da condividere una sola copia. Se un servizio non riesce ad accedere al browser, l'avvio fallisce con un messaggio che indica il percorso cercato.

Blocca la versione di Playwright. Ogni release è associata a una build specifica del browser, quindi un npm update senza versione bloccata può sostituire il browser mentre un servizio è in esecuzione. Al 16 novembre 2026, l'ultima release è la 1.65.1: consulta quindi le note di rilascio prima di modificare il blocco della versione. Sui server ARM64, considera che la versione 1.63 ha rinominato le directory dei browser; questo è importante per il profilo AppArmor descritto più avanti.

Esistono due build di Chromium e non sono lo stesso programma. In modalità headless, Playwright usa per impostazione predefinita la headless shell, un binario più piccolo che funziona solo in modalità headless. Un'installazione standard la scarica accanto al browser completo, mentre npx playwright install --with-deps --only-shell installa soltanto la shell. Il browser completo è quello ottenuto con il canale chromium, che la documentazione sui browser di Playwright definisce «il vero browser Chrome, quindi più autentico, affidabile e dotato di più funzionalità». Usa la shell per i download massivi. Usa il browser completo quando un sito si comporta in modo diverso e devi determinarne il motivo.

Perché un browser headless si arresta in modo anomalo in un container

Docker assegna a ogni container un /dev/shm di 64 MB. La documentazione di Docker è esplicita: «Se si omette completamente la dimensione, il sistema usa 64m». Chromium trasferisce il contenuto renderizzato tra i propri processi tramite quell’area di memoria condivisa, quindi una sola pagina complessa può riempirla. Il processo renderer termina e il client segnala che il target si è arrestato, anche se la stessa pagina funziona correttamente sul laptop. Verificare la dimensione dall’interno del container prima di modificare la configurazione.

df -h /dev/shm

Esistono due correzioni effettive. Sono alternative, non complementari. --ipc=host inserisce il container nel namespace IPC dell’host, quindi il container usa il /dev/shm dell’host, che normalmente è pari alla metà della RAM. La guida Docker di Playwright lo consiglia perché, senza questa impostazione, «Chromium può esaurire la memoria e arrestarsi». Il compromesso è la perdita dell’isolamento IPC tra container e host. --shm-size=1g mantiene il namespace privato e aumenta semplicemente la dimensione del mount.

docker run --rm -it --init --ipc=host --user pwuser mcr.microsoft.com/playwright:v1.62.0-noble /bin/bash

Il flag --disable-dev-shm-usage è la soluzione indicata nella maggior parte dei risultati di ricerca, ma svolge una funzione diversa: sposta quei file da /dev/shm a una directory temporanea. Se /tmp risiede su disco, si sostituisce l’arresto anomalo con un rendering più lento e operazioni di scrittura su disco. Se /tmp è un tmpfs, i dati restano nella RAM e sono limitati soltanto dalla dimensione del tmpfs; la documentazione del kernel indica che, per impostazione predefinita, questa dimensione è pari alla metà della RAM fisica. Inoltre, le pagine tmpfs possono essere trasferite nello swap. È un modo in cui un browser può consumare rapidamente la memoria di una VPS di piccole dimensioni. Playwright 1.62 passa --disable-dev-shm-usage per impostazione predefinita; per usare il /dev/shm configurato, rimuovere quell’argomento con ignoreDefaultArgs: ['--disable-dev-shm-usage'] nelle opzioni di avvio.

Il costo effettivo di --no-sandbox

Chromium isola ogni renderer in una sandbox basata sui user namespace di Linux. Questa sandbox costituisce il confine tra una pagina ostile e il server. Playwright disabilita la sandbox di Chromium per impostazione predefinita; abilitala con chromiumSandbox: true nelle opzioni di avvio. Quando la sandbox abilitata non può essere avviata, Chromium rifiuta di eseguire e nel log compare una riga simile a questa:

Failed to move to new namespace: PID namespaces supported, Network namespace supported, but failed: errno = Operation not permitted

Il suggerimento più comune è --no-sandbox. Le pagine sulla sicurezza di Chromium sono esplicite sul costo: «Non lo consigliamo, perché riduce significativamente la sicurezza e può impedire il corretto funzionamento di Chromium». Un agent che segue i link naviga per definizione sul web pubblico, cioè proprio nell'ambiente in cui questa sicurezza ridotta viene messa alla prova. Individua la causa reale.

L'esecuzione come root e il blocco dei user namespace sono due cause da verificare. La sandbox di Chromium non è disponibile quando il processo viene eseguito come root; per questo l'immagine di Playwright include l'utente ordinario pwuser. In Docker, Playwright raccomanda inoltre un profilo seccomp che consenta clone, setns e unshare per la navigazione in sandbox. In Ubuntu 24.04 e versioni successive, AppArmor limita i user namespace non privilegiati e nega l'accesso a un binario Chromium in un percorso non coperto da alcun profilo distribuito. Il download di Playwright in ~/.cache/ms-playwright si trova esattamente in un percorso di questo tipo. Verifica entrambi gli aspetti:

id -u
sysctl kernel.apparmor_restrict_unprivileged_userns
sudo dmesg | grep -i userns_create

Un 1 ottenuto da sysctl e una riga del kernel contenente apparmor="DENIED" operation="userns_create" confermano la seconda causa. Consenti quel singolo binario in /etc/apparmor.d/pw-chromium, mantenendo la restrizione per tutto il resto del sistema:

abi <abi/4.0>,
include <tunables/global>

profile pw-chromium /{home/*/.cache/ms-playwright,opt/pw-browsers}/*/chrome-*/{chrome,headless_shell,chrome-headless-shell} flags=(unconfined) {
  userns,
}

Carica il profilo con sudo apparmor_parser -r /etc/apparmor.d/pw-chromium. Su x86-64, Playwright installa il browser completo in chrome-linux64/chrome e la shell in chrome-headless-shell-linux64/chrome-headless-shell. Su ARM64, Playwright 1.62 li installava in directory separate: chromium-<revision>/chrome-linux/chrome e chromium_headless_shell-<revision>/chrome-linux/headless_shell. Dalla versione 1.63, ARM64 segue lo schema x86-64 con chrome-linux-arm64/chrome e chrome-headless-shell-linux-arm64/chrome-headless-shell. Il glob chrome-* copre tutti questi layout e il ramo /opt/pw-browsers copre un'installazione condivisa eseguita con PLAYWRIGHT_BROWSERS_PATH. Il percorso contiene anche la revisione del browser, quindi cambia a ogni aggiornamento di Playwright. I glob precedenti continuano a funzionare. Un profilo scritto per un singolo percorso esatto smette invece di corrispondere senza segnalare il problema, e dopo un aggiornamento apparentemente non correlato il browser ricomincia a non funzionare.

Perché le schermate acquisite risultano vuote o piene di riquadri

Una schermata vuota, o piena di rettangoli vuoti, è generalmente dovuta a un problema di font e non a un errore di rendering. install-deps usa una base funzionante: fonts-liberation, fonts-freefont-ttf, fonts-noto-color-emoji, fonts-unifont, fonts-ipafont-gothic per il giapponese, fonts-wqy-zenhei per il cinese e fonts-tlwg-loma-otf per il tailandese. In questo insieme non è presente Noto CJK, quindi il coreano e diversi altri script usano il fallback che fontconfig riesce a trovare. Interroga fontconfig invece di procedere per tentativi:

fc-match "sans-serif:lang=ko"
fc-match "sans-serif:lang=ar"
fc-list | wc -l

Se una lingua necessaria viene associata a unifont o a un fallback privo di glifi reali, installa fonts-noto-core e fonts-noto-cjk, quindi esegui di nuovo il controllo. Fontconfig memorizza nella cache i risultati, quindi riavvia il browser dopo aver installato i font. Un'immagine ridotta priva di font registra Fontconfig error: Cannot load default config file all'avvio e visualizza vuota ogni pagina.

La lingua e il fuso orario sono separati dai font e modificano il contenuto della pagina, non solo il suo aspetto. Le impostazioni predefinite di lingua e fuso orario del contesto Playwright corrispondono a quelle del sistema; controlla quindi la configurazione dell'immagine invece di presumere che LANG non sia impostato o che il fuso orario sia UTC. Impostali per ogni contesto del browser e non per l'intera macchina, in modo che un singolo browser possa gestire attività per regioni diverse.

const context = await browser.newContext({
  locale: 'en-GB',
  timezoneId: 'Europe/Paris',
});

Perché i processi del browser lasciati aperti fanno usare la swap al server

Due problemi diversi condividono il nome "zombie". Uno zombie vero è un processo terminato il cui processo padre non ha mai chiamato wait(). Mantiene una voce PID e nient'altro, quindi non consuma memoria. Questi processi si accumulano quando il browser viene eseguito come PID 1 in un container, perché PID 1 non dispone di un reaper predefinito. Il flag --init di Docker risolve esattamente questo problema, avviando un init minimale che "inoltra i segnali e raccoglie i processi". In Compose l'equivalente è init: true.

Il leak che fa davvero usare la swap al server è diverso: si tratta di processi Chromium ancora attivi che nessuno ha chiuso. Si verifica quando un task genera un'eccezione tra newContext() e close(), oppure quando lo script di controllo viene terminato e lascia orfano il relativo albero di processi del browser. Il caso peggiore è il codice che avvia un browser nuovo per ogni richiesta. Contali:

pgrep -c -f 'headless_shell|chrome'
ps -eo pid,ppid,rss,etime,comm --sort=-rss | head -20

Questo conteggio dovrebbe tornare al valore di inattività tra un task e l'altro. Se aumenta nell'arco di una giornata, la correzione va applicata al codice, non ai flag di avvio: chiudi il context in un blocco finally, chiudi il browser su SIGTERM e ricrea il browser dopo un numero fisso di task, invece di lasciarlo in esecuzione per un mese. Con systemd, un arresto o un riavvio termina tutti i processi nel cgroup dell'unità, quindi sudo systemctl restart browser.service è un reset affidabile. Un browser avviato manualmente all'interno di un multiplexer di terminale non offre la stessa garanzia e i relativi processi orfani sopravvivono alla sessione.

Quanta RAM richiede un singolo contesto del browser

Formulate la domanda in modo preciso, perché «un browser» non corrisponde a un solo processo. Chromium esegue un processo browser, un processo GPU, processi di utilità e un processo renderer per ogni sito. L'isolamento dei siti assegna inoltre un renderer separato agli iframe di siti diversi. Un BrowserContext è un contenitore separato per cookie e dati persistenti all'interno dello stesso albero di processi, quindi un secondo contesto ha un costo ridotto. Una seconda pagina, invece, non è economica, perché avvia processi renderer; una pagina con molta pubblicità ne avvia diversi.

Il valore da misurare è quindi il picco di memoria dell'intero albero di processi durante il vostro carico di lavoro. Un dato pubblicato sul blog di qualcun altro non è utile in questo caso, perché la risposta dipende dalle pagine aperte dal vostro agente. Eseguite la misurazione sulla macchina che userete, visitando i siti previsti:

sudo systemd-run --unit=browser-probe -p MemoryMax=2G -p MemorySwapMax=0 -p WorkingDirectory=/srv/agent /usr/bin/node worker.js
systemctl status browser-probe

Su Ubuntu 24.04, la riga Memory: nell'output mostra l'utilizzo corrente e il picco di utilizzo dell'unità. Eseguite il worker con una pagina alla volta, annotate il picco e ripetete la prova con due pagine aperte per verificare il costo effettivo di una seconda pagina. La concorrenza si calcola quindi in modo diretto: prendete la RAM totale, sottraete quella necessaria al resto del sistema, mantenete alcune centinaia di MB di margine e dividete il risultato per il picco misurato per worker. Per dimensionare la macchina sottostante, consultate quanta RAM e CPU richiede un VPS per un agente.

Imponete questo limite in due punti. Nel codice, usate un pool di worker con dimensione fissa o un semaforo, così un picco di richieste dell'agente viene accodato invece di avviare altri browser. Nel sistema operativo, usate un limite cgroup, così un bug nella coda non può compromettere l'intera macchina:

[Service]
MemoryMax=2G
MemorySwapMax=0
TasksMax=512
Restart=always

MemorySwapMax=0 è più importante di quanto sembri. Senza questo limite, il cgroup può spostare le pagine nella swap quando si avvicina al limite. In questo modo la macchina spesso resta operativa, ma ogni richiesta diventa lenta, una situazione più difficile da diagnosticare rispetto a un errore netto. La swap ritarda soltanto il problema: la documentazione di systemd indica che, se l'utilizzo «cannot be contained under the limit, out-of-memory killer is invoked inside the unit». Con la swap impostata a zero, l'unità non può usare la swap; il raggiungimento di MemoryMax attiva il reclaim prima di un'azione dell'OOM killer, se il reclaim non riesce a contenere l'utilizzo. Restart=always riavvia il servizio quando termina il processo principale, ma l'uccisione da parte dell'OOM killer del solo renderer non garantisce un riavvio. In Compose, gli stessi controlli sono mem_limit, shm_size e init, descritti in impostare i limiti di memoria in Docker Compose.

Mantieni l'endpoint del browser fuori da Internet pubblico

Playwright può eseguire il browser come server e fornire all'agente un URL WebSocket:

const { chromium } = require('playwright');
const server = await chromium.launchServer({ port: 3000 });
console.log(server.wsEndpoint());

Questo endpoint non richiede autenticazione. La documentazione dell'API di Playwright lo dichiara esplicitamente: "Qualsiasi processo o pagina Web, inclusi quelli in esecuzione in Playwright, che conosca wsPath può assumere il controllo dell'utente del sistema operativo." L'host predefinito è localhost, "che accetta connessioni soltanto dall'interfaccia di loopback", e la documentazione avverte che specificare un indirizzo esplicito come 0.0.0.0 "espone l'RPC del browser a qualsiasi sistema in grado di raggiungere la porta in ascolto". Il --remote-debugging-port di Chrome è ancora più rischioso. Il protocollo DevTools non implementa alcun tipo di autenticazione e dipende interamente dal binding sull'interfaccia di loopback.

Verifica ciò che hai effettivamente pubblicato. Esegui il controllo anche da una seconda macchina, oltre che dal VPS:

ss -ltnp

Qualsiasi servizio del browser associato a 0.0.0.0 costituisce un problema di sicurezza. Ricorda che la maggior parte dei provider utilizza un firewall di rete separato nel pannello di controllo. Le regole ufw non ne sono a conoscenza. Raggiungi l'endpoint da un'altra macchina tramite un tunnel SSH o una VPN privata:

ssh -N -L 3000:127.0.0.1:3000 you@your-vps

Il rischio non consiste soltanto nel furto del tempo di esecuzione del browser. Un browser che puoi controllare è uno strumento per falsificare richieste, posizionato all'interno della tua rete. Chiunque raggiunga quel socket può fare in modo che il browser richieda http://127.0.0.1:8080, la pagina di amministrazione del database o l'indirizzo dei metadati cloud 169.254.169.254, quindi leggere la risposta dalla pagina. Il firewall vede una richiesta proveniente dal VPS stesso e quindi autorizzata. Considera l'endpoint di controllo equivalente all'accesso shell a quel sistema.

I server MCP hanno la stessa struttura. npx @playwright/mcp@latest --headless --port 8931 espone un servizio HTTP su localhost e --host 0.0.0.0 è il flag che trasforma uno strumento locale in uno pubblico. Il README del progetto dichiara chiaramente che Playwright MCP "non è un confine di sicurezza". Mantieni la porta sull'interfaccia di loopback e consenti all'agente di raggiungerla attraverso lo stesso tunnel.

Le pagine lette dall’agent sono input non attendibile

Un agent che naviga sul Web aperto inserisce in un modello testi scritti da persone sconosciute, insieme alle istruzioni che il modello deve seguire. Una pagina può contenere testo rivolto al modello, chiedendogli di abbandonare l’attività, chiamare uno strumento o inviare dati a un URL. Il modello riceve entrambi i contenuti come testo, quindi non ha un modo affidabile per distinguere le parole della pagina dalle tue istruzioni. Configura l’ambiente in modo che una pagina ostile abbia poche possibilità di interferire.

  • Esegui il browser con un utente OS dedicato, senza chiavi SSH e senza credenziali cloud nell’ambiente.
  • Usa un contesto nuovo per ogni attività e --isolated con Playwright MCP; chiudi il browser MCP tra un’attività e l’altra per eliminare lo storage della sessione.
  • Mantieni una allowlist delle origini quando l’attività lo consente. Playwright MCP accetta --allowed-origins e --blocked-origins come elenchi separati da punto e virgola. Questi filtri non si applicano ai redirect e non costituiscono un confine di sicurezza.
  • Richiedi un passaggio umano prima di qualsiasi azione che modifichi lo stato, ad esempio l’invio di email o una spesa.

Meglio ancora, esegui l’intero browser su una macchina che puoi eliminare e ricreare. È lo stesso principio di eseguire gli agent di coding in una VM usa e getta. Se il compito effettivo dell’agent è cercare informazioni anziché navigare senza vincoli, uno strumento più circoscritto è più sicuro di un browser completo: una skill di ricerca basata sul tuo SearXNG restituisce i risultati senza caricare la pagina ostile.

FAQ

Perché Chromium va in crash in Docker ma funziona correttamente direttamente sullo stesso VPS?

Perché il container riceve per impostazione predefinita un /dev/shm di 64 MB, mentre l'host ne dispone di uno molto più grande. Chromium trasferisce il contenuto renderizzato tramite quest'area di memoria condivisa. Una pagina pesante può quindi riempirla e causare la terminazione del processo renderer. Esegui df -h /dev/shm all'interno del container per confermare la causa. Avvia quindi il container con --ipc=host, che usa la memoria condivisa dell'host, oppure con --shm-size=1g, che aumenta quella propria del container. --disable-dev-shm-usage sposta soltanto il problema in /tmp. Playwright 1.62 passa questo flag per impostazione predefinita; usa ignoreDefaultArgs: ['--disable-dev-shm-usage'] per fare in modo che Chromium utilizzi la memoria condivisa dimensionata.

--no-sandbox è sicuro se il VPS non esegue altro?

No. La sandbox impedisce a una pagina dannosa di raggiungere il resto della macchina. Le pagine sulla sicurezza di Chromium descrivono il flag con queste parole: "We do not encourage this as it will significantly reduce your security, and may prevent Chromium from working properly." Un agent che segue collegamenti naviga sul web aperto. Correggi invece la causa: non eseguire il browser come root e, su Ubuntu 24.04, aggiungi un profilo AppArmor che includa userns, per il percorso del binario del browser, in modo da consentire i namespace utente non privilegiati soltanto per quel programma. Abilita esplicitamente la sandbox con chromiumSandbox: true. In Docker, usa anche il profilo seccomp raccomandato da Playwright.

Quanti browser posso eseguire su un VPS di piccole dimensioni?

Misuralo. Non copiare un numero predefinito. Chromium avvia un processo renderer per ogni sito. La risposta dipende quindi dalle pagine che apri. Esegui un worker con systemd-run e imposta MemoryMax. Leggi il picco dalla riga Memory: in systemctl status. Dividi quindi la RAM libera per quel picco e mantieni un margine. Applica il limite due volte: usa una coda nel codice e un MemoryMax nel file dell'unità. In questo modo una raffica di richieste resta in attesa invece di causare lo swapping della macchina.

Il mio agent può connettersi al browser da un'altra macchina?

Sì, ma non associare mai la porta a 0.0.0.0. L'endpoint del server Playwright e la porta Chrome DevTools accettano qualsiasi client che possa raggiungerli, senza password. Mantieni il listener su 127.0.0.1 e trasferisci la connessione tramite un tunnel SSH o una VPN privata. Verifica con ss -ltnp sul server ed esegui un controllo della porta dall'esterno. Controlla anche il firewall di rete separato del provider.

Perché gli screenshot sono vuoti se la pagina è stata caricata correttamente?

Mancano i font. Se nessun font copre lo script della pagina, il testo viene visualizzato come riquadri vuoti oppure non viene visualizzato affatto. Una pagina con poche immagini appare quindi vuota. Esegui fc-match "sans-serif:lang=ko" per ogni lingua che acquisisci. Installa fonts-noto-core e fonts-noto-cjk quando il risultato è un fallback generico. Riavvia quindi il browser, così fontconfig ricarica la cache. Un container privo di font registra Fontconfig error: Cannot load default config file all'avvio.

Questo articolo ti è stato utile?