Cómo instalar Paperclip AI en un VPS Ubuntu y publicarlo con Cloudflare Tunnel
Guía paso a paso para instalar Paperclip AI en un VPS, dejarlo como servicio y exponerlo de forma segura con un subdominio en Cloudflare.
En esta guía vamos a instalar Paperclip AI en un servidor Ubuntu, dejarlo funcionando como servicio del sistema y publicarlo de forma segura mediante Cloudflare Tunnel, sin abrir el puerto 3100 directamente a Internet.
La idea es montar una instalación sencilla, práctica y segura:
Usuario
↓
https://paperclip.tudominio.com
↓
Cloudflare Tunnel
↓
http://127.0.0.1:3100
↓
Paperclip AI en el VPS
Con esta arquitectura, Paperclip queda escuchando solo en localhost, y Cloudflare Tunnel se encarga de exponerlo mediante HTTPS usando un subdominio propio.
Requisitos previos
Necesitas:
Servidor Ubuntu 22.04 / 24.04
Dominio gestionado en Cloudflare
Acceso SSH al servidor
Usuario no root con permisos sudo
Node.js 20 o superior
En este ejemplo usaremos:
Usuario Linux: moises
Subdominio: paperclip.tudominio.com
Puerto interno de Paperclip: 3100
Sustituye estos valores por los tuyos.
1. Crear un usuario con permisos sudo
Entra como root en el servidor y crea el usuario:
adduser moises
Añádelo al grupo sudo:
usermod -aG sudo moises
Comprueba que el usuario pertenece al grupo sudo:
groups moises
Deberías ver algo parecido a:
moises : moises sudo
A partir de este punto, trabaja con el usuario normal:
su - moises
Comprueba que estás usando el usuario correcto:
whoami
Debe responder:
moises
2. Instalar Node.js 22
Comprueba la versión actual de Node y npm:
node -v
npm -v
Paperclip necesita Node.js 20 o superior. Si tienes una versión inferior, instala Node.js 22 usando NodeSource:
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
Verifica la instalación:
node -v
npm -v
Ejemplo de salida válida:
v22.22.2
10.9.7
3. Instalar y arrancar Paperclip
Ejecuta Paperclip con el usuario normal, no con sudo:
npx paperclipai onboard --yes
Es importante no usar sudo, porque Paperclip guarda su configuración en la carpeta del usuario:
/home/moises/.paperclip
Si lo ejecutas con sudo, podrías generar archivos propiedad de root y luego tener problemas de permisos.
Si todo va bien, verás algo parecido a:
Mode embedded-postgres | static-ui
Deploy local_trusted
Bind loopback (127.0.0.1)
Server 3100
UI http://127.0.0.1:3100
Database /home/moises/.paperclip/instances/default/db
La línea importante es:
Server listening on 127.0.0.1:3100
Eso significa que Paperclip está funcionando, pero solo accesible desde el propio servidor.
4. Probar Paperclip mediante túnel SSH
Desde tu ordenador local puedes crear un túnel SSH hacia el servidor:
ssh -L 3100:127.0.0.1:3100 moises@IP_DEL_SERVIDOR
Después abre en tu navegador:
http://127.0.0.1:3100
Si ves la interfaz de Paperclip, la instalación básica está correcta.
5. Crear un servicio systemd para Paperclip
Ahora vamos a dejar Paperclip funcionando como servicio. Así arrancará automáticamente al reiniciar el servidor y se levantará de nuevo si se cae.
Primero detén Paperclip si lo tienes ejecutándose en primer plano:
CTRL + C
Comprueba que el puerto quedó libre:
ss -ltnp | grep ':3100' || echo "Puerto 3100 libre"
Crea el servicio:
sudo tee /etc/systemd/system/paperclip.service > /dev/null <<'EOF'
[Unit]
Description=Paperclip AI
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=moises
Group=moises
WorkingDirectory=/home/moises
Environment=HOME=/home/moises
Environment=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
ExecStart=/usr/bin/npx --yes paperclipai run
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
EOF
Recarga systemd y activa el servicio:
sudo systemctl daemon-reload
sudo systemctl enable --now paperclip
sudo systemctl status paperclip --no-pager
Debe aparecer algo como:
Active: active (running)
Prueba la salud de la API:
curl http://127.0.0.1:3100/api/health
6. Comandos útiles para Paperclip
Ver estado:
sudo systemctl status paperclip --no-pager
Reiniciar:
sudo systemctl restart paperclip
Detener:
sudo systemctl stop paperclip
Iniciar:
sudo systemctl start paperclip
Ver logs en vivo:
journalctl -u paperclip -f
7. Instalar pnpm
Aunque Paperclip puede arrancar con npx, algunas instrucciones de su documentación usan pnpm.
Como estamos usando Node moderno, podemos activar pnpm mediante Corepack:
sudo corepack enable
corepack prepare pnpm@latest --activate
pnpm -v
8. Instalar cloudflared
Ahora instalaremos cloudflared, el servicio que permitirá conectar nuestro VPS con Cloudflare Tunnel.
Añade el repositorio oficial de Cloudflare:
sudo mkdir -p --mode=0755 /usr/share/keyrings
curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg \
| sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared any main" \
| sudo tee /etc/apt/sources.list.d/cloudflared.list
sudo apt-get update
sudo apt-get install -y cloudflared
cloudflared --version
9. Autenticar cloudflared con Cloudflare
Ejecuta:
cloudflared tunnel login
El comando mostrará una URL.
Abre esa URL en el navegador, inicia sesión en Cloudflare y selecciona el dominio que quieres usar.
Cuando termine correctamente, verás algo parecido a:
You have successfully logged in.
10. Crear el túnel
Crea un túnel para Paperclip:
cloudflared tunnel create paperclip-tonyhelper
El comando devolverá un ID parecido a:
Created tunnel paperclip-tonyhelper with id XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Ahora crea el registro DNS del subdominio:
cloudflared tunnel route dns paperclip-tonyhelper paperclip.tudominio.com
11. Configurar el túnel
Obtén el ID del túnel:
TUNNEL_ID=\((cloudflared tunnel list | awk '/paperclip-tonyhelper/ {print \)1; exit}')
echo $TUNNEL_ID
Crea la configuración:
sudo mkdir -p /etc/cloudflared
sudo cp ~/.cloudflared/\({TUNNEL_ID}.json /etc/cloudflared/\){TUNNEL_ID}.json
sudo tee /etc/cloudflared/config.yml > /dev/null <<EOF
tunnel: ${TUNNEL_ID}
credentials-file: /etc/cloudflared/${TUNNEL_ID}.json
ingress:
- hostname: paperclip.tudominio.com
service: http://127.0.0.1:3100
- service: http_status:404
EOF
sudo chmod 600 /etc/cloudflared/${TUNNEL_ID}.json
sudo chmod 644 /etc/cloudflared/config.yml
Prueba el túnel manualmente:
sudo cloudflared tunnel --config /etc/cloudflared/config.yml run
Si ves líneas como estas, está funcionando:
Registered tunnel connection
Detén la prueba manual:
CTRL + C
12. Instalar cloudflared como servicio
Instala y arranca el servicio:
sudo cloudflared service install
sudo systemctl enable --now cloudflared
sudo systemctl status cloudflared --no-pager
Debe aparecer:
Active: active (running)
13. Permitir el hostname público en Paperclip
Al entrar por el dominio, Paperclip puede mostrar este mensaje:
Hostname 'paperclip.tudominio.com' is not allowed for this Paperclip instance.
Esto ocurre porque Paperclip, por seguridad, solo acepta determinados hostnames.
Para permitir el subdominio, ejecuta:
pnpm dlx paperclipai allowed-hostname paperclip.tudominio.com
Si pnpm pregunta qué paquetes puede construir, selecciona todos:
a
Enter
Después reinicia Paperclip:
sudo systemctl restart paperclip
sudo systemctl status paperclip --no-pager
14. Probar el dominio
Desde el servidor puedes probar:
curl -I https://paperclip.tudominio.com
Desde el navegador abre:
https://paperclip.tudominio.com
Si todo está correcto, ya deberías ver Paperclip desde tu dominio.
15. Recomendación de seguridad
Aunque Paperclip ya está detrás de Cloudflare Tunnel, no conviene dejarlo expuesto públicamente sin control de acceso.
Lo recomendable es proteger el subdominio con Cloudflare Access, permitiendo solo usuarios autorizados.
La arquitectura ideal sería:
paperclip.tudominio.com
↓
Cloudflare Access
↓
Cloudflare Tunnel
↓
127.0.0.1:3100
↓
Paperclip
Así evitas que cualquier persona con la URL pueda acceder al panel.
16. Comandos finales de mantenimiento
Ver estado de Paperclip:
sudo systemctl status paperclip --no-pager
Reiniciar Paperclip:
sudo systemctl restart paperclip
Ver logs de Paperclip:
journalctl -u paperclip -f
Ver estado de Cloudflare Tunnel:
sudo systemctl status cloudflared --no-pager
Reiniciar Cloudflare Tunnel:
sudo systemctl restart cloudflared
Ver logs de Cloudflare Tunnel:
journalctl -u cloudflared -f
17. Resumen
Con esta instalación conseguimos:
Paperclip funcionando en Ubuntu
Base de datos PostgreSQL embebida
Servicio systemd con autoarranque
Reinicio automático si se cae
Publicación mediante Cloudflare Tunnel
Subdominio propio
Sin abrir el puerto 3100 al exterior
Esta es una buena base para empezar a usar Paperclip como panel de control para agentes de IA y automatizaciones.
18. Próximos pasos
Después de esta instalación, lo recomendable sería:
Proteger el dominio con Cloudflare Access
Configurar backups externos
Revisar actualizaciones de Paperclip
Conectar modelos de IA
Crear los primeros agentes
Integrarlo con herramientas como GitHub, n8n o servicios internos
Con esto ya tienes Paperclip instalado, persistente y accesible desde un dominio propio de forma segura.