Référence / Agent Sandboxes

Exécuter une commande

Exécute bash -lc dans un bac à sable en cours d'exécution et diffuse en continu stdout, stderr et le résultat de sortie.

POST/v1/customer/tenants/{tenantId}/sandboxes/{sandboxId}/exec

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.

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.

Corps de la requête

Envoyez Content-Type: application/json.

Champs JSON de la requête
Champ	Description
`cmd`stringObligatoire	Commande shell non vide, d'au plus 64 KiB ; aucun octet NUL. S'exécute avec bash -lc.
`cwd`stringFacultatif	Répertoire de travail absolu ; /workspace par défaut. Maximum du schéma publié : 1024 caractères.
`env`objectFacultatif	Jusqu'à 64 variables d'environnement. Les noms respectent ^[A-Za-z_][A-Za-z0-9_]{0,127}$ ; les valeurs font au plus 8192 octets, sans NUL.
`timeout_seconds`integerFacultatif	De 1 à 3600 secondes ; 300 par défaut si omis.

Comportement et limites

Envoyez application/json ; limite de taille du corps de la requête : 128 KiB. Jusqu'à quatre commandes simultanées par bac à sable ; au-delà, 409 session_limit_reached.
Chaque ligne stdout/stderr contient des données (data) en base64. La ligne finale exit contient exit_code, timed_out et truncated ; reason apparaît lorsque le bac à sable a été arrêté, a expiré ou a été supprimé.
La déconnexion annule la commande. La sortie est plafonnée à 8 MiB. Une commande ayant dépassé son délai et encore active 30 secondes plus tard est annulée avec le code de sortie 124 ; une troncature se termine par le code 137.

Réponses

Codes de réponse HTTP
État	Signification
200 Flux ouvert	application/x-ndjson
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.
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.

cURL

curl --no-buffer --request POST \
  "https://api.runzivo.dev/v1/customer/tenants/${TENANT_ID}/sandboxes/${SANDBOX_ID}/exec" \
  --header "Authorization: Bearer ${RUNZIVO_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
  "cmd": "printf '"'"'hello\\n'"'"'",
  "cwd": "/workspace",
  "timeout_seconds": 300
}'

Exemple de réponse

application/x-ndjson · Flux illustratif. Décodez en base64 le champ data de chaque segment de sortie. Il s'agit de lignes distinctes, et non d'un tableau JSON.

200 · application/x-ndjson

{"type":"stdout","data":"aGVsbG8K"}
{"type":"exit","exit_code":0,"timed_out":false,"truncated":false}

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

200 Flux ouvert

Flux illustratif. Décodez en base64 le champ data de chaque segment de sortie. Il s'agit de lignes distinctes, et non d'un tableau JSON.

application/x-ndjson

{"type":"stdout","data":"aGVsbG8K"}
{"type":"exit","exit_code":0,"timed_out":false,"truncated":false}

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

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