핵심 개념

endue OS 의 모든 API 는 아래 개념 위에 있어요. 이름이 비슷한 것이 몇 있으니 맨 아래 “헷갈리는 말” 도 봐 주세요.

사용자 (usr_) ── 계정 ──1:1── 지갑 (크레딧 잔액 · 원장)
      └──1:N── Project (prj_)
                  └──1:N── Station (stn_) ──1:1── OS (osi_)
                              ├──1:N── Device (res_)   type = actual | virtual
                              │          ├── Workload   actual: agent   virtual: vm · storage · agent
                              │          └──1:N── App (app_)   기기 안의 앱 (android 패키지) — 저장한 것
                              └──1:1── Dock — 1단: Device | 1단에 고정한 App,  2단: 그 Device 의 App

개념	뜻
Project	Station 을 묶는 단위예요. 이름·설명만 있어요. 사용자당 20개까지 만들고, 하나도 없을 때 Station 을 만들면 “기본 프로젝트” 가 생겨요. 팀·조직은 아직 없어요 — 프로젝트는 만든 사람만 다뤄요.
Station	사용자의 환경. 컴퓨터 한 대처럼 보여요. 기기·명령·Dock 은 모두 Station 안에 있어요.
OS	Station 에 정확히 하나. 버전·상태(`running`·`halted`)·설정(한도)을 가져요. 따로 만들거나 지울 수 없어요. halt 하면 명령을 막고 돌던 virtual Device 를 멈춰요.
Device	OS 가 관리하는 기기 하나. kind 는 `chrome`·`mac`·`android`·`linux`·`windows`. `type` 이 둘이에요 — actual(내 기기에 에이전트를 설치)과 virtual(플랫폼이 클라우드에 VM 을 띄우고 에이전트를 넣음). id 는 `res_` 예요.
Workload	Device 에 할당된 것. `vm`(컴퓨트 한 대)·`storage`(영구 볼륨)·`agent` 세 가지예요. actual 은 agent 하나, virtual 은 vm·storage(없을 수 있어요)·agent.
Agent	기기·VM 에 설치된 프로그램. Device 와 1:1 이에요. 릴레이에 먼저 접속하고, 받은 도구 요청을 기기에서 실행해요. LLM 은 들어 있지 않아요.
App	Device 안의 앱(android 패키지)을 저장한 것. 그 기기의 Dock 2단에 늘 있고, `pinned` 면 1단에도 있어요. 클라우드에 띄운 android 와 손에 든 폰이 같은 방식이에요.
설치된 앱	Device 안의 네이티브 앱 목록(`installed-apps`). OS 는 저장하지 않고 에이전트에게 그때그때 물어요. 저장한 것만 App 이 돼요.
Dock	2단이에요. 1단은 Device 와 1단에 고정한 App 의 순서 있는 목록(최대 30칸), 2단은 Device 를 누르면 펼쳐지는 그 Device 의 App 이에요. 저장되는 것은 1단의 순서뿐이에요.
명령	Device 에 보내는 도구 실행 한 번. 상태는 `queued`→`dispatched`→`running`→`succeeded` 등 10종이에요.
크레딧	endue OS 안의 유일한 화폐예요. 내 계정에 지갑이 하나 있고, 모든 프로젝트의 명령·컴퓨트·스토리지가 이 크레딧을 써요. 잔액이 0 이하면 비용을 만드는 동작이 402 `INSUFFICIENT_CREDITS` 예요.

기기를 더하는 두 길 — 내 기기에 설치 · 클라우드에 만들기

둘 다 POST /stations/{id}/devices 하나로 만들어요. type 만 달라요.

	내 기기에 설치 — `actual`	클라우드에 만들기 — `virtual`
누가 에이전트를 넣나	사용자 — 응답의 `enrollment`(주소·토큰)로 설치	OS — VM·Storage 를 띄우고 에이전트를 넣어요
kind	mac · linux · windows · chrome · android	linux · chrome (Fly.io) · windows · android (AWS) — 실제 클라우드는 프리뷰. mac 은 actual 만
상태	`online` 만	`online` + `compute_status`(`provisioning` … `running` … `stopped`)
시작·정지	없어요 (409 `DEVICE_STATE_CONFLICT`)	`start`·`stop`·`restart`
비용	명령 수만큼 크레딧. 기기는 사용자의 것	명령 + 켜져 있는 시간(크기별) + 볼륨 크기×시간
만들 수 있나	언제나	`GET /stations/{id}/device-kinds` 가 kind 마다 답해요
가이드	기기 연결하기	클라우드에 만들기

헷갈리는 말

App(기기 안의 앱을 저장한 것, app_) ≠ 설치된 앱(에이전트가 알려 주는 목록) ≠ endue AI 의 앱(클라이언트). v0.2.0 이전의 App(Station 의 실행 단위)은 virtual Device 가 됐어요.
Device = 예전 이름 Resource. id(res_)도, 이벤트의 resource_id 도 같은 값이에요. 옛 /resources/* 경로는 v0.1.0 호환으로 남아 있어요.
Agent(기기에 설치된 프로그램, agnt_) ≠ endue AI 의 AI 에이전트(ag_).
storage Workload(블록 볼륨, vol_) ≠ 저장 객체(Station 의 파일 저장소, /objects).

식별자

모든 id 는 접두사 + ULID 예요. prj_·stn_·osi_·res_(Device)·wkl_(vm)·vol_(storage)·agnt_·app_·cmd_·dck_·whk_·evt_·led_(원장)·chk_(체크아웃)·aud_(감사 로그) 등. 사용자는 usr_{신원 공급자의 sub} 로 셀 전체에서 같아요. 비밀값은 접두사로 구분해요 — API 키 osk_, 연결 토큰 osat_, 이벤트 입장권 ostk_, 웹훅 비밀 oswh_.