codacle.
DocsIniciá sesión →

Docs · 50

Self-hosting.

Env vars, migrations de Supabase, integración con Anthropic, y cómo correr el worker.

Pre-requisitos

  • Node 20+ con corepack habilitado para pnpm.
  • Cuenta de Supabase — un proyecto nuevo, con la URL y la service-role key a mano.
  • Cuenta de Anthropic con acceso a Managed Agents (skills, agents, environments, memory_stores). Hoy es invite-only — pedilo desde la consola.

Variables de entorno

Las que necesitás en .env.local (en la raíz del monorepo):

# Supabase
SUPABASE_URL=https://xxxx.supabase.co
SUPABASE_SERVICE_ROLE_KEY=eyJ...
NEXT_PUBLIC_SUPABASE_URL=https://xxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

# Worker config
WORKER_POLL_INTERVAL_MS=2000      # cada cuánto polleea jobs
WORKER_MAX_CONCURRENT_JOBS=1      # un job a la vez por default

Las primeras dos las usa supabaseAdmin() (service-role bypass de RLS). Las NEXT_PUBLIC_* están reservadas para client components si llegamos a usar el client directo (hoy todo pasa por server actions).

Aplicar migrations

Todas las migrations son SQL plano en packages/db/migrations/*.sql, numeradas en orden. Para aplicar:

  1. Abrí el SQL Editor de Supabase.
  2. Corré cada archivo en orden (001 → 002 → ... → 010), una a la vez.
  3. Si una falla por "ya existe", chequeá que la versión más reciente del archivo tiene if not exists / if exists en todos los DDL.

Lista actual de tablas que se crean:

  • organizations, users (auth seed)
  • workspaces — la entidad raíz
  • jobs — cola de trabajo del worker
  • vault_atoms — el grafo de conocimiento
  • messages — chat de Barbara
  • kits + kit_publications — catálogo de motores
  • workspace_phases — progreso live por workspace
  • workspace_runs — telemetría de runs (con pricing_snapshot)

Storage buckets

Codacle usa un bucket de Supabase Storage para los archivos subidos por el user. Tenés que crearlo manualmente:

  • Bucket: workspace-files
  • Visibility: private
  • Policy: ninguna (service-role bypasea); si querés bypassear RLS desde el client, agregá una policy que filtre por org_id.

Levantar la web

pnpm install
pnpm --filter web dev

Por default arranca en localhost:3000. La home pública es /, el dashboard en /dashboard, el marketplace en /marketplace. Los docs (este sitio) están en /docs.

Levantar el worker

En otra terminal:

pnpm --filter worker dev

El worker polleea Supabase. Logs visibles directo en consola. Para production usá un process manager (pm2, systemd, supervisord) — el binario es apps/worker/dist/index.js después de pnpm --filter worker build.

Registrar el primer kit

El monorepo no viene con kits pre-registrados. Para tener algo en el marketplace:

pnpm --filter web register-kit --kit-dir ./kits/oracle-forms-to-apex

(Asumiendo que tenés ese directorio. Ver Cómo escribir un kit para crear el tuyo desde cero.)

Después del register, el marketplace muestra el kit. Click → wizard → workspace → job → worker corre → la magia pasa.

Operación de día a día

  • /dashboard — qué hay en vuelo.
  • /ops — telemetría: tokens, costo, success rate, modelos. Filtros por kit + período.
  • /ops/[id] — drill-down a un workspace específico con timeline live.
  • /ops/errors — runs fallidos con sus mensajes de error.
  • /ops/resources — snapshot de los recursos vivos en Anthropic (sessions, environments, memory_stores). Cross-checked contra DB para detectar huérfanos.
  • /kits — catálogo de versions registradas, con publicar/rollback.

Cost monitoring

cost-report corre desde la línea de comandos:

pnpm --filter web cost-report -- --days 30

Imprime totales USD agrupados por kit + modelo. Los precios usados son los del pricing_snapshot capturado al cierre del run — si Anthropic cambia rates después, el reporte sigue mostrando lo que pagaste ese día (no lo que pagarías hoy si re-corrieras todo).

Cleanup periódico

Anthropic Managed Agents factura por recursos vivos (memory_stores principalmente). El worker borra el memory_store al cerrar el job correctamente, pero si algo falla puede quedar huérfano:

pnpm --filter web cleanup-orphaned -- --dry-run

Lista recursos en Anthropic que no aparecen en workspace_runs ni en kits. Sin --dry-run, los borra. Cron mensual recomendado.