Coders Core v2 호환 개발 가이드

이 문서는 2026-10-24 현재 구현을 기준으로, 개발자가 자신의 코드와 프론트를 Coders Core v2에서 실행하거나 외부 서비스에서 Coders API를 호출하는 방법을 설명합니다.

기본 원칙은 다음과 같습니다.

• 일반적인 서비스 로직은 HTTP 코드로 작성합니다. 계좌 생성·정산 코드를 모든 서비스에 넣을 필요는 없습니다.
• 프로젝트에는 제공할 엔드포인트·프론트·요청 예산·필요 권한을 선언합니다.
• 사용자가 실행 계좌와 권한을 제공합니다. 선언만으로 권한이 부여되지는 않습니다.
• 다른 Coders 코드나 자원을 사용할 때는 현재 실행 계좌와 하위 호출 예산을 전달합니다.

1. 어떤 형태로 연결할 것인가#

현재 GitHub 실행은 임의의 웹 서버를 통째로 배포하는 방식이 아닙니다. 지원하는 ASGI 실행 형식으로 코드를 제공해야 합니다. 별도로 운영하는 서버가 Coders API를 호출하는 것은 일반 HTTP 클라이언트로 가능합니다.

2. 가장 작은 호환 프로젝트#

저장소를 다음처럼 구성합니다.

coders.json
api/
  analyze.py
public/
  index.html
  .coders-ui.json

2.1 프로젝트 명세: coders.json#

{
  "version": 1,
  "name": "텍스트 분석",
  "frontend": {"directory": "public"},
  "endpoints": {
    "analyze": {
      "file": "api/analyze.py",
      "path": "/",
      "methods": ["POST"],
      "budget": "11.000"
    }
  },
  "permissions": []
}

frontend와 endpoints 중 하나 이상이 필요합니다. 알 수 없는 필드는 거부합니다. 명세 파일이 없는 저장소의 자동 감지나 대시보드 설정과의 병합은 지원하지 않습니다.

엔드포인트의 file 대신 다음처럼 현재 설치된 공식 어댑터를 연결할 수도 있습니다. file과 endpoint는 동시에 지정할 수 없습니다.

{
  "endpoint": "coders-openai",
  "budget": "30.000"
}

공식 어댑터 이름을 적는 것과 사용자에게 데이터 전송 권한을 받는 것은 별개입니다. 임의의 가변 사용자 엔드포인트를 이 참조 항목에 연결하는 것은 현재 지원하지 않습니다.

2.2 백엔드: api/analyze.py#

from fastapi import FastAPI, Request

app = FastAPI()


@app.post("/")
async def analyze(request: Request):
    # 일반적인 HTTP 코드입니다. 계좌 생성이나 반환 코드는 필요하지 않습니다.
    body = await request.json()
    text = body.get("text", "")
    return {"characters": len(text), "words": len(text.split())}

실행 모듈은 app이라는 ASGI 애플리케이션을 제공해야 합니다. uvicorn.run()으로 포트를 열거나 서버를 계속 띄워두지 않습니다. 실행기가 요청을 전달하고 응답 후 컨테이너를 정리합니다.

플랫폼 이미지에 설치된 패키지만 사용할 수 있습니다. 현재 예제의 FastAPI·httpx는 사용 가능하지만, requirements.txt, npm 스크립트, Dockerfile을 자동 실행하지 않습니다. 저장소의 다른 Python 파일도 실행 컨테이너에 함께 복사되지 않습니다. 로컬 모듈 import나 저장소 파일 읽기에 의존하지 마세요.

순수 ASGI를 직접 구현한다면 HTTP뿐 아니라 lifespan 시작·종료 이벤트를 올바르게 처리하거나 lifespan 미지원 규약을 따라야 합니다. 동작하는 순수 ASGI 예제는 로컬 예제를 참고하세요.

컨테이너의 메모리·파일·백그라운드 태스크는 영속 저장소가 아닙니다. 요청 사이에 유지할 데이터는 Coders 저장소 등 별도의 지속성 있는 자원에 저장합니다. ASGI 코드가 202를 반환해도 컨테이너의 백그라운드 작업이 계속 살아 있지는 않습니다.

2.3 sandbox 화면: public/.coders-ui.json#

{
  "title": "텍스트 분석",
  "actions": [
    {
      "title": "분석하기",
      "endpoint": "analyze",
      "fields": [
        {"name": "text", "label": "분석할 내용", "multiline": true}
      ]
    }
  ]
}

Coders가 입력 화면을 만들고 {"text":"입력값"}을 해당 엔드포인트에 POST합니다. 이 화면에서 사용할 엔드포인트는 JSON 응답을 반환하도록 작성합니다. 임의의 개발자 JavaScript를 실행하거나 개발자 HTML의 폼을 그대로 사용하지 않습니다.

actions는 최대 16개, 작업별 fields도 최대 16개입니다. endpoint는 coders.json에 있는 별칭이어야 합니다. 필드 이름은 영문 소문자로 시작하는 소문자·숫자·_ 조합이며 최대 40자입니다.

이 파일이 없으면 sandbox에서는 HTML의 제한된 텍스트 미리보기만 표시합니다. 기본 모드에서도 서비스 버튼을 제공하려면 선언형 화면을 함께 넣으세요.

2.4 all 화면: public/index.html#

<!doctype html>
<html lang="ko">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>텍스트 분석</title>
<form>
  <textarea name="text" required></textarea>
  <button>분석하기</button>
</form>
<pre role="status"></pre>
<script type="module">
import { createClient } from '/_coders/sdk.js';
const coders = createClient();
const form = document.querySelector('form');
const output = document.querySelector('pre');

form.addEventListener('submit', async event => {
  event.preventDefault();
  try {
    const result = await coders.request('/api/analyze', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({text: form.elements.text.value}),
    });
    output.textContent = JSON.stringify(result.data, null, 2);
  } catch {
    output.textContent = '결과를 확인하지 못했습니다.';
  }
});
</script>
</html>

이 코드는 기본 호출 예제입니다. 잔액 부족과 재시도 처리는 아래 규약을 추가로 적용합니다.

all에서는 프로젝트의 HTML·JavaScript를 실행합니다. CSS·JS·폰트 등은 공개 폴더에 함께 넣어 같은 출처에서 제공하세요. 현재 프론트의 CSP는 외부 CDN 스크립트·외부 fetch 등을 허용하지 않으므로, all이라는 이유만으로 임의의 외부 브라우저 리소스가 로드되지는 않습니다. 서버 코드의 직접 외부 통신 허용과 구분해야 합니다.

/api/와 /_coders/는 예약 경로입니다. 프로젝트 프론트에서 계좌 비밀 키나 Coders 로그인 토큰을 저장·전달하지 않습니다. Core가 프로젝트 세션으로 실행 계좌를 선택합니다.

3. GitHub에서 처음 실행하기#

저장소를 공개로 만들고 루트에 명세와 코드를 커밋합니다. 브랜치 이름 대신 전체 40자리 커밋 해시로 접속합니다.

브라우저 진입
https://api.coders.kr/{owner}/{repo}/{commit}

엔드포인트 호출
https://api.coders.kr/{owner}/{repo}/{commit}/analyze

브라우저에서는 로그인 → 필요한 경우 준비 화면 → 프로젝트 사용 동의 → 실행 화면으로 이어집니다. 같은 커밋의 준비 결과는 공유하고, 사용자별 계좌·권한·데이터는 분리합니다. 같은 저장소라도 커밋이 다르면 별도 프로젝트 주소와 연결을 사용합니다.

새 커밋은 새 주소입니다. 이미 준비된 주소의 코드를 덮어쓰지 않습니다. 커밋을 고정해도 플랫폼 런타임 업데이트까지 고정하는 재현 빌드를 의미하지는 않습니다.

실제 공개 예제: coders-kr/coders-github-example. 복사 가능한 파일은 이 저장소의 examples/github에도 있습니다.

외부 API 호출#

다음은 신뢰할 수 있는 서버나 CLI에서 실행합니다. 환경 변수에는 저장소·커밋·계좌 키와 작업별 REQUEST_KEY를 설정합니다. 같은 작업을 재전송할 때는 REQUEST_KEY도 유지합니다.

curl --request POST \
  "https://api.coders.kr/${GITHUB_OWNER}/${GITHUB_REPO}/${COMMIT_SHA}/analyze" \
  --header "Coders-Grant: ${CODERS_ACCOUNT_KEY}" \
  --header 'Coders-Budget: 11.000' \
  --header "Idempotency-Key: ${REQUEST_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"text":"안녕하세요 Coders"}'

이미 등록된 엔드포인트는 Core 호스트의 /v1/invoke/{이름}에 같은 규약으로 호출합니다. 이 서버 API를 다른 출처의 프론트에서 계좌 키를 넣어 직접 호출하는 패턴으로 설계하지 마세요. 브라우저 프로젝트는 같은 출처의 /api/{별칭}과 세션을 사용합니다.

준비 중의 202#

아직 준비되지 않은 커밋에 API 요청을 보내면 원래 엔드포인트 대신 다음과 같은 준비 상태를 반환합니다.

{
  "state": "queued",
  "execution_started": false,
  "status_url": "https://core-v2.coders.kr/github/OWNER/REPO/COMMIT/_status",
  "status_path": "/github/OWNER/REPO/COMMIT/_status"
}

1. status_url을 조회합니다. 중개 서버 안에서는 상대 경로인 status_path를 사용할 수 있습니다.
2. state=ready가 되면 같은 본문·예산·요청 키로 원래 API를 다시 호출합니다.
3. 준비가 실패하면 오류를 확인합니다. 실패 후 재준비는 60초가 지난 뒤 새 준비 요청 키로 시작합니다.

처음 준비를 시작한 계좌가 준비 시도 비용을 지불합니다. 현재는 운영자가 설정한 요청 기본 요금이며, 실패한 준비도 청구됩니다. 같은 준비 작업을 기다리는 다른 호출자에게 준비비를 다시 청구하지 않습니다. 준비비와 이후 실행 예산을 모두 감당할 가용액이 필요합니다.

이 202는 직접 호출한 GitHub 엔드포인트가 아직 실행되지 않았다는 의미입니다. 이미 실행된 상위 코드가 하위 준비 결과를 받아 202로 반환한 경우, 상위 실행의 재전송은 기존 결과를 재생할 수 있습니다. 상위 코드의 실행 ID와 상태도 함께 구분해야 합니다.

4. 계좌·예산·요금 규칙#

사용자의 기본 계좌 아래에 프로젝트 계좌를 두고, Core가 호출마다 실행 계좌를 분할합니다. 코드에는 부모 키 대신 새 실행 계좌 키를 전달합니다.

• 평범한 요청 완료와 실행 계좌 반환은 Core가 처리합니다. 개발자 코드가 매번 계좌를 닫을 필요는 없습니다.
• 명시적으로 만든 장기 보유 계좌는 보유자가 별도로 종료해야 합니다.
• 요청 연결이 끊어져도 이미 접수된 실행이 바로 취소되는 것은 아닙니다.
• 실패해도 이미 발생한 컴퓨팅 비용·외부 자원 사용·확정 송금은 사라지지 않습니다.
• GitHub 저장소 소유자에게 자동 지급되는 서비스 이용료는 없습니다. 지급이 필요하면 일반 송금 API를 사용합니다.

예산은 가격과 다릅니다#

호스팅 실행은 요청 접수 비용과 컴퓨팅 예약을 먼저 확보합니다. 하위 호출·송금·저장소 사용도 같은 실행 계좌 안에서 예산을 사용합니다. 사용하지 않은 돈은 원장 규칙에 따라 상위로 돌아갑니다.

따라서 30원 송금 코드의 예산을 30원으로 잡으면 부족할 수 있습니다. 요청료와 컴퓨팅 예약, 하위 호출까지 포함해 배정해야 합니다. 예제의 11.000은 작은 처리 작업용 예산이며 모든 서비스에 적용할 고정값이 아닙니다. 단가·예약액·시간 제한은 운영 설정을 확인하세요.

원화는 소수점 여섯 자리까지 처리하고 화면에서는 소수점 세 자리로 표시합니다. 요청 금액에는 쉼표·원 표시를 넣지 않고 "30.000001" 같은 십진 문자열을 사용하면 됩니다. 회계 계산은 부동소수점 대신 Decimal 등 정확한 십진 연산으로 처리합니다.

프로젝트의 매일 충전 목표#

첫 동의 때 목표가 100원이면 기본 계좌에서 프로젝트 잔액을 100원까지 채웁니다. 이후 한국 시간 자정에 부족분만 보충합니다. 실행 중인 하위 예산도 잔액에 포함하며, 100원 이상 남아 있으면 회수하거나 추가 충전하지 않습니다.

낮에 잔액이 부족하면 자동 보충하지 않고 추가 할당을 확인받습니다. 기본 계좌가 부족하면 가능한 만큼만 채우고 부족분을 표시합니다. 목표 잔액은 일별 지출 한도도, 무료 지급액도 아닙니다.

5. sandbox와 all의 호환 조건#

신규 기본값은 sandbox입니다. 기존 coders-only는 호환 모드로 남아 있으며 새 프로젝트의 기본 설계로 삼지 않습니다.

일반 코드가 직접 외부 API를 부르는 구조라면 all에서 동작할 수 있어도 sandbox 호환을 위해 수정이 필요합니다. 외부 작업을 Coders의 승인된 중개 엔드포인트로 옮기고, 사용자가 필요한 권한을 허용하도록 연결합니다.

프로젝트 권한 선언#

{
  "permissions": ["transfer", "transfer-precise"]
}

위 내용은 coders.json의 해당 항목입니다. 전체 명세의 다른 필드도 함께 작성해야 합니다.

• transfer: 일반 송금. 1원 단위, 송금자 정보 비공개, 한국 시간 다음 자정에 수취 계좌별 합산 지급입니다.
• transfer-precise: 정밀 송금. 소수점 여섯 자리까지 즉시 지급합니다.
• 송금 대상과 실제 금액은 코드가 결정합니다. 사용자는 프로젝트의 송금 권한을 한 번 허용하고, 이후 예산과 공통 제한 안에서 사용합니다.
• 선언한 권한을 거절하거나 나중에 철회할 수 있습니다. 코드는 거절을 처리해야 합니다.
• OpenAI·행 공유 등은 현재 별도의 권한 요청 흐름입니다. 지원하지 않는 이름을 permissions에 임의로 추가할 수 없습니다.

6. 실행 코드에서 하위 호출·송금하기#

실행 중인 코드에는 다음 값이 제공됩니다.

중개 서버를 사용할 때는 현재 키만 전달합니다. 부모 계좌 키, 다른 사용자의 키, 관리자 키를 가져오거나 전달하지 않습니다.

다음은 이미 등록된 하위 엔드포인트를 호출하는 코드 조각입니다. my-child-endpoint는 실제 등록 이름으로 바꿉니다. 상위 요청 예산에는 자신의 컴퓨팅 비용 외에 아래의 11원도 들어 있어야 합니다.

import os
import httpx

async def call_child(request, payload):
    async with httpx.AsyncClient(base_url=os.environ["CODERS_URL"]) as client:
        response = await client.post(
            "/v1/invoke/my-child-endpoint",
            headers={
                "Coders-Grant": request.headers["Coders-Grant"],
                "Coders-Budget": "11.000",
                "Idempotency-Key": request.headers["Idempotency-Key"] + ":child",
            },
            json=payload,
        )
        return response

하위 호출을 위해 개발자가 먼저 계좌를 만들 필요는 없습니다. Core가 예산을 분할하고 하위 실행 키를 전달합니다. 서로 다른 하위 작업에는 :child-a, :child-b처럼 다른 키를 사용하고, 같은 작업의 재전송에는 같은 키와 입력을 유지합니다.

현재 중개 서버에서 허용하는 주요 경로는 다음과 같습니다.

• /v1/invoke/{이름}: 등록 엔드포인트 실행
• /github/{owner}/{repo}/{commit}/{endpoint} 및 /_status: GitHub 코드 실행·준비 상태 조회
• /v1/accounts/current, /split, /transfers, /close: 현재 계좌 작업
• /v1/permissions/requests: 권한 요청
• /store/...: 지원하는 데이터 저장소 작업

이 경로들은 CODERS_URL 기준의 상대 경로로 호출합니다. 중개 서버에 임의 외부 URL을 넣어 프록시처럼 사용할 수 없습니다.

송금은 /v1/accounts/transfers에 현재 계좌 키와 작업 키를 넣어 다음 본문으로 POST합니다. 이 계좌 관리 요청 자체에는 Coders-Budget 대신 현재 계좌의 가용액을 사용하며 요청 비용도 필요합니다.

{
  "recipient_id": "수취 계좌의 공개 ID",
  "amount": "30.000",
  "mode": "standard"
}

standard는 일반 송금, precise는 정밀 송금입니다. mode를 생략하면 허용된 프로젝트 송금 모드에 따라 결정되므로 의도가 분명하면 명시하세요. 일반 송금의 status=scheduled는 접수·정산 대기이며 즉시 지급 완료를 뜻하지 않습니다. 상세 규약은 권한 문서를 참고하세요.

7. 오류와 재시도#

Coders-Execution-Id는 접수된 실행을 식별합니다. 같은 계좌에서 같은 키와 같은 입력을 재전송하면 기존 실행 결과를 재생하고, 입력·예산 등을 바꾸면 충돌할 수 있습니다.

• 접수 전 거부: 계좌 확인·추가 할당 후 같은 원래 요청을 재시도합니다.
• 이미 완료된 실행의 실패: 같은 키는 실패 결과를 재생합니다. 작업을 새로 실행하려면 새 키가 필요하며 비용이 추가될 수 있습니다.
• 지급·외부 작업이 있었거나 결과가 불명확한 실행: 전체 요청을 새 키로 자동 재실행하지 않습니다. 이미 수행된 부작용을 먼저 확인합니다.

컴퓨팅 예약 부족과 실행 중 컴퓨팅 예산 소진은 다릅니다. 후자는 요청 예산 숫자를 크게 하는 것만으로 항상 해결되지 않으므로 처리 시간·하위 호출 구조·운영 설정을 함께 확인합니다.

프론트 처리#

sandbox 화면은 Core가 계좌·권한 확인 모달과 안전한 재시도를 처리합니다. all 프론트는 개발자가 SDK 결과를 보고 UX를 연결합니다.

• result.requiresAccountAction, result.accountActionUrl로 Core의 확인 화면에 연결합니다.
• 별도 사용자 클릭에서 coders.openAccountWindow(url)를 호출하거나, SDK가 검증한 URL을 그대로 새 탭 링크로 제공합니다.
• 창 확인 결과 checked는 확인 알림이며 결제 성공·잔액 보증이 아닙니다.
• 접수 전 거부는 사용자의 재시도 동작에 result.retry()를 연결할 수 있습니다. SDK는 확인 창을 닫았다는 이유만으로 유료 요청을 자동 실행하지 않습니다.
• 전송 예외의 error.retry()도 기존 키·본문을 유지합니다.

현재 SDK의 openAccountWindow()는 URL의 기존 쿼리를 채널 값으로 교체합니다. 엔드포인트별 예산을 쓰는 경우 endpoint 정보가 빠져 확인 금액이 프로젝트 기본 예산을 기준으로 표시될 수 있습니다. 정확한 URL을 유지해야 할 때는 반환된 accountActionUrl을 그대로 새 탭 링크로 연결하세요. 프론트 연동의 핵심 규약은 이 절의 프론트 처리에 있습니다.

공통 /c 칩은 /run과 all의 HTML 페이지에 Core가 제공합니다. 직접 잔액 조회 코드를 넣거나 칩에 계좌 키를 전달할 필요가 없습니다. all 프로젝트 코드는 칩의 Coders 출처 iframe 안에 있는 계좌 정보를 직접 읽을 수 없습니다.

8. 현재 지원 범위 확인#

하위 파일 경로에는 빈 경로, 절대 경로, .·.. 경로 요소, ?, #, 역슬래시를 사용하지 않습니다. 공개 폴더 밖의 파일은 프론트로 제공하지 않습니다.

9. 호환 완료 점검#

• [ ] 루트에 유효한 coders.json이 있고, 전체 커밋 해시로 접근한다.
• [ ] 명세의 파일·경로·메서드와 실제 app의 라우트가 맞는다.
• [ ] 추가 설치·로컬 모듈·영속 프로세스에 의존하지 않는다.
• [ ] sandbox를 지원한다면 선언형 화면이 있고, 해당 작업은 JSON을 반환한다.
• [ ] all 프론트의 리소스는 같은 출처에서 제공하며 계좌 비밀 키를 포함하지 않는다.
• [ ] 예산에 접수 비용·컴퓨팅 예약·하위 작업 비용을 포함했다.
• [ ] 필요한 송금 권한을 선언하고, 거절·철회도 처리한다.
• [ ] 하위 호출은 현재 계좌 키와 작업별 키를 사용하고 정책을 완화하지 않는다.
• [ ] 준비 중 202, 잔액 부족 402, 권한 부족 403을 각각 처리한다.
• [ ] 결과 불명 재전송과 명시적인 새 실행을 구분해 중복 지급을 방지한다.

관련 주제: GitHub 준비 · 계좌·예산 · 권한 · 오류·재시도.

Core v2 OpenAPI에서 API 경로와 입력 형식을 확인할 수 있습니다.