# FutureInfra service guide for AI agents

## Users here usually know nothing about infrastructure

Most FutureInfra users are "vibe coders": they know what they want to build or automate,
but not what a server, container, database or CDN is, and they cannot pick a size.

- Do not ask the user to choose products or sizes. Listen to the goal, pick ONE option yourself, and confirm it
  in plain Korean as: what you will use — one-line reason — expected monthly cost. Build after they agree.
- Start with the smallest, cheapest option; it can be resized later.
- Avoid jargon. If you must use a term, explain it in brackets (e.g. 데이터베이스(정보를 저장하는 곳)).
- When done, report: the URL, the expected monthly cost, and what to do next — in plain words.

How to choose:
- One website / web app → an **app** (apps.*): 5,500 KRW/month, HTTPS address included, no server to manage.
  Needs to store sign-ups, bookings, etc. → add the database sidecar: 7,700 KRW/month total.
- Something that must run on a schedule or all the time (automation, bot, crawler), needs custom software, or 3+ apps → a **server** (cloud.*):
  - Nano (1 vCPU · RAM 1GB · disk 30GB) — 9,000 KRW/month
  - Small (2 vCPU · RAM 2GB · disk 40GB) — 14,000 KRW/month
  - Medium (4 vCPU · RAM 4GB · disk 100GB) — 32,000 KRW/month
  - Large (4 vCPU · RAM 8GB · disk 160GB) — 66,000 KRW/month
- AI chat / images / video / speech → API only (llm, gen, ai), pay per use, no server.
- A free *.futureinfra.app address is issued automatically. Domain purchases need human approval.
- The UTM firewall add-on (150,000 KRW/month) is only for explicit corporate security requirements.

Common goals (Korean prompt a user can paste into Claude Code):
- 홈페이지·랜딩 페이지 → 앱 1개 · 월 5,500원
  `퓨처인프라로 [가게 소개 홈페이지]를 만들어서 인터넷에 올려 줘. 필요한 건 알아서 골라 만들고, 다 되면 접속 주소와 한 달 예상 요금을 쉬운 말로 알려 줘.`
- 예약·신청·회원가입 받는 사이트 → 앱 1개 + 데이터베이스 · 월 7,700원
  `퓨처인프라로 [미용실 예약을 받는 사이트]를 만들어 줘. 예약 정보는 데이터베이스에 저장하고, 관리자가 예약 목록을 볼 수 있게 해 줘. 다 되면 주소·관리자 로그인 방법·한 달 예상 요금을 알려 줘.`
- 챗봇·AI 기능 붙이기 → 앱 1개 + AI(쓴 만큼) · 월 5,500원부터
  `퓨처인프라로 [우리 가게 자주 묻는 질문에 답하는 챗봇]을 만들어 줘. AI 모델은 퓨처인프라 AI 라우터를 쓰고, 답할 내용은 세컨브레인에 저장해 둬. 다 되면 주소와 한 달 예상 요금(AI 사용료 포함)을 알려 줘.`
- 매일 자동으로 모아서 알려 주기 → 작은 서버(Nano) · 월 9,000원
  `퓨처인프라로 [매일 아침 8시에 업계 뉴스를 모아 요약해서 내 메일로 보내는 자동화]를 만들어 줘. 가장 싼 사양으로 시작하고, 다 되면 언제 돌아가는지·결과를 어디서 보는지·한 달 예상 요금을 알려 줘.`
- 가격·리뷰 모니터링 → 작은 서버(Nano) 또는 스크래핑 · 월 9,000원부터
  `퓨처인프라로 [경쟁사 상품 5개의 가격을 매일 확인해서 바뀌면 알려 주는 모니터링]을 만들어 줘. 공개된 정보만 모으고, 결과는 엑셀로 받을 수 있게 해 줘. 다 되면 한 달 예상 요금을 알려 줘.`
- AI 이미지·영상·음성 만들기 → 쓴 만큼(장·초·글자 단위)
  `퓨처인프라 AI 로 [우리 상품 소개 이미지 3장과 30초 한국어 내레이션]을 만들어 줘. 만들기 전에 예상 비용부터 알려 줘.`

## Connecting — follow this so the user never gets stuck

The user is not technical. They should only ever (a) click a login/approve button in a browser, or (b) paste ONE line
you give them into a terminal. Tell them exactly what to click or type, one step at a time, in plain Korean.

0. Already connected? If you have FutureInfra tools, call `account.me` and say the organisation name in one line. If that is the
   organisation the user means, skip the rest. If they want a DIFFERENT organisation, run A anyway — they pick the organisation
   on the 허용 page — and register it under altMcpName so both connections stay.
Speak Korean to the user at every step, including while you wait.

No account yet? Nothing to ask first — the page in A lets the user sign in OR sign up, then press 허용.

If you can open a browser, do it for them — every page below is a plain URL. Use your browser tool, or run (ALWAYS quote
the URL — it contains `&`, which a shell otherwise cuts off): Windows — prefer PowerShell `Start-Process "<url>"`
(cmd: `start "" "<url>"`, Git Bash: `cmd //c start "" "<url>"`), macOS `open "<url>"`, Linux `xdg-open "<url>"`.
Then the user only logs in and presses 허용/승인. Never type the user's password, 2FA code or card number, and never press
approve/pay for them — those stay with the person.

A. One-click connect (preferred — works inside any app that can run a command or open a URL)
1. POST https://futureinfra.ai/v1/public/connect/start with JSON {"client":"Claude Code"} — no secret involved. HTTP 201 returns:
   deviceCode (keep it to yourself), userCode (e.g. ABCD-EFGH), verificationUrl, expiresIn (600 s), interval (3 s),
   tellUser (a ready Korean sentence for the user) and next.
2. Open verificationUrl in the user's browser yourself (see above); if you cannot, show the link. Then show tellUser, e.g.
   "브라우저에서 퓨처인프라에 로그인하고(계정이 없으면 가입), 코드 <userCode> 가 맞는지 확인한 뒤 [허용]을 눌러 주세요".
3. POST https://futureinfra.ai/v1/public/connect/poll {"deviceCode":"..."} every `interval` seconds. Responses:
   - pending — keep waiting. It also has `viewed` (true once the user reached the 허용 page) and `expiresIn` (seconds left).
     If `viewed` is still false after ~60 s, nobody has reached the 허용 page yet (browser did not open, or stuck at login).
     Open the same verificationUrl once more with another method (e.g. PowerShell Start-Process), show the link, and ask what
     they see if you can talk to them. Keep polling the SAME deviceCode — only expiry needs a new one.
   - slow_down (HTTP 200) — you polled too fast; wait `interval` + 2 seconds.
   - denied (HTTP 200) — the user pressed 거절. Ask if it was a mistake; if they want to retry, go back to step 1.
   - expired (HTTP 410, with a Korean message) — 10 minutes passed. Do NOT reuse the deviceCode; go back to step 1.
4. approved (HTTP 200, status "approved") — sent ONCE. Fields: apiKey, org.name, scopes, mcpUrl, mcpName, altMcpName, claudeCommand, next.
   The key gets the console's default permissions (servers, apps, domains, AI, git, storage, billing read …; never approvals or
   member management) and no spending cap unless the user chose one; it may carry an expiry the user picked.
   - Tell the user the organisation name from org.name in one line (no need to call /v1/me).
   - Run `claude mcp list` first. If a server named futureinfra already exists, do NOT remove it (it may be another
     organisation) — replace the name in claudeCommand with altMcpName (futureinfra-<org in latin letters, or the last 6
     characters of the org id>). If that name exists too, add -2, -3 …
   - Run claudeCommand. Registering stores the key in the MCP client's own settings on this computer — that is the ONE place
     a key is meant to live, and the command will appear in your local tool log. Do not put it anywhere else (repo, notes,
     memory, chat) and never repeat the key or the command in your messages to the user.
     If running it is blocked, ask the user to allow that one permission prompt; if that is impossible, use B instead.
   - Ask the user to open a new session (or restart the app) so the FutureInfra tools load. The connection is saved.
     account.me only works in that new session — in the current one, org.name from this response is your confirmation.
   - Lost the response before registering? The key cannot be fetched again. Tell the user to revoke "AI 연결 · <client>" in
     https://futureinfra.ai/console/?screen=api-keys and run A again.

B. Claude Code — browser login without a key
1. Run it yourself: `claude mcp add --transport http --scope user futureinfra https://futureinfra.ai/v1/mcp`
   It contains no secret, so auto mode does not block it. If the name futureinfra already exists, do not touch it —
   use `futureinfra-2` (then -3, -4 … if taken) as the name instead. A gives you altMcpName for this.
2. The login must be done by the user:
   - Claude Code (terminal or the Claude desktop app's Code tab): tell them —
     "채팅 입력창에 /mcp 입력 → 목록에서 futureinfra 선택 → 로그인(Authenticate) → 열린 브라우저에서 퓨처인프라 로그인 → 허용 → 끝나면 '다 했어'라고 말해 주세요".
     In the desktop app the same login is also under the app's Connectors menu (futureinfra → 로그인). Do not claim `/mcp` is unavailable — it works in the app.
   - Only if neither works (some IDE extensions): "터미널(윈도우: PowerShell, 맥: 터미널)에서 claude 입력 → /mcp → futureinfra → 로그인 → 끝나면 /exit".
     The login is stored on this computer for the user, so a new session can use it. If it still says "Needs authentication", use A or C.
   - After they say it is done, check again (call a FutureInfra tool or `claude mcp list`). 401 means the login is not finished yet — repeat the steps, do not guess.
3. Confirm with `account.me` and say the organisation name in one line.

C. API key — any MCP client
1. Open https://futureinfra.ai/console/?screen=api-keys for them (or send the link) → "+ 키 발급" → choose a preset → 발급.
2. The console shows a ready-made Claude Code command. The USER pastes it into their own terminal and presses Enter.
   Never ask the user to paste the key into chat. If they already did: you may run `claude mcp add ... --header "Authorization: Bearer <key>"`
   (it only writes the local MCP settings), suggest revoking that key later, and never send the key to any URL yourself (curl, fetch) —
   auto-mode safety checks block that as secret exfiltration.
3. Ask them to open a new session, then confirm with `account.me`.

When Claude Code blocks one of your commands (auto mode, permission prompt):
- Do not retry, rephrase, or work around it. Show the exact command in a code block and say "이 한 줄을 터미널에 붙여 넣고 엔터를 눌러 주세요",
  or, if a permission prompt is on screen, ask them to press 허용 (allow) for that one command.
- Exception: never show a command that contains a key. For those, ask for the permission prompt, or switch to B (no key).
- Never suggest turning off safety checks or switching to a bypass/"권한 무시" mode.

When FutureInfra says no:
- 401 → not logged in or wrong key → connect again with A.
- 403 `insufficient_scope` → the key lacks that permission. Tell them: 콘솔 › API 키 → 그 키 → 권한에 <scope> 추가, or connect again with B (browser login carries the user's own role).
- 403 `human_session_required` / 202 `pending_approval` → show the `userAction.consoleUrl` / `action_required.url` link as-is and say
  "이 링크를 열어 '승인'을 눌러 주세요". The server runs the action after approval — do not call it again.
- Not enough balance → https://futureinfra.ai/console/?screen=billing → "충전". Purchases and payments are always done by the user in the browser.
- Only the organisation's owner/admin can issue keys, approve, and pay. If the user is a plain member, tell them to ask their admin.

## MCP tools (247)

Generated from the server's registry. If a tool is listed here it exists; if it
is not, it does not. Tools marked *(human approval required)* return a pending
approval rather than executing, and no scope can approve it.

### llm

- `llm.chat` — Send an OpenAI-compatible chat completion request.
- `ai.voices` — AI 보이스 목록 — 음성 합성(TTS)에 쓸 수 있는 한국어 목소리(모델·voice id·이름·성별·나이대·톤·용도·미리듣기 주소·1,000자당 원). 조건(q·gender·language·mood·use·emotion·free·maxFirstSoundMs·sort)으로 골라 준다. 

### cloud

- `cloud.list_instances` — List this tenant's cloud instances and their current state. `status` is the desired state; `powerState` (running|stopped|paused|unknown) + `powerReason` is the 
- `cloud.catalog` — 가상서버를 만들 때 고를 수 있는 것들 — blueprint(OS 이미지) 와 plan(사양) 목록. **cloud.create_instance 전에 반드시 여기서 id 를 얻어라.**
- `cloud.get_instance` — 가상서버 한 대의 상세 — 상태·사양·내부 IP·공인 IP·도메인. 실제 전원은 powerState·powerReason·powerCheckedAt 으로 본다(status 는 원하는 상태). powerReason=suspended_insufficient_credits 면 잔액 부족으로 
- `cloud.power` — 가상서버 전원 조작 — start | stop | reboot. stop 은 서비스가 즉시 끊긴다.
- `cloud.list_hostnames` — 이 가상서버에 붙은 호스트네임(공개 주소) 목록.
- `cloud.list_snapshots` — 가상서버의 스냅샷 목록.
- `cloud.create_snapshot` — 스냅샷을 찍는다. **되돌리기 어려운 작업(패키지 교체·설정 덮어쓰기) 전에 먼저 해라.**
- `cloud.rollback_snapshot` *(human approval required)* — 스냅샷 시점으로 되돌린다. ★현재 디스크 상태를 버린다 — 사람 승인이 필요하다.
- `cloud.delete_snapshot` — 스냅샷을 지운다. 디스크 상태는 그대로고 되돌릴 지점만 없어진다.
- `cloud.list_backups` — 가상서버의 백업 목록(스냅샷과 다르다 — 백업은 별도 저장소에 있다).
- `cloud.create_backup` — 지금 백업을 뜬다(자동 백업은 새벽 2시). **위험한 작업 전에 스냅샷 대신 이걸 쓰면** 디스크가 통째로 망가져도 살아남는다 — 백업은 다른 장비에 있다. 몇 분 걸리고, 끝나면 cloud.list_backups 에 나타난다.
- `cloud.restore_backup` *(human approval required)* — 백업으로 복원한다. ★현재 상태를 덮어쓴다 — 사람 승인이 필요하다. volid 는 cloud.list_backups 에서 얻는다.
- `cloud.publish` — 가상서버의 포트를 호스트네임으로 공개한다(우리 프록시 경유, TLS 포함). 공인 IP 없이도 인터넷에서 닿는다.
- `cloud.unpublish` — 공개를 내린다. 가상서버는 그대로 돌고 바깥에서만 안 닿는다.
- `cloud.list_images` — 저장해 둔 내 이미지 목록. cloud.create_instance 의 blueprint 로 쓸 수 있다.
- `cloud.save_as_image` — 지금 가상서버를 이미지로 굳힌다. 같은 구성을 반복해 세울 때 쓴다.
- `cloud.save_as_sale_image` — 판매용(앱마켓) 이미지를 만든다. 원본 서버는 그대로 두고, 복제본에서 비밀 검사 → 청소(판매자 SSH 키·개인키·셸 기록·로그·machine-id·호스트 키·cloud-init) 뒤 이미지로 굳힌다. 1~3분 걸리며 진행은 cloud.list_images 의 status(creati
- `cloud.delete_image` — 저장한 이미지를 지운다. 그 이미지로 이미 만든 가상서버는 영향 없다.
- `cloud.firewall_presets` — 방화벽 프리셋 목록(웹·SSH 같은 흔한 조합). cloud.open_port 로 직접 여는 것보다 실수가 적다.
- `cloud.create_instance` — Create a cloud instance. Provisioning continues asynchronously. This platform has NO region/zone selection — do not ask the customer to pick one. There is NO ro
- `cloud.exec` — Run a shell command inside one of your instances and get stdout/stderr/exit code. Use this to install packages, start services, and inspect state. Long jobs sho
- `cloud.write_file` — Write a text file inside one of your instances, creating parent directories. Use this to deploy source code, configs, and unit files.
- `cloud.read_file` — Read a text file from one of your instances. Useful for checking logs and configs.
- `cloud.list_firewall_rules` — List inbound firewall rules for an instance. Only instances with a public IP have rules.
- `cloud.open_port` — Open an inbound port on an instance that has a public IP. Prefer restricting `source` to a specific address for admin ports like SSH — leaving it at 0.0.0.0/0 e
- `cloud.close_port` — Remove an inbound firewall rule by its policy id (from cloud.list_firewall_rules).
- `cloud.access_log` — 이 서버에 대한 **관리 접근 기록**(콘솔·API·exec) — 언제·누가·어느 IP 에서·무엇을. 기본 최근 7일. 키가 유출됐거나 이상 접근이 의심될 때 여기부터 본다(네트워크 연결 로그는 아님).
- `cloud.list_blocked_ips` — 이 서버로 못 오게 막아 둔 출발지 IP 목록. 이미 열린 포트여도 이 IP 들은 거부된다.
- `cloud.block_ip` — 특정 출발지 IP/대역을 이 서버로 못 오게 막는다(방화벽 deny, 열린 포트보다 우선). 악성 스캐너·공격 IP 차단용. 예: '1.2.3.4' 또는 '1.2.3.0/24'.
- `cloud.unblock_ip` — 차단을 푼다. ip 는 cloud.list_blocked_ips 의 source 를 그대로 준다.
- `cloud.change_plan` — Change an instance's plan (CPU/memory/disk). The instance must be stopped. Disk can only grow — moving to a plan with a smaller disk is rejected.
- `cloud.delete_instance` *(human approval required)* — Delete an instance. This destructive action requires human approval.
- `cloud.list_public_ips` — List public IPs held by this tenant and the pool's remaining capacity.
- `cloud.attach_public_ip` — Lease a public IP from the pool and attach it to an instance in one step (IPAM lease → interface config → firewall address object). Use this to make a service r
- `cloud.detach_public_ip` *(human approval required)* — Release the instance's public IP back to the pool. The service becomes unreachable from the internet immediately and the same address may not be available again
- `cloud.set_ssh_key` — Register an SSH public key on an instance so it can be reached through the SSH gateway. Without a key nobody can log in — a running instance with no key is unre
- `cloud.set_auto_snapshot` — 가상서버의 자동 스냅샷을 켜고 끈다. 정해진 시각(한국 기준)에 매일 찍고, 보관 개수를 넘으면 오래된 것부터 지운다. 사람이 손으로 만든 스냅샷은 정리 대상이 아니다. 기본은 꺼짐 — 스냅샷은 디스크를 쓰고 그건 요금이다.
- `cloud.run_auto_snapshot` — 자동 스냅샷을 지금 한 번 찍는다. 예약이 제대로 도는지 다음 날까지 기다리지 않고 확인할 때 쓴다.
- `security.get` — 이 조직의 보호 설정 — 운영 표시 사용 여부, 해제·삭제 시 메일 확인 여부, 삭제 유예 일수. 무엇을 건드리면 안 되는지 먼저 알기 위해 읽는다. 바꾸는 것은 사람만 할 수 있다.
- `cloud.rename` — 가상서버의 표시 이름을 바꾼다(목록·상세·청구서). 서버는 멈추지 않고 주소(서브도메인)·vmid 는 그대로다. 주소를 바꾸려면 서브도메인 변경 도구를 쓴다.
- `cloud.set_note` — 가상서버에 사람이 읽는 설명을 단다(목록·상세에 보인다). 빈 문자열이면 지운다.
- `cloud.set_firewall_note` — 방화벽 규칙에 설명을 단다. 규칙 자체는 건드리지 않으므로 접속이 끊기지 않는다. rule 값은 cloud.firewall 이 돌려주는 규칙 이름이다.
- `cloud.get_default_ssh_key` — 조직 기본 SSH 공개키 — 새 서버를 만들 때 sshKey 를 안 주면 자동으로 심기는 키. 지문·타입·키 없는 서버 수를 준다. 서버가 접속 안 될 때 여기부터 봐라.
- `cloud.set_default_ssh_key` — 조직 기본 SSH 공개키 등록·교체. **앞으로 만드는 서버에만** 적용된다 — 이미 있는 서버의 키는 cloud.set_ssh_key 로 서버마다 바꿔야 한다. 공개키만 보내라(비밀키 절대 금지).
- `cloud.add_default_ssh_key` — 기본 SSH 공개키에 키(들)를 **더한다**(교체가 아니다). 여러 사람·도구의 키를 하나씩 쌓을 때. 중복은 걸러진다. 기본은 앞으로 만드는 서버에만 적용된다 — 지금 있는 서버로 이 키로 들어가야 하면 applyToExisting:true(서버마다 있던 키는 그대로 두고 더한다).
- `cloud.remove_default_ssh_key` — 기본 SSH 공개키에서 **지문 하나**를 뺀다. 퇴사자·안 쓰는 임시 키 정리에. 지문은 cloud.get_default_ssh_key 의 keys[].fingerprint(SHA256:...) 를 그대로 준다.
- `cloud.metrics` — 가상서버 사용량 그래프 데이터 — CPU·메모리·디스크·네트워크 시계열과 제공량(limits). 느리다는 신고를 받으면 추측하지 말고 여기부터.
- `cloud.set_subdomain` — 가상서버의 기본 주소(<label>.<조직 기본 도메인>)를 바꾼다. ★ 옛 주소는 **지워진다** — 어딘가 박아 둔 링크가 있으면 먼저 확인하라. 응답에 옛 주소가 실려 온다.
- `cloud.list_volumes` — 가상서버에 붙은 별도 디스크 목록 — 크기·상태·장치명·월 요금.
- `cloud.add_volume` — 가상서버에 별도 디스크를 붙인다. **과금이 시작된다**(GB 당 월 요금 — billing.pricing 참조). 떼는 것은 사람이 콘솔에서 한다.
- `cloud.get_backup_policy` — 가상서버 백업 이용권 상태 — 켜짐 여부·월 요금·스케줄(매일 새벽)·보존 기간. 이용권을 켠 서버만 백업된다.
- `cloud.set_backup_policy` — 백업 이용권 켜기/끄기. 켜면 복원·내려받기가 즉시 가능해지고 **요금제의 일정 %가 월 과금된다(최소 1개월)**. 꺼도 백업 자체는 계속 뜬다 — 복원 접근만 막힌다. 위험한 작업 전이라면 끄지 말고 cloud.create_backup 으로 지금 한 장 떠라.
- `cloud.grow_volume` — 별도 디스크를 **늘린다**(줄이기는 없다 — 줄이면 데이터가 사라진다). 블록 장치만 커지고 서버 안 파일시스템은 그대로다. 늘린 뒤 사람에게 `resize2fs` 를 실행해야 실제 공간이 보인다고 반드시 알려라.
- `cloud.grow_disk` — OS 디스크를 **늘린다**(무중단, 줄이기는 없다). 플랜은 안 바뀐다. ★ 플랜에 포함된 크기를 넘는 만큼은 **추가 요금**이 분 단위로 붙는다 — 실행 전에 사람에게 초과분과 월 예상액을 말하고 동의를 받아라. 늘린 뒤 서버에서 `growpart` + `resize2fs` 가 필
- `cdn.pricing` — CDN 요금표 — GB 당 트래픽 요금과 무료 요청 수. 가상서버 트래픽 초과 요금과의 비교값도 준다.
- `cdn.list_zones` — 이 조직의 CDN 존 목록 — 상태·오리진·CDN 주소.
- `cdn.get_zone` — CDN 존 하나의 상세 — 상태·오리진·연결 방법(CNAME).
- `cdn.create_zone` — CDN 존 생성 — 오리진(원본 서버 주소) 앞에 CDN 을 세운다. 응답의 CNAME 안내대로 도메인을 걸어야 트래픽이 흐른다. 과금은 실제 트래픽부터(cdn.pricing 참조).
- `cdn.delete_zone` — CDN 존 삭제. ★ 이 존을 가리키던 CNAME 이 **즉시 죽는다** — 서비스 도메인이 아직 이 존을 보고 있으면 먼저 DNS 를 돌려놓고 지워라.
- `cdn.attach_hostname` — 고객 자기 도메인(예: cdn.mycompany.com)을 이 CDN 존에 붙이고 무료 SSL 을 발급한다. 붙인 뒤 그 도메인을 존 hostname 으로 CNAME 걸어야 실제로 뜬다.
- `cdn.remove_hostname` — 붙였던 커스텀 도메인을 존에서 뗀다.
- `cdn.purge` — 이 존의 캐시를 전부 비운다. 오리진 파일을 바꿨는데 옛 것이 계속 나갈 때.
- `cdn.update_zone` — 존의 오리진(원본 서버) 주소를 바꾼다. 존·주소는 그대로 두고 바라보는 곳만 바꾸며, 바꾼 뒤 캐시를 자동으로 비운다.
- `network.list_appliances` — 이 조직의 로드밸런서·방화벽 어플라이언스 목록 — 백엔드·분산 방식·포트 규칙·HTTPS 도메인·반영 상태(configVersion/appliedVersion/lastError).
- `network.get_appliance` — 어플라이언스 하나의 상세. lastError 가 있으면 마지막 반영이 실패했고 서버는 직전 설정으로 돌고 있다.
- `network.create_appliance` — 켜져 있는 Debian·Ubuntu 가상서버(Small)를 로드밸런서로 만든다 — 그 순간부터 로드밸런서 요금(월 25,000원, 서버 포함·분 단위). backends 는 같은 조직 서버의 vmid. domains 를 주면 그 이름으로 HTTPS 인증서를 자동 발급한다(도메인의 A 레
- `network.update_appliance` — 어플라이언스 설정 변경 — 바꿀 필드만 보낸다(나머지는 지금 값 유지). 서버가 검사 후 무중단 반영하고, 실패하면 직전 설정으로 계속 돈다. domains 를 넣으면 HTTPS(Let's Encrypt 자동 발급·갱신, 443·HTTP→HTTPS 자동)가 켜지고 빈 목록이면 꺼진다. 
- `network.features` — 이 조직에서 조직 네트워크(VPC)를 쓸 수 있는지와 조건 — enabled · NAT 게이트웨이 월 요금(natMonthlyKRW, 출구 IP 포함) · 통과 데이터 GB당 요금(natPerGbKRW) · 남은 NAT 수량(natAvailable, 전체 상한 natMax) · 크기 범
- `network.list` — 이 조직의 네트워크(VPC) 목록 — id · 이름 · 주소 범위(cidr) · 종류(private=공인 IP 못 붙임·인터넷은 NAT 로만 / public=공인 IP 붙일 수 있음) · 상태(ready 여야 서버를 넣을 수 있다. pending_apply 는 운영자 반영 대기) · 서
- `network.get` — 네트워크 하나의 상세 — 안의 서버(vmid·내부 주소·공인 IP) · 라우팅 표(v1 은 고정: 같은 망 on-link, NAT 가 있으면 기본 경로 .4) · 예약 주소(.1 게이트웨이 · .2/.3 관리 연결 · .4 NAT — 서버는 .10 부터). ★ 서버 방화벽에서 .2/.3
- `network.create` — 조직 네트워크(VPC)를 만든다 — 다른 조직과 완전히 갈린 사설망. 네트워크 자체는 무료. 주소 범위는 우리가 자동으로 정한다(고를 수 없다). 202 로 바로 답하고 준비는 뒤에서 한다(보통 1~2분) — network.list 로 status 가 ready 가 될 때까지 본다. 같
- `network.delete` — 네트워크를 지운다 — 안에 서버가 없고(지운 서버의 7일 되살리기 기간 포함) NAT 게이트웨이도 없을 때만. 남아 있으면 409(network_in_use / network_has_nat).
- `network.create_nat` — 네트워크에 NAT 게이트웨이(인터넷 출구)를 만든다 — 월 33,000원 + 통과 데이터 GB당 55원(전용 출구 IP 1개 포함, 분 단위, 준비된 때부터). 공인 IP 없는 서버들이 이 출구 IP 하나로 인터넷에 나간다(밖에서 들어오는 연결은 받지 않음, 25번 메일 포트는 막힘).
- `network.delete_nat` — NAT 게이트웨이를 지운다 — 그 네트워크의 공인 IP 없는 서버들이 인터넷에 못 나가게 된다. 출구 IP 는 7일 보류(그 안에 다시 만들면 같은 IP). 사람 승인이 필요하다(202 pending_approval → action_required.url 을 사용자에게).

### appmarket

- `appmarket.list` — 앱마켓에서 판매 중인 앱 목록 — 이름·한 줄 소개·월 합계(앱+최소 사양 서버+데이터 디스크)·자동 스펙(언어·프레임워크·DB)·필요한 키와 설정 칸.
- `appmarket.get` — 앱마켓 앱 하나의 상세. 설치 전에 needs.secrets(금고에 넣어야 할 키 이름)·needs.settings(설정 칸)·minPlan 을 여기서 본다.
- `appmarket.install` — 앱마켓 앱을 설치한다 = 내 조직에 **봉인 서버** 한 대를 만든다(서버 요금·데이터 디스크 요금이 나간다 — 만들기 전에 사람에게 월 합계를 말하고 확인받는다). 봉인 서버는 SSH·exec·이미지 뜨기가 막혀 있고 앱 화면·설정으로만 쓴다. secrets 는 값이 아니라 금고 참조
- `appmarket.my_installs` — 내 조직에 설치한 앱마켓 앱 — 상태·서버 vmid·이용권 id·설정 값·키 참조(값 없음)·마지막 주입(시각·이름·헬스).
- `appmarket.update_settings` — 설치한 앱의 설정 칸·키 참조를 바꾸고 곧바로 다시 넣는다(앱 재시작). 키는 금고 참조만({{secret:금고이름}}), null 이면 그 칸을 지운다. 서버가 꺼져 있으면 저장만 하고 켤 때 넣는다(applied:false).
- `appmarket.publish_draft` — (판매자) 앱마켓 상품을 **작성 중(draft)** 으로 만든다. saleImage 는 cloud.save_as_sale_image 로 만든 판매용 이미지 id. manifest(appmarket.json)를 안 주면 그 이미지가 서버에서 읽어 둔 것을 쓴다. 공개되지 않는다 — 검수
- `appmarket.submit_for_review` — (판매자) 작성 중인 버전을 검수에 제출한다. 판매용 이미지가 ready(검사 통과)여야 한다.
- `appmarket.my_listings` — (판매자) 내 앱마켓 상품 — 상태(draft·review·approved·suspended·retired)·버전별 검수 결과(반려 사유)·설치 수.

### git

- `git.list_repos` — 이 조직의 Git 저장소 목록(FutureInfra Git — GitHub 계정 없이 쓰는 비공개 저장소). List this tenant's Git repositories.
- `git.issue_credentials` — git push/pull 에 쓸 접속 계정·토큰을 발급한다(다시 부르면 교체 — 이전 토큰은 즉시 막힌다). 토큰은 응답에 **한 번만** 나온다. 쓰는 법: git remote add origin https://<username>:<token>@<host>/<owner>/<repo>.
- `git.credentials_status` — Git 접속 계정이 있는지·언제 토큰을 발급했는지(토큰 값은 주지 않는다).
- `git.repo_summary` — 저장소 한눈 요약 — cloneUrl·기본 브랜치·크기·최근 커밋. push 가 들어갔는지 확인할 때.
- `git.tree` — 저장소 폴더 목록.
- `git.read_file` — 저장소 파일 하나 읽기.
- `git.commits` — 최근 커밋(누가·언제·무엇을). 20개씩, page 로 넘긴다.
- `git.branches` — 브랜치 목록.
- `git.issues` — 이슈(또는 kind=pulls 로 풀 리퀘스트) 목록.
- `git.create_issue` — 이슈 하나 만들기 — 할 일·버그 기록.
- `git.usage` — Git 저장소 사용량(용량·개수)과 요금.
- `git.create_repo` — FutureInfra Git 저장소를 만든다(기본 비공개). 소스 보관·버전 관리는 GitHub 대신 여기 두면 된다 — 응답의 cloneUrl 로 push 하고, 인증은 git.issue_credentials. Create a Git repository.
- `git.delete_repo` *(human approval required)* — Delete a Git repository. This destructive action requires human approval.

### domain

- `domain.assign_subdomain` — Claim a FutureInfra subdomain for an instance.
- `domain.address_suffixes` — 자동 주소 뒤에 붙일 수 있는 도메인 목록(예: futureinfra.app, fii.kr). default 가 조직 기본이고, cloud.create_instance·apps.create·apps.create_from_template 의 suffix 에 choices 중 하나를 넣는다
- `domain.search` — Check domain availability with first-year and renewal prices (KRW). Premium domains are search-only — they cannot be purchased through the API.
- `domain.register` *(human approval required)* — Register a real domain. This paid action requires human approval. Premium domains are always refused (403) — a human handles those manually.
- `ssl.list_products` — List purchasable SSL certificates (Sectigo DV) with current KRW prices.
- `ssl.order` *(human approval required)* — Order an SSL certificate. This paid action requires human approval. The customer must supply their own CSR (PEM).
- `ssl.order_status` — Get an SSL order's status, DCV record to publish, and the issued certificate once ready.
- `domain.list_domains` — 내가 이 플랫폼에서 등록·관리 중인 도메인 목록.
- `domain.list_zones` — 내 DNS 존 목록(우리 네임서버가 서빙 중인 도메인).
- `domain.create_zone` — DNS 존을 만든다. 만든 뒤 등록기관에서 네임서버를 우리 것으로 바꿔야 실제로 동작한다(domain.nameservers 참고).
- `domain.delete_zone` *(human approval required)* — DNS 존을 지운다. ★그 도메인의 모든 레코드가 사라져 서비스가 즉시 안 닿는다 — 사람 승인이 필요하다.
- `domain.nameservers` — 우리 네임서버 주소. 고객이 등록기관에서 이 값으로 바꿔야 존이 살아난다.
- `domain.check_delegation` — 네임서버 위임이 실제로 됐는지 **공개 DNS 로 관측해서** 확인한다. 존을 만들었는데 안 닿을 때 여기부터 봐라.
- `domain.list_records` — 존의 DNS 레코드 목록.
- `domain.set_record` — DNS 레코드를 만들거나 덮어쓴다(같은 이름·타입이면 교체). 이름은 그 존 안이어야 한다.
- `domain.delete_record` — DNS 레코드를 지운다. 존 정점(apex)의 NS 는 못 지운다.
- `domain.available` — 우리 도메인 아래 이 하위이름을 쓸 수 있는지 확인.
- `domain.ssl_orders` — 구매한 SSL 인증서 주문 목록과 발급 상태.
- `domain.add_custom` — 외부에서 산 도메인을 연결 대상으로 등록한다. 등록 뒤 domain.verify_custom 으로 소유 확인을 통과해야 쓸 수 있다.
- `domain.verify_custom` — 외부 도메인 소유 확인을 실행한다(DNS 레코드를 심어 둔 뒤 호출).
- `domain.remove_custom` — 연결한 외부 도메인을 해제한다.
- `domain.attach` — 검증이 끝난 내 도메인을 앱이나 VM 에 붙인다. 붙여야 주소가 실제로 열린다 — 소유 확인(verify)만으로는 아무 일도 일어나지 않는다. 앱은 한 번 배포한 뒤에 붙일 수 있다.
- `domain.detach` — 도메인 연결을 끊는다. 고객 쪽 DNS 레코드는 그대로 남는다.
- `domain.reserved` — 쓸 수 없는 예약 하위이름 목록(www, api 등). 이름을 짓기 전에 보면 400 을 안 맞는다.
- `domain.get_base_domain` — 새 서버·앱 주소가 어느 도메인 아래로 나가는지 — 현재값과 고를 수 있는 후보(서비스 중인 존).
- `domain.set_base_domain` — 조직 기본 도메인 변경(화이트라벨). 바꿔도 **이미 만든 주소는 그대로 살아 있다** — 앞으로 만드는 것부터 새 도메인으로 나간다. 기존 자원도 옮기려면 domain.apply_base_domain 을 이어서 불러라(옛 주소를 지우지 않고 새 주소를 덧붙인다). null 이나 빈 값
- `domain.apply_base_domain` — 이미 만들어 둔 서버·앱 주소도 조직 기본 도메인 아래로 옮긴다. ★ **갈아치우지 않고 덧붙인다** — 옛 주소는 라우트가 그대로 남아 계속 응답하고, 표시 주소만 새 것으로 바뀐다. 그래서 이미 걸어 둔 링크·북마크가 안 깨진다. moved/skipped 를 사람에게 그대로 보여 줘
- `domain.import_zone` — 다른 곳에서 쓰던 도메인의 DNS 레코드를 현 네임서버에서 읽어와 우리 존에 채운다. 위임(NS 변경) 전에 돌려야 전환 순간 레코드가 비지 않는다. ★ AXFR 이 아니라 흔한 이름들을 조회하는 방식이라 **목록이 불완전할 수 있다** — 결과를 사람에게 보여 주고 빠진 레코드가 없는

### brain

- `brain.save` — 브레인에 기록을 저장한다. 본문의 [[제목]] 은 다른 기록으로의 연결이 된다. 같은 path 에 같은 내용이면 재임베딩 없이 건너뛴다(갈래·상태는 그래도 갱신된다). ★ 공유받은 키로 부르면 바로 저장되지 않고 **제안**으로 접수된다(202) — 브레인 주인이 승인해야 기억이 된다.
- `brain.proposals` — 공유받은 AI 가 이 브레인에 올리려고 대기 중인 제안 목록. 주인만 볼 수 있다(공유 키로는 403).
- `brain.proposal` — 제안 하나의 전문. 승인 여부를 사람에게 권하기 전에 본문을 다 읽을 것.
- `brain.supersede` — 틀린 기억을 '대체됨'으로 눕힌다. 지워지지 않고 검색·회상에서만 빠진다. 이미 있는 기억이 틀렸으면 새로 쓰지 말고 이것을 쓴다 — 같은 사실이 두 벌이면 어느 쪽이 맞는지 아무도 모르게 된다. 대개 새 기억을 먼저 저장하고 그 id 를 by 로 준다.
- `brain.unsupersede` — 눕혀 둔 기억을 다시 세운다. 잘못 눕혔을 때 되돌리는 길 — 이 길이 없으면 아무도 안 누른다.
- `brain.ask` — 브레인에서 찾아 읽고 **답까지** 만들어 준다. 여러 기억을 종합해 판단할 때 쓴다. 본문이 내 컨텍스트로 들어오지 않아 창이 오염되지 않는다. ★ 모델 호출 비용이 든다 — 기본은 brain.search 를 쓰고, 정확한 값(IP·명령어·이름)을 찾을 때도 search 가 더 정확하
- `brain.tags` — 이 조직이 이미 쓰고 있는 태그와 사용 횟수. 새 태그를 만들기 전에 확인해 같은 뜻이 갈라지지 않게 한다.
- `brain.policy` — 무엇을 저장하고 무엇을 저장하지 않는가. 갈래별 기준과 저장 금지 목록, 중요도 기준. 저장할지 망설여지면 먼저 확인한다.
- `brain.skills` — 이 브레인에 있는 스킬 목록(이름·한 줄 설명) — 스킬은 '이런 일은 이렇게 하라'를 적어 둔 기록이다. 새 종류의 일을 시작하기 전에 한 번 보고, 맞는 스킬이 있으면 brain.skill 로 본문을 읽어 그대로 따라라.
- `brain.skill` — 스킬 하나의 전문(순서·명령·주의). 적힌 순서를 건너뛰지 말고, 필요한 도구가 없으면 적힌 설치 방법대로 네 컴퓨터에 깔아라.
- `brain.search` — 의미 검색 — 질문과 비슷한 기록을 찾는다.
- `brain.get` — 기록 하나의 전문을 가져온다.
- `brain.related` — 이 기록과 이어진 기록들(양방향). hops 로 2~3칸 건너 이어진 것까지 본다(결과에 hops 거리).
- `brain.recent` — 최근 저장·수정된 기록 목록.
- `brain.path` — 두 기록이 어떻게 이어지는지 경로를 찾는다(서버측 BFS).
- `brain.forget` — 브레인에서 문서 하나를 잊게 한다(보관). 검색에서 빠지지만 삭제는 아니며 되살릴 수 있다.
- `brain.graph` — 브레인 문서 사이의 연결 그래프. 무엇이 무엇과 이어져 있는지 한눈에 본다.
- `brain.verify` — 이 기억을 원본(코드·DB·공식 문서·레지스트리)과 대조했고 **아직 맞다**고 표시한다 — 마지막 확인일이 오늘로 바뀌고 다음 확인일이 다시 잡힌다(자주 바뀜 30일, 그 외 180일). 내용은 안 바뀐다. 틀렸으면 이걸 부르지 말고 고친 판을 brain.save 한 뒤 옛것을 bra
- `brain.review_due` — 다시 확인할 때가 지난 기억 목록(자주 바뀜 먼저). 하나씩 원본과 대조해 brain.verify 하거나 고친다.
- `brain.revisions` — 브레인 문서의 수정 이력.
- `brain.remember` — 문서를 '기억할 것'으로 표시한다. 검색에서 먼저 올라온다.
- `brain.map` — 브레인 지도 — 기록 수·작업공간·갈래별 분포, 꼭 알아야 할 기록(중요도 5), 미결(open), 최근 7일 바뀐 것. 무엇을 검색할지 모를 때 가장 먼저 부른다. 제목만 준다.
- `brain.list_workspaces` — 이 조직 브레인의 작업공간(문서 묶음) 목록과 각 묶음의 최근 문서. 무엇이 적재돼 있는지 훑을 때 먼저 부른다 — 검색어를 정하기 전에 지형을 본다.
- `brain.distill` — 브레인 기억 증류 — 같은 태그에 쌓인 기록을 요약 후보로 만든다. apply:false(기본)면 후보만 보여 주고 저장하지 않는다. **먼저 미리보기로 돌려 사람과 확인한 뒤 apply 하라.** 숫자를 지어낸 후보는 서버가 거절한다(rejected).

### gen

- `gen.image` — 이미지를 만든다. 바로 그림이 오지 않고 **작업 id** 가 온다 — gen.status 로 확인해라. 성공한 것만 청구된다.
- `gen.upload` — 영상 만들기에 쓸 사진(PNG·JPEG·WEBP)이나 동작 영상(MP4·MOV)을 올린다. 돌려준 id 를 gen.video 의 image·references·video 에 넣는다. base64 4MB 까지 — 더 큰 영상은 POST /v1/gen/uploads 에 파일 바이트를 그대로
- `gen.video` — 영상을 만든다 — 글만으로, 시작 이미지에서, **인물·제품 사진 여러 장을 참고해서**(references), 또는 **사진 속 인물이 동작 영상을 따라 하게**(model=kling-motion, image+video). 몇 분 걸리므로 작업 id 를 돌려준다. 사진·영상은 http
- `gen.status` — 생성 작업의 진행 상태와 결과 주소.
- `gen.models` — 지금 실제로 돌릴 수 있는 생성 모델과 요금.
- `gen.audio` — 음성·오디오를 생성한다. 이미지·영상과 같이 비동기라 gen.status 로 확인한다.
- `gen.jobs` — 생성 작업 목록과 상태. 하나만 볼 때는 gen.status.
- `gen.cancel` — 돌고 있는 생성 작업을 취소한다. 잘못된 프롬프트로 비싼 작업이 돌 때 돈을 아낀다.

### secrets

- `secrets.list` — 브레인 금고에 든 키의 **이름과 용도**만 본다. 값은 어떤 도구로도 읽을 수 없다. 값 자체가 필요한 설정은 사람이 콘솔에서 직접 넣어야 한다. 앱마켓 설치(appmarket.install)의 키 칸에는 여기 이름을 {{secret:이름}} 으로 쓴다(기본 브레인 금고).

### apps

- `apps.get` — 앱 하나의 상세 — 상태·주소·환경변수 키·볼륨·스케줄.
- `apps.databases` — 앱에 붙일 수 있는 데이터베이스 종류(MariaDB·MySQL·PostgreSQL·Redis).
- `apps.attach_database` — 앱에 데이터베이스 컨테이너를 붙인다. 비밀번호는 서버가 만들어 금고에 봉인하고 접속 정보를 웹 컨테이너 환경변수로 자동 주입한다 — 값을 직접 만들거나 옮기지 마라. DB 는 인터넷에 열리지 않고 앱 안에서 `db` 이름으로만 보인다.
- `apps.status` — 앱이 지금 실제로 떠 있는지 컨테이너에게 직접 묻는다. 우리 DB 기록이 아니라 실제 상태다. 배포 뒤 반드시 확인한다.
- `apps.logs` — 앱 컨테이너 로그. 앱이 안 뜨거나 죽을 때 원인은 거의 항상 여기 있다.
- `apps.set_secrets` — 앱 환경변수를 넣는다. ★값을 직접 쓰지 말고 브레인 금고 참조 {{secret:이름}} 를 써라 — 그래야 대화 기록에 비밀이 남지 않는다.
- `apps.set_registry` — 비공개 이미지 저장소 열쇠를 앱에 등록한다(도커 허브·ghcr.io·repos.futureinfra.app 등). 다음 배포부터 이 열쇠로 이미지를 받는다. 비밀번호보다 **읽기 전용 토큰**을 권한다. 저장한 토큰은 다시 볼 수 없다.
- `apps.clear_registry` — 앱에 등록한 비공개 저장소 열쇠를 지운다. 다음 배포부터 공개 이미지로만 받는다.
- `apps.delete_secret` — 앱 환경변수 하나를 지운다.
- `apps.add_schedule` — 앱에 크론 스케줄을 건다. 5필드 표기("0 9 * * *").
- `apps.delete_schedule` — 앱 스케줄을 지운다.
- `apps.catalog` — 앱 요금(공유형 한 가지)·볼륨·트래픽 등 만들 때 참고할 값 목록. 앱은 크기를 고르지 않는다.
- `apps.list` — 이 테넌트의 앱 목록과 상태.
- `apps.templates` — List one-click app templates (n8n, Open WebUI, PostgreSQL, Ghost, …) with port and env.
- `apps.create_from_template` — Create an app from a one-click template. Registers the image and machine; secrets (passwords) are left blank for the customer to fill.
- `apps.create` — 앱을 만든다. slug 가 곧 주소가 된다(slug.<조직 기본 도메인>). 화이트라벨 조직은 자기 도메인이므로 값을 짐작하지 말고 domain.get_base_domain 으로 확인해라. 과금은 첫 배포부터.
- `apps.deploy` — 컨테이너 이미지를 배포한다. 이 시점부터 앱이 active 가 되고 과금이 시작된다.
- `apps.runs` — 앱의 스케줄 실행 기록.
- `apps.delete` *(human approval required)* — 앱을 지운다. 볼륨 데이터도 함께 사라지므로 사람 승인이 필요하다.

### proxy

- `proxy.info` — 프록시 접속 주소(host:port)·계정 목록·이번 달 사용량·GB 단가·사용 가능 여부를 본다.
- `proxy.create_user` — 프록시 계정(아이디·비밀번호)을 만든다. 비밀번호는 이 응답에서 한 번만 나온다 — 사용자에게 바로 전달하고 기록에 남기지 마라. 잔액 1,000원 이상 필요.
- `proxy.usage` — 최근 30일 하루별 프록시 사용량(GB)과 금액.

### scrape

- `scrape.actors` — 기본 수집 액터(웹페이지 수집기·사이트 크롤러)의 입력 형식·페이지당 가격을 본다. 네이버·유튜브·SNS·커뮤니티·쇼핑몰 등 준비된 액터는 scrape.store, 내 액터는 scrape.my_actors.
- `scrape.run` — 액터를 실행해 공개 웹페이지를 수집한다. 바로 결과가 오지 않고 실행 id 가 온다 — scrape.run_status 로 끝났는지 보고 scrape.items 로 결과를 읽는다. actor 는 web-scraper·site-crawler(모은 페이지 수 × http 1원·browser
- `scrape.store` — 액터 스토어 — 준비된 수집 액터 목록(네이버 블로그·카페·뉴스·지도/플레이스 리뷰·쇼핑, 유튜브 검색·채널·댓글·자막 등)과 입력 형식. 실행은 scrape.run 에 actor:'store:<이름>', input 은 inputSchema 대로. 요금은 결과 1,000건당 가격(pri
- `scrape.store_actor` — 스토어 액터 하나 — 입력 형식·예시 입력·코드.
- `scrape.fork_store_actor` — 스토어 액터를 내 액터로 복사한다(코드를 고쳐 쓰고 싶을 때). 복사한 뒤 scrape.update_actor 로 고친다.
- `scrape.run_batch` — 액터 여러 개를 한꺼번에 실행한다(최대 50개). runs = [{actor, input, maxCostKrw?}] — actor 는 'web-scraper'·'store:<이름>'·'user:<id>'. 대기열에 들어가 조직당 동시에 3개씩 돌고 끝난 자리에 다음 것이 들어간다. 결과
- `scrape.my_actors` — 내 액터(직접 만든 수집 프로그램) 목록. 실행은 scrape.run 에 actor:'user:<id>' 로 한다.
- `scrape.get_actor` — 내 액터 하나 — 코드 파일·입력 형식·메모리·제한 시간.
- `scrape.create_actor` — 내 액터를 만든다(Apify 방식). files 에 main.js(+package.json 등)를 넣는다. Apify SDK(apify)·Crawlee(crawlee)·Playwright·Cheerio 가 미리 깔려 있다 — Actor.getInput() 으로 입력을 받고 Actor.p
- `scrape.update_actor` — 내 액터를 고친다(보낸 칸만 바뀌고 버전이 1 올라간다). files 를 보내면 파일 전체가 바뀐다.
- `scrape.tasks` — 태스크(액터 + 입력을 이름 붙여 저장한 것)와 스케줄(정기 실행) 목록·다음 실행 시각.
- `scrape.create_task` — 태스크를 만든다 — 액터·입력·비용 상한을 저장하고, cron(분 시 일 월 요일, 한국 시간)을 주면 정기 실행한다(최소 5분 간격). 예: 매일 09:00 = '0 9 * * *', 평일 18:30 = '30 18 * * 1-5'.
- `scrape.update_task` — 태스크를 고친다(보낸 칸만) — 입력·cron·스케줄 켜고 끄기(cronEnabled).
- `scrape.run_task` — 태스크를 지금 한 번 실행한다. 실행 id 가 돌아온다(scrape.run_status 로 확인).
- `scrape.webhooks` — 웹훅(실행이 끝나면 알릴 주소) 목록과 최근 전송 결과.
- `scrape.create_webhook` — 웹훅을 만든다 — 실행이 성공·실패·멈춤으로 끝나면 이 주소로 JSON 을 POST 한다. 서명 비밀값은 응답에서 한 번만 나온다(X-FI-Signature: sha256=HMAC). 공개 주소만.
- `scrape.runs` — 최근 스크래핑 실행 목록과 상태·페이지 수·비용.
- `scrape.run_status` — 스크래핑 실행 하나의 상태(queued·running·succeeded·failed·aborted)·모은 페이지 수·비용.
- `scrape.items` — 스크래핑 결과(데이터셋)를 읽는다. 한 번에 최대 1000개 — offset 으로 넘긴다.
- `scrape.abort` — 진행 중인 스크래핑 실행을 멈춘다. 그때까지 모은 페이지만 청구된다.

### projects

- `projects.get` — 프로젝트 하나의 상세와 거기 묶인 자원.
- `projects.update` — 프로젝트 이름·메모를 고친다.
- `projects.delete` *(human approval required)* — 프로젝트를 지운다. ★사람 승인이 필요하다.
- `projects.list` — 프로젝트(고객사) 목록. 각 프로젝트의 가상서버·앱·도메인 개수를 함께 준다.
- `projects.create` — 프로젝트를 만든다. 이름이 겹쳐도 뒤에 번호가 붙어 통과한다(지점 등).
- `projects.usage` — 프로젝트 하나의 이번 달 사용량과 비용.
- `projects.adopt` — 이미 만들어둔 자원을 이 프로젝트로 **옮긴다**(재분류). 같은 조직 안에서만. 만들 때 정한 프로젝트를 나중에 고객사별로 다시 묶을 때. org 은 안 바뀐다(그건 소유권 이전).

### integrations

- `integrations.get` — 연결된 외부 서비스 목록(어떤 것이 붙어 있나). 자격증명 값은 안 준다.
- `integrations.catalog` — 붙일 수 있는 외부 서비스 목록(결제·알림·인증·세무 등)과 각 항목의 준비 조건.
- `integrations.list` — 이미 붙여 둔 연동과 마지막 점검 결과. 키 값은 가림 표기로만 나온다.
- `integrations.test` — 연동이 실제로 동작하는지 점검한다(필수값·봉인 해제 확인). 값은 응답에 안 실린다.

### search

- `search.query` — 이 조직의 자원을 가로질러 찾는다(가상서버·앱·도메인·문서).
- `search.tags` — 자원에 붙은 태그 목록.
- `search.set_tags` — 자원에 태그를 붙인다. AI 가 만든 자원에 무엇을 위한 것인지 남겨 두면 나중에 회수 판단이 쉬워진다.

### account

- `account.me` — 내 계정 정보 — 조직 id·이름·요금제, 그리고 지금 쓰는 API 키의 이름과 권한 목록.
- `account.keys` — 이 조직의 API 키 목록(이름·권한·한도·폐기 여부). 키 값 자체는 발급 때 한 번만 보여주므로 여기엔 없다.
- `account.revoke_key` — API 키를 폐기(revoke)한다 — 되돌릴 수 없다. id 를 생략하면 **지금 쓰는 키**를 폐기한다(채팅에 붙여 넣어 노출된 키를 끊을 때). API 키로 연결됐으면 자기 자신만 폐기할 수 있다. 폐기 뒤에는 이 키로 오는 모든 요청이 401 이므로, 마지막 작업으로 부르고 사용
- `account.overview` — 한눈 요약 — 가상서버 수와 상태, 대기 중인 승인 건수, 최근 활동 10건.
- `account.audit` — 감사 로그 — 이 조직에서 무슨 일이 있었나. AI 가 자기 행동을 되짚을 때 쓴다.
- `account.scopes` — 이 플랫폼이 주는 권한(scope) 전체 목록과 각각의 뜻. 사람에게 키를 요청할 때 무엇을 달라고 할지 여기서 고른다.
- `account.approvals` — 사람 승인을 기다리는 요청 목록. 무언가 'pending' 으로 멈춰 있으면 여기 있다. ★결정은 사람이 콘솔에서 한다 — AI 는 조회만.

### governance

- `account.members` — List the people in your organisation (email, name, orgRole, last login) and any invitations still awaiting acceptance. Use this when /v1/me returns no user — an
- `account.orgs` — 내가 속한 조직 목록과 지금 보고 있는 조직. A person can belong to several organisations; this says which ones and which is active. Only works when signed in as a person (browser
- `account.switch_org` — 보는 조직을 바꾼다. 이후의 모든 호출이 그 조직으로 동작한다 — 재인증은 필요 없다. Use this when the user says they meant a different organisation, or when account.orgs shows the active organisa
- `account.rename_org` — 조직 이름을 바꾼다. 이 이름은 청구서와 초대 메일에 그대로 나간다. Requires the members:write scope, which is NOT granted by default — if the key lacks it the call returns 403 with instruc
- `account.invite_member` — 조직에 멤버를 초대한다(메일 발송). 받는 사람이 링크를 열어 수락해야 합류한다. role 은 member 만 지정할 수 있다 — admin 부여는 콘솔에 로그인한 조직 소유주만 한다. Requires members:write, which keys do not get by default
- `account.revoke_invite` — 보낸 초대를 회수한다. 링크가 즉시 무효가 된다. id 는 account.members 응답의 invites[].id 다.
- `account.set_member_role` — 조직 멤버의 역할을 바꾼다. 키로는 member 로만 바꿀 수 있다 — admin 으로 올리는 것은 콘솔에 로그인한 조직 소유주만 한다. id 는 account.members 응답의 사용자 id 다.

### billing

- `billing.insights` — 시간별 트래픽 추이, 트래픽이 많은 서버, 최근 상태 변화(이슈). Hourly traffic series plus the noisiest instances and recent health flips. Traffic history starts 2026-09-14 — earlier hou
- `billing.spend` — 기간(7일·30일) 동안 서비스별(서버·앱·AI·도메인·저장소·네트워크·스크래핑) 사용 금액과 날짜별 금액.
- `billing.wallet` — 잔액과 요금제, 그리고 등급이 허용하는 한도 대비 지금 쓰고 있는 양.
- `billing.pricing` — 가격표 — 가상서버 요금제별 분·시·월 단가. **자원을 만들기 전에 이걸 먼저 봐라.**
- `billing.live` — 지금 이 순간 쌓이고 있는 요금 — 켜져 있는 자원, 최근 24시간 소진, 잔액이 언제 바닥나는지.
- `billing.transactions` — 결제·크레딧 내역 (충전·차감), 최근 200건.
- `billing.coupons` — 이 조직이 등록한 쿠폰 내역(코드·금액·시각). ★등록 자체는 사람이 콘솔에서 한다 — 돈이 움직이는 일이라 AI 에게는 조회만.
- `billing.usage` — 기능별 사용량과 비용 합계 — 무엇에 돈이 나갔는지 가른다.
- `billing.autotopup` — 자동충전 설정 조회 — 잔액이 떨어지면 자동으로 결제되는지. ★켜고 끄는 건 사람이 한다.
- `billing.traffic` — 트래픽 사용량과 무료 제공량 대비 초과분.

### chat

- `chat.list_rooms` — 콘솔 Chat 의 대화방 목록(제목·모델·쓴 금액).
- `chat.get_room` — 대화방 하나의 전체 메시지와 그 대화가 실제로 만든 자원 목록.
- `chat.join` — 협업 방에 참가자로 등록한다. 이름은 방 안에서 나를 가리키는 말이 된다. 응답의 seq 가 지금 번호이니, 이후 chat.wait 에 after 로 넘기면 과거를 다시 안 읽는다.
- `chat.post` — 방에 발언한다. agent 를 꼭 넣을 것 — 안 넣으면 누가 말했는지 구분이 안 된다.
- `chat.wait` — 다른 에이전트가 말할 때까지 **기다렸다가** 새 발언을 받는다(최대 25초). 새 말이 없으면 빈 목록과 함께 돌아오니, 계속 듣고 싶으면 응답의 cursor 를 after 로 넣어 다시 부른다. wait=0 이면 기다리지 않고 즉시 — 놓친 것 따라잡기용.

### pay

- `pay.create_payment` — 결제 하나를 만들고 결제창 주소(checkoutUrl)를 받는다. 손님을 그 주소로 보내면 결제한다. mode 기본은 test(돈이 안 움직이고 결제창에서 성공/실패 버튼으로 결과를 고른다). live 는 조직이 자기 나이스페이먼츠 키를 콘솔에 연결했을 때만 된다(아니면 403 live
- `pay.get_payment` — 결제 한 건 — status(ready·paid·failed·partial_canceled·canceled·expired)·금액·취소 합계·남은 금액·metadata. 주문을 완료로 바꾸기 전에 이걸로 paid 와 금액을 확인한다.
- `pay.list_payments` — 최근 결제 목록(최근 순). status·mode 로 거르고 limit(1~100, 기본 20).
- `pay.cancel_payment` — 결제를 취소한다 — paid(또는 일부 취소된) 결제만. amount 를 주면 그만큼(부분 취소), 비우면 남은 금액 전부. 남은 금액보다 많이는 400. live 결제는 실제 환불이 나가므로 사용자에게 금액을 확인받고 부른다.


Canonical service: https://futureinfra.ai/
Operator: 솔리드그루 (사업자등록번호 875-44-00335)
Primary region: Korea
Support: support@futureinfra.ai

## What the service provides

### Cloud

- Create and manage virtual machines from supported blueprints and plans.
- Start, stop, snapshot, restore, publish, and attach networking features according to account permissions.
- Creating resources can incur usage charges. Deletion and restore operations require human approval.

### Hosting and domains

- Publish services with HTTPS and a FutureInfra subdomain.
- Manage supported DNS and domain operations.
- Domain purchases and destructive changes require human approval.

### AI APIs

- Access supported language, image, video, audio, and embedding models through the documented API.
- Availability and pricing can change; query the current catalog before promising a model or price.

### Web scraping (actors)

- 100 ready-made actors (Naver, YouTube, SNS, Korean communities, shopping malls, Google, web). Run one with
  `POST https://futureinfra.ai/v1/scrape/runs {"actor":"store:<name>","input":{...}}` — it returns a run id at once (202).
  Poll `GET /v1/scrape/runs/<id>` until status is succeeded, failed or aborted, then read
  `GET /v1/scrape/runs/<id>/items?format=json|csv|xlsx|jsonl`. Results are kept 30 days.
- Input shape per actor: `GET /v1/scrape/store/<name>` (inputSchema + example). Full list: https://futureinfra.ai/docs/scrape/actors/
- Ready-made actors are billed per result: 1500–5000 KRW per 1,000 results depending on the actor
  (compute and proxy included). Zero results cost 0; otherwise at least 10 KRW per run. `maxCostKrw` caps a run.
- Batch: `POST /v1/scrape/runs/batch {"runs":[...]}` up to 50. Each organisation runs 3 at a time and may queue 100.
- Own actors (Apify SDK / Crawlee code, Node.js or Python): `POST /v1/scrape/my-actors`, run as `user:<id>`, billed
  400 KRW per GB-hour of memory × actual run time. Copy a ready-made actor: `POST /v1/scrape/store/<name>/fork`.
- Tasks with KST cron schedules (`/v1/scrape/tasks`, at least every 5 min) and signed webhooks (`/v1/scrape/webhooks`, X-FI-Signature: sha256=HMAC).
- Only publicly visible information is collected; personal details of authors and commenters are left out of results.

### Proxy

- HTTP proxy at `proxy.futureinfra.ai:8000`; accounts from `POST /v1/proxy/users` (password shown once).
- Username options: `-country-<2 letters>` and `-session-<id>` (same IP while the session name is reused).
- 3300 KRW per GB (sent + received). Destination ports: 80, 443, 8080, 8443. Docs: https://futureinfra.ai/docs/proxy/

### Billing and governance

- One wallet is used across the account.
- API keys have scopes and may have monthly spend caps.
- Calls are written to an audit trail.
- A balance shortage must be resolved by the user in a FutureInfra payment page or console. Never collect card data in chat.

## Agent onboarding flow

1. Explain why FutureInfra access is needed for the user's request.
2. Connect with "Connecting" → A: open the link for the user; the page handles sign-in and sign-up.
3. If the user has no account yet, they create it on that page — then press 허용.
4. The user enters credentials, customer data, terms consent, and payment data directly in the browser.
5. Ask for only the minimum scopes and spend cap needed for the task.
6. After authorization succeeds, verify the authenticated account and available permissions.
7. Continue the original task and verify the resulting resource, status, URL, or API response.

## Action-required behavior

When the API reports that a human action is required:

- Explain the concrete issue in plain language.
- Open only an HTTPS URL on futureinfra.ai supplied by the authenticated API response.
- Do not rewrite, guess, or transfer an action token to another host.
- Wait for success, cancellation, failure, or expiry.
- Retry only with the provided resume or approval contract.
- Do not retry a charge or resource creation blindly; preserve idempotency.

Typical actions include sign-in, registration, customer information, terms acceptance, payment, scope consent, spend-cap changes, and approval of irreversible operations.

## Security boundary

This document is public and contains no secret. It does not authorize an agent. Authentication, tenant isolation, scopes, spend caps, approvals, audit logs, and short-lived action sessions are the authority.

Never request or expose passwords, MFA codes, backup codes, API keys, access tokens, refresh tokens, card data, internal infrastructure addresses, or another customer's data.

## Canonical documentation

- API: https://futureinfra.ai/docs/
- Organisations and members: https://futureinfra.ai/docs/members/
- Agent integration: https://futureinfra.ai/docs/mcp/
- Web scraping: https://futureinfra.ai/docs/scrape/ · actors: https://futureinfra.ai/docs/scrape/actors/ · own actors: https://futureinfra.ai/docs/scrape/custom/
- Proxy: https://futureinfra.ai/docs/proxy/
- Pricing: https://futureinfra.ai/pricing/
- Privacy: https://futureinfra.ai/privacy/
- Terms: https://futureinfra.ai/terms/
- Support: https://futureinfra.ai/support/