기기 연결하기

“내 기기에 설치” 하면 Station 의 actual Device 가 돼요. 플랫폼이 컴퓨트를 띄워 주는 다른 길은 클라우드에 만들기 (virtual Device) 예요. 에이전트가 릴레이로 먼저 접속하므로(아웃바운드 WSS) 기기에 공인 주소나 열린 포트가 필요 없어요.

1. 기기 등록

curl -s -X POST $OS/api/v1/stations/$STN/devices \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"type":"actual","kind":"mac","name":"내 맥북"}' | jq '.data | {device_id: .device.device_id, enrollment}'
# { "device_id": "res_…", "enrollment": { "endpoint": "wss://…/api/v1/relay/socket", "token": "osat_…" } }

응답은 201 {device, enrollment} 예요. 등록하면 Dock 1단 끝에 기기로 붙어요.
enrollment.token 은 이 응답에서만 보여요. 잃어버리면 토큰 회전 POST /devices/{id}/agent/rotate-token 으로 새로 받아요 (접속 중이면 409 AGENT_CONNECTED).
description·labels 도 함께 줄 수 있어요. 한도는 OS 설정 max_resources(409 DEVICE_LIMIT_REACHED)와 allowed_kinds(422 DEVICE_KIND_NOT_ALLOWED)예요.

2. 에이전트 실행

kind	에이전트	붙이는 법
`mac`	mac-agent (Rust)	`ENDUE_WS_TOKEN=osat_… endue-mac-agent --endpoint <endpoint> --workspace-root ~/EndueWorkspace`
`linux`	linux-agent (Rust)	같은 값으로. systemd 설치 스크립트가 있어요
`windows`	windows-agent (Rust) 프리뷰	PowerShell 설치 스크립트(예약 작업). 파일 도구는 되지만 프로그램 실행은 격리가 생길 때까지 거절해요(`sandbox_unavailable`). Windows 에서는 아직 돌려 보지 않았어요
`chrome`	chrome-agent (MV3 확장)	확장 팝업에 주소와 토큰을 넣어요
`android`	android-agent (APK)	앱에 주소와 토큰을 넣어 프로비저닝해요

토큰 하나에 프로세스 하나. 같은 토큰으로 둘을 띄우면 서로를 밀어내며 번갈아 붙어요.

3. 확인

curl -s $OS/api/v1/devices/$DEV -H "Authorization: Bearer $TOKEN" | jq '.data | {type, status, online, workloads}'
curl -s $OS/api/v1/devices/$DEV/tools -H "Authorization: Bearer $TOKEN" | jq '.data[].name'

핸드셰이크가 끝나면 온라인이에요. actual 의 workloads 는 agent 하나예요. compute_status·size 는 virtual 만의 것이라 null 이에요. 도구 목록은 에이전트가 describe_tools 로 알려 준 카탈로그예요 — 플랫폼은 도구를 정하지 않아요.

기기 목록은 GET /stations/{id}/devices 예요. ?type=actual 이나 ?kind=android 로 걸러요.

온라인을 아는 방법

endue OS 는 가만히 있는 에이전트에게 아무것도 묻지 않아요 (비용 원칙). 에이전트가 보내는 ping 에 런타임이 자동으로 답할 뿐이에요. 대신:

기기 하나를 조회하거나 명령을 보내기 직전에 마지막 ping 시각을 봐요. ping 주기의 2.5배보다 오래됐으면 그 자리에서 오프라인으로 판정해요.
끊긴 뒤 60초 안에 같은 모습으로 다시 붙으면 아무 일도 없었던 것으로 쳐요 (배포 때 일괄 재접속이 이벤트·DB 쓰기를 만들지 않게).

그래서 목록의 online 은 조용히 죽은 기기를 늦게 알 수 있어요. 정확히 알아야 하면 그 기기를 한 번 조회해요.

바꾸기, 켜고 끄기, 지우기

PATCH /devices/{id} — 이름·설명·라벨을 바꿔요. size 는 virtual 만이라 actual 에 주면 409 DEVICE_STATE_CONFLICT.
POST /devices/{id}/disable — 명령을 막아요 (409 RESOURCE_DISABLED). enable 로 풀어요.
start·stop·restart 는 virtual 만이에요 — actual 에는 409 DEVICE_STATE_CONFLICT.
DELETE /devices/{id} — 에이전트를 폐기해요. 접속 중인 소켓은 4001 로 바로 닫히고, v1.1 이후 에이전트는 다시 붙지 않아요. Dock 항목과 그 기기에 저장한 앱도 함께 지워져요.