RIDM Apps 배포 가이드

RIDM Apps는 깃흐름으로 코드를 올리면 빌드·배포하고 <이름>.ridm.ai 로 공개하는 호스팅이에요(깃허브도 사용가능). 신청은 콘솔의 내 앱에서, 요금은 요금 페이지에서 확인하세요. 이용 조건은 이용약관 제3장이 정해요. 무엇이 들어 있는지 한눈에 보려면 앱 호스팅 소개를 보세요.

깃흐름 — 코드 보관·배포 (깃허브도 사용가능)

깃흐름은 흐름이 앱마다 코드 보관함(git 저장소)을 하나씩 주는 기능이에요. GitHub 계정이 없어도 돼요. 컴퓨터에 깃흐름 프로그램(명령어 hrum)을 깔고 hrum save로 저장, hrum push로 올리면 빌드되고 <이름>.ridm.ai에 공개돼요. 빌드·검사·첫 배포 규칙은 GitHub로 올릴 때와 같아요.

프로그램 내려받기와 짧은 설명은 깃흐름 프로그램 페이지에도 있어요.

설치

따로 깔 것은 없어요(Node.js 없이 도는 실행 파일이에요). 설치 스크립트는 내려받은 파일의 SHA-256이 맞을 때만 설치해요.

컴퓨터터미널에 붙여 넣을 줄설치되는 곳
macOS · Linuxcurl -fsSL https://console.hrum.ai/git/install.sh | sh~/.local/bin/hrum
Windows (PowerShell)irm https://console.hrum.ai/git/install.ps1 | iex%LOCALAPPDATA%\Programs\HRUM\bin (사용자 PATH에 추가돼요)
설치 없이 (Node만)npx -y <npx 주소> <명령>설치하지 않아요. 지금 버전의 npx 주소는 latest.json에 있어요

설치가 끝나면 새 터미널을 열고 hrum help로 확인해요. 메시지는 컴퓨터 언어에 맞춰 한국어나 영어로 나와요. hrum config lang ko로 바꾸거나 명령마다 --lang en을 붙여요. 새 버전은 hrum update로 확인해요.

로그인 (hrum login)

  1. 프로젝트 폴더에서 hrum login <앱이름>을 실행해요. 터미널에 XXXX-XXXX 모양의 코드가 나오고, 브라우저에 콘솔 승인 화면이 열려요.
  2. 콘솔에 로그인한 채로 터미널의 코드를 직접 입력하고 「확인」을 눌러요.
  3. 요청 시각·기기 이름·앱을 보고, 방금 내가 실행한 게 맞으면 「허용」을 눌러요. 누가 보내 준 코드나 링크라면 「거절」을 눌러요.

허용하면 이 컴퓨터에 그 앱 전용 토큰이 저장돼요(macOS 키체인, Windows 자격 증명 관리자, Linux libsecret, 없으면 나만 읽을 수 있는 파일). 토큰은 화면이나 로그에 나오지 않아요. 브라우저를 쓸 수 없는 컴퓨터는 아래 기기와 토큰을 보세요.

명령

괄호 안 한국어 이름도 같은 명령이에요. 모든 명령에 --json, --lang ko|en, --app <앱이름>을 붙일 수 있어요.

명령하는 일
hrum init [앱] (새프로젝트)이 폴더를 앱 저장소에 연결해요. .gitignore·.gitattributes·AGENTS.md 안내 블록을 넣고, Dockerfile이 없으면 기본 파일을 넣어요. 앱에 이미 코드가 있으면 내려받아요
hrum clone <앱> (가져오기)다른 컴퓨터에서 앱 코드를 새 폴더로 받아요
hrum save "메모" (저장)바뀐 파일을 한 번에 저장해요. 환경 파일이나 비밀값 모양이 보이면 저장하지 않아요
hrum push (올리기)흐름에 올리고 배포가 끝날 때까지 진행을 보여 줘요. 기다리지 않으려면 --no-wait
hrum pull (받기)다른 컴퓨터나 AI가 올린 것을 받아요. 같은 곳을 양쪽에서 고쳤으면 두 내용을 다 남기고 알려 줘요
hrum deploy (배포)main의 최신 저장을 다시 배포해요. 콘솔의 「지금 배포」와 같아요
hrum status (상태) · hrum history (이력)안 올린 변경, 저장 목록, 각 저장의 배포 결과
hrum logs (로그)돌고 있는 앱이 찍은 기록
hrum undo (되돌리기)서비스를 바로 전에 잘 돌던 버전으로 돌려요. 코드는 그대로예요
hrum restore <번호> (복원)코드를 그 저장 시점 내용으로 되살려 새 저장으로 남겨요. 이력은 지우지 않아요. 그다음 hrum push
hrum url (주소)앱 주소와 저장소 주소

저장·올리기·받기·배포·로그·되돌리기는 hrum login만으로 돼요(배포·되돌리기는 읽기·쓰기 기기만, 로그는 읽기 전용 기기도 돼요). hrum devices만 콘솔 계정 로그인이 필요해요. hrum login --email <내 이메일>으로 한 번 로그인하거나, 콘솔 앱 화면에서 해요.

AI 도구로 쓰기

Claude Code·Cursor·Codex 같은 AI 도구에 아래 한 줄을 붙여 넣으면 연결부터 배포까지 해요. <앱이름>만 바꿔요.

이 폴더를 흐름 앱 <앱이름>에 연결하고 배포해 줘: hrum login <앱이름> (브라우저가 열리면 터미널의 코드를 내가 입력하고 「허용」을 누를게) 후 hrum init <앱이름>, 그다음 hrum save · hrum push --json

기기와 토큰

GitHub와 오가기

깃흐름 한도

앱 하나 기준이에요. 플랜을 바꾸면 다음 올리기부터 새 한도가 적용돼요. 하루 횟수는 한국 시간 0시에 새로 세요.

한도무료베이직프로
저장소 전체500MB2GB5GB
한 번에 올리는 양100MB100MB100MB
파일 하나50MB100MB100MB
하루 올리기 횟수50번300번1,000번

저장소가 가득 차도 받기(hrum pull, git clone)는 돼요. 강제 올리기(force push)와 main 지우기는 막혀 있어요. main이 아닌 가지에 올리면 저장만 되고 배포되지 않아요.

깃흐름 오류

오류 코드는 언어와 상관없이 같아요. --json 결과의 code, 또는 git이 보여 주는 remote: [HRUM_E_…] 줄에서 봐요.

코드뜻할 일
HRUM_E_NOT_LOGGED_IN로그인이 필요해요hrum login
HRUM_E_NO_TOKEN이 컴퓨터가 그 앱에 연결되지 않았어요hrum login <앱이름>
HRUM_E_TOKEN_REVOKED · HRUM_E_TOKEN_EXPIRED연결이 끊겼거나 만료됐어요hrum login으로 다시 연결
HRUM_E_LOGIN_DENIED · HRUM_E_LOGIN_EXPIRED「거절」을 눌렀거나 10분이 지났어요hrum login 다시
HRUM_E_APP_NOT_FOUND그 이름의 앱이 내 계정에 없어요앱 이름 확인, 콘솔에서 앱 만들기
HRUM_E_APP_NOT_HRUMGitHub에 연결된 앱이에요앱 화면 「깃흐름으로 옮기기」
HRUM_E_NOT_A_REPO이 폴더가 아직 앱에 연결되지 않았어요hrum init <앱이름>
HRUM_E_UNCOMMITTED저장하지 않은 변경이 있어요hrum save "메모" 뒤 다시 올리기
HRUM_E_BEHIND흐름에 이 컴퓨터에 없는 저장이 있어요hrum pull 뒤 다시 올리기
HRUM_E_CONFLICT같은 파일을 양쪽에서 고쳤어요알려 준 파일을 고치고 hrum save
HRUM_E_SECRET_FOUND · HRUM_E_ENV_FILE비밀값이나 환경 파일이 보여요파일에서 빼고 값은 환경변수로
HRUM_E_CRLF_DOCKERFILEWindows 줄바꿈이라 빌드가 실패해요hrum save --fix-crlf
HRUM_E_CASE_COLLISION대소문자만 다른 파일 이름이 있어요하나만 남기기
HRUM_E_READ_ONLY_TOKEN읽기 전용 토큰이에요쓰기 토큰으로 다시 연결
HRUM_E_REPO_MOVEDGitHub로 옮긴 앱이라 받기만 돼요GitHub에 올리기
HRUM_E_APP_NOT_WRITABLE앱이 멈췄거나 해지 중이라 올릴 수 없어요받기는 돼요. 콘솔에서 앱 상태 확인
HRUM_E_DAILY_LIMIT오늘 올리기 횟수를 다 썼어요내일 다시
HRUM_E_REPO_FULL · HRUM_E_PUSH_TOO_BIG · HRUM_E_FILE_TOO_BIG한도를 넘었어요큰 파일을 빼거나 나눠서 올리기
HRUM_E_FORCE_PUSH · HRUM_E_DELETE_DENIED강제 올리기·지우기는 막혀 있어요hrum pull 뒤 다시 올리기
HRUM_E_PUSH_BUSY다른 곳에서 올리는 중이에요잠시 뒤 다시
HRUM_E_BUILD_FAILED · HRUM_E_START_FAILED빌드나 시작이 실패했어요메시지의 이유를 보고 고친 뒤 다시 올리기
HRUM_E_DEPLOY_TIMEOUT배포가 아직 안 끝났어요hrum status로 확인
HRUM_E_NETWORK · HRUM_E_RATE_LIMITED연결이 안 되거나 요청이 너무 많아요잠시 뒤 다시

배포 흐름

  1. 신청 — 내 앱에서 플랜과 주소(서브도메인)를 골라요. 주소는 나중에 바꿀 수 없어요.
  2. 코드 연결 — 앱 화면에서 「깃허브 연결 없이 시작하기」를 고르고 깃흐름 프로그램을 깔아 hrum login으로 연결해요. (깃허브도 사용가능: 앱 화면에서 GitHub App ridm-apps-builder를 설치하고 저장소와 브랜치를 골라요. 권한은 저장소 읽기뿐이에요.)
  3. 올리기 — hrum push로 main에 올릴 때마다(깃허브는 연결한 브랜치에 푸시할 때마다) 빌드가 시작돼요. 빌드 기록과 실패 로그는 앱 화면에 표시돼요.
  4. 첫 배포 — 빌드가 성공하면 자동 검사를 거쳐 바로 공개돼요(아래). 그 뒤의 푸시도 자동으로 반영돼요.

Dockerfile 요구사항

Next.js 스타터

next.config.js에 output: 'standalone'을 넣고 아래 Dockerfile을 저장소 루트에 두세요. public 폴더가 없으면 그 줄은 지워요.

FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

FROM node:22-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:22-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build --chown=1000:1000 /app/public ./public
COPY --from=build --chown=1000:1000 /app/.next/standalone ./
COPY --from=build --chown=1000:1000 /app/.next/static ./.next/static
USER 1000
EXPOSE 3000
CMD ["node", "server.js"]

Next.js가 아니어도 돼요. 포트 3000에서 응답하는 컨테이너면 어떤 스택이든 동작해요.

실행 환경

쿠키

여러 파트너 앱이 ridm.ai 아래에 있으므로, 게이트웨이가 쿠키를 앱 주소에만 묶어요. 앱 코드는 평소처럼 쿠키를 쓰면 돼요. 다만:

데이터베이스

앱마다 전용 PostgreSQL DB가 만들어지고, 접속 정보가 환경변수로 들어와요: DATABASE_URL(SSL 필수)과 PGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD, PGSSLMODE. 용량 한도는 플랜마다 다르며 앱 화면에 사용량이 표시돼요.

DB 연결은 인증서까지 검증하는 TLS예요. 인증서 발급 기관(Amazon RDS)은 컨테이너에 미리 설치되어 있어서(NODE_EXTRA_CA_CERTS·PGSSLROOTCERT) 코드에 SSL 옵션을 따로 넣지 않아도 돼요 — new Pool({ connectionString: process.env.DATABASE_URL, max: 2 })면 돼요. 연결은 앱당 3개까지라 풀 크기는 2 이하로 두세요.

환경변수

콘솔에서 비밀키 넣기 (사람)

어떤 이름이든 사람이 콘솔에서 넣을 수 있어요. AI 도구가 넣을 수 없는 이름(아래)도 이 방법으로 넣어요.

  1. console.hrum.ai에 로그인하고 왼쪽 메뉴의 내 앱을 열어요.
  2. 앱 카드를 아래로 내려 환경변수 칸을 찾아요. 지금 저장된 이름이 값 대신 ••••••••로 보여요.
  3. 첫 칸 이름 (예: STRIPE_SECRET_KEY)에 이름을 적어요. 소문자나 다른 글자는 입력하는 대로 대문자·밑줄로 바뀌어요.
  4. 둘째 칸 값에 값을 붙여 넣어요. 입력란은 비밀번호처럼 가려져요.
  5. 저장을 누르면 「환경변수를 저장했어요: 이름. 앱이 곧 다시 시작돼요.」가 나와요. 같은 이름으로 다시 저장하면 값이 바뀌어요.
  6. 지울 때는 그 줄의 삭제 → 확인 창의 삭제를 눌러요. 지우면 앱이 다시 시작되고 값은 되살릴 수 없어요.

값을 옮기는 동안 지킬 것:

AI로 비밀키 넣기 (AI 운영 토큰)

AI 코딩 도구가 사람 대신 환경변수를 넣으려면 AI 운영 토큰이 있어야 해요. 콘솔 관리 토큰(hrum_cm_…, AI로 콘솔 관리하기)을 발급할 때 사람이 hosting_ops 권한을 체크한 토큰이에요. 이 권한이 있으면 작업마다 동의를 다시 받지 않아요. 환경변수 넣기는 값이 AI 모델을 거치지 않도록 HRUM MCP에 두지 않았으니 아래 HTTP 경로를 써요.

AI 경로로 넣을 수 있는 이름은 _KEY·_SECRET·_TOKEN·_PASSWORD·_PASSWD·_PASS·_SALT·_CLIENT_ID로 끝나는 이름뿐이에요(예: STRIPE_SECRET_KEY, MASTER_KEY). 그중에서도 실행 환경이나 접속 주소를 바꾸는 이름은 거절돼요: _URL·_URI·_ENDPOINT·_HOST·_PROXY로 끝나는 이름, NODE_·LD_·DYLD_·PYTHON·JAVA_·_JAVA_·JDK_·RUBY·PERL·GIT_·NPM_CONFIG_·GLOBAL_AGENT_·AWS_ENDPOINT_URL로 시작하는 이름, 그리고 HTTP_PROXY·HTTPS_PROXY·NODE_TLS_REJECT_UNAUTHORIZED·SSL_CERT_FILE·PATH·OPENAI_API_BASE 같은 이름. 다른 이름(예: ADMIN_PATH, SMTP_HOST)은 사람이 콘솔에서 넣어요. 지우기는 AI 경로로도 할 수 있어요(예약 이름 제외).

토큰 받기 — 30일 동안 써요.

  1. AI가 인증 없이 POST https://api.hrum.ai/api/v1/partners/v1/console-ai/consents에 {"action":"token_issue","payload":{"scopes":["hosting_ops"],"label":"내 앱 운영"}}을 보내요. 응답 data에 consentUrl·userCode(8자리)·code·pollSecret이 와요.
  2. AI는 사용자에게 consentUrl과 8자리 코드만 보여 줘요. pollSecret은 보여 주지 않아요.
  3. 사람이 콘솔에 로그인한 브라우저로 링크를 열고(10분 안에), 확인 코드 칸에 AI 도구 화면의 8자리 코드를 넣고, hosting_ops를 체크한 뒤 동의를 눌러요. 체크 아래 경고(새면 환경변수 덮어쓰기·배포·재시작이 가능하다는 내용)를 읽고 눌러요.
  4. AI가 GET …/console-ai/consents/{code}를 헤더 X-Consent-Poll-Secret과 함께 부르면, 승인 뒤 첫 응답의 data.token.value로 토큰을 딱 한 번 받아요. 화면에 찍지 말고 바로 비밀 저장소(키체인, 권한 600 파일 등)에 넣어요.
  5. 필요 없어지면 콘솔 API 키 화면의 「AI 콘솔 관리 토큰」에서 취소를 눌러요. 그 즉시 막혀요. 계정당 살아 있는 토큰은 10개까지예요.

호출 — 기본 주소 https://api.hrum.ai, 헤더 Authorization: Bearer hrum_cm_…. 앱 id는 GET /api/v1/partners/v1/console-ai/hosting 응답의 data.apps[].id(UUID)예요.

할 일요청응답
이름 목록GET /api/v1/partners/v1/console-ai/hosting/apps/{appId}/env{"success":true,"data":{"env":{"names":[…]}}} — 값 없음
넣기·바꾸기PUT …/hosting/apps/{appId}/env/{NAME} 본문 {"value":"…"}바뀐 이름 목록. 앱이 다시 시작돼요
지우기DELETE …/hosting/apps/{appId}/env/{NAME}바뀐 이름 목록. 앱이 다시 시작돼요

예시(bash·zsh). 값과 토큰을 명령줄 인자로 넘기지 않고, 값은 표준 입력으로 보내요. $APP_ID, 키체인 항목 이름은 자기 것으로 바꿔요.

# 1) Read secrets into shell variables (nothing is printed)
HRUM_CM_TOKEN=$(security find-generic-password -s hrum-console-ops -w)
VALUE=$(security find-generic-password -s myapp-STRIPE_SECRET_KEY -w)

# 2) Value goes through stdin, token through a header file: neither shows up in ps or shell history
printf '%s' "$VALUE" | jq -Rs '{value: .}' | curl -s -X PUT \
  -H @<(printf 'Authorization: Bearer %s' "$HRUM_CM_TOKEN") \
  -H 'Content-Type: application/json' --data-binary @- \
  "https://api.hrum.ai/api/v1/partners/v1/console-ai/hosting/apps/$APP_ID/env/STRIPE_SECRET_KEY" \
  | jq '.data.env.names // .'

# 3) Forget the value
unset VALUE

저장이 끝나면 응답에 이름 목록만 나와요. 앱이 새 값으로 다시 시작됐는지는 앱 주소를 열어 확인해요.

AI로 배포하고 로그 보기 (AI 운영 토큰)

같은 AI 운영 토큰(hosting_ops)으로 배포를 시작하고, 배포 상태와 앱이 찍는 로그를 볼 수 있어요. 사이트에 들어가지 않아도 돼요.

HRUM MCP 0.3.3부터는 MCP 도구로도 같은 일을 해요: hrum_hosting_deploy(배포 시작)·hrum_hosting_deploys(배포 상태)·hrum_hosting_logs(런타임 로그). hrum_ai_connect로 hosting_ops 권한 토큰을 받은 뒤 부르면 되고, 앱 id는 hrum_hosting_status에서 봐요. MCP를 쓰지 않는 도구는 아래 HTTP 경로를 써요.

할 일요청응답
배포 시작POST …/hosting/apps/{appId}/deploy 본문 {} 또는 {"commit":"40자 sha"}{"deployId","commitSha","retried","status":"queued"}. 콘솔 「지금 배포」와 똑같이 연결 브랜치의 최신 커밋을 빌드해요(첫 배포 검토·요금제 규칙도 같아요). commit은 그 최신 커밋일 때만 받아요 — 예전 커밋은 아직 안 돼요(400 COMMIT_NOT_BRANCH_HEAD). 1분에 2번까지
배포 상태GET …/hosting/apps/{appId}/deploys?limit=20최신순 id·commitSha·status·queuedAt·startedAt·finishedAt·liveAt·failReason·scanFindings(비밀값 검사에 걸린 파일·줄·규칙만)·logTail(빌드 로그 끝)·startFailReason·startFailLog
로그 요청POST …/hosting/apps/{appId}/logs 본문 {"lines":100}(1~200)202 {"requestId"}
로그 받기GET …/hosting/apps/{appId}/logs/{requestId}status가 pending이면 2~3초 뒤 다시, delivered면 lines. 3분 지나면 expired

로그와 실패 사유는 내보내기 전에 가려요: 그 앱에 저장된 환경변수 값, 그리고 sk-…·AKIA…·Bearer …·JWT·…_live_… 같은 키 모양은 [redacted]로 바뀌어요. 그래도 앱이 비밀값을 로그에 찍지 않게 만드는 게 먼저예요. 모든 호출(거절 포함)은 토큰·앱·결과와 함께 기록돼요.

콘솔 로그인 세션이나 HRUM MCP 로그인 세션으로도 같은 경로가 있어요: POST …/console/hosting/apps/{appId}/deploy-now(MCP는 가입으로 만든 세션만), GET …/console/hosting/apps/{appId}/deploys, POST …/console/hosting/apps/{appId}/logs 본문 {"lines":100}(1~200, MCP는 가입으로 만든 세션만) → GET …/logs/{requestId}. 자기 앱만 되고, 로그 줄은 같은 규칙으로 가려져요. 가져온 로그 내용은 전달(또는 요청)한 때부터 24시간 뒤 지워져요(2026-12-01부터 7일, 이용약관 제20조 제5항).

HRUM_CM_TOKEN=$(security find-generic-password -s hrum-console-ops -w)
API=https://api.hrum.ai/api/v1/partners/v1/console-ai/hosting/apps/$APP_ID
git push origin main
curl -s -X POST -H @<(printf 'Authorization: Bearer %s' "$HRUM_CM_TOKEN") \
  -H 'Content-Type: application/json' -d '{}' "$API/deploy" | jq '.data // .'
curl -s -H @<(printf 'Authorization: Bearer %s' "$HRUM_CM_TOKEN") \
  "$API/deploys?limit=3" | jq '.data.deploys[] | {id, commitSha, status, liveAt, failReason}'

비밀키 안전 규칙 (AI 도구가 지킬 것)

실제 있었던 일: 판매 관리 앱을 만들던 AI 도구가 앱의 마스터 키를 환경변수로 넣으려 했는데, 그때는 AI가 쓸 운영 경로가 없어 거기서 멈췄어요. 지금은 MASTER_KEY처럼 _KEY로 끝나는 이름은 AI 운영 토큰으로 넣을 수 있고, 그 밖의 이름은 사람이 콘솔에서 넣어요. 어느 쪽이든 값이 채팅으로 오가지 않게 해요.

환경변수 오류

오류 본문은 {"success":false,"statusCode":…,"message":"…"}이에요. 환경변수 오류에는 code가 없으니 상태 코드와 아래 문구 앞부분으로 구분해요. 원문 전체는 llms.txt에 있어요.

상태메시지 앞부분원인 → 해결
400이름은 대문자·숫자·밑줄만이름 규칙 위반 → 대문자·숫자·밑줄, 숫자로 시작 안 함, 64자 이하
400플랫폼이 쓰는 이름이라PORT·HOSTNAME·NODE_OPTIONS·DATABASE_URL, RIDM_·PG 접두 → 다른 이름으로
400AI 연결이 자동으로 넣는 이름이라HRUM_API_KEY → 이 앱은 「AI 연결」이 켜져 있어 플랫폼이 넣어요. 직접 넣으려면 「AI 연결」을 꺼요
400이 계정에서 발급한 API 키만 넣을 수 있어요내 콘솔 「API 키」의 키를 넣어요
400AI 연결이 앱마다 만든 키는 넣을 수 없어요콘솔 「API 키」에서 발급한 키를 넣어요
400값을 입력해 주세요값이 비었어요
400값에 줄바꿈을 넣을 수 없여러 줄 값(PEM 개인 키 등) → base64 한 줄로 바꿔 넣고 앱에서 풀어 써요
400값은 3000바이트까지값이 3,000바이트를 넘어요 → 큰 값은 DB나 외부 비밀 저장소에
400환경변수 전체 크기가 한도를 넘어앱 전체 합계가 64KB를 넘어요 → 안 쓰는 환경변수를 지우거나 값을 줄여요
400실행 환경을 바꾸는 이름이라 AI 경로AI 경로 거절 이름 → 사람이 콘솔에서
400AI 경로(AI 운영 토큰·MCP)로는 _KEY비밀 이름 접미가 아님 → 이름을 바꾸거나 사람이 콘솔에서
400Validation failed (uuid is expected)앱 id가 UUID가 아님 → GET /console-ai/hosting의 apps[].id
401MGMT_TOKEN_INVALID토큰이 없거나 만료·취소 → 새로 발급
403MGMT_SCOPE_DENIED (scope: "hosting_ops")토큰에 hosting_ops가 없어요 → 체크해서 새로 발급
404앱을 찾을 수 없다른 계정의 앱이거나 삭제된 앱 → 앱 id 확인
404없는 환경변수지우려는 이름이 없어요 → 이름 목록 확인
409해지된 앱은 환경변수를 바꿀 수 없해지 진행 중인 앱 → 바꿀 수 없어요
409환경변수는 앱당 60개까지안 쓰는 이름을 지우고 다시
429—넣기·지우기는 1분에 30번까지 → 잠시 뒤 다시
503환경변수 저장소가 준비되지 않서버 쪽 문제 → 잠시 뒤 다시, 계속되면 문의

AI 연결

앱에서 사주·AI API를 부를 수 있게 이 앱만 쓰는 API 키를 플랫폼이 넣어 주는 기능이에요. 모든 계정에서 쓸 수 있어요.

  1. 켜기 — 콘솔 앱에서 앱 상세를 열고 「AI 연결 사용」을 켜요. 앱 전용 키가 만들어져 환경변수 HRUM_API_KEY로 들어가고, 앱이 다시 시작돼요.
  2. 부르기 — 앱 서버 코드에서 process.env.HRUM_API_KEY를 읽어 X-Partner-Api-Key 헤더에 담아요. 키 값은 콘솔에도 보이지 않아요. 브라우저로 보내는 코드에는 넣지 마세요.

켜 둔 동안에는 HRUM_API_KEY를 직접 넣을 수 없어요. 직접 넣은 값이 있으면 켜기 전에 지워요(안 지우면 「기존 HRUM_API_KEY 환경변수를 먼저 지워 주세요」가 떠요). 이 키로 쓴 요금은 내 크레딧에서 나가고, 앱 상세에서 정한 하루 사용 한도에 닿으면 그날은 멈춰요. 끄면 키가 바로 끊기고, 다시 켜면 새 키가 만들어져요. 이 키로는 결제 API를 부를 수 없어요 — 앱에서 결제 받기는 콘솔에서 발급한 키로 해요.

앱에서 결제 받기

앱 이용자의 결제를 흐름 결제 페이지로 받을 수 있어요. 판매는 판매자(개인·개인사업자·법인)로 등록하고 승인된 뒤에 열려요. 판매자 등록은 콘솔의 정산에서 해요. 조건은 이용약관 제32조~제39조가 정해요. 무료 플랜 앱도 판매할 수 있어요. 다만 월 전송 한도에 이르거나 정지되어 앱 공개가 멈춘 동안에는 새 결제 열기가 409 APP_NOT_SERVING으로 거절돼요. 이미 연 결제와 주문 확인·환불은 그대로 돼요.

  1. API 키 넣기 — 콘솔 API 키에서 발급한 키를 환경변수(예: HRUM_PARTNER_KEY)로 넣어요. 「AI 연결」이 넣어 주는 HRUM_API_KEY로는 결제 API를 부를 수 없어요. 키는 서버 코드에서만 쓰고 브라우저로 보내지 마세요.
  2. 상품 등록 — POST /api/v1/partners/v1/storefront/skus 본문 {"appId","name","priceWon"}. 가격은 여기 등록한 값으로만 결제돼요. 30일 이용권처럼 한 번 결제하고 자동 갱신 없이 앱이 기간을 관리하는 상품은 "accessDays"(이용 기간, 1~30일)를 같이 넣어요. 환불 기준은 "refundPolicy"(1,000자까지)에 넣어요. 둘 다 선택이고, 넣으면 결제 화면에 그대로 보여요. 자동 갱신(정기결제) 상품은 받지 않아요.
  3. 결제 열기 — 서버에서 POST /api/v1/partners/v1/storefront/checkouts 본문 {"appId","skuId","qty","returnUrl"}을 보내고, 응답의 checkoutUrl로 이용자를 보내요. returnUrl은 이 앱 주소(<이름>.ridm.ai 또는 연결한 도메인)의 https 주소만 돼요.
  4. 결과 확인 — 결제가 끝나면 이용자가 returnUrl?orderId=…로 돌아와요. 서버에서 GET /api/v1/partners/v1/storefront/orders/{orderId}로 status가 paid인지 확인한 뒤 상품을 주세요. 주소에 붙은 값만 믿으면 안 돼요.

모든 요청에는 X-Partner-Api-Key 헤더가 필요해요. 환불이 필요하면 주문번호와 함께 [email protected]로 알려 주세요. 환불되면 주문 status가 canceled 또는 partial_canceled로 바뀌어요.

결제·환불 시험 — 시험용 결제 모드는 따로 없어요. 가장 싼 상품을 실제 카드로 결제한 뒤, 결제일부터 7일 안에 결제 화면의 「환불 요청」이나 [email protected]로 그 주문의 전액 환불을 요청해요. 전액 환불된 시험 결제는 정산되지 않아 자기 거래로 보지 않고, 남는 비용도 없어요(이용약관 제44조 제5항). 개인 제작자 상품은 내 콘솔에 로그인한 브라우저에서는 결제가 막혀요.

자체 결제와 흐름 결제는 혼용할 수 없어요 — 흐름 결제로 판매하는 앱은 상품·서비스 대금(포인트 충전 포함)을 흐름 결제로만 받아요. 내 명의로 계약한 결제대행사(자체 결제)를 쓰려면 그 앱에서는 흐름 판매를 쓰지 않아요. 자체 결제의 운영 조건은 자유롭게 정할 수 있고, 그 매출과 환불은 내가 직접 처리해요(이용약관 제44조 제7항).

const res = await fetch("https://api.hrum.ai/api/v1/partners/v1/storefront/checkouts", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-Partner-Api-Key": process.env.HRUM_PARTNER_KEY },
  body: JSON.stringify({ appId, skuId, qty: 1, returnUrl: "https://myapp.ridm.ai/paid" }),
});
const { checkoutUrl } = (await res.json()).data;

키 권한별로 부를 수 있는 것

키를 만들 때 권한을 고를 수 있어요. 고른 권한 밖의 경로를 부르면 403 KEY_SCOPE_MISSING이에요. 권한을 고르지 않은 기존 키는 모든 경로를 그대로 불러요. 경로 전체는 OpenAPI 문서에 있어요.

정산 데이터 API

콘솔 「정산」 화면과 같은 숫자를 서버에서 받아요. 내 키의 내 데이터만 보여요. 기간 from·to는 한국 날짜(YYYY-MM-DD, 양끝 포함)이고, 비우면 이번 달이에요. 한 번에 366일까지 돼요.

const res = await fetch("https://api.hrum.ai/api/v1/partners/v1/settlement/summary?from=2026-11-01&to=2026-11-30", {
  headers: { "X-Partner-Api-Key": process.env.HRUM_PARTNER_KEY },
});
const { sales, payouts, payoutFee } = (await res.json()).data;

판매자 웹훅

결제 완료·환불·지급이 생기면 내 서버로 알려 드려요. 주소는 https://만 되고(포트 443·8443), 사설·내부 주소는 등록할 수 없어요.

  1. 주소 등록 — PUT /api/v1/partners/v1/webhooks/endpoint 본문 {"url":"https://myapp.ridm.ai/hrum/webhook"}. 응답의 secret(whsec_…)은 이때 한 번만 보여요. 바로 서버 환경변수 HRUM_WEBHOOK_SECRET에 넣으세요. 새로 받으려면 {"url": …, "rotateSecret": true}.
  2. 이벤트 — order.paid(결제 완료), order.refunded(환불 한 건), payout.scheduled(지급 예정), payout.completed(지급 완료), webhook.test(POST /webhooks/test). 본문은 {"id","type","created","data"}이고 구매자 정보는 들어 있지 않아요. 같은 일은 같은 id로 한 번만 만들어지니 id로 중복을 걸러 주세요.
  3. 플랫폼 사본 — 플랫폼 키로 주소를 등록하면 그 플랫폼에서 열린 판매자 주문의 order.paid·order.refunded 사본도 와요. 헤더·서명은 같고 id는 판매자 쪽과 달라요. data에 sellerId·spaceId가 더 들어 있어요.
  4. 서명 확인 — 헤더 Hrum-Signature: t=<unix초>,v1=<hex>. v1은 비밀값으로 만든 HMAC-SHA256(t + "." + 받은 본문 그대로)예요. 5분보다 오래된 t는 버리세요.
  5. 다시 보내기 — 10초 안에 2xx로 답하지 않으면 1분·5분·30분·2시간·12시간 뒤 다시 보내요(최대 6번). 전송 기록은 GET /webhooks/deliveries, 다시 보내기는 POST /webhooks/deliveries/{eventId}/redeliver.
const crypto = require("node:crypto");
function verifyHrumWebhook(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(String(header || "").split(",").map((p) => p.trim().split("=")));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const want = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const got = Buffer.from(parts.v1 || "", "hex");
  return got.length === want.length && crypto.timingSafeEqual(got, want);
}
// Express: 본문을 JSON으로 바꾸기 전에 원본 그대로 확인해요
app.post("/hrum/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verifyHrumWebhook(raw, req.get("Hrum-Signature"), process.env.HRUM_WEBHOOK_SECRET)) return res.sendStatus(400);
  const event = JSON.parse(raw); // event.id 를 이미 처리했으면 200만 돌려줘요
  res.sendStatus(200);
});

첫 배포와 자동 검사

첫 빌드가 성공하면 자동 검사를 거쳐 자동으로 승인되고, 바로 주소가 공개돼요. 첫 배포가 공개되기 전에는 유료 요금이 차감되지 않아요. 저장소에 비밀값(키·토큰·비밀번호)이 들어 있으면 빌드가 실패해요. 새 외부 접속 대상·새 위험 패턴이 발견되거나 저장소 소유자가 바뀌어도 배포는 자동으로 반영되며, 그 내용은 기록돼요. 모든 자동 승인과 검사 결과는 기록되고 운영자가 사후에 확인하며, 문제가 있으면 공개를 중지할 수 있어요. 공개가 중지되면 사유를 이메일과 앱 화면으로 알려 드려요. 금지 행위는 약관 제26조를 보세요.

요금·한도

앱 종류: 일반 앱 / 메타버스 — 호스팅은 하나이고, 콘솔 「내 호스팅」에서 신청할 때 앱 종류를 골라요. 일반 앱 플랜은 앱마다, 메타버스 플랜은 계정 하나에 걸려요. 이 문서의 나머지는 일반 앱 기준이에요.

플랜별 요금·메모리·DB·월 전송은 요금 페이지에 있어요. 유료 플랜 요금은 충전한 크레딧에서 매월 차감돼요. 결제일에 잔액이 부족하면 앱이 멈추고, 충전하면 자동으로 재개돼요. 월 전송량은 방문자에게 보낸 응답과 앱이 밖으로 보낸 트래픽(외부 API 호출·업로드·DB 쓰기 포함)을 합한 양이에요. WebSocket은 주고받은 프레임 양쪽 방향이 모두 들어가요. 한도에 이르면 열린 WebSocket도 1008로 닫혀요. 한도에 이르면 공개와 앱 실행이 함께 멈추며(다음 달 1일에 재개), 유료 플랜은 앱 화면에서 전송 블록을 사면 몇 분 안에 다시 켜져요. 80%와 한도 도달 때 이메일로 알려 드려요.

백업·해지

문의: contact@float.do