Runtime de Codificación Remota

Un runtime de codificación remota neutral respecto al modelo y al cliente, con un plano de control Cloudflare estable y Runners locales solo de salida.

ChatGPT / Claude / Cursor / any MCP client
          │ HTTPS stateless MCP
          ▼
Cloudflare Worker
  Admin UI · RegistryDO · RunnerDO
          │ authenticated outbound WebSocket RPC
          ▼
Local Runner
  filesystem · transactional patch · Git · process · persistent jobs

Cloudflare no ejecuta código ni llama a un modelo de IA. El cliente MCP realiza el razonamiento; el Runner realiza el trabajo de sistema de archivos, Git y procesos. Cerrar el navegador, el chat, la solicitud MCP o el WebSocket del Runner no detiene un trabajo que ya se ha iniciado.

Arquitectura

• Worker: el único endpoint público de MCP/plano de control. Autentica las URLs de los clientes MCP, sirve la pequeña interfaz de administración y enruta mensajes RPC acotados.

• RegistryDO: metadatos SQLite para Runners, espacios de trabajo, trabajos históricos, estado de contraseña/sesión del administrador y credenciales de clientes MCP.

• RunnerDO: un Durable Object hibernable por Runner. Posee el WebSocket saliente actual del Runner y el puente RPC correlacionado; nunca ejecuta trabajo de codificación.

• Runner: un proceso Node solo de salida con asignaciones de espacios de trabajo de confianza, confinamiento de rutas, servicios de parches/Git, subprocesos locales y metadatos persistentes de registros/trabajos.

• Protocol: packages/protocol proporciona esquemas TypeScript estrictos y un JSON Schema generado y neutral respecto al lenguaje para futuros Runners en Go/Rust.

El núcleo Cloudflare usa solo Workers más Durable Objects respaldados por SQLite. No usa OAuth, KV, D1, Queues, R2, Sandbox, Containers, Dynamic Workers, túneles, SSH entrante, el runtime de GitHub Actions ni APIs de modelos de IA.

Related MCP server: cloud-to-local

Despliegue

Requisitos: Node.js 20+, npm, Git, Wrangler y una cuenta de Cloudflare con Durable Objects respaldados por SQLite habilitados.

git clone https://github.com/aloneio/remote-coding-runtime.git
cd remote-coding-runtime
npm install
npm test
npm run typecheck
npm run build
npm run validate:worker

Configure los tres secretos de producción utilizados por la administración de Runners y el canal de control interno:

cd apps/worker
npx wrangler secret put ADMIN_TOKEN
npx wrangler secret put RUNNER_TOKEN_PEPPER
npx wrangler secret put INTERNAL_CONTROL_SECRET

A continuación, despliegue solo cuando esté listo:

npx wrangler deploy --config wrangler.jsonc

npm run validate:worker ejecuta Wrangler con --dry-run. Verifique que su salida contiene --dry-run: exiting now; no demuestra las cuotas de una cuenta desplegada ni el comportamiento de red en producción.

Configuración inicial

Abra la URL raíz desplegada, por ejemplo:

https://mcp.aloneio.com/

Un RegistryDO recién creado muestra:

Welcome to Remote Coding Runtime
Create administrator password

La primera solicitud de configuración válida gana atómicamente. No se requiere contraseña de arranque. Establezca la contraseña inmediatamente después del despliegue. Si otra persona reclama una instancia pública no inicializada, elimine/restablezca su estado en Cloudflare y vuelva a desplegarla.

Las contraseñas no se almacenan en texto plano. El Registry almacena un verificador PBKDF2-HMAC-SHA-256 versionado con una sal aleatoria. El inicio de sesión crea una sesión opaca aleatoria de siete días; el navegador recibe una cookie Secure, HttpOnly, SameSite=Strict, Path=/, mientras que RegistryDO almacena solo su hash SHA-256. Los cambios de contraseña revocan todas las sesiones existentes.

Las solicitudes administrativas de cambio de estado usan un token CSRF vinculado a la sesión y comprobaciones de mismo origen. La configuración y el inicio de sesión también usan cookies CSRF de preautenticación de corta duración.

Añadir un Runner

La autenticación del Runner permanece independiente del inicio de sesión del administrador y de las credenciales de los clientes MCP. Inscriba o rote un Runner mediante la API protegida por ADMIN_TOKEN:

curl -sS -X POST https://mcp.aloneio.com/admin/runners \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"runner_id":"home-pc"}'

El token del Runner en texto plano solo se devuelve mediante una inscripción/rotación exitosa. Almacénelo de forma segura y luego inicie el Runner:

CODING_RUNNER_TOKEN='returned-runner-token' \
  npx tsx apps/runner/src/cli.ts start \
  --server wss://mcp.aloneio.com \
  --runner-id home-pc \
  --workspace zero=/home/me/code/zero\;writable\;noshell

Sintaxis de los espacios de trabajo:

--workspace id=path[;readonly|writable][;shell|noshell]

Los valores predeterminados son readonly;noshell. En producción se requiere wss://; ws:// en claro solo se acepta para loopback junto con --insecure-local.

El Runner solo necesita acceso a Internet de salida. No expone HTTP, MCP, OAuth, SSH ni puertos entrantes.

Crear clientes MCP

Inicie sesión en / y luego use el panel /admin:

1. Introduzca un nombre como ChatGPT Web, Claude o Cursor Desktop.

2. Seleccione los ámbitos Read, Write y/o Execute.

3. Pulse Crear.

4. Copie la URL generada inmediatamente. Solo se muestra una vez.

Ejemplo:

https://mcp.aloneio.com/fJ3...43-character-base64url-secret...x92/mcp

Configure solo esa URL en el cliente MCP. No se requiere flujo OAuth, callback ni cabecera Bearer adicional. Cada cliente debe tener su propia URL:

ChatGPT → secret A
Claude  → secret B
Cursor  → secret C

El panel admite:

• Crear

• Renombrar

• Rotar

• Revocar

• Ámbitos coding:read, coding:write, coding:exec por cliente

• Visualización de creación/último uso/estado/prefijo de clave

La rotación invalida la URL anterior inmediatamente y muestra la sustitución una sola vez. La revocación hace que la URL devuelva el mismo 404 Not Found que se usa para secretos desconocidos.

Modelo de seguridad de la URL secreta

/<secret>/mcp es una credencial de API. Trate la URL completa como una contraseña:

• no la publique;

• no la incluya en capturas de pantalla;

• no la confirme en Git;

• no la pegue en registros, incidencias ni análisis;

• cree una URL diferente para cada cliente/dispositivo MCP;

• rótela inmediatamente si se sospecha una fuga.

La aplicación nunca registra la URL/ruta entrante y almacena solo un verificador SHA-256 más un prefijo corto de visualización. Las respuestas MCP/administración usan Cache-Control: no-store; el HTML también usa Referrer-Policy: no-referrer, una CSP restrictiva, nosniff y bloqueo de marcos. La infraestructura fuera de la aplicación puede registrar las rutas de solicitud, así que configure la redacción de registros de Cloudflare y dependa de la rotación/revocación para la recuperación.

Catálogo de herramientas

Runtime

runner_list
runner_info
workspace_list
env_info

Sistema de archivos

fs_read
fs_list
fs_search
fs_apply_patch

Ejecución y trabajos persistentes

exec_start
exec_run
job_list
job_get
job_logs
job_cancel
job_input

Git

git_status
git_diff

coding:read permite lecturas del runtime/sistema de archivos, job_list/job_get/registros e inspección de Git. coding:write permite aplicar parches. coding:exec permite iniciar/ejecutar/cancelar/introducir entrada en procesos. Un trabajo se comparte dentro de la instancia de administrador único en lugar de pertenecer a un solo cliente MCP: Claude puede descubrir y leer un trabajo creado antes por ChatGPT si tiene el ámbito requerido.

Trabajos persistentes

exec_start devuelve un job_id rápidamente. El Runner persiste el estado local autoritativo en:

~/.remote-coding-runner/state/
├── runner.json
└── jobs/<job_id>/
    ├── meta.json
    ├── stdout.log
    └── stderr.log

El Worker almacena solo metadatos acotados. job_list lee instantáneas de RegistryDO y, por tanto, funciona mientras un Runner está desconectado. El stdout/stderr completo permanece en el Runner y se lee mediante job_logs paginado una vez que el Runner está en línea.

La sincronización del Runner inserta o actualiza trabajos actuales/recientes sin eliminar el historial anterior solo porque se omitió de una instantánea acotada. El Registry conserva trabajos activos/no terminales y hasta 1.000 trabajos terminales por Runner. Un trabajo puede registrar created_by_client_id para auditoría, pero ese campo no restringe el acceso entre clientes.

Tras un reinicio del Runner, un proceso que aún coincide con su PID/huella guardada pasa a unknown. La reconciliación diferida durante job_get, job_list y la sincronización lo mantiene como unknown mientras está vivo y lo cambia a interrupted tras su desaparición porque el resultado real de salida no está disponible. Una cancelación recuperada pasa a cancelled solo cuando una evidencia duradera demuestra que este Runner entregó la solicitud de terminación; no se inventa ningún código de salida.

Los archivos de registro en disco permanecen completos y sin límite de tamaño de forma predeterminada. Supervise el uso de disco del Runner.

Seguridad del sistema de archivos y de los parches

Las solicitudes MCP proporcionan solo runner_id, workspace_id y rutas relativas al espacio de trabajo. El Runner rechaza:

• rutas absolutas POSIX;

• rutas de unidad, UNC y de dispositivo de Windows;

• bytes NUL y recorridos ..;

• IDs de espacio de trabajo desconocidos;

• ascendencia de symlinks/junctions y escapes;

• symlinks de escritura directa;

• escrituras en espacios de trabajo de solo lectura.

fs_read y job_logs usan cursores de bytes seguros para UTF-8. Las páginas diminutas que contienen caracteres chinos, emojis y caracteres acentuados se pueden concatenar exactamente sin caracteres de reemplazo.

fs_apply_patch admite operaciones Add/Update/Delete/Move, líneas base SHA-256 esperadas, coincidencia exacta de hunks, preparación/copias de seguridad en el mismo directorio, reversión, preservación de BOM/saltos de línea/modos y resultados estructurados acotados. Errores estables y seguros como invalid_patch, missing_file, target_exists, baseline_changed, errores de hunk, patch_install_failed y patch_rollback_failed llegan a MCP sin exponer rutas absolutas del host.

Esto es un límite de autorización de espacio de trabajo/ruta, no un sandbox de sistema operativo frente a adversarios hostiles. Ejecute repositorios o comandos no fiables dentro de una VM/contenedor externo con montajes, secretos y acceso de red restringidos.

Tiempos de espera y descubrimiento de entorno

Las constantes compartidas del protocolo mantienen alineados los plazos:

normal Runner operation maximum: 8,000 ms
Worker → Runner bridge timeout: 12,000 ms

Esto deja un margen de transporte/respuesta de cuatro segundos. exec_run y Git usan el límite local compartido; los trabajos más largos deben usar exec_start.

env_info almacena en caché sondeos paralelos acotados para plataforma, arquitectura, nombre de host, shell, Node, npm, pnpm, Python, Git, Go, rustc, Cargo y Docker. Las herramientas ausentes o que agotan el tiempo de espera devuelven { "available": false } en lugar de hacer fallar la solicitud.

Pruebas

npm test
npm run typecheck
npm run build
npm run validate:worker

El conjunto incluye pruebas de protocolo, pruebas del sistema de archivos/procesos/parches/Git/recuperación del Runner, pruebas de Durable Object de Worker y de autenticación de administrador/cliente, y una E2E real con Wrangler local + Runner real. La cobertura incluye:

• configuración atómica de una sola vez;

• comportamiento de contraseña/sesión PBKDF2, caducidad, cierre de sesión, invalidación de contraseña y CSRF;

• creación/rotación/revocación/404/aplicación de ámbitos de URL secreta por cliente;

• MCP real → Worker → Runner fs_read;

• paginación UTF-8 de archivos/registros;

• ejecución persistente después de que se cierra una solicitud MCP;

• desconexión del transporte del Runner, continuación local, reconexión y sincronización;

• el Cliente A inicia un trabajo y el Cliente B lo descubre con job_list mientras está desconectado;

• límites de recorrido, symlink, solo lectura, parches, Git, tiempo de espera, salida y concurrencia.

Las pruebas locales no demuestran las cuotas de una cuenta de Cloudflare concreta, la redacción de registros de edge en producción, la compatibilidad con clientes de Internet ni un evento de reinicio/hibernación desplegado. El despliegue sigue siendo un paso de aceptación a cargo del operador.

Ámbito excluido deliberadamente

El MVP no incluye MCP Tasks, terminal PTY/web, cuentas multiusuario, organizaciones, equipos, facturación, agentes de IA, RAG, automatización de navegador, runtime de GitHub Actions, Cloudflare Sandbox ni Cloudflare Containers.

Agradecimientos y licencia

Esta es una implementación independiente bajo Apache-2.0. La investigación de diseño consideró:

• xyTom/coding-tools-mcp, Apache-2.0 + NOTICE;

• volter-ai/volter-tunnel, Apache-2.0 + NOTICE;

• Hiroshimeow/agent-mcp-gateway, MIT;

• Documentación de Cloudflare Workers, Durable Objects, WebSocket Hibernation, el manejador MCP de Agents y el SDK TypeScript de MCP.

El repositorio solicitado davidlosasgonzalez/codeagent-mcp no estaba disponible en la URL pública durante la investigación, por lo que no se usó código ni licencia del mismo.