# Computer Control API

Computer Control API를 사용하면 등록된 컴퓨터를 원격으로 제어할 수 있습니다.
대상 머신에서 소형 에이전트(`screen-remote-agent`)가 실행되어 명령을
폴링하고, 실행하고, 결과를 다시 게시합니다. 이를 통해 LLM 기반 GUI
자동화가 가능해집니다.

## 아키텍처

```
┌─────────────┐  queue cmd   ┌──────────┐  poll   ┌─────────────────┐
│ LLM Agent   │ ───────────▶ │ Synapse  │ ◀───── │ screen-remote   │
│ (user-side) │              │  Server  │ ──────▶│ (on target PC)  │
└─────────────┘              └──────────┘ result  └─────────────────┘
                                     ▲
                                     │
                              ┌─────────────┐
                              │  Human UI   │
                              │ (browser)   │
                              └─────────────┘
```

## 사용자 측 엔드포인트 (Mind Key 또는 JWT)

### GET /computers/list

등록된 모든 컴퓨터를 나열합니다.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/list
```

### GET /computers/:id

단일 컴퓨터의 상세 정보를 가져옵니다.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001
```

### POST /computers/install-code

새 컴퓨터 등록용 설치 코드를 생성합니다.

```bash
curl -X POST https://synapse.schaefer.zone/computers/install-code \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"computer_name": "office-mac"}'
```

응답: `{ "install_code": "ic_xyz789", "expires_at": "..." }`

### POST /computers/:id/commands

원격 에이전트가 실행할 명령을 큐에 추가합니다.

```bash
curl -X POST https://synapse.schaefer.zone/computers/comp_001/commands \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "screenshot",
    "payload": {}
  }'
```

응답: `{ "command_id": "cmd_001", "status": "queued" }`

### GET /computers/:id/command (쿼리 경유)

GET 요청으로 명령을 큐에 추가합니다 (단순한 경우용).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/computers/comp_001/command?type=screenshot"
```

### GET /computers/:id/commands

컴퓨터의 최근 명령을 나열합니다.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/computers/comp_001/commands?limit=50"
```

### GET /computers/:id/commands/:cid

특정 명령의 상태 및 결과를 가져옵니다.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001/commands/cmd_001
```

### GET /computers/:id/screenshot

원샷: 스크린샷 명령을 큐에 추가하고 최대 30초 동안 결과를 기다립니다.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001/screenshot > screenshot.png
```

### POST /computers/:id/disable

컴퓨터를 비활성화합니다 (토큰을 취소하고, 감사를 위해 기록은 유지).

```bash
curl -X POST -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001/disable
```

### DELETE /computers/:id

컴퓨터를 영구적으로 삭제합니다.

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001
```

## 에이전트 측 엔드포인트 (Computer Token)

이 엔드포인트들은 대상 머신에서 실행되는 `screen-remote-agent`가
사용합니다. Mind Key가 아닌 Computer Token(`/computers/register`가 반환)을
사용합니다.

### POST /computers/register

설치 코드를 상환하고 Computer Token을 받습니다.

```bash
curl -X POST https://synapse.schaefer.zone/computers/register \
  -H "Content-Type: application/json" \
  -d '{
    "code": "ic_xyz789",
    "computer_name": "office-mac",
    "platform": "darwin",
    "platform_release": "14.5.0",
    "python": "3.12.4"
  }'
```

응답: `{ "computer_id": "comp_001", "computer_token": "ct_..." }`

> [!CRITICAL]
> `computer_token`을 저장하십시오 — 한 번만 표시되며 모든 에이전트 측
> 엔드포인트에 필요합니다.

### GET /computers/me/poll

새 명령을 롱 폴링합니다. 에이전트는 이것을 루프에서 호출합니다.

```bash
curl -H "Authorization: Bearer ct_YOUR_COMPUTER_TOKEN" \
     "https://synapse.schaefer.zone/computers/me/poll?wait=30"
```

대기 중인 명령이 있으면 즉시 반환되거나, 없으면 `wait`초 후에 반환됩니다.

### POST /computers/me/commands/:cid/result

명령 실행 결과를 게시합니다.

```bash
curl -X POST https://synapse.schaefer.zone/computers/me/commands/cmd_001/result \
  -H "Authorization: Bearer ct_YOUR_COMPUTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "done",
    "result": { "screenshot_b64": "iVBORw0KG..." }
  }'
```

## 명령 유형

| 유형 | 페이로드 | 설명 |
|------|---------|-------------|
| `screenshot` | `{}` | 화면을 PNG로 캡처 (base64) |
| `click` | `{x, y}` | 좌표 클릭 |
| `move` | `{x, y}` | 좌표로 마우스 이동 |
| `type` | `{text}` | 커서 위치에 텍스트 입력 |
| `key` | `{keys: ["Ctrl","c"]}` | 키 조합 누름 |
| `scroll` | `{deltaX, deltaY}` | 스크롤 휠 |
| `drag` | `{fromX, fromY, toX, toY}` | 드래그 앤 드롭 |

## 일반적인 패턴: LLM 기반 GUI 자동화

```python
# LLM agent workflow
1. List computers: GET /computers/list
2. Take screenshot: GET /computers/:id/screenshot
3. Analyze screenshot (vision model)
4. Queue click: POST /computers/:id/commands {type:"click", payload:{x,y}}
5. Wait for result: GET /computers/:id/commands/:cid
6. Take new screenshot to verify
7. Repeat until task done
```

## 다음 단계

- [Browser Proxy](/docs/api/browser) — 브라우저 자동화용 별도 서비스
- [Self-Hosted Agents Guide](/docs/guides/self-hosted-agents)