Faire tourner Chromium headless pour un agent IA sur VPS
Évitez les erreurs Chromium liées à /dev/shm, au sandbox et aux polices sur VPS. Ce guide couvre aussi les processus orphelins et l’accès local sécurisé.
Ce que vous allez exécuter
Un navigateur headless sur un VPS est Chromium sans fenêtre, piloté par votre code plutôt que par une personne. Sur un serveur, il s’agit d’un arbre de processus qui fonctionne sur la durée et avec lequel votre agent communique via un socket local. Son installation tient en une commande. Le travail commence ensuite. Vous limitez les ressources que le navigateur peut utiliser sur la machine et vous gardez son endpoint de contrôle hors de l’Internet public.
Ce guide part du principe que le choix de l’outil est déjà fait et que vous devez maintenant l’exploiter. Si vous comparez encore les crawlers et les extracteurs, commencez par les alternatives auto-hébergées à Firecrawl, puis revenez ici. Tout ce qui suit utilise le Chromium de Playwright, car Playwright fournit son propre build du navigateur et son propre installateur de dépendances. Les mêmes commandes fonctionnent donc sur un VPS Ubuntu vierge et dans un conteneur. Les commandes figent Playwright en version 1.62.
Installer Chromium sans deviner les dépendances
npm i -D playwright@1.62.0
npx playwright install --with-deps chromium--with-deps exécute apt pour installer les bibliothèques partagées et les polices dont Chromium a besoin, puis demande les privilèges root lorsqu’il arrive à cette étape. Le build du navigateur est téléchargé dans ~/.cache/ms-playwright pour l’utilisateur qui a exécuté la commande. Cela compte sur un serveur, car l’utilisateur du service n’est généralement pas celui avec lequel vous vous connectez. Installez une fois les paquets système en tant qu’administrateur avec sudo npx playwright install-deps chromium, puis définissez PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers à la fois dans la commande d’installation et dans l’unité de service afin de partager une seule copie. Un service qui ne peut pas accéder à son navigateur échoue au démarrage avec un message indiquant le chemin qu’il a recherché.
Épinglez la version de Playwright. Chaque release est associée à un build de navigateur précis. Un npm update sans version peut donc remplacer le navigateur utilisé par un service en cours d’exécution. Au 16 novembre 2026, la dernière release est la 1.65.1. Consultez donc les release notes avant de modifier la version épinglée. Sur les serveurs ARM64, notez que la version 1.63 a renommé les répertoires des navigateurs. Cela compte pour le profil AppArmor présenté plus loin.
Il existe deux builds de Chromium, et ce ne sont pas le même programme. En mode headless, Playwright utilise par défaut le headless shell, un binaire plus petit qui ne fonctionne qu’en mode headless. Une installation standard le télécharge à côté du navigateur complet, tandis que npx playwright install --with-deps --only-shell installe uniquement le shell. Le navigateur complet est celui que vous obtenez avec le channel chromium. La documentation des navigateurs de Playwright le décrit comme « le vrai navigateur Chrome, donc plus authentique, plus fiable et offrant davantage de fonctionnalités ». Utilisez le shell pour les téléchargements en volume. Utilisez le navigateur complet lorsqu’un site se comporte différemment et que vous devez en déterminer la cause.
Pourquoi un navigateur headless plante dans un conteneur
Docker attribue un /dev/shm de 64 MB à chaque conteneur. La documentation Docker est explicite : « If you omit the size entirely, the system uses 64m ». Chromium transmet le contenu rendu entre ses processus via cette zone de mémoire partagée. Une seule page lourde peut donc la remplir. Le renderer s’arrête alors et votre client signale une cible qui a planté, alors que la page fonctionne correctement sur votre laptop. Vérifiez la taille depuis l’intérieur du conteneur avant de modifier quoi que ce soit.
df -h /dev/shmIl existe deux correctifs réels. Ils s’excluent mutuellement et ne se combinent pas. --ipc=host place le conteneur dans le namespace IPC de l’hôte. Il utilise ainsi le /dev/shm de l’hôte, qui représente normalement la moitié de la RAM. Le guide Docker de Playwright le recommande, car sans cette option, « Chromium can run out of memory and crash ». En contrepartie, vous supprimez l’isolation IPC entre le conteneur et l’hôte. --shm-size=1g conserve le namespace privé et augmente simplement la taille du mount.
docker run --rm -it --init --ipc=host --user pwuser mcr.microsoft.com/playwright:v1.62.0-noble /bin/bashLe flag --disable-dev-shm-usage est la solution proposée par la plupart des résultats de recherche. Il a toutefois un autre effet : il déplace ces fichiers de /dev/shm vers un répertoire temporaire. Si /tmp se trouve sur le disque, vous remplacez le plantage par un rendu plus lent et des écritures disque. Si /tmp est un tmpfs, les données restent en RAM. Leur taille est alors limitée uniquement par celle du tmpfs, que la documentation du kernel définit par défaut à la moitié de la RAM physique. Les pages tmpfs peuvent aussi être évacuées vers le swap. C’est une façon pour un navigateur de consommer rapidement les ressources d’un petit VPS. Playwright 1.62 transmet --disable-dev-shm-usage par défaut. Pour utiliser le /dev/shm dont vous avez défini la taille, supprimez cet argument avec ignoreDefaultArgs: ['--disable-dev-shm-usage'] dans vos options de lancement.
Ce que coûte réellement chromiumSandbox: true
Chromium isole chaque renderer dans un sandbox basé sur les user namespaces Linux. Ce sandbox constitue la frontière entre une page hostile et votre serveur. Playwright désactive le sandbox Chromium par défaut. Activez-le donc avec chromiumSandbox: true dans vos options de lancement. Lorsque le sandbox activé ne peut pas démarrer, Chromium refuse de s’exécuter et le journal contient une ligne comme celle-ci :
Failed to move to new namespace: PID namespaces supported, Network namespace supported, but failed: errno = Operation not permittedLe conseil habituel consiste à utiliser --no-sandbox. Les pages de sécurité de Chromium indiquent clairement le coût de cette option : « Nous ne recommandons pas cette solution, car elle réduit fortement votre sécurité et peut empêcher Chromium de fonctionner correctement. » Un agent qui suit des liens navigue par définition sur le Web ouvert. C’est précisément là que cette réduction de sécurité est mise à l’épreuve. Recherchez la cause réelle.
L’exécution avec root et le blocage des user namespaces sont deux causes à vérifier. Le sandbox de Chromium n’est pas disponible lorsque le programme s’exécute avec root. C’est pourquoi l’image Playwright fournit un utilisateur ordinaire nommé pwuser. Dans Docker, Playwright recommande également un profil seccomp qui autorise clone, setns et unshare pour la navigation avec sandbox. Avec Ubuntu 24.04 et les versions ultérieures, AppArmor restreint les user namespaces non privilégiés. Un binaire Chromium situé dans un chemin couvert par aucun profil fourni est alors refusé. Le téléchargement Playwright situé sous ~/.cache/ms-playwright utilise précisément un tel chemin. Vérifiez les deux points :
id -u
sysctl kernel.apparmor_restrict_unprivileged_userns
sudo dmesg | grep -i userns_createUn 1 provenant de sysctl, associé à une ligne du kernel contenant apparmor="DENIED" operation="userns_create", confirme la seconde cause. Autorisez ce binaire dans /etc/apparmor.d/pw-chromium. La restriction reste ainsi appliquée à tout le reste du système :
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,
}Chargez la configuration avec sudo apparmor_parser -r /etc/apparmor.d/pw-chromium. Sur x86-64, Playwright place le navigateur complet dans chrome-linux64/chrome et le shell dans chrome-headless-shell-linux64/chrome-headless-shell. Sur ARM64, Playwright 1.62 les installait dans des répertoires distincts : chromium-<revision>/chrome-linux/chrome et chromium_headless_shell-<revision>/chrome-linux/headless_shell. Depuis la version 1.63, ARM64 suit le modèle x86-64 avec chrome-linux-arm64/chrome et chrome-headless-shell-linux-arm64/chrome-headless-shell. Le glob chrome-* couvre toutes ces configurations. La branche /opt/pw-browsers couvre une installation partagée créée avec PLAYWRIGHT_BROWSERS_PATH. Le chemin contient également la révision du navigateur. Il change donc à chaque mise à niveau de Playwright. Les globs ci-dessus restent compatibles avec ces changements. Un profil configuré pour un chemin exact cesse silencieusement de correspondre. Le navigateur recommence alors à échouer après une mise à jour qui semblait sans rapport.
Pourquoi les captures d’écran sont vides ou remplies de rectangles
Une capture d’écran vide, ou remplie de rectangles vides, indique généralement un problème de polices plutôt qu’un bug de rendu. install-deps installe une base fonctionnelle : fonts-liberation, fonts-freefont-ttf, fonts-noto-color-emoji, fonts-unifont, fonts-ipafont-gothic pour le japonais, fonts-wqy-zenhei pour le chinois et fonts-tlwg-loma-otf pour le thaï. Cet ensemble ne contient pas Noto CJK. Le coréen et plusieurs autres écritures utilisent donc une police de repli que fontconfig peut trouver. Interrogez fontconfig au lieu de procéder par supposition :
fc-match "sans-serif:lang=ko"
fc-match "sans-serif:lang=ar"
fc-list | wc -lSi la langue qui vous intéresse utilise unifont ou une police de repli dépourvue de glyphes utilisables, installez fonts-noto-core et fonts-noto-cjk, puis relancez la vérification. fontconfig met ses résultats en cache. Redémarrez donc le navigateur après l’installation des polices. Une image allégée qui ne contient aucune police journalise Fontconfig error: Cannot load default config file au démarrage et affiche toutes les pages vides.
La locale et le fuseau horaire sont indépendants des polices. Ils modifient le contenu de la page, pas seulement son apparence. La locale et le fuseau horaire du contexte Playwright utilisent par défaut les paramètres du système. Vérifiez donc la configuration de l’image au lieu de supposer que LANG n’est pas défini ou que le fuseau horaire est UTC. Définissez-les pour chaque contexte de navigateur plutôt qu’à l’échelle de la machine. Un même navigateur peut ainsi exécuter des tâches pour différentes régions.
const context = await browser.newContext({
locale: 'en-GB',
timezoneId: 'Europe/Paris',
});Pourquoi des processus de navigateur oubliés font utiliser le swap à la machine
Deux problèmes différents sont désignés par le terme « zombie ». Un véritable processus zombie est un processus terminé dont le parent n’a jamais appelé wait(). Il conserve une entrée de PID, mais rien d’autre. Il ne consomme donc pas de mémoire. Vous en accumulez lorsque le navigateur s’exécute avec le PID 1 dans un conteneur, car le PID 1 ne dispose d’aucun mécanisme de réapage par défaut. L’option --init de Docker corrige précisément ce problème en exécutant un petit processus init qui « transmet les signaux et réapage les processus ». Dans Compose, l’équivalent est init: true.
La fuite qui fait réellement utiliser le swap à la machine est différente : il s’agit de processus Chromium encore actifs que personne n’a fermés. Elle se produit lorsqu’une tâche lève une exception entre newContext() et close(), ou lorsque le script de contrôle est tué et laisse son arbre de processus du navigateur orphelin. Le pire cas est celui d’un code qui lance un nouveau navigateur pour chaque requête. Comptez-les :
pgrep -c -f 'headless_shell|chrome'
ps -eo pid,ppid,rss,etime,comm --sort=-rss | head -20Ce nombre doit revenir à sa valeur au repos entre les tâches. S’il augmente au fil de la journée, le correctif se trouve dans votre code, pas dans les options de lancement : fermez le contexte dans un bloc finally, fermez le navigateur à SIGTERM et recyclez le navigateur après un nombre fixe de tâches au lieu de le laisser fonctionner pendant un mois. Avec systemd, un arrêt ou un redémarrage tue tous les processus du cgroup de l’unité. sudo systemctl restart browser.service constitue donc une réinitialisation fiable. Un navigateur lancé manuellement dans un terminal multiplexé ne bénéficie d’aucune garantie équivalente, et ses processus orphelins survivent à la session.
De quelle quantité de RAM un contexte de navigateur a-t-il besoin
Posez la question avec précision, car « un navigateur » ne correspond pas à un seul processus. Chromium exécute un processus de navigateur, un processus GPU, des processus utilitaires et un processus de rendu par site. L’isolation des sites attribue également leur propre processus de rendu aux iframes provenant d’autres sites. Un BrowserContext est un espace de stockage et un conteneur de cookies distincts dans cette même arborescence, donc un deuxième contexte coûte peu. Ce n’est pas le cas d’une deuxième page, car elle démarre des processus de rendu. Une page contenant beaucoup de publicités en démarre plusieurs.
La valeur à mesurer est donc la mémoire maximale de toute l’arborescence avec votre propre charge de travail. Une valeur publiée sur le blog de quelqu’un d’autre ne vous sera d’aucune utilité, car ce sont les pages ouvertes par votre agent qui déterminent le résultat. Mesurez sur la machine que vous utiliserez, avec les sites que vous visiterez :
sudo systemd-run --unit=browser-probe -p MemoryMax=2G -p MemorySwapMax=0 -p WorkingDirectory=/srv/agent /usr/bin/node worker.js
systemctl status browser-probeSur Ubuntu 24.04, la ligne Memory: de cette sortie indique l’utilisation actuelle et maximale de l’unité. Exécutez le worker avec une seule page à la fois, notez le pic, puis recommencez avec deux pages ouvertes pour mesurer le coût réel d’une deuxième page. La concurrence se calcule ensuite simplement : prenez la quantité totale de RAM, soustrayez la mémoire nécessaire au reste de la machine, gardez quelques centaines de Mo de marge, puis divisez le résultat par le pic mesuré par worker. Pour dimensionner la machine sous-jacente, consultez la quantité de RAM et de CPU nécessaire à un VPS pour agent.
Appliquez cette limite à deux endroits. Dans votre code, utilisez un pool fixe de workers ou un sémaphore, afin que les requêtes d’agent en rafale soient mises en file d’attente au lieu de lancer de nouveaux navigateurs. Dans le système d’exploitation, utilisez une limite cgroup, afin qu’un bug dans la file d’attente ne fasse pas tomber toute la machine :
[Service]
MemoryMax=2G
MemorySwapMax=0
TasksMax=512
Restart=alwaysMemorySwapMax=0 est plus important qu’il n’y paraît. Sans ce paramètre, le cgroup peut envoyer des pages dans le swap lorsqu’il approche de la limite. La machine reste alors souvent disponible, mais chaque requête devient lente. Ce comportement est plus difficile à diagnostiquer qu’un échec net. Le swap ne fait que retarder le problème : la documentation de systemd indique que si l’utilisation « ne peut pas être contenue sous la limite, l’out-of-memory killer est invoqué dans l’unité ». Avec le swap défini à zéro, l’unité ne peut pas utiliser le swap. Atteindre MemoryMax déclenche une récupération de mémoire avant un OOM kill si cette récupération ne suffit pas à contenir l’utilisation. Restart=always redémarre le service lorsque son processus principal se termine, mais l’OOM kill d’un seul processus de rendu ne garantit pas un redémarrage. Les mêmes contrôles dans Compose sont mem_limit, shm_size et init. Ils sont présentés dans la définition de limites mémoire dans Docker Compose.
N’exposez pas l’endpoint du navigateur sur Internet
Playwright peut exécuter le navigateur en tant que serveur et fournir à votre agent une URL WebSocket :
const { chromium } = require('playwright');
const server = await chromium.launchServer({ port: 3000 });
console.log(server.wsEndpoint());Cet endpoint ne comporte aucune authentification. La documentation de l’API Playwright l’indique clairement : « Tout processus ou toute page web, y compris ceux exécutés dans Playwright, qui connaît le wsPath peut prendre le contrôle de l’utilisateur du système d’exploitation. » L’hôte par défaut est localhost, « qui n’accepte les connexions que depuis l’interface loopback », et la documentation avertit que la transmission d’une adresse explicite telle que 0.0.0.0 « expose le RPC du navigateur à tout ce qui peut atteindre le port en écoute ». Le --remote-debugging-port de Chrome est encore plus risqué. Le protocole DevTools ne fournit aucune authentification et dépend entièrement d’une liaison sur loopback.
Vérifiez ce que vous avez réellement publié. Effectuez également ce contrôle depuis une deuxième machine, et pas seulement depuis le VPS :
ss -ltnpTout port de navigateur lié à 0.0.0.0 constitue un problème de sécurité. N’oubliez pas que la plupart des fournisseurs exécutent un firewall réseau distinct dans leur panneau de contrôle. Vos règles ufw n’en ont aucune connaissance. Accédez à l’endpoint depuis une autre machine au moyen d’un tunnel SSH ou d’un VPN privé :
ssh -N -L 3000:127.0.0.1:3000 you@your-vpsLe risque ne se limite pas au vol de temps de navigation. Un navigateur que vous pouvez piloter est un outil de falsification de requêtes situé à l’intérieur de votre réseau. Toute personne qui atteint ce socket peut lui faire interroger http://127.0.0.1:8080, votre page d’administration de base de données ou l’adresse de métadonnées cloud 169.254.169.254, puis lire la réponse dans la page. Votre firewall voit une requête provenant du VPS lui-même, ce qui est autorisé. Considérez l’endpoint de contrôle comme équivalent à un accès shell sur cette machine.
Les serveurs MCP présentent le même risque. npx @playwright/mcp@latest --headless --port 8931 sert du contenu HTTP sur localhost, et --host 0.0.0.0 est l’option qui transforme un outil local en service public. Le README du projet indique clairement que Playwright MCP « n’est pas une frontière de sécurité ». Laissez le port sur loopback et permettez à l’agent d’y accéder via le même tunnel.
Les pages consultées par votre agent sont des entrées non fiables
Un agent qui consulte le Web ouvert transmet à un modèle du texte rédigé par des inconnus, alors que ce modèle reçoit aussi vos instructions. Une page peut contenir du texte qui s’adresse au modèle et lui demande d’abandonner la tâche, d’appeler un outil ou de publier des données vers une URL. Le modèle reçoit tout sous forme de texte. Il ne peut donc pas distinguer de manière fiable les instructions de la page des vôtres. Configurez l’ensemble de manière à limiter ce qu’une page malveillante peut exploiter.
- Exécutez le navigateur sous son propre utilisateur système, sans clés SSH ni identifiants cloud dans son environnement.
- Utilisez un contexte vierge pour chaque tâche et
--isolatedavec Playwright MCP ; fermez le navigateur MCP entre les tâches afin de supprimer le stockage de cette session. - Définissez une allowlist d’origines lorsque la tâche le permet. Playwright MCP accepte
--allowed-originset--blocked-originssous forme de listes séparées par des points-virgules. Ces filtres ne s’appliquent pas aux redirections et ne constituent pas une frontière de sécurité. - Exigez une intervention humaine avant toute action qui modifie l’état, comme l’envoi d’un e-mail ou une dépense.
Mieux encore, exécutez l’ensemble du navigateur sur une machine que vous pouvez supprimer et reconstruire. C’est le même principe que l’exécution d’agents de programmation dans une VM éphémère. Si le véritable objectif de l’agent est la recherche plutôt que la navigation libre, un outil plus limité est plus sûr qu’un navigateur complet : une skill de recherche basée sur votre propre SearXNG renvoie les résultats sans jamais charger la page malveillante.
FAQ
Pourquoi Chromium plante-t-il dans Docker alors qu’il fonctionne correctement directement sur le même VPS ?
Parce que le conteneur reçoit par défaut un /dev/shm de 64 MB, tandis que l’hôte en possède un beaucoup plus grand. Chromium fait transiter le contenu rendu par cette zone de mémoire partagée. Une page lourde la remplit donc et le processus de rendu se termine. Exécutez df -h /dev/shm dans le conteneur pour le confirmer, puis démarrez-le avec --ipc=host, qui utilise la mémoire partagée de l’hôte, ou avec --shm-size=1g, qui augmente celle du conteneur. --disable-dev-shm-usage ne fait que déplacer le problème vers /tmp. Playwright 1.62 transmet cette option par défaut. Utilisez ignoreDefaultArgs: ['--disable-dev-shm-usage'] pour que Chromium utilise la mémoire partagée que vous avez dimensionnée.
L’option --no-sandbox est-elle sûre si le VPS n’exécute rien d’autre ?
Non. Le sandbox empêche une page malveillante d’accéder au reste de la machine. Les pages de sécurité de Chromium indiquent à propos de cette option : « Nous ne recommandons pas cette option, car elle réduit considérablement votre sécurité et peut empêcher Chromium de fonctionner correctement. » Un agent qui suit des liens parcourt le Web ouvert. Corrigez plutôt la cause : n’exécutez pas le navigateur en tant que root et, sur Ubuntu 24.04, ajoutez un profil AppArmor contenant userns, pour le chemin du binaire du navigateur, afin d’autoriser les user namespaces non privilégiés pour ce seul programme. Activez explicitement le sandboxing avec chromiumSandbox: true. Dans Docker, utilisez également le profil seccomp recommandé par Playwright.
Combien de navigateurs puis-je exécuter sur un petit VPS ?
Mesurez la consommation au lieu de reprendre un nombre arbitraire. Chromium démarre un processus de rendu par site. La réponse dépend donc des pages que vous ouvrez. Exécutez un worker avec systemd-run et définissez MemoryMax. Relevez le pic sur la ligne Memory: dans systemctl status, puis divisez votre RAM libre par ce pic en conservant une marge. Appliquez cette limite deux fois : avec une file d’attente dans votre code et avec un MemoryMax dans le fichier d’unité. Une rafale de requêtes attendra ainsi au lieu de provoquer du swapping sur la machine.
Mon agent peut-il se connecter au navigateur depuis une autre machine ?
Oui, mais ne liez jamais le port à 0.0.0.0. Le endpoint du serveur Playwright et le port Chrome DevTools acceptent tout client qui peut les atteindre, sans mot de passe. Laissez le listener sur 127.0.0.1 et faites transiter la connexion par un tunnel SSH ou un VPN privé. Vérifiez avec ss -ltnp sur le serveur et effectuez un test du port depuis l’extérieur. Contrôlez également le firewall réseau distinct de votre fournisseur.
Pourquoi mes captures d’écran sont-elles vides alors que la page est manifestement chargée ?
Des polices sont manquantes. Si aucune police ne couvre le script utilisé par la page, le texte apparaît sous forme de cases vides ou ne s’affiche pas du tout. Une page contenant peu d’images semble alors vide. Exécutez fc-match "sans-serif:lang=ko" pour chaque langue que vous scrapez. Installez fonts-noto-core et fonts-noto-cjk lorsque le résultat est une police de fallback générique, puis redémarrez le navigateur afin que fontconfig recharge son cache. Un conteneur sans aucune police journalise Fontconfig error: Cannot load default config file au démarrage.