Documentation
Référence de l’API d’exécution et de terminal
Exécutez une commande avec une sortie diffusée en continu, ou ouvrez le terminal du bac à sable comme WebSocket. Les deux exigent un bac à sable en cours d’exécution et un jeton qui peut modifier les bacs à sable.
Exécuter une commande
POST /v1/customer/tenants/{tenantId}/sandboxes/{sandboxId}/exec avec cmd (obligatoire, exécuté avec bash -lc), cwd (/workspace par défaut), env (jusqu’à 64 variables) et timeout_seconds. Le corps fait au plus 128 KiB, et cmd au plus 64 KiB.
La réponse est de type application/x-ndjson : des lignes {"type":"stdout"|"stderr","data":"<base64>"} à mesure que la sortie arrive, puis une ligne exit avec exit_code, timed_out et truncated. Quand Runzivo a mis fin à la commande, exit contient aussi reason : sandbox_stopped, sandbox_expired ou sandbox_deleted.
Ouvrir le terminal
GET /v1/customer/tenants/{tenantId}/sandboxes/{sandboxId}/terminal passe à un WebSocket. Les clients d’API et de CLI envoient Authorization. Les octets du terminal circulent en trames binaires dans les deux sens, jamais en base64.
La seule trame de texte est la taille de fenêtre du client, {"type":"resize","cols":N,"rows":N} avec 1 à 1000 pour chaque valeur. Envoyez-la une fois après l’ouverture et à chaque changement. Répondez au ping du serveur, envoyé toutes les 30 secondes, par un pong.
Ticket de terminal pour les navigateurs
Un navigateur ne peut pas définir Authorization sur un WebSocket. POST /v1/customer/tenants/{tenantId}/sandboxes/{sandboxId}/terminal-ticket retourne url, ticket et expires_at. Ouvrez url en ajoutant ?ticket=<ticket>. Un ticket ne fonctionne qu’une fois, dure 30 secondes et désigne un seul bac à sable. Un bac à sable peut avoir 10 tickets inutilisés (429 ticket_limit_reached).
Le ticket se trouve dans l’URL. Ne journalisez donc pas la chaîne de requête de cette route dans vos propres mandataires.
Codes de fermeture et refus
- 1000 : sandbox_stopped, sandbox_expired, sandbox_deleted, shell_exited ou idle_timeout.
- 1003 : une trame de texte inconnue ou invalide. 1008 input_rate : entrée au-delà de 256 KiB par seconde en continu, ou une rafale de 1 MiB. 1009 : une trame de plus de 64 KiB. 1011 : une défaillance du serveur, output_overflow quand la sortie est lue trop lentement.
- 401 ticket_invalid : un ticket erroné, déjà utilisé, expiré ou étranger, avant toute mise à niveau.
- 409 sandbox_wrong_state : le bac à sable n’est pas en cours d’exécution. 409 session_limit_reached : trop de commandes ou de terminaux. 503 sandbox_exec_unavailable : exec ou le terminal n’est pas configuré.