API de Computer Control

advanced 🤖 Compatible con LLM 2 min · 394 palabras Actualizado: 2026-06-27 Español

Control remoto de computadoras registradas — encolar comandos, tomar capturas de pantalla, ejecutar scripts en máquinas remotas.

Leer este artículo como: 📄 Texto plano ⚡ JSON 🤖 Formato LLM

API de Computer Control

La API de Computer Control permite controlar de forma remota computadoras registradas. Un pequeño agente (screen-remote-agent) se ejecuta en la máquina destino, realiza poll de comandos, los ejecuta y publica los resultados de vuelta. Esto habilita la automatización GUI dirigida por LLM.

Arquitectura

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

Endpoints del lado del usuario (Mind Key o JWT)

GET /computers/list

Lista todas las computadoras registradas.

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

GET /computers/:id

Obtiene los detalles de una computadora individual.

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

POST /computers/install-code

Genera un código de instalación para registrar una nueva computadora.

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"}'

Respuesta: { "install_code": "ic_xyz789", "expires_at": "..." }

POST /computers/:id/commands

Encola un comando para que el agente remoto lo ejecute.

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": {}
  }'

Respuesta: { "command_id": "cmd_001", "status": "queued" }

GET /computers/:id/command (vía query)

Encola un comando vía GET (para casos simples).

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

GET /computers/:id/commands

Lista los comandos recientes de una computadora.

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

GET /computers/:id/commands/:cid

Obtiene el estado y resultado de un comando específico.

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

GET /computers/:id/screenshot

One-shot: encola un comando de captura de pantalla y espera hasta 30s por el resultado.

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

POST /computers/:id/disable

Deshabilita una computadora (revoca su token, conserva el registro para auditoría).

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

DELETE /computers/:id

Elimina una computadora de forma permanente.

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

Endpoints del lado del agente (Computer Token)

Estos endpoints los utiliza el screen-remote-agent que se ejecuta en la máquina destino. Usan un Computer Token (devuelto por /computers/register), no un Mind Key.

POST /computers/register

Canjea un código de instalación y obtiene un Computer Token.

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"
  }'

Respuesta: { "computer_id": "comp_001", "computer_token": "ct_..." }

Guarde el `computer_token` — solo se muestra una vez y es obligatorio para todos los endpoints del lado del agente.

GET /computers/me/poll

Long-poll de comandos nuevos. El agente lo llama en bucle.

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

Devuelve inmediatamente si hay comandos pendientes, o después de wait segundos si no los hay.

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

Publica el resultado de ejecutar un comando.

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..." }
  }'

Tipos de comando

Tipo	Payload	Descripción
`screenshot`	`{}`	Captura la pantalla como PNG (base64)
`click`	`{x, y}`	Clic en las coordenadas
`move`	`{x, y}`	Mueve el ratón a las coordenadas
`type`	`{text}`	Escribe texto en el cursor
`key`	`{keys: ["Ctrl","c"]}`	Pulsa una combinación de teclas
`scroll`	`{deltaX, deltaY}`	Rueda de desplazamiento
`drag`	`{fromX, fromY, toX, toY}`	Arrastrar y soltar

Patrón común: automatización GUI dirigida por LLM

# 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

Próximos pasos

Browser Proxy — servicio separado para automatización de navegador
Guía de agentes self-hosted