API Computer Control

advanced 🤖 LLM-friendly 2 min · 383 mots Mis à jour : 2026-06-27 Français

Contrôle à distance d'ordinateurs enregistrés — file d'attente de commandes, captures d'écran, exécution de scripts sur machines distantes.

Lire cet article en : 📄 Texte brut ⚡ JSON 🤖 Format LLM

API Computer Control

L'API Computer Control permet de télécommander des ordinateurs enregistrés. Un petit agent (screen-remote-agent) s'exécute sur la machine cible, effectue le polling des commandes, les exécute et renvoie les résultats. Cela permet l'automatisation d'interface graphique pilotée par LLM.

Architecture

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

Endpoints côté utilisateur (Mind Key ou JWT)

GET /computers/list

Liste tous les ordinateurs enregistrés.

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

GET /computers/:id

Récupère les détails d'un seul ordinateur.

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

POST /computers/install-code

Génère un code d'installation pour enregistrer un nouvel ordinateur.

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

Réponse : { "install_code": "ic_xyz789", "expires_at": "..." }

POST /computers/:id/commands

Met en file d'attente une commande à exécuter par l'agent distant.

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

Réponse : { "command_id": "cmd_001", "status": "queued" }

GET /computers/:id/command (via requête)

Met en file d'attente une commande via GET (pour les cas simples).

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

GET /computers/:id/commands

Liste les commandes récentes d'un ordinateur.

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

GET /computers/:id/commands/:cid

Récupère le statut et le résultat d'une commande spécifique.

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

GET /computers/:id/screenshot

Action unique : met en file d'attente une commande de capture d'écran et attend jusqu'à 30 s le résultat.

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

POST /computers/:id/disable

Désactive un ordinateur (révoque son jeton, conserve l'enregistrement pour audit).

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

DELETE /computers/:id

Supprime définitivement un ordinateur.

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

Endpoints côté agent (Computer Token)

Ces endpoints sont utilisés par le screen-remote-agent s'exécutant sur la machine cible. Ils utilisent un Computer Token (renvoyé par /computers/register), pas une Mind Key.

POST /computers/register

Échange un code d'installation contre 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"
  }'

Réponse : { "computer_id": "comp_001", "computer_token": "ct_..." }

Sauvegardez le `computer_token` — il n'est affiché qu'une seule fois et est requis pour tous les endpoints côté agent.

GET /computers/me/poll

Long-polling de nouvelles commandes. L'agent l'appelle en boucle.

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

Renvoie immédiatement si des commandes sont en attente, ou après wait secondes sinon.

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

Publie le résultat de l'exécution d'une commande.

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

Types de commandes

Type	Payload	Description
`screenshot`	`{}`	Capture l'écran en PNG (base64)
`click`	`{x, y}`	Clique aux coordonnées
`move`	`{x, y}`	Déplace la souris aux coordonnées
`type`	`{text}`	Saisit du texte au curseur
`key`	`{keys: ["Ctrl","c"]}`	Appuie sur une combinaison de touches
`scroll`	`{deltaX, deltaY}`	Fait défiler à la molette
`drag`	`{fromX, fromY, toX, toY}`	Glisser-déposer

Schéma courant : automatisation d'interface graphique pilotée par LLM

# Workflow de l'agent LLM
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

Prochaines étapes

Proxy navigateur — service distinct pour l'automatisation de navigateur
Guide des agents auto-hébergés