Computer-Control-API

advanced 🤖 LLM-freundlich 2 Min · 316 Wörter Aktualisiert: 2026-06-27 Deutsch

Fernsteuerung registrierter Rechner — Commands in die Warteschlange stellen, Screenshots aufnehmen, Scripts auf Remote-Maschinen ausführen.

Diesen Artikel lesen als: 📄 Plain Text ⚡ JSON 🤖 LLM-Format

Computer-Control-API

Die Computer-Control-API ermöglicht die Fernsteuerung registrierter Rechner. Ein kleiner Agent (screen-remote-agent) läuft auf der Zielmaschine, fragt Commands ab, führt sie aus und postet Ergebnisse zurück. Das ermöglicht LLM-gesteuerte GUI-Automatisierung.

Architektur

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

Nutzerseitige Endpunkte (Mind Key oder JWT)

GET /computers/list

Alle registrierten Rechner auflisten.

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

GET /computers/:id

Details eines einzelnen Rechners abrufen.

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

POST /computers/install-code

Installationscode zur Registrierung eines neuen Rechners generieren.

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

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

POST /computers/:id/commands

Ein Command für den Remote-Agent in die Warteschlange stellen.

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

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

GET /computers/:id/command (via Query)

Ein Command via GET einreihen (für einfache Fälle).

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

GET /computers/:id/commands

Letzte Commands für einen Rechner auflisten.

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

GET /computers/:id/commands/:cid

Status + Ergebnis eines bestimmten Commands abrufen.

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

GET /computers/:id/screenshot

One-Shot: ein Screenshot-Command einreihen und bis zu 30s auf das Ergebnis warten.

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

POST /computers/:id/disable

Einen Rechner deaktivieren (widerruft seinen Token, behält den Eintrag fürs Audit).

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

DELETE /computers/:id

Einen Rechner dauerhaft löschen.

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

Agentseitige Endpunkte (Computer-Token)

Diese Endpunkte werden vom screen-remote-agent auf der Zielmaschine verwendet. Sie verwenden einen Computer-Token (von /computers/register zurückgegeben), keinen Mind Key.

POST /computers/register

Installationscode einlösen und einen Computer-Token erhalten.

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

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

Speichere den `computer_token` — er wird nur einmal angezeigt und wird für alle agentseitigen Endpunkte benötigt.

GET /computers/me/poll

Long-Poll für neue Commands. Der Agent ruft dies in einer Schleife auf.

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

Kehrt sofort zurück, wenn Commands ausstehen, sonst nach wait Sekunden.

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

Das Ergebnis der Ausführung eines Commands posten.

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

Command-Typen

Typ	Payload	Beschreibung
`screenshot`	`{}`	Bildschirm als PNG aufnehmen (base64)
`click`	`{x, y}`	An Koordinaten klicken
`move`	`{x, y}`	Maus zu Koordinaten bewegen
`type`	`{text}`	Text am Cursor tippen
`key`	`{keys: ["Ctrl","c"]}`	Tastenkombination drücken
`scroll`	`{deltaX, deltaY}`	Scrollrad
`drag`	`{fromX, fromY, toX, toY}`	Drag-and-Drop

Typisches Pattern: LLM-gesteuerte GUI-Automatisierung

# 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

Nächste Schritte

Browser-Proxy — separater Dienst für Browser-Automatisierung
Self-Hosted-Agents-Guide