SSD Nodes Learn Hosting plans →
Guías Matt ConnorPor Matt Connor

Chromium headless para agentes de IA en un VPS

Evite fallos de Chromium headless en un VPS: /dev/shm pequeno, flags de sandbox, fuentes ausentes y procesos filtrados. Ajuste los limites antes del agente.

Lo que está ejecutando

Un navegador headless en un VPS es Chromium sin ventana, controlado por su código en lugar de una persona. En un servidor, es un árbol de procesos de larga duración con el que su agente se comunica mediante un socket local. Instalarlo requiere un comando. El trabajo empieza después. Debe limitar los recursos que el navegador puede consumir de la máquina y mantener su endpoint de control fuera de Internet pública.

Esta guía presupone que ya ha elegido la herramienta y que ahora debe operarla. Si todavía está comparando crawlers y extractores, empiece por las alternativas autoalojadas a Firecrawl y vuelva después. Todo lo que sigue usa el Chromium de Playwright, porque Playwright incluye su propia compilación del navegador y su propio instalador de dependencias. Por eso, los mismos comandos funcionan en un VPS de Ubuntu sin más configuración y dentro de un contenedor. Los comandos fijan Playwright en la versión 1.62.

Instalar Chromium sin adivinar las dependencias

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

--with-deps ejecuta apt para obtener las bibliotecas compartidas y las fuentes que necesita Chromium, y solicita acceso como root cuando llega a ese paso. La compilación del navegador se descarga en ~/.cache/ms-playwright para el usuario que ejecutó el comando. Esto es importante en un servidor porque el usuario del servicio normalmente no es el usuario con el que inicia sesión. Instale una vez los paquetes del sistema como administrador con sudo npx playwright install-deps chromium y, después, establezca PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers tanto en el comando de instalación como en la unidad del servicio para compartir una sola copia. Si un servicio no puede acceder a su navegador, falla al iniciarse con un mensaje que indica la ruta que buscó.

Fije la versión de Playwright. Cada versión está vinculada a una compilación concreta del navegador, por lo que un npm update sin fijar puede sustituir el navegador mientras un servicio está en ejecución. A fecha de November 16, 2026, la última versión es 1.65.1, así que revise las notas de la versión antes de cambiar la versión fijada. En servidores ARM64, tenga en cuenta que 1.63 cambió el nombre de las carpetas del navegador. Esto afecta al perfil de AppArmor que aparece más adelante.

Existen dos compilaciones de Chromium y no son el mismo programa. En modo headless, Playwright usa de forma predeterminada el shell headless, un binario más pequeño que sólo funciona en modo headless. Una instalación normal lo descarga junto al navegador completo, mientras que npx playwright install --with-deps --only-shell instala únicamente el shell. El navegador completo se obtiene con el canal chromium, que la documentación de navegadores de Playwright describe como "el navegador Chrome real y, por tanto, más auténtico, fiable y con más funciones". Use el shell para realizar descargas masivas. Use el navegador completo cuando un sitio se comporte de forma distinta y necesite averiguar el motivo.

Por qué un navegador sin interfaz gráfica se bloquea en un contenedor

Docker asigna a cada contenedor un /dev/shm de 64 MB. La documentación de Docker es explícita: «Si omite por completo el tamaño, el sistema usa 64m». Chromium pasa el contenido renderizado entre sus procesos mediante esa área de memoria compartida, por lo que una sola página pesada puede llenarla. El proceso de renderizado muere y el cliente informa de que el destino se bloqueó, aunque la página funcione correctamente en su equipo. Confirme el tamaño desde dentro del contenedor antes de cambiar nada.

df -h /dev/shm

Hay dos soluciones reales y son alternativas, no complementarias. --ipc=host coloca el contenedor en el espacio de nombres IPC del host, por lo que usa el /dev/shm del host, que normalmente equivale a la mitad de la RAM. La guía de Docker de Playwright lo recomienda porque, sin esta opción, «Chromium puede quedarse sin memoria y bloquearse». El coste es que se pierde el aislamiento IPC entre el contenedor y el host. --shm-size=1g mantiene el espacio de nombres privado y simplemente aumenta el tamaño del montaje.

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

La opción --disable-dev-shm-usage es la respuesta que encontrará en la mayoría de los resultados de búsqueda, pero hace algo diferente: mueve esos archivos de /dev/shm a un directorio temporal. Si /tmp está en disco, cambia el bloqueo por un renderizado más lento y escrituras en disco. Si /tmp es un tmpfs, los datos vuelven a estar en la RAM, limitados únicamente por el tamaño máximo del tmpfs, que la documentación del kernel establece de forma predeterminada en la mitad de la RAM física; además, las páginas de tmpfs pueden trasladarse al espacio de intercambio. Así es como un navegador puede consumir la memoria de un VPS pequeño. Playwright 1.62 pasa --disable-dev-shm-usage de forma predeterminada; para usar el /dev/shm cuyo tamaño configuró, quite ese argumento con ignoreDefaultArgs: ['--disable-dev-shm-usage'] de las opciones de inicio.

El coste real de --no-sandbox

Chromium aísla cada proceso de renderizado en un sandbox basado en los espacios de nombres de usuario de Linux. Ese sandbox es la frontera entre una página hostil y el servidor. Playwright desactiva el sandbox de Chromium de forma predeterminada, así que actívelo con chromiumSandbox: true en las opciones de inicio. Cuando el sandbox habilitado no puede iniciarse, Chromium se niega a ejecutarse y el registro contiene una línea como esta:

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

La recomendación habitual es --no-sandbox. Las páginas de seguridad del propio Chromium son claras sobre el coste: "No recomendamos esto porque reducirá significativamente la seguridad y puede impedir que Chromium funcione correctamente". Un agente que sigue enlaces navega por la web abierta por definición. Ese es precisamente el entorno en el que se pone a prueba la reducción de seguridad. Busque la causa real.

Ejecutar como root y tener bloqueados los espacios de nombres de usuario son dos causas que se deben comprobar. El sandbox de Chromium no está disponible cuando se ejecuta como root. Por eso la imagen de Playwright incluye un usuario normal llamado pwuser. En Docker, Playwright también recomienda un perfil de seccomp que permita clone, setns y unshare para la navegación con sandbox. En Ubuntu 24.04 y posteriores, AppArmor restringe los espacios de nombres de usuario sin privilegios. También deniega los binarios de Chromium ubicados en rutas que no cubre ningún perfil incluido. La descarga de Playwright en ~/.cache/ms-playwright usa precisamente una de esas rutas. Compruebe ambas cosas:

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

Un 1 procedente de sysctl junto con una línea del kernel que contenga apparmor="DENIED" operation="userns_create" confirma la segunda causa. Permita ese binario en /etc/apparmor.d/pw-chromium. Así mantiene la restricción para todo lo demás en el equipo:

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,
}

Cárguelo con sudo apparmor_parser -r /etc/apparmor.d/pw-chromium. En x86-64, Playwright coloca el navegador completo en chrome-linux64/chrome y el shell en chrome-headless-shell-linux64/chrome-headless-shell. En ARM64, Playwright 1.62 los instaló en directorios separados: chromium-<revision>/chrome-linux/chrome y chromium_headless_shell-<revision>/chrome-linux/headless_shell. Desde la versión 1.63, ARM64 sigue el patrón de x86-64 con chrome-linux-arm64/chrome y chrome-headless-shell-linux-arm64/chrome-headless-shell. El comodín chrome-* cubre todas estas estructuras. La rama /opt/pw-browsers cubre una instalación compartida realizada con PLAYWRIGHT_BROWSERS_PATH. La ruta también contiene la revisión del navegador, por lo que cambia con cada actualización de Playwright. Los comodines anteriores siguen funcionando después de esos cambios. Un perfil escrito para una ruta exacta deja de coincidir silenciosamente y el navegador vuelve a fallar después de una actualización que parecía no estar relacionada.

Por qué las capturas aparecen en blanco o llenas de cuadros

Una captura en blanco o llena de rectángulos vacíos suele indicar un problema de fuentes, no un fallo de renderizado. install-deps obtiene una base funcional: fonts-liberation, fonts-freefont-ttf, fonts-noto-color-emoji, fonts-unifont, fonts-ipafont-gothic para japonés, fonts-wqy-zenhei para chino y fonts-tlwg-loma-otf para tailandés. Ese conjunto no incluye Noto CJK, por lo que el coreano y otros scripts dependen de la fuente que fontconfig encuentre. Consulte fontconfig en lugar de hacer suposiciones:

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

Si el idioma que necesita se resuelve en unifont o en una alternativa sin glifos reales, instale fonts-noto-core y fonts-noto-cjk y vuelva a ejecutar la comprobación. Fontconfig almacena los resultados en caché, por lo que debe reiniciar el navegador después de instalar las fuentes. Una imagen reducida sin ninguna fuente registra Fontconfig error: Cannot load default config file durante el arranque y renderiza todas las páginas en blanco.

La configuración regional y la zona horaria son independientes de las fuentes. También cambian el contenido de la página, no sólo su aspecto. La configuración regional y la zona horaria del contexto de Playwright usan de forma predeterminada los ajustes del sistema. Por tanto, compruebe la configuración de la imagen en lugar de suponer que LANG no está definido o que la zona horaria es UTC. Configure estos valores por contexto del navegador y no por máquina. Así, un mismo navegador puede ejecutar tareas para distintas regiones.

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

Por qué los procesos del navegador que quedan abiertos hacen que el servidor use swap

Dos problemas distintos reciben el nombre de «zombi». Un zombi real es un proceso finalizado cuyo proceso padre nunca llamó a wait(). Conserva una entrada de PID y nada más, por lo que no consume memoria. Estos procesos se acumulan cuando el navegador se ejecuta como PID 1 en un contenedor, porque PID 1 no tiene un recolector de procesos predeterminado. La opción --init de Docker corrige exactamente esto al ejecutar un proceso init pequeño que «reenvía señales y recolecta procesos». En Compose, el equivalente es init: true.

La fuga que realmente hace que el servidor use swap es distinta: son procesos de Chromium activos que ningún proceso cerró. Ocurre cuando una tarea genera una excepción entre newContext() y close(), o cuando se termina el script de control y deja huérfano su árbol de procesos del navegador. La peor variante es el código que inicia un navegador nuevo para cada petición. Cuéntelos:

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

Ese recuento debe volver a su valor inactivo entre tareas. Si aumenta durante un día, la corrección está en el código, no en las opciones de inicio: cierre el contexto en un bloque finally, cierre el navegador en SIGTERM y recicle el navegador después de un número fijo de tareas en lugar de mantenerlo en ejecución durante un mes. Con systemd, una detención o un reinicio termina todos los procesos del cgroup de la unidad, por lo que sudo systemctl restart browser.service es un restablecimiento fiable. Un navegador iniciado manualmente dentro de un multiplexor de terminal no ofrece esa garantía, y sus procesos huérfanos sobreviven a la sesión.

Cuánta RAM necesita un contexto del navegador

Plantee la pregunta con precisión, porque «un navegador» no es un solo proceso. Chromium ejecuta un proceso del navegador, un proceso de GPU, procesos de utilidades y un proceso de renderizado por sitio. Además, el aislamiento de sitios asigna otro proceso de renderizado a los iframes de sitios distintos. Un BrowserContext es un almacén de cookies y un área de almacenamiento independientes dentro de ese mismo árbol, por lo que un segundo contexto consume pocos recursos. Una segunda página no, porque inicia procesos de renderizado, y una página con muchos anuncios inicia varios.

Por tanto, debe medir el uso máximo de memoria de todo el árbol con su propia carga de trabajo. Una cifra publicada en el blog de otra persona no sirve en este caso, porque las páginas que abre su agente determinan el resultado. Mida en la máquina que utilizará y con los sitios que visitará:

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

En Ubuntu 24.04, la línea Memory: de esa salida muestra el uso actual y máximo de la unidad. Ejecute el worker con una página cada vez, anote el valor máximo y repita la prueba con dos páginas abiertas para comprobar cuánto consume realmente la segunda. La concurrencia se calcula entonces de forma directa: reste de la RAM total lo que necesite el resto del sistema, conserve unos cientos de MB de margen y divida el resultado entre el uso máximo medido por worker. Para dimensionar la máquina subyacente, consulte cuánta RAM y CPU necesita un VPS para un agente.

Aplique ese límite en dos lugares. En el código, use un pool fijo de workers o un semáforo, de modo que una ráfaga de solicitudes del agente se ponga en cola en lugar de iniciar navegadores. En el sistema operativo, use un límite de cgroup, para que un error en la cola no arrastre consigo toda la máquina:

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

MemorySwapMax=0 es más importante de lo que parece. Sin él, el cgroup puede enviar páginas a swap cuando se acerca al límite. Por eso, el sistema suele seguir activo mientras todas las solicitudes se vuelven lentas, lo que es más difícil de diagnosticar que un fallo limpio. La swap sólo retrasa el problema: la documentación de systemd indica que, si el uso «no puede mantenerse dentro del límite, se invoca el out-of-memory killer dentro de la unidad». Con la swap limitada a cero, la unidad no puede usar swap. Al alcanzar MemoryMax, se inicia el reclaim antes de un OOM kill si el reclaim no consigue contener el uso. Restart=always reinicia el servicio cuando termina su proceso principal, pero un OOM kill que afecte sólo a un proceso de renderizado no garantiza un reinicio. Los mismos controles en Compose son mem_limit, shm_size y init, descritos en cómo establecer límites de memoria en Docker Compose.

Mantenga el endpoint del navegador fuera de Internet pública

Playwright puede ejecutar el navegador como servidor y proporcionar a su agente una URL de WebSocket:

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

Ese endpoint no tiene autenticación. La documentación de la API de Playwright lo indica directamente: «Cualquier proceso o página web (incluidos los que se ejecutan en Playwright) que conozca wsPath puede tomar el control del usuario del sistema operativo». El host predeterminado es localhost, «que sólo acepta conexiones desde la interfaz de loopback», y la documentación advierte que pasar una dirección explícita, como 0.0.0.0, «expone el RPC del navegador a cualquier elemento que pueda alcanzar el puerto en escucha». El --remote-debugging-port de Chrome es todavía más problemático. El protocolo DevTools no tiene ningún tipo de autenticación y depende por completo de estar enlazado a loopback.

Compruebe qué ha publicado realmente. Hágalo también desde una segunda máquina, además de hacerlo desde el VPS:

ss -ltnp

Cualquier servicio de navegador enlazado a 0.0.0.0 constituye un hallazgo. Recuerde que la mayoría de los proveedores ejecutan un firewall de red independiente en su panel de control. Sus reglas de ufw no tienen información sobre ese firewall. Acceda al endpoint desde otra máquina mediante un túnel SSH o una VPN privada:

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

El riesgo es mayor que el simple robo de tiempo de navegador. Un navegador que se puede controlar es una máquina de falsificación de solicitudes dentro de su red. Quien alcance ese socket puede hacer que consulte http://127.0.0.1:8080, la página de administración de su base de datos o la dirección de metadatos de la nube en 169.254.169.254, y después leer la respuesta desde la página. El firewall ve una solicitud procedente del propio VPS, por lo que la permite. Trate el endpoint de control como si equivaliera al acceso shell a ese equipo.

Los servidores MCP tienen el mismo diseño. npx @playwright/mcp@latest --headless --port 8931 sirve contenido mediante HTTP en localhost, y --host 0.0.0.0 es la opción que convierte una herramienta local en una herramienta pública. El README del proyecto indica claramente que Playwright MCP «no es un límite de seguridad». Mantenga el puerto en loopback y permita que el agente acceda a él mediante el mismo túnel.

Las páginas que lee el agente son entradas no confiables

Un agente que navega por la web abierta introduce en el modelo texto escrito por terceros, mientras el modelo también recibe tus instrucciones. Una página puede contener texto dirigido al modelo para indicarle que abandone la tarea, llame a una herramienta o publique datos en una URL. El modelo recibe ambos contenidos como texto, por lo que no puede distinguir de forma fiable las palabras de la página de tus instrucciones. Diseña el entorno de modo que una página hostil tenga poco margen de acción.

  • Ejecuta el navegador con su propio usuario del sistema operativo, sin claves SSH ni credenciales de servicios cloud en su entorno.
  • Usa un contexto nuevo para cada tarea y --isolated con Playwright MCP; cierra el navegador de MCP entre tareas para descartar el almacenamiento de esa sesión.
  • Mantén una lista de permitidos de orígenes cuando el trabajo lo permita. Playwright MCP acepta --allowed-origins y --blocked-origins como listas separadas por punto y coma. Estos filtros no afectan a las redirecciones y no constituyen un límite de seguridad.
  • Exige la intervención de una persona antes de cualquier acción que cambie el estado, como enviar correo o gastar dinero.

Mejor aún, mantén todo el navegador en una máquina que puedas eliminar y reconstruir. El mismo principio se aplica a ejecutar agentes de código en una VM desechable. Si el trabajo real del agente es buscar y no navegar de forma abierta, una herramienta más limitada es más segura que un navegador completo: una skill de búsqueda respaldada por tu propio SearXNG devuelve resultados sin cargar nunca la página hostil.

FAQ

¿Por qué Chromium se bloquea en Docker, pero funciona correctamente directamente en el mismo VPS?

Porque el contenedor obtiene 64 MB de /dev/shm de forma predeterminada, mientras que el host tiene uno mucho mayor. Chromium procesa el contenido renderizado mediante esa área de memoria compartida. Por eso, una página pesada puede llenarla y hacer que muera el proceso de renderizado. Ejecute df -h /dev/shm dentro del contenedor para confirmarlo. Después, inicie el contenedor con --ipc=host, que usa la memoria compartida del host, o con --shm-size=1g, que amplía la memoria propia del contenedor. --disable-dev-shm-usage sólo traslada el problema a /tmp. Playwright 1.62 aplica esa opción de forma predeterminada. Use ignoreDefaultArgs: ['--disable-dev-shm-usage'] para que Chromium utilice la memoria compartida que dimensionó.

¿Es seguro usar --no-sandbox si el VPS no ejecuta nada más?

No. El sandbox impide que una página maliciosa acceda al resto de la máquina. Las páginas de seguridad de Chromium indican lo siguiente sobre esa opción: "No recomendamos usarla porque reducirá considerablemente la seguridad y puede impedir que Chromium funcione correctamente". Un agente que sigue enlaces navega por la web abierta. Corrija la causa en su lugar: no ejecute el navegador como root. En Ubuntu 24.04, añada un perfil de AppArmor que incluya userns, para la ruta del binario del navegador. Así, los espacios de nombres de usuario sin privilegios se permiten sólo para ese programa. Habilite el sandbox explícitamente con chromiumSandbox: true. En Docker, use también el perfil seccomp recomendado por Playwright.

¿Cuántos navegadores puedo ejecutar en un VPS pequeño?

Mídalo. No copie una cifra. Chromium inicia un proceso de renderizado por sitio, por lo que la respuesta depende de las páginas que abra. Ejecute un worker con systemd-run y establezca MemoryMax. Lea el pico de la línea Memory: en systemctl status. Después, divida la RAM libre por ese pico y deje margen. Aplique el límite dos veces: use una cola en el código y un MemoryMax en el archivo de unidad. Así, una ráfaga de solicitudes espera en lugar de hacer que la máquina use swap.

¿Puede mi agente conectarse al navegador desde otra máquina?

Sí, pero nunca vincule el puerto a 0.0.0.0. El endpoint del servidor de Playwright y el puerto de Chrome DevTools aceptan cualquier cliente que pueda acceder a ellos y no requieren contraseña. Mantenga el listener en 127.0.0.1 y transporte la conexión mediante un túnel SSH o una VPN privada. Verifique ss -ltnp en el servidor y compruebe el puerto desde el exterior. Revise también el firewall de red independiente de su proveedor.

¿Por qué mis capturas de pantalla aparecen en blanco si la página se cargó correctamente?

Faltan fuentes. Si no hay ninguna fuente que cubra el script de la página, el texto se muestra como cuadros vacíos o no se muestra. Por eso, una página con pocas imágenes puede producir una captura que parece estar en blanco. Ejecute fc-match "sans-serif:lang=ko" para cada idioma que extraiga. Instale fonts-noto-core y fonts-noto-cjk cuando la respuesta sea una alternativa genérica. Reinicie el navegador para que fontconfig vuelva a cargar su caché. Un contenedor sin ninguna fuente registra Fontconfig error: Cannot load default config file al iniciar.

¿Te resultó útil este artículo?