Référence / Agent Sandboxes

Ouvrir un terminal

Passe à un WebSocket pour le terminal interactif d'un bac à sable en cours d'exécution.

GET/v1/customer/tenants/{tenantId}/sandboxes/{sandboxId}/terminal

URL de base : https://api.runzivo.dev

Authentification

Envoyez Authorization: Bearer <token> avec un jeton d’accès client ou une clé d’API de l’espace de travail.

Permission de clé d’API : sandboxes:write. Ce sont des permissions, et non des portées héritées. Une clé dotée de la portée all:all fonctionne aussi, dans les limites des permissions actuelles de son créateur dans l’espace de travail.

Un navigateur peut plutôt utiliser un billet de terminal à usage unique, sans en-tête Authorization.

Paramètres

Paramètres de chemin et de requête
Champ	Description
`tenantId`string · pathObligatoire	L'ID de locataire (tenant) de votre espace de travail. Remplacez l'espace réservé par un ID auquel votre jeton a accès.
`sandboxId`string · pathObligatoire	L'id renvoyé à la création du bac à sable : sbx_ suivi de 24 caractères hexadécimaux en minuscules.
`ticket`string · queryFacultatif	Billet de terminal de navigateur à usage unique. Fournissez-le sans Authorization ; les clients d’API et de CLI envoient plutôt un jeton bearer.

Corps de la requête

Aucun corps de requête n’est requis.

Comportement et limites

Nécessite un client WebSocket. L'exemple cURL montre seulement la requête de mise à niveau HTTP ; ce n'est pas un client de terminal interactif.
Les octets du terminal circulent en trames binaires dans les deux sens, jamais en base64. La seule trame de texte est un objet resize : {"type":"resize","cols":80,"rows":24} ; chaque dimension doit être comprise entre 1 et 1000.
Répondez par pong aux pings du serveur (toutes les 30 secondes). Jusqu'à deux terminaux par bac à sable. Une nouvelle connexion crée un nouveau shell ; une session déconnectée ne reprend pas.
Codes de fermeture : 1000 pour une fermeture normale ou liée au cycle de vie, ou un délai d'inactivité de 30 minutes ; 1003 trame de texte invalide ; 1008 input_rate ; 1009 trame de plus de 64 KiB ; 1011 défaillance du serveur ou output_overflow.

Réponses

Codes de réponse HTTP
État	Signification
101 Changement de protocole	WebSocket
400 Requête invalide	JSON mal formé, champs inconnus ou valeurs invalides. Les mises à niveau de terminal rejettent aussi les négociations (handshakes) mal formées.
401 Non autorisé	Jeton porteur (bearer) manquant ou invalide. Une requête de terminal avec ticket peut plutôt renvoyer ticket_invalid.
403 Interdit	L'appelant n'a pas l'appartenance à l'espace de travail ni la permission requise, ou la clé d'API n'est pas autorisée. Les codes incluent tenant_membership_required, permission_required et api_key_scope_required.
404 Introuvable	Aucun bac à sable avec cet ID n'existe dans l'espace de travail autorisé.
409 Conflit	L'opération n'est pas permise dans l'état actuel du bac à sable. Consultez les notes de l'opération pour d'autres codes de conflit possibles.
426 Mise à niveau requise	La requête ne contenait pas de demande de mise à niveau vers WebSocket.
500 Erreur interne	Le serveur n'a pas pu traiter la requête.
503 Indisponible	Le service de bacs à sable est indisponible. Les opérations d'exécution de commande et de terminal peuvent aussi renvoyer sandbox_exec_unavailable.

Les exemples utilisent des identifiants, des dates et des valeurs fictifs. Consultez la réponse et l’état réels dans votre espace de travail.

Limites et facturation des bacs à sable →

Outils de la page

Voir en Markdown (anglais)

Poser une question à une IA sur cette page

Ouvrir dans ChatGPT Ouvrir dans Claude Ouvrir dans Cursor

Claude affiche une bannière de mise en garde sur toute invite préremplie. C’est normal : examinez l’invite, puis envoyez-la.

Exemple de requête

Requête à titre d’illustration. Définissez RUNZIVO_TOKEN et TENANT_ID et SANDBOX_ID dans votre interpréteur de commandes. Remplacez les valeurs fictives par les vôtres. Cette page n’envoie aucune requête.

Définissez WEBSOCKET_KEY avec un nonce de 16 octets encodé en base64, généré à neuf. Cette requête cURL montre seulement la mise à niveau HTTP ; utilisez un client WebSocket pour les trames du terminal.

cURL

curl --http1.1 --request GET \
  "https://api.runzivo.dev/v1/customer/tenants/${TENANT_ID}/sandboxes/${SANDBOX_ID}/terminal" \
  --header "Authorization: Bearer ${RUNZIVO_TOKEN}" \
  --header "Connection: Upgrade" \
  --header "Upgrade: websocket" \
  --header "Sec-WebSocket-Version: 13" \
  --header "Sec-WebSocket-Key: ${WEBSOCKET_KEY}"

Exemple de réponse

WebSocket · Un socket mis à niveau n'a pas de corps de réponse JSON. Échange de protocole illustratif :

101 · WebSocket

Client → server: binary terminal input bytes
Client → server: text {"type":"resize","cols":80,"rows":24}
Server → client: binary terminal output bytes
Server → client: ping (client replies pong)

Connexion du navigateur avec un billet

JavaScript à titre d’illustration après l’obtention d’un billet. Utilisez l’URL retournée, ne la journalisez pas et envoyez la saisie du terminal en trames binaires.

JavaScript

// ticketResponse is the terminal-ticket response.
const url = new URL(ticketResponse.url);
url.searchParams.set("ticket", ticketResponse.ticket);
const socket = new WebSocket(url);
socket.binaryType = "arraybuffer";
socket.addEventListener("open", () => {
  socket.send(JSON.stringify({ type: "resize", cols: 80, rows: 24 }));
});

Tous les exemples de réponse (aussi accessibles sans JavaScript)

101 Changement de protocole

Un socket mis à niveau n'a pas de corps de réponse JSON. Échange de protocole illustratif :

WebSocket

Client → server: binary terminal input bytes
Client → server: text {"type":"resize","cols":80,"rows":24}
Server → client: binary terminal output bytes
Server → client: ping (client replies pong)

400 Requête invalide

JSON mal formé, champs inconnus ou valeurs invalides. Les mises à niveau de terminal rejettent aussi les négociations (handshakes) mal formées.

application/json

{
  "error": {
    "code": "invalid_request"
  }
}

401 Non autorisé

Jeton porteur (bearer) manquant ou invalide. Une requête de terminal avec ticket peut plutôt renvoyer ticket_invalid.

application/json

{
  "error": {
    "code": "unauthorized"
  }
}

403 Interdit

L'appelant n'a pas l'appartenance à l'espace de travail ni la permission requise, ou la clé d'API n'est pas autorisée. Les codes incluent tenant_membership_required, permission_required et api_key_scope_required.

application/json

{
  "error": {
    "code": "permission_required"
  }
}

404 Introuvable

Aucun bac à sable avec cet ID n'existe dans l'espace de travail autorisé.

application/json

{
  "error": {
    "code": "sandbox_not_found"
  }
}

409 Conflit

L'opération n'est pas permise dans l'état actuel du bac à sable. Consultez les notes de l'opération pour d'autres codes de conflit possibles.

application/json

{
  "error": {
    "code": "sandbox_wrong_state"
  }
}

426 Mise à niveau requise

La requête ne contenait pas de demande de mise à niveau vers WebSocket.

application/json

{
  "error": {
    "code": "websocket_required"
  }
}

500 Erreur interne

Le serveur n'a pas pu traiter la requête.

application/json

{
  "error": {
    "code": "internal_error"
  }
}

503 Indisponible

Le service de bacs à sable est indisponible. Les opérations d'exécution de commande et de terminal peuvent aussi renvoyer sandbox_exec_unavailable.

application/json

{
  "error": {
    "code": "sandboxes_unavailable"
  }
}