Cómo auto-alojar SimplePDF Copilot

Benjamin André-Micolon

SimplePDF Copilot es una implementación de referencia con licencia MIT para añadir una barra lateral de chat con IA al editor de SimplePDF. Puedes hacer un fork de la aplicación Copilot, desplegarla en tu propia infraestructura, conectar tu propio proveedor de IA y enrutar los documentos completados a tu propio almacenamiento.

El editor de SimplePDF en sí sigue siendo un iframe alojado. Auto-alojar Copilot significa que tú eres dueño de la aplicación de chat, del enrutamiento de IA, de los prompts, de las herramientas y del flujo de almacenamiento alrededor del editor.

Esta guía cubre el camino desde localhost hasta producción.

Si usas Claude Code, Codex u otra herramienta de codificación agéntica, apúntala a la habilidad fork-and-go. La habilidad guía al agente a través del fork, la configuración y el despliegue, una pregunta a la vez.

Qué auto-alojas

Aplicación de chat Copilot. Se ejecuta en tu infraestructura. Tú la controlas.
Prompt del sistema y registro de herramientas. Viven en tu despliegue de Copilot. Tú los controlas.
Enrutamiento de IA. En el lado servidor, BYOK en el navegador o endpoint local. Tú lo controlas.
Almacenamiento de documentos completados. Almacenamiento de SimplePDF por defecto, o tu almacenamiento con BYOS. Tú lo controlas cuando BYOS está activado.
Iframe del editor SimplePDF. Sigue alojado por SimplePDF.

Requisitos previos

Un plan SimplePDF Pro o superior. Ejecutar Copilot en tu propio dominio requiere white-labeling, control programático del editor y un origen permitido en tu panel de SimplePDF. Sin esas capacidades, el editor solo se carga en el origen de la demo alojada o en http://localhost:3001.
Una clave de un proveedor de IA, un flujo BYOK o un endpoint local compatible con OpenAI. Anthropic, OpenAI, DeepSeek, Google Gemini y Mistral están integrados de fábrica.
Un runtime Node 24. La plantilla actual de despliegue de Copilot usa Node 24 y la aplicación se ejecuta sin modificaciones en DigitalOcean App Platform, Cloudflare Containers, Vercel, Render, fly.io, Railway o Docker auto-alojado.

Paso 1: Ejecuta la demo en local

Clona el repositorio y ejecuta la demo contra el espacio de demo compartido de SimplePDF. Para este paso no se requiere ninguna cuenta de SimplePDF.

git clone https://github.com/SimplePDF/simplepdf-embed.git
cd simplepdf-embed/copilot
npm install
cp .env.example .env
printf "\nVITE_SIMPLEPDF_COMPANY_IDENTIFIER=spdf-copilot\n" >> .env
npm run dev

El servidor de desarrollo corre en http://localhost:3001. Abre la barra lateral del chat, pega una clave de proveedor o apunta a un endpoint local compatible con OpenAI como Ollama o LM Studio.

El espacio de demo permite exactamente un único origen local: http://localhost:3001. Cualquier otro puerto u host será rechazado por el iframe. Para ejecutar en tu propio dominio, continúa al Paso 2.

Paso 2: Configura tu cuenta de SimplePDF

Suscríbete al plan Pro o superior. Desde el panel de SimplePDF:

Copia tu companyIdentifier. Este es el valor que pondrás en VITE_SIMPLEPDF_COMPANY_IDENTIFIER.
Añade a la lista blanca tu origen de servicio, por ejemplo https://app.example.com. El iframe se niega a cargar en orígenes que no estén en la lista blanca.
Opcionalmente, personaliza tu marca para retirar los elementos de SimplePDF del editor.

Paso 3: Despliega en tu host

El camino más rápido es el botón de despliegue de un clic en DigitalOcean del README de SimplePDF Copilot. DigitalOcean compila la carpeta copilot/ con Node 24 y solicita las variables de entorno.

VITE_SIMPLEPDF_COMPANY_IDENTIFIER (requerida): el identificador de tu empresa SimplePDF.
SHARED_API_KEYS (opcional): permite compartir una demo sin pedir a cada visitante que pegue una clave de proveedor.
REDIS_URL (opcional): persiste los contadores de límite de tasa entre contenedores.
IP_HASH_SALT (requerida cuando REDIS_URL está definido): sala los hashes de IP persistidos.

Para otros destinos de despliegue, incluyendo Cloudflare Containers, Vercel, Render, fly.io, Railway y Docker auto-alojado, sigue la sección de otros destinos de despliegue del README.

Una vez desplegado, añade el origen desplegado, por ejemplo https://copilot.example.com, a la lista blanca de tu panel de SimplePDF antes de abrir la aplicación.

Paso 4: Conecta tu proveedor de IA

El streaming en el lado servidor vive en src/routes/api/chat.ts. La selección de proveedor vive en src/server/language_model.ts. Usa esta ruta cuando tu aplicación sea dueña de la clave de proveedor, los límites de tasa, los logs y la configuración por inquilino.

Para claves proporcionadas por el usuario, la ruta BYOK directa desde el navegador en src/lib/byok/ llama al proveedor desde el navegador y omite tu servidor. Esta es también la forma adecuada para endpoints locales compatibles con OpenAI como Ollama o LM Studio.

Tres rutas, tres fronteras de confianza:

Clave de proveedor en el servidor. Tu aplicación es dueña de la cuenta del proveedor y de la política por inquilino. El tráfico de IA fluye a través de tu servidor hasta el proveedor de IA.
BYOK en el navegador. Los usuarios traen su propia clave de proveedor. El tráfico de IA fluye desde el navegador directamente al proveedor seleccionado, sin pasar por tu servidor.
Endpoint local compatible con OpenAI. El tráfico de IA permanece en el dispositivo o la red del usuario. El navegador habla con el endpoint local; nada va a un proveedor de IA externo.

Paso 5: Enruta los envíos a tu propio almacenamiento

Por defecto, los documentos completados aterrizan en el almacenamiento de SimplePDF. Con Bring Your Own Storage desde Pro, los documentos completados se suben directamente desde el navegador a tu almacenamiento configurado usando URLs prefirmadas.

Esto cambia la ruta de almacenamiento de los documentos completados. Por sí solo, no controla qué contexto del documento se envía al proveedor de IA configurado. Configura la ruta de IA por separado en el Paso 4.

Configurar el almacenamiento:

Paso 6: Verifica la configuración en producción

Antes de compartir la aplicación con los usuarios, verifica la ruta completa de extremo a extremo:

Abre la URL de Copilot desplegada desde el origen de la lista blanca.
Confirma que el iframe del editor SimplePDF se carga sin errores de origen.
Envía un prompt de prueba y confirma que se usa la ruta de IA seleccionada.
Rellena un campo y confirma que el valor aparece en el editor PDF.
Envía o descarga un documento de prueba.
Si BYOS está activado, confirma que el PDF completado aterriza en tu almacenamiento, no en el de SimplePDF.
Revisa los logs en busca de secretos, texto del documento, PHI, PII u otros datos sensibles que no quieras persistir.

Personaliza el prompt del sistema y las herramientas

Una vez que Copilot funcione de extremo a extremo en tu infraestructura, la siguiente capa de personalización es el prompt del sistema y el registro de herramientas expuesto al modelo. Ambos viven en src/server/tools.ts. La interfaz de chat en sí es src/components/chat_pane.tsx. Los locales están en src/locales/.

Para todo lo demás, incluyendo forkear, configurar y adaptar Copilot a una superficie de producto no trivial, la habilidad fork-and-go guía a un asistente de codificación con IA a través del trabajo, una decisión a la vez.

Solución de problemas

El iframe del editor se niega a cargar

Comprueba que el origen de la aplicación padre esté en la lista blanca del panel de SimplePDF. El espacio de demo local solo permite http://localhost:3001.

La demo local funciona pero la producción no

Confirma que VITE_SIMPLEPDF_COMPANY_IDENTIFIER usa tu propio identificador de empresa SimplePDF y que tu dominio de producción está en la lista de orígenes permitidos.

Se pide a los usuarios que peguen una clave de IA

Eso es lo esperado en modo BYOK. Para compartir una demo preconfigurada, configura SHARED_API_KEYS y usa el flujo de URL ?share=<id>.

Los límites de tasa se reinician en cada despliegue

Los límites de tasa en memoria se reinician cuando la aplicación se reinicia. Usa REDIS_URL y IP_HASH_SALT si los contadores deben persistir entre contenedores o reinicios.

Los PDF completados no llegan a tu almacenamiento

Confirma que Bring Your Own Storage está configurado en SimplePDF y prueba con un PDF pequeño antes de usar formularios en producción.

¡Eso es todo! Tu aplicación Copilot ahora se ejecuta en tu infraestructura, usa la ruta de IA que has configurado y puede enviar los documentos completados a tu almacenamiento cuando BYOS está activado.

Si tienes alguna pregunta, no dudes en contactarnos en support@simplepdf.com