← Volver al listado de tecnologías ← Índice de Paperclip

Instalación y primeros pasos

Por: Artiko
paperclipinstalaciónconfiguracióndocker

Antes de empezar: requisitos del sistema

Paperclip es un servidor Node.js con React en el frontend. Los requisitos son deliberadamente simples para reducir la fricción de adopción. No necesitas configurar PostgreSQL por separado en instalaciones locales: el sistema incluye una base de datos embebida que funciona sin ningún setup adicional.

Requisitos mínimos:

Verificar las versiones antes de empezar:

node --version    # debe ser v20.x.x o superior
pnpm --version    # debe ser 9.15.x o superior

Si Node.js no está instalado o la versión es antigua, la forma más limpia de gestionarlo es con nvm o fnm:

# Con fnm (recomendado, más rápido)
curl -fsSL https://fnm.vercel.app/install | bash
fnm install 20
fnm use 20

# Con nvm (alternativa clásica)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
nvm use 20

Para instalar pnpm si no lo tienes:

npm install -g pnpm@latest
# o con corepack (incluido en Node.js 16+)
corepack enable
corepack prepare pnpm@latest --activate

Método 1: npx onboard (recomendado para empezar rápido)

El método más rápido para tener Paperclip funcionando es el comando onboard. Este comando descarga, configura y arranca todo con una sola línea:

npx paperclipai onboard --yes

El flag --yes acepta todos los valores por defecto sin preguntar. Si lo omites, el instalador te hará preguntas interactivas sobre el directorio de instalación, el puerto, y otras opciones.

¿Qué hace este comando exactamente?

  1. Descarga el paquete paperclipai desde npm.
  2. Crea el directorio ~/.paperclip/ en tu home.
  3. Inicializa la base de datos embebida (SQLite en modo desarrollo).
  4. Genera un archivo de configuración en ~/.paperclip/config.json.
  5. Arranca el servidor en el puerto 3100.
  6. Abre automáticamente el navegador en http://localhost:3100.

El proceso completo tarda menos de 2 minutos en una conexión decente. Al terminar, verás algo así en la terminal:

✓ Paperclip installed successfully
✓ Database initialized
✓ Server started on port 3100

Open your browser at: http://localhost:3100

To stop the server: npx paperclipai dev:stop
To start again:     npx paperclipai run

Limitaciones del método npx: Este método es ideal para exploración y desarrollo. Para producción, se recomienda el método de instalación manual o Docker, que dan más control sobre la configuración.

Método 2: Clonado manual del repositorio

Para desarrollo del propio Paperclip, para contribuir al proyecto, o para tener control total sobre la instalación, el método manual es el camino correcto.

# Clonar el repositorio
git clone https://github.com/paperclipai/paperclip.git
cd paperclip

# Instalar dependencias
pnpm install

# Configurar variables de entorno
cp .env.example .env

El archivo .env.example contiene todas las variables con sus valores por defecto:

# .env - Configuración básica

# Base de datos PostgreSQL
# En desarrollo local, puedes usar la cadena embebida
DATABASE_URL=postgres://paperclip:paperclip@localhost:5432/paperclip

# Puerto del servidor de la API
PORT=3100

# Si el servidor debe servir también la UI de React
# false = UI y API en el mismo proceso (recomendado para desarrollo)
# true = sirve solo la API, útil para deployments separados
SERVE_UI=false

# Modo de autenticación
# local_trusted: sin autenticación (solo para uso local)
# authenticated: requiere tokens (para acceso remoto)
AUTH_MODE=local_trusted

# Deshabilitar telemetría (métricas anónimas de uso)
# PAPERCLIP_TELEMETRY_DISABLED=1

Para desarrollo local sin configurar PostgreSQL, Paperclip puede usar una base de datos embebida. Si quieres usar PostgreSQL, necesitas tenerlo corriendo:

# Con Docker (la forma más rápida)
docker run -d \
  --name paperclip-postgres \
  -e POSTGRES_USER=paperclip \
  -e POSTGRES_PASSWORD=paperclip \
  -e POSTGRES_DB=paperclip \
  -p 5432:5432 \
  postgres:16-alpine

# Con PostgreSQL instalado localmente
createdb paperclip
createuser paperclip -P  # te pedirá la contraseña

Una vez configurado el .env, arrancar el servidor de desarrollo:

pnpm dev

Este comando arranca:

Para construir para producción:

pnpm build

Para correr en modo producción (después del build):

pnpm paperclipai run

Para ejecutar los tests:

pnpm test:run

Para verificar tipos TypeScript:

pnpm typecheck

Método 3: Docker

Docker es el método recomendado para producción. Aísla el servidor, simplifica las actualizaciones, y facilita el despliegue en cualquier nube.

Construcción de la imagen:

# Clonar el repo o tener el Dockerfile
git clone https://github.com/paperclipai/paperclip.git
cd paperclip

# Construir la imagen
docker build -t paperclip-local .

El Dockerfile usa construcción multi-stage para minimizar el tamaño de la imagen final:

# Dockerfile (simplificado para ilustración)
FROM node:20-alpine AS builder
WORKDIR /app
RUN npm install -g pnpm
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build

FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
EXPOSE 3100
CMD ["node", "dist/server.js"]

Ejecutar el contenedor:

docker run -d \
  --name paperclip \
  -p 3100:3100 \
  -e DATABASE_URL="postgres://user:pass@host:5432/paperclip" \
  -e PORT=3100 \
  -e AUTH_MODE=local_trusted \
  -v paperclip-data:/app/data \
  paperclip-local

Con docker-compose (recomendado para incluir PostgreSQL):

# docker-compose.yml
version: '3.8'

services:
  paperclip:
    build: .
    ports:
      - "3100:3100"
    environment:
      DATABASE_URL: postgres://paperclip:paperclip@postgres:5432/paperclip
      PORT: 3100
      AUTH_MODE: local_trusted
      SERVE_UI: "false"
    depends_on:
      postgres:
        condition: service_healthy
    volumes:
      - paperclip-data:/app/data
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: paperclip
      POSTGRES_PASSWORD: paperclip
      POSTGRES_DB: paperclip
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U paperclip"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  paperclip-data:
  postgres-data:

Arrancar con docker-compose:

docker-compose up -d

# Ver logs
docker-compose logs -f paperclip

# Parar
docker-compose down

Estructura de directorios generados

Después de la instalación, Paperclip crea varios directorios. Entender su propósito te ayuda a hacer backups correctos y entender dónde vive qué.

Instalación con npx onboard:

~/.paperclip/
├── config.json          # Configuración principal del servidor
├── data/                # Datos de la base de datos embebida
│   ├── paperclip.db     # Base de datos SQLite (dev local)
│   └── attachments/     # Archivos adjuntos de tareas
├── companies/           # Exports de empresas
│   └── example-co/
│       ├── org.json     # Estructura del org chart
│       └── goals.json   # Iniciativas y goals
└── logs/                # Logs del servidor
    ├── server.log
    └── agents.log

Instalación manual (clonado):

La instalación manual mantiene todo dentro del directorio del repositorio. El directorio data/ se crea en la raíz del proyecto y está en .gitignore para no commitear datos:

paperclip/
├── src/                 # Código fuente del servidor
├── ui/                  # Código fuente de la UI React
├── dist/                # Build de producción (generado)
├── data/                # Datos locales (en .gitignore)
│   └── paperclip.db
├── .env                 # Tu configuración (en .gitignore)
├── .env.example         # Plantilla de configuración
├── package.json
└── pnpm-lock.yaml

Verificar que la instalación funciona

Una vez que el servidor está corriendo, verificar con curl:

# Health check del servidor
curl http://localhost:3100/api/health

# Respuesta esperada:
# {"status":"ok","version":"x.y.z","uptime":42}

Si obtienes esa respuesta, el servidor está funcionando correctamente. Si obtienes un error de conexión, verificar:

# Ver si el proceso está corriendo
lsof -i :3100
# o
netstat -tlpn | grep 3100

# Ver logs del servidor
tail -f ~/.paperclip/logs/server.log
# o si es instalación manual
tail -f ./logs/server.log

Explorar la UI por primera vez

Abre http://localhost:3100 en el navegador. La primera vez que accedes a una instalación limpia verás el onboarding wizard, que te guía en cuatro pasos:

flowchart LR
    A[Bienvenida] --> B[Crear primera empresa]
    B --> C[Configurar Board]
    C --> D[Tutorial interactivo]
    D --> E[Dashboard principal]

Paso 1 — Bienvenida: Una introducción breve a la filosofía de Paperclip. Puedes saltarla.

Paso 2 — Crear primera empresa: Te pide un nombre, descripción, e industria para tu primera Company. Esto crea la entidad principal en la base de datos.

Paso 3 — Configurar el Board: Defines quién eres tú como Board member. Nombre, email (para notificaciones), y nivel de supervisión deseado (mínima intervención / supervisión activa / control total).

Paso 4 — Tutorial interactivo: Un tour por la UI que muestra el org chart, el sistema de tickets, y los controles del Board. Altamente recomendable en el primer uso.

Después del onboarding, llegas al Dashboard principal, que tiene cinco secciones:

Comandos de gestión del servidor

Paperclip incluye comandos para gestionar el ciclo de vida del servidor desde la terminal:

# Listar todos los procesos de Paperclip corriendo
npx paperclipai dev:list

# Salida esperada:
# PID    PORT   STATUS    STARTED
# 12345  3100   running   2026-04-05 09:00:00

# Parar el servidor en el puerto 3100
npx paperclipai dev:stop

# Parar todos los servidores de Paperclip
npx paperclipai dev:stop --all

# Arrancar en modo producción (un solo proceso)
pnpm paperclipai run

# Arrancar con un puerto personalizado
PORT=4000 pnpm paperclipai run

Para instalaciones con npx:

# El comando onboard sin --yes muestra opciones interactivas
npx paperclipai onboard

# Ver ayuda de todos los comandos disponibles
npx paperclipai --help

Configuración avanzada del entorno

Además de las variables básicas, Paperclip soporta configuración más fina:

# .env - Variables avanzadas

# Puerto alternativo si el 3100 está ocupado
PORT=3200

# URL base para webhooks y callbacks (útil detrás de un proxy)
BASE_URL=https://paperclip.midominio.com

# Nivel de logging
LOG_LEVEL=info  # debug | info | warn | error

# Límite de conexiones simultáneas a la base de datos
DB_POOL_SIZE=5

# Timeout para ejecuciones de agentes (en milisegundos)
AGENT_EXECUTION_TIMEOUT=300000  # 5 minutos por defecto

# Máximo de agentes ejecutando simultáneamente
MAX_CONCURRENT_AGENTS=10

# Clave secreta para JWT (si AUTH_MODE=authenticated)
JWT_SECRET=tu-clave-super-secreta-aqui

# Directorio alternativo para datos
DATA_DIR=/ruta/personalizada/para/datos

Actualizar Paperclip

Para mantener Paperclip actualizado con las últimas versiones:

# Con npx (siempre usa la última versión)
npx paperclipai@latest onboard --yes

# Con instalación manual
cd /ruta/al/repo/paperclip
git pull origin main
pnpm install
pnpm build
pnpm paperclipai run

# Con Docker
docker pull paperclipai/paperclip:latest
docker-compose pull
docker-compose up -d

Antes de actualizar, hacer backup de la base de datos:

# Backup SQLite (instalación local)
cp ~/.paperclip/data/paperclip.db ~/.paperclip/data/paperclip.db.backup

# Backup PostgreSQL
pg_dump paperclip > paperclip_backup_$(date +%Y%m%d).sql

Resolución de problemas comunes

El puerto 3100 ya está en uso:

# Encontrar qué proceso usa el puerto
lsof -i :3100

# Matar el proceso (cambiar por el PID encontrado)
kill -9 <PID>

# O usar un puerto alternativo
PORT=3200 npx paperclipai run

Error de permisos en el directorio ~/.paperclip:

# Asegurar que el directorio tiene los permisos correctos
chmod 755 ~/.paperclip
chown -R $USER:$USER ~/.paperclip

La UI no carga pero la API responde:

Verificar que SERVE_UI está en false (o no definido) en el .env. Si está en true, el servidor solo sirve la API y necesitas servir la UI por separado.

# Verificar la variable
echo $SERVE_UI

# Corregir en .env
SERVE_UI=false

Error de conexión a la base de datos:

# Verificar que PostgreSQL está corriendo
pg_isready -h localhost -p 5432

# Verificar la cadena de conexión
psql "$DATABASE_URL" -c "SELECT 1"

El agente no se despierta según el schedule:

El sistema de heartbeats requiere que el servidor esté corriendo continuamente. Si usas pnpm dev, el servidor se recarga ante cambios y puede interrumpir heartbeats programados. Para testing de heartbeats, usa pnpm paperclipai run.

Siguiente paso

Con Paperclip instalado y corriendo, el siguiente capítulo cubre la arquitectura y los conceptos fundamentales: el modelo de datos, cómo fluye el contexto desde los goals hasta los agentes, y el ciclo de vida completo de una tarea. Entender estos conceptos es la base para configurar tu primera empresa con criterio.

← Volver al listado de tecnologías ← Índice de Paperclip