Endpoints desktop

Gestion des bureaux#

Endpoints pour creer, lister, mettre a jour et controler le cycle de vie des bureaux.

Lister les bureaux#

GET /api/desktops

Retourne tous les bureaux appartenant a l'utilisateur authentifie.

Reponse :

[
  {
    "id": "clx...",
    "name": "my-agent",
    "status": "running",
    "tier": "pro",
    "ipAddress": "10.0.3.42",
    "createdAt": "2026-03-15T10:00:00Z",
    "keepAlive": false
  }
]

Creer un bureau#

POST /api/desktops

Body :

Reponse : 201 avec l'objet bureau cree.

Note : Le providerConfig.apiKey est votre propre cle de provider IA (BYOK). Elle est injectee dans la VM au demarrage et n'est jamais stockee dans la base de donnees de Le Bureau.

Obtenir un bureau#

GET /api/desktops/:id

Retourne un bureau avec tous les details incluant l'adresse IP, les metriques de ressources et le statut de disponibilite de l'agent.

Mettre a jour un bureau#

PATCH /api/desktops/:id

Body :

Supprimer un bureau#

DELETE /api/desktops/:id

Detruit le bureau et sa VM. Le contenu du disque de donnees est perdu. Retourne 204 No Content.

Demarrer un bureau#

POST /api/desktops/:id/start

Demarre un bureau arrete. Le bureau transite par booting vers running. Retourne 200 avec le bureau mis a jour.

Arreter un bureau#

POST /api/desktops/:id/stop

Arrete la VM du bureau proprement. Retourne 200 avec le bureau mis a jour.

Redemarrer un bureau#

POST /api/desktops/:id/restart

Arrete puis demarre le bureau. Equivalent a stop + start mais atomique. Retourne 200.

Interaction avec le bureau#

Envoyer un message chat#

POST /api/desktops/:id/chat

Envoie un message a l'agent IA sur le bureau. L'agent traite le message et retourne une reponse.

Body :

Reponse :

{
  "response": "J'ai installe PostgreSQL et cree la base de donnees...",
  "messageId": "msg_abc123"
}

Note : Le bureau doit etre en etat running avec agentReady: true. Si l'agent n'est pas pret, vous recevez un 503 Service Unavailable.

Streamer la reponse chat#

POST /api/desktops/:id/chat/stream

Identique a l'endpoint chat, mais retourne un flux SSE avec des morceaux de reponse incrementaux. Utilisez ceci pour un effet de frappe en temps reel.

Body : identique a /chat.

Obtenir l'historique du chat#

GET /api/desktops/:id/chat/messages

Retourne l'historique complet de la conversation pour le bureau.

Executer une commande#

POST /api/desktops/:id/exec

Execute une commande unique sur le bureau via SSH.

Body :

Reponse :

{
  "stdout": "...",
  "stderr": "...",
  "exitCode": 0
}

Executer un script Bash#

POST /api/desktops/:id/bash

Execute un script bash multi-lignes sur le bureau. Le script est ecrit dans un fichier temporaire et execute.

Body :

Operations sur les fichiers#

GET /api/desktops/:id/files?path=/home/agent/project

Liste les fichiers au chemin donne.

POST /api/desktops/:id/files

Upload ou ecriture d'un fichier.

Body :

Capture d'ecran#

GET /api/desktops/:id/screenshot

Retourne une capture d'ecran PNG de l'affichage actuel du bureau. Utile pour surveiller l'activite de l'agent depuis des scripts.

Metriques#

GET /api/desktops/:id/metrics

Retourne l'utilisation actuelle du CPU, de la RAM et du disque pour le bureau.

Reponse :

{
  "cpu": 23.5,
  "memory": { "used": 1024, "total": 4096, "percent": 25.0 },
  "disk": { "used": 5120, "total": 20480, "percent": 25.0 }
}

Flux de statut des bureaux#

GET /api/desktops/stream

Un endpoint SSE qui pousse des mises a jour de statut en temps reel pour tous vos bureaux. Voir Endpoints streaming pour les details sur la consommation SSE.

Codes d'erreur#