원격 코딩 런타임

모델 중립적이고 클라이언트 중립적인 원격 코딩 런타임으로, 하나의 안정적인 Cloudflare 제어 평면과 아웃바운드 전용 로컬 러너를 갖추고 있습니다.

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는 코드를 실행하거나 AI 모델을 호출하지 않습니다. MCP 클라이언트가 추론을 수행하고, 러너가 파일 시스템, Git, 프로세스 작업을 수행합니다. 브라우저, 채팅, MCP 요청 또는 러너 WebSocket을 닫아도 이미 시작된 작업은 중지되지 않습니다.

아키텍처

• Worker: 유일한 공개 MCP/제어 평면 엔드포인트입니다. MCP 클라이언트 URL을 인증하고, 소규모 관리 UI를 제공하며, 제한된 RPC 메시지를 라우팅합니다.

• RegistryDO: 러너, 작업 공간, 과거 작업, 관리자 비밀번호/세션 상태, MCP 클라이언트 자격 증명에 대한 SQLite 메타데이터입니다.

• RunnerDO: 러너당 하나의 하이버네이션 가능한 Durable Object입니다. 현재 아웃바운드 러너 WebSocket과 상관된 RPC 브리지를 소유하며, 코딩 작업을 실행하지 않습니다.

• Runner: 신뢰할 수 있는 작업 공간 매핑, 경로 제한, 패치/Git 서비스, 로컬 하위 프로세스, 영구 로그/작업 메타데이터를 갖춘 아웃바운드 전용 Node 프로세스입니다.

• 프로토콜: packages/protocol은 엄격한 TypeScript 스키마와 향후 Go/Rust 러너를 위한 생성된 언어 중립 JSON Schema를 제공합니다.

Cloudflare 코어는 Workers와 SQLite 기반 Durable Objects만 사용합니다. OAuth, KV, D1, Queues, R2, Sandbox, Containers, Dynamic Workers, 터널, 인바운드 SSH, GitHub Actions 런타임 또는 AI 모델 API를 사용하지 않습니다.

Related MCP server: cloud-to-local

배포

요구 사항: Node.js 20+, npm, Git, Wrangler, SQLite 기반 Durable Objects가 활성화된 Cloudflare 계정.

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

러너 관리 및 내부 제어 채널에서 사용하는 세 가지 프로덕션 비밀을 구성합니다:

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

그런 다음 준비가 되었을 때만 배포합니다:

npx wrangler deploy --config wrangler.jsonc

npm run validate:worker는 Wrangler를 --dry-run으로 실행합니다. 출력에 --dry-run: exiting now가 포함되어 있는지 확인하세요. 배포된 계정의 할당량이나 프로덕션 네트워크 동작을 증명하지는 않습니다.

첫 설정

배포된 루트 URL을 엽니다. 예:

https://mcp.aloneio.com/

새로운 RegistryDO는 다음을 표시합니다:

Welcome to Remote Coding Runtime
Create administrator password

첫 번째 유효한 설정 요청이 원자적으로 승리합니다. 부트스트랩 비밀번호는 필요하지 않습니다. 배포 직후 비밀번호를 설정하세요. 초기화되지 않은 공개 인스턴스를 다른 사람이 클레임하면 Cloudflare 상태를 삭제/재설정하고 재배포하세요.

비밀번호는 평문으로 저장되지 않습니다. Registry는 무작위 솔트와 함께 버전화된 PBKDF2-HMAC-SHA-256 검증기를 저장합니다. 로그인은 무작위 7일 불투명 세션을 생성합니다. 브라우저는 Secure, HttpOnly, SameSite=Strict, Path=/ 쿠키를 받고, RegistryDO는 SHA-256 해시만 저장합니다. 비밀번호 변경은 모든 기존 세션을 취소합니다.

관리자 상태 변경 요청은 세션 바인딩 CSRF 토큰과 동일 출처 검사를 사용합니다. 설정 및 로그인도 수명이 짧은 사전 인증 CSRF 쿠키를 사용합니다.

러너 추가

러너 인증은 관리자 로그인 및 MCP 클라이언트 자격 증명과 독립적입니다. ADMIN_TOKEN으로 보호된 API를 통해 러너를 등록하거나 교체합니다:

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"}'

평문 러너 토큰은 성공적인 등록/교체 시에만 반환됩니다. 안전하게 저장한 후 러너를 시작합니다:

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

작업 공간 구문:

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

기본값은 readonly;noshell입니다. 프로덕션에서는 wss://가 필요합니다. 평문 ws://는 루프백과 함께 --insecure-local이 있는 경우에만 허용됩니다.

러너는 아웃바운드 인터넷 액세스만 필요합니다. HTTP, MCP, OAuth, SSH 또는 인바운드 포트를 노출하지 않습니다.

MCP 클라이언트 생성

/에서 로그인한 후 /admin 대시보드를 사용합니다:

1. ChatGPT Web, Claude 또는 Cursor Desktop과 같은 이름을 입력합니다.

2. Read, Write 및/또는 Execute 범위를 선택합니다.

3. Create를 누릅니다.

4. 생성된 URL을 즉시 복사합니다. 한 번만 표시됩니다.

예:

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

MCP 클라이언트에 해당 URL만 구성합니다. OAuth 흐름, 콜백 또는 추가 Bearer 헤더가 필요하지 않습니다. 각 클라이언트는 자체 URL을 가져야 합니다:

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

대시보드는 다음을 지원합니다:

• 생성

• 이름 변경

• 교체

• 취소

• 클라이언트별 coding:read, coding:write, coding:exec 범위

• 생성/마지막 사용/상태/키 접두사 표시

교체는 이전 URL을 즉시 무효화하고 대체 URL을 한 번 표시합니다. 취소는 URL이 알 수 없는 비밀에 사용되는 것과 동일한 404 Not Found를 반환하게 합니다.

비밀 URL 보안 모델

/<secret>/mcp는 API 자격 증명입니다. 전체 URL을 비밀번호처럼 취급하세요:

• 게시하지 마세요.

• 스크린샷에 포함하지 마세요.

• Git에 커밋하지 마세요.

• 로그, 이슈 또는 분석에 붙여넣지 마세요.

• 모든 MCP 클라이언트/장치에 대해 다른 URL을 만드세요.

• 유출이 의심되면 즉시 교체하세요.

애플리케이션은 들어오는 URL/경로를 기록하지 않으며 SHA-256 검증기와 짧은 표시 접두사만 저장합니다. MCP/관리자 응답은 Cache-Control: no-store를 사용합니다. HTML은 또한 Referrer-Policy: no-referrer, 제한적인 CSP, nosniff 및 프레임 차단을 사용합니다. 애플리케이션 외부의 인프라는 여전히 요청 경로를 기록할 수 있으므로 Cloudflare 로그 편집을 구성하고 복구를 위해 교체/취소에 의존하세요.

도구 카탈로그

런타임

runner_list
runner_info
workspace_list
env_info

파일 시스템

fs_read
fs_list
fs_search
fs_apply_patch

실행 및 영구 작업

exec_start
exec_run
job_list
job_get
job_logs
job_cancel
job_input

Git

git_status
git_diff

coding:read는 런타임/파일 시스템 읽기, job_list/job_get/로그 및 Git 검사를 허용합니다. coding:write는 패치를 허용합니다. coding:exec는 프로세스 시작/실행/취소/입력을 허용합니다. 작업은 단일 관리자 인스턴스 내에서 공유되며 특정 MCP 클라이언트가 소유하지 않습니다. Claude는 필요한 범위가 있으면 ChatGPT가 이전에 생성한 작업을 발견하고 읽을 수 있습니다.

영구 작업

exec_start는 신속하게 job_id를 반환합니다. 러너는 다음 위치에 로컬 권위 상태를 유지합니다:

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

Worker는 제한된 메타데이터만 저장합니다. job_list는 RegistryDO 스냅샷을 읽으므로 러너가 오프라인일 때도 작동합니다. 전체 stdout/stderr는 러너에 남아 있으며 러너가 온라인일 때 페이지가 매겨진 job_logs를 통해 읽습니다.

러너 동기화는 현재/최근 작업을 업서트하지만 제한된 스냅샷에서 생략되었다고 해서 이전 기록을 삭제하지 않습니다. Registry는 활성/비종료 작업과 러너당 최대 1,000개의 종료 작업을 유지합니다. 작업은 감사 목적으로 created_by_client_id를 기록할 수 있지만 해당 필드는 클라이언트 간 액세스를 제한하지 않습니다.

러너 재시작 후 저장된 PID/지문과 일치하는 프로세스는 unknown이 됩니다. job_get, job_list 및 동기화 중 지연 조정은 프로세스가 살아 있는 동안 unknown으로 유지하고 실제 종료 결과를 알 수 없으므로 사라진 후 interrupted로 변경합니다. 복구된 취소는 이 러너가 종료 요청을 전달했다는 내구성 있는 증거가 있을 때만 cancelled가 됩니다. 종료 코드는 발명되지 않습니다.

디스크의 로그 파일은 기본적으로 완전하고 무제한입니다. 러너 디스크 사용량을 모니터링하세요.

파일 시스템 및 패치 안전

MCP 요청은 runner_id, workspace_id 및 작업 공간 상대 경로만 제공합니다. 러너는 다음을 거부합니다:

• POSIX 절대 경로;

• Windows 드라이브, UNC 및 장치 경로;

• NUL 바이트 및 .. 탐색;

• 알 수 없는 작업 공간 ID;

• 심볼릭 링크/정션 조상 및 이스케이프;

• 쓰기 통과 심볼릭 링크;

• 읽기 전용 작업 공간에 대한 쓰기.

fs_read 및 job_logs는 UTF-8 안전 바이트 커서를 사용합니다. 중국어, 이모지 및 악센트 문자가 포함된 작은 페이지는 대체 문자 없이 정확히 연결될 수 있습니다.

fs_apply_patch는 추가/업데이트/삭제/이동 작업, 예상 SHA-256 기준선, 정확한 헝크 일치, 동일 디렉터리 스테이징/백업, 롤백, BOM/줄바꿈/모드 보존 및 제한된 구조화 결과를 지원합니다. invalid_patch, missing_file, target_exists, baseline_changed, 헝크 오류, patch_install_failed 및 patch_rollback_failed와 같은 안정적인 안전 오류는 호스트 절대 경로를 노출하지 않고 MCP에 도달합니다.

이것은 작업 공간/경로 권한 부여 경계이지 적대적인 운영 체제 샌드박스가 아닙니다. 신뢰할 수 없는 저장소나 명령을 제한된 마운트, 비밀 및 네트워크 액세스가 있는 외부 VM/컨테이너에서 실행하세요.

시간 초과 및 환경 검색

공유 프로토콜 상수는 마감 시간을 정렬합니다:

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

이것은 4초의 전송/응답 여유를 남깁니다. exec_run 및 Git은 공유 로컬 제한을 사용합니다. 더 긴 작업은 exec_start를 사용해야 합니다.

env_info는 플랫폼, 아키텍처, 호스트 이름, 셸, Node, npm, pnpm, Python, Git, Go, rustc, Cargo 및 Docker에 대한 제한된 병렬 프로브를 캐시합니다. 누락되거나 시간 초과된 도구는 요청을 실패시키는 대신 { "available": false }를 반환합니다.

테스트

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

이 스위트에는 프로토콜 테스트, 러너 파일 시스템/프로세스/패치/Git/복구 테스트, Worker Durable Object 및 관리자/클라이언트 인증 테스트, 실제 로컬 Wrangler + 실제 러너 E2E가 포함됩니다. 적용 범위는 다음과 같습니다:

• 원자적 일회성 설정;

• PBKDF2 비밀번호/세션 동작, 만료, 로그아웃, 비밀번호 무효화 및 CSRF;

• 클라이언트별 비밀 URL 생성/교체/취소/404/범위 적용;

• 실제 MCP → Worker → 러너 fs_read;

• UTF-8 파일/로그 페이지 매김;

• MCP 요청이 닫힌 후 영구 실행;

• 러너 전송 연결 끊김, 로컬 계속, 재연결 및 동기화;

• 클라이언트 A가 작업을 시작하고 클라이언트 B가 오프라인 상태에서 job_list로 발견;

• 탐색, 심볼릭 링크, 읽기 전용, 패치, Git, 시간 초과, 출력 및 동시성 경계.

로컬 테스트는 특정 Cloudflare 계정의 할당량, 프로덕션 에지 로그 편집, 인터넷 클라이언트 호환성 또는 배포된 재시작/하이버네이션 이벤트를 증명하지 않습니다. 배포는 운영자가 소유한 수용 단계로 남아 있습니다.

의도적으로 제외된 범위

MVP에는 MCP Tasks, PTY/웹 터미널, 다중 사용자 계정, 조직, 팀, 청구, AI 에이전트, RAG, 브라우저 자동화, GitHub Actions 런타임, Cloudflare Sandbox 또는 Cloudflare Containers가 포함되지 않습니다.

감사 및 라이선스

이것은 독립적인 Apache-2.0 구현입니다. 디자인 연구는 다음을 고려했습니다:

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

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

• Hiroshimeow/agent-mcp-gateway, MIT;

• Cloudflare Workers, Durable Objects, WebSocket Hibernation, Agents MCP handler 및 MCP TypeScript SDK 문서.

요청된 davidlosasgonzalez/codeagent-mcp 저장소는 연구 중 공개 URL에서 사용할 수 없었으므로 해당 코드나 라이선스는 사용되지 않았습니다.