Instalar kody-celld: Guía Completa y Verificada

kody-celld es una reimplementación independiente de kody.codes diseñada para tu propio hardware. Reproduce el mismo contrato MCP (search + execute, paquetes, secretos, jobs) que ofrece la versión en la nube de Cloudflare, pero como servicio local autocontenido.

¿Qué es kody-celld?

kody-celld ejecuta en Deno celld — el modelo de programación Cloudflare Workers + Durable Objects en tus propias máquinas, con un bucket S3 compatible para durabilidad. Se puede usar como:

• Componente in-situ de un servicio existente
• Capa integrada completa autocontenida
• Servicio local sin requerir cuenta ni dominio Cloudflare

Prerrequisitos

Instalación con Docker (5 minutos)

Paso 1: Crear compose.yaml

Guarda este archivo en una carpeta o pégalo en el UI de Compose/"stack" de tu NAS:

services:
 kody:
  image: ghcr.io/kentcdodds/kody-celld:latest
  init: true
  restart: unless-stopped
  ports:
   - '8080:8080'
  environment:
   # La dirección exacta que escribirás en el navegador / darás a clientes MCP.
   # Las cookies de sign-in y OAuth redirects están vinculadas a esto, así que debe coincidir:
   # máquina local -> http://localhost:8080 (como abajo)
   # NAS / VPS en tu LAN -> http://192.168.1.20:8080 o http://nas.local:8080
   # detrás de reverse proxy -> https://kody.example.com
   KODY_PUBLIC_URL: http://localhost:8080
  volumes:
   - kody-data:/data
volumes:
 kody-data:

Nota importante: Los comandos usan http://localhost:8080; si configuras un KODY_PUBLIC_URL diferente, usa ese en lugar de localhost (localhost solo funciona desde la máquina que ejecuta Docker).

Paso 2: Iniciar el contenedor

docker compose up -d

El contenedor se iniciará en segundo plano. El pull de la imagen tomará aproximadamente un minuto.

Paso 3: Verificar salud

curl http://localhost:8080/health # {"ok":true, ...}

Deberías recibir una respuesta JSON con {"ok":true}.

Paso 4: Leer y respaldar admin token

docker compose exec kody cat /data/kody.env # KODY_ADMIN_TOKEN + KODY_MASTER_KEY — back this up

CRÍTICO: Copia estos valores en un archivo seguro. Son necesarios para la configuración inicial y no se muestran después.

Paso 5: Crear tu cuenta

Abre http://localhost:8080/ en un navegador. La página Set up Kody te pedirá:

• Admin token (copiado del paso 4)
• Tu email
• Contraseña

Esto te iniciará sesión en /account. Si creaste el primer usuario con la admin API, /setup desaparecerá; inicia sesión en /signin con el token kc_… que devolvió, luego establece contraseña en /account.

Paso 6: Conectar un MCP client

claude mcp add --transport http kody http://localhost:8080/mcp

Cursor / VS Code / Claude Desktop: añade un HTTP MCP server con esa URL. Los clientes que solo toman URL + header usan token estático de /account/tokens:

Authorization: Bearer kc_…

Pide "search Kody" — deberías recibir el capability catalog.

Instalación sin Docker (local)

Prerrequisitos: Node ≥ 24.3, celld ≥ 0.6 en tu PATH (install), y npm install (proporciona eesbuild, que celld usa para bundle el Worker).

# Clonar repositorio
git clone https://github.com/kentcdodds/kody-celld && cd kody-celld

# Instalar dependencias
npm install

# Iniciar desarrollo
npm run dev # celld dev . --port 8787 (state persists in .celld/dev)

En otra terminal:

# Smoke test completo
npm run smoke # mcp, packages, secrets, jobs, limits, memory, blobs, browser, webhooks, email, integrations, secret-providers, oauth-server, web, npm, install, community against http://127.0.0.1:8787

# Smoke test con cron real
npm run smoke:cron # same, plus waits (~60s) for celld's real cron trigger to run a job

Nota: La dev config envía valores placeholder KODY_ADMIN_TOKEN / KODY_MASTER_KEY en wrangler.jsonc. Solo funcionan contra loopback: el Worker se niega a servir requests no-loopback mientras esos placeholders están en efecto. Pon valores reales en un .dev.vars file (git-ignored) si quieres exponer un dev node.

Backup

CRÍTICO: Todo (users, packages, secrets, jobs, blobs, kody.env) está en el volumen kody-data. Nada se escribe en otro lado; borrar el contenedor es seguro, docker compose down -v NO.

# Backup completo
docker compose stop && \
docker run --rm -v <project>_kody-data:/data -v "$PWD":/backup alpine tar czf /backup/kody-data.tgz -C / data && \
docker compose start

# Restaurar (descomprimir en el volumen)
# Descomprime kody-data.tgz dentro del volumen kody-data

Upgrade

# Pull nueva imagen
docker compose pull && docker compose up -d

# Desde source checkout:
git pull && docker compose up -d --build

# State y generated keys se mantienen

TLS / Reverse Proxy

Coloca tu reverse proxy (Synology Reverse Proxy, Nginx Proxy Manager, Caddy, Traefik) delante de 8080 con un certificado y establece:

KODY_PUBLIC_URL=https://kody.example.com

No expongas el puerto 8080 directamente.

Logs

docker compose logs -f kody

Failover (Fleet)

Para dos o más nodos compartiendo un bucket S3-compatible (MinIO bundled): compose.fleet.yaml — ver la guía.

Errores Habituales

Seguridad

• Secrets: AES-GCM encrypted con per-user HKDF key derivada de KODY_MASTER_KEY. Run history registra secret names only.
• Host approval: Los sandbox code no pueden aprobar hosts, leer valores o alcanzar /admin.
• HTTPS required: Las llamadas externas requieren HTTPS (excepto loopback hosts en KODY_ALLOW_INSECURE_SECRET_HOSTS).
• Master key rotation: Usa KODY_MASTER_KEY_PREVIOUS + POST /admin/secrets/rekey.
• Package security: packageInstall con host allowlist + SSRF guard, per-install /community catalog.

FAQ

¿Puedo usar kody-celld sin dominio?

Sí. No requiere cuenta ni dominio Cloudflare. Funciona perfectamente en LAN/Tailscale.

¿Cómo actualizar los secretos de forma segura?

Los secrets se cifran con AES-GCM usando una key derivada de KODY_MASTER_KEY. Para rotación:

KODY_MASTER_KEY_PREVIOUS=old-key
POST /admin/secrets/rekey

¿Cómo conectar MCP clients que no soportan OAuth?

Usa token estático de /account/tokens:

Authorization: Bearer kc_…

¿Cómo verificar que todo funciona?

Ejecuta:

npm run smoke # Verifica mcp, packages, secrets, jobs, limits, memory, blobs, browser, webhooks, email, integrations

Documentación Adicional

• docs/getting-started.md — walkthrough completo
• docs/architecture.md — arquitectura
• docs/decision-standalone-vs-adapters.md — por qué es standalone
• docs/packages.md — paquetes
• docs/secrets.md — secretos
• docs/operations.md — límites, cuotas y audit
• docs/ai.md — AI, memories y semantic search
• docs/blobs.md — blobs y browser rendering
• docs/npm.md — npm imports
• docs/email.md — email
• docs/webhooks.md — webhooks
• docs/integrations.md — OAuth integrations
• docs/web-ui.md — sign-in + web UI
• docs/community.md — community catalog
• docs/mcp-oauth.md — MCP OAuth 2.1
• docs/secret-providers.md — provider-backed secrets
• docs/known-gaps.md — provision matrix y limitaciones

Licencia

FSL-1.1-ALv2 (same as kody).