클라우드에 만들기

virtual Device 는 플랫폼이 클라우드에 띄우는 기기예요 — 화면에서는 기기 추가의 “클라우드에 만들기” 예요. 만들면 OS 가 컴퓨트 공급자에게 VM 과 영구 볼륨(Storage)을 받고, 그 안에 에이전트를 설치해요. 내 기기에 에이전트를 직접 까는 길은 기기 연결하기 예요.

만들 수 있는 kind 보기

어떤 kind 를 띄울 수 있는지는 그 환경의 컴퓨트 공급자가 정해요. GET /stations/{id}/device-kinds 가 kind(linux·chrome·android·windows)마다 available·reason(kind_not_allowed·no_provider·provider_unavailable)·provider·regions 를 답해요. 머신을 만들거나 깨우지 않아요. API 키로도 읽어요.

만들기

curl -s -X POST $OS/api/v1/stations/$STN/devices \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"type":"virtual","name":"web","kind":"chrome","size":"small","storage_gb":1,"pin_to_dock":true}' \
  | jq '.data.device | {device_id, compute_status, workloads}'

필드	뜻	기본
`type`	`virtual`	필수
`kind`	`linux` · `chrome` · `android` · `windows`. `mac` 이나 공급자가 못 띄우는 kind 는 422 `DEVICE_KIND_NOT_HOSTABLE`	필수
`name`	이름 (1~100자)	필수
`size`	`small`(1 vCPU·1 GB) · `medium`(2·4 GB) · `large`(4·8 GB)	small
`storage_gb`	영구 볼륨 크기 (0~500). 0 이면 볼륨 없이	linux 10 · android 8 · chrome 1 · windows 32
`start`	만들자마자 시작	true
`pin_to_dock`	Dock 1단 끝에 기기로 붙이기	true

응답은 201 {device} 이고 compute_status 는 provisioning·starting·stopped(start: false) 중 하나예요. actual 과 달리 enrollment 가 없어요 — 토큰은 OS 가 관리해요. 공급자에 닿지 못해도 503 이 아니라 201 + failed(status_reason: compute_unavailable) — 기기는 남아 있어서 다시 시작하거나 지울 수 있어요.

virtual Device 만들기·크기 바꾸기·지우기는 사용자 JWT 로만 돼요 (비용을 만드는 일). API 키면 403 FORBIDDEN.
계정 잔액이 0 이하면 402 INSUFFICIENT_CREDITS (크레딧).
한도: 409 VIRTUAL_DEVICE_LIMIT_REACHED(OS max_virtual_devices)·VOLUME_QUOTA_EXCEEDED(max_volume_gb)·DEVICE_LIMIT_REACHED(max_resources). OS 가 멈춰 있으면 409 OS_HALTED.

Workload

virtual Device 의 workloads 에는 세 가지가 있어요.

type	무엇	id
`vm`	컴퓨트 한 대 — `provider`·`region`·`cpus`·`memory_mb`·`status`	`wkl_`
`storage`	영구 볼륨 — `size_gb`·`mount_path`·`status`. VM 이 멈춰도 남고, 기기를 지우면 함께 지워져요. `storage_gb: 0` 이면 없어요	`vol_`
`agent`	설치된 에이전트 — `status`(`pending`·`online`·`offline`)·`version`	`agnt_` (준비 중이면 null)

상태 — `compute_status`

stateDiagram-v2
  [*] --> provisioning: 만들기
  provisioning --> starting: 공급자 머신 생성
  provisioning --> failed: 공급자 실패
  provisioning --> stopped: start=false
  starting --> running: 에이전트 접속
  starting --> failed: 5분 안에 에이전트 없음
  running --> stopping: stop · OS halt · 잔액 음수
  stopping --> stopped
  stopped --> starting: start
  failed --> starting: start
  running --> starting: restart
  running --> deleting: delete
  stopped --> deleting: delete
  deleting --> [*]

starting → running 은 에이전트가 붙을 때예요. 기다리는 동안 GET /devices/{id} 를 부르거나, 이벤트의 device.status_changed 를 받아요.
플랫폼은 공급자를 주기적으로 감시하지 않아요. starting·stopping 인 기기를 단건 조회할 때만 공급자에게 한 번 물어 맞춰요.
status(pending·active·disabled)는 등록 상태로, actual 과 같은 뜻이에요. compute_status 와 따로예요.

시작·정지·재시작

동작	하는 일
`start`	머신이 없으면 만들고, 있으면 켜요. 200 의 `compute_status` 는 `starting`. 시작할 때마다 에이전트 토큰을 새로 내요 — 원문 토큰은 어디에도 저장되지 않아요
`stop`	머신을 멈춰요. Storage 는 남아요. 20초 안에 멈추면 `stopped`, 아니면 `stopping`
`restart`	멈춘 뒤 새 토큰으로 다시 켜요

stopping·deleting 중 시작은 409 DEVICE_STATE_CONFLICT. actual 에 부르면 같은 409 예요 (details.type).
start·restart 는 크레딧을 확인해요 — 잔액이 0 이하면 402 INSUFFICIENT_CREDITS. OS 가 멈춰 있으면 409 OS_HALTED.
공급자에 닿지 못하면 503 COMPUTE_UNAVAILABLE 이고 상태는 그대로예요.
셋 다 API 키로도 돼요.

크기는 PATCH /devices/{id} {"size":"medium"} 로 바꿔요. 다음 시작부터 적용돼요.

지우기

DELETE /devices/{id} → 204. VM·Storage·에이전트·Dock 항목·저장한 앱이 모두 없어져요. 공급자 실패면 503 이고 compute_status: deleting 으로 남아요 — 다시 부르면 이어서 지워요.

비용

virtual Device 는 내 계정의 크레딧을 세 가지로 써요 — 명령 1건마다, running 인 분 × 크기별 단가, 있는 동안 Storage GB × 시간. 멈춰 두면 컴퓨트는 쓰지 않고 Storage 만 남아요. 단가는 GET /billing/rates 예요.

안의 정보 읽기

running 이면 그 device_id 로 명령을 보내요. kind 별로 자주 쓰는 도구:

kind	도구 예
linux	`workspace_info` · `list_dir` · `read_file` · `write_file` · `run_program`
chrome	`navigate` · `tab_list` · `screenshot` (+ 화면)
android	`app_list` · `app_launch` · `screenshot` (+ 설치된 앱)

정확한 목록과 입력 스키마는 GET /devices/{id}/tools 가 기준이에요.