# Deploy

> Deploy(https://deploy.core.today)는 Git 저장소를 연결하면 빌드부터 배포, HTTPS 주소(`https://<이름>.apps.core.today`)까지 해 주는 컨테이너 배포 플랫폼입니다. 이 문서는 코딩 에이전트(LLM)가 사용자의 코드를 Deploy 에 배포하고, 빌드 결과를 확인해 고치는 데 필요한 규칙과 API 를 담고 있습니다.

**누가 무엇을 하나요.** 사람은 처음 한 번 에이전트 로그인을 승인합니다(에이전트가 보여 준 링크를 열어 “승인”). 그 뒤로는 에이전트가 사용자의 권한으로 그 조직 안에서 프로젝트·데이터베이스 만들기, 환경변수·크기 설정, 빌드·배포, 로그 확인·재시도를 API 로 직접 합니다. 삭제·커스텀 도메인·NAS 폴더·알림은 사람이 콘솔에서 합니다.

**저장소가 지켜야 할 것.**

- 앱은 `PORT` 환경변수의 포트에서 `0.0.0.0` 으로 HTTP 를 받습니다. HTTPS 는 플랫폼이 앞단에서 처리합니다.
- Dockerfile 이 있으면 그대로 쓰고, 없으면 언어·프레임워크를 자동 감지합니다(Railpack — Node·Python·Go·Rust·Ruby·PHP·Java·.NET·Elixir·Deno·Bun·정적 사이트). lockfile 을 커밋합니다.
- 서버는 amd64 입니다. 저장소 주소는 `https://` 형식만 됩니다(SSH 주소 불가).
- 컨테이너 안에 쓴 파일은 재시작하면 사라집니다. 데이터는 관리형 데이터베이스나 오브젝트 스토리지에 두고, 로그는 stdout/stderr 로 냅니다.
- 인증 없이 200 을 돌려주는 가벼운 헬스체크 경로(예 `/health`)를 두면 무중단으로 배포됩니다.
- 비밀값은 저장소에 넣지 않습니다. 환경변수로 넣습니다(API 의 `env`, 또는 사람이 콘솔에서). 빌드 시점 값(`NEXT_PUBLIC_*` 등)을 바꾸면 다시 빌드해야 합니다.

**배포 순서.**

1. 저장소를 위 조건에 맞추고 push 합니다.
2. 토큰을 찾습니다: 환경변수 `KUBECORE_AGENT_TOKEN` 또는 파일 `~/.config/kubecore/agent-token`. 없거나 `GET https://deploy.core.today/api/v1/me` 가 401 이면 로그인합니다 — `POST https://deploy.core.today/api/v1/auth/device` 의 `verificationUrl` 과 `userCode` 를 사용자에게 보여 주고 승인을 부탁한 뒤, `interval` 초마다 `POST https://deploy.core.today/api/v1/auth/token` 을 불러 `approved` 가 오면 `token`(`kca_…`)을 그 파일에 권한 600 으로 저장합니다(10분 안에 승인이 없으면 처음부터). 토큰을 출력·커밋하지 않습니다.
3. 프로젝트가 없으면 `POST https://deploy.core.today/api/v1/projects` 로 만듭니다(`{"slug","repo","ref","port","healthPath","env":{…}}`). 첫 빌드가 바로 시작되고 응답에 빌드 ID 가 옵니다. `slug` 는 프로젝트 ID 라 나중에 바꿀 수 없고(소문자·숫자·하이픈, 2~30자), 따로 `address` 를 주지 않으면 주소도 `https://<slug>.apps.core.today` 입니다. 비공개 저장소는 `gitTokenFrom`(같은 조직의 다른 프로젝트에 저장된 접근 토큰을 그대로 씀)이나 `gitToken` 을 줍니다. 데이터베이스가 필요하면 `POST https://deploy.core.today/api/v1/databases` 에 `"project":"<slug>"` 를 주면 접속 정보가 환경변수로 들어가고 재배포됩니다.
4. 빌드 상태(`GET …/builds/<id>`)를 `done` 이 `true` 가 될 때까지 5~10초 간격으로 확인합니다(보통 1~3분, 최대 30분). 이미 있는 프로젝트는 `POST …/builds` 로 새 빌드를 시작합니다. 폴링할 수 없는 시스템(CI·봇)은 `callbackUrl` 을 주면 끝났을 때 서명한 결과를 받습니다(전체 가이드 6.7).
5. `stage` 가 `failed` 면 `message`·`summary` 와 빌드 로그를 읽고, 코드를 고쳐 push 한 뒤 4번으로 돌아갑니다. 설정(포트·환경변수·크기)이 원인이면 `PATCH https://deploy.core.today/api/v1/projects/<slug>` 로 고칩니다(빌드 설정·빌드 시점 값이면 `"rebuild": true`).
6. `succeeded` 면 프로젝트 `phase` 가 `running` 인지, 공개 주소가 응답하는지 확인하고 주소를 사용자에게 알려 줍니다.

**API.** 모든 요청에 `Authorization: Bearer <토큰>` 헤더가 필요합니다. 에이전트 토큰(`kca_`)은 승인한 사람이 속한 조직 하나에서, 그 사람의 역할만큼 통합니다. 프로젝트 API 토큰(`kc_`, 프로젝트의 “배치 작업” 탭에서 발급)은 그 프로젝트 하나의 빌드·로그·작업에만 통합니다 — CI 에 넣을 때 씁니다.

```
V1=https://deploy.core.today/api/v1

POST   $V1/auth/device           로그인 시작 (인증 없음). 본문 {"name":"<에이전트 이름>"} → verificationUrl · userCode · deviceCode
POST   $V1/auth/token            로그인 결과. 본문 {"deviceCode":"…"} → pending | approved(token) | denied | expired
GET    $V1/me                    토큰 확인 (누구 · 어느 조직 · 만료). 401 이면 다시 로그인
DELETE $V1/auth/token            로그아웃 (지금 토큰 폐기)
GET    $V1/projects              조직의 프로젝트 목록
POST   $V1/projects              프로젝트 만들기 + 첫 빌드. 본문 {"slug","repo","port",…}
PATCH  $V1/projects/<slug>       설정 바꾸기. 본문 {"env":{"KEY":"값","OLD":null},"size":"m","rebuild":true,…}
GET    $V1/databases             데이터베이스 목록
POST   $V1/databases             데이터베이스 만들기 (+ 프로젝트에 연결). 본문 {"slug","engine","project",…}
GET    $V1/databases/<slug>      데이터베이스 상태 (ready)
POST   $V1/databases/<slug>/attach  프로젝트에 연결. 본문 {"project":"<slug>","env":"DATABASE_URL"}
```

프로젝트 하나에 대한 것 (두 토큰 모두):

```
BASE=https://deploy.core.today/api/v1/projects/<slug>

GET    $BASE                     프로젝트 상태 (phase · message · url · 마지막 빌드)
POST   $BASE/builds              빌드 시작. 본문(선택): {"ref":"<브랜치|태그|커밋>","preview":true,"callbackUrl":"https://…"}
GET    $BASE/builds              최근 빌드 목록
GET    $BASE/builds/<id>         빌드 상태 (stage · done · failedStage · message · summary)
GET    $BASE/builds/<id>/logs    빌드 로그, text/plain (?stage=fetch|build|deploy&tail=300)
DELETE $BASE/builds/<id>         진행 중인 빌드 취소
GET    $BASE/logs                앱 로그, text/plain (?tail=300&previous=1)
POST   $BASE/jobs                배치 작업 시작 (GET 은 목록, GET·DELETE $BASE/jobs/<id>)
```

## 문서

- [에이전트용 전체 가이드](https://deploy.core.today/llms-full.txt): 저장소 조건, 빌드 방식, 에이전트 로그인, 만들기·설정 API 의 모든 필드, API 요청·응답 예, 상태별 대처, 문제 해결, 제한사항
- [사용자 가이드](https://deploy.core.today/docs): 사람이 읽는 가이드. 콘솔 화면을 기준으로 한 설명과 토큰·웹훅 만드는 법

## Optional

- [문제 해결](https://deploy.core.today/docs#troubleshooting): 증상별 원인과 조치
- [코드 샌드박스](https://deploy.core.today/llms-full.txt): 배포와 별개로, 대화형 AI 서비스가 사용자 코드를 격리된 환경에서 돌리는 API — Python·Node·헤드리스 Chromium(puppeteer·playwright)·문서 도구 (전체 가이드 9.7)
- [데이터베이스](https://deploy.core.today/llms-full.txt): 관리형 데이터베이스 엔진, 만들기 API·생성 링크, 연결하면 들어가는 환경변수 (전체 가이드 9.5)
- [사용량·단가·크레딧](https://deploy.core.today/docs#billing): 요금 규칙과 단가표