Documentation

Créer votre premier bac à sable

Créez un bac à sable Linux, écrivez et examinez un fichier, puis arrêtez-le et supprimez-le. Suivez le parcours avec le CLI ou les solutions de rechange par l’API et le portail ci-dessous.

1. Se connecter et sélectionner un espace de travail

Installez d’abord le CLI rzv. Connectez-vous, listez vos espaces de travail et remplacez <workspace-id> par un ID ou un slug de la liste. Créer des bacs à sable, exécuter des commandes et changer leur état exige le rôle de propriétaire ou d’administrateur.

Les exemples sont des commandes à exécuter, pas des résultats capturés. Remplacez chaque paramètre fictif entre chevrons avant d’exécuter une commande. Pour le reste de ce parcours, utilisez l’ID de bac à sable retourné par votre propre requête de création.

Terminal · se connecter et sélectionner votre espace de travail

rzv login
rzv workspaces list
rzv workspaces select <workspace-id>

Installer le CLI rzv

2. Vérifier les tailles et la capacité

Listez vos bacs à sable avant d’en créer un. La réponse indique les tailles actuellement offertes, la limite d’exécutions simultanées de l’espace de travail, ainsi que l’état, le temps restant et les crédits utilisés de chaque bac à sable.

Le CLI prend en charge 2vcpu-8gb, 4vcpu-16gb, 8vcpu-32gb et 16vcpu-64gb. Les tailles disponibles dépendent de la capacité des hôtes. Ce parcours utilise 2vcpu-8gb. Choisissez une autre taille offerte si celle-ci n’est pas disponible. Créer ou démarrer un bac à sable exige aussi du crédit dans l’espace de travail.

Terminal · vérifier la disponibilité actuelle

rzv sandboxes list

Tailles, limites et facturation

3. Créer un bac à sable

Créez et démarrez un bac à sable nommé code-check avec un disque d’espace de travail de 20 GiB. Copiez l’ID du bac à sable à partir de la réponse. Chaque fois que les exemples suivants indiquent <sandbox-id>, remplacez-le par cet ID.

Le disque peut faire de 5 à 64 GiB. La valeur par défaut est de 20 GiB si vous omettez --disk-gib. Pour réessayer la création en toute sécurité, fournissez le même --idempotency-key dans les deux requêtes.

Terminal · créer un bac à sable dans l’espace de travail sélectionné

rzv sandboxes create --name code-check --size 2vcpu-8gb --disk-gib 20

4. Attendre qu’il soit en cours d’exécution

Examinez le nouveau bac à sable. Si son état est pending ou starting, répétez get jusqu’à ce qu’il passe à running avant d’envoyer des commandes. Un état failed inclut la cause. Corrigez-la avant de continuer.

Terminal · remplacez <sandbox-id> par l’ID retourné

rzv sandboxes get <sandbox-id>

5. Écrire un fichier de résultat

Cette commande écrit une ligne dans result.txt, dans /workspace. Elle devrait se terminer avec succès sans afficher le contenu du fichier. L’étape suivante relit le fichier.

Le -- sépare les options de rzv de la commande distante. Utilisez explicitement bash -lc pour la syntaxe du shell, comme la redirection. Gardez le script entre guillemets pour que votre shell local ne redirige pas la sortie vers un fichier local.

Terminal · écrire un fichier dans le bac à sable

rzv sandboxes exec <sandbox-id> -- bash -lc 'printf "hello sandbox\n" > result.txt'

6. Examiner le résultat

Lisez le fichier avec une deuxième commande. Elle devrait afficher hello sandbox suivi d’un saut de ligne. Le CLI diffuse stdout et stderr en continu et se termine avec le code de sortie de la commande distante.

Terminal · lire le fichier dans le bac à sable

rzv sandboxes exec <sandbox-id> -- cat result.txt

7. Arrêter quand vous avez besoin d’une pause

L’arrêt met fin à la facturation de l’exécution et conserve les fichiers de /workspace pendant la durée de vie du bac à sable. Examinez son état après la demande d’arrêt. Redémarrez-le si vous devez continuer avant son expiration.

La durée de vie de huit heures commence au premier démarrage. L’arrêt ne suspend pas l’horloge et un nouveau démarrage ne la réinitialise pas.

Terminal · arrêter et examiner le bac à sable

rzv sandboxes stop <sandbox-id>
rzv sandboxes get <sandbox-id>

Facultatif : reprendre un bac à sable arrêté

Redémarrez le même bac à sable pour retrouver ses fichiers avant la fin de sa durée de vie de huit heures. Attendez que son état soit running avant d’envoyer une autre commande.

Terminal · reprendre dans la durée de vie existante

rzv sandboxes start <sandbox-id>
rzv sandboxes get <sandbox-id>

8. Supprimer une fois terminé

Supprimez le bac à sable créé pour ce parcours quand vous n’avez plus besoin de ses fichiers. La suppression retire la VM et ses fichiers. Vérifiez ensuite la liste pour voir l’état obtenu.

Terminal · supprimer le bac à sable du parcours

rzv sandboxes delete <sandbox-id>
rzv sandboxes list

Plus d’exemples de commandes et de terminal

Autre option par l’API : créer un bac à sable

Envoyez le jeton d’accès d’une personne, ou une clé d’API d’espace de travail avec la permission sandboxes:write, comme jeton porteur. Fournissez RZV_TOKEN de façon sécurisée et remplacez <tenant-id> par l’ID de votre espace de travail. Répéter client_operation_id retourne le bac à sable créé par la première requête.

Lisez l’ID du bac à sable retourné et attendez que son état soit running avant d’envoyer une requête exec. La référence de l’API documente les requêtes de cycle de vie et d’état.

Terminal · remplacez l’ID de l’espace de travail et fournissez RZV_TOKEN

curl -X POST "https://api.runzivo.dev/v1/customer/tenants/<tenant-id>/sandboxes" \
  -H "Authorization: Bearer $RZV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"agent-1","size":"2vcpu-8gb","client_operation_id":"agent-1-create"}'

Voir les permissions des clés d’API pour les bacs à sable

Référence de l’API du cycle de vie des bacs à sable

Autre option par l’API : exécuter une commande

Une fois que le bac à sable est running, remplacez <sandbox-id> par l’ID retourné. Cet exemple demande à l’invité Linux d’identifier son système d’exploitation. L’API exec diffuse la sortie en continu, puis l’événement de sortie final.

Terminal · exécuter dans un bac à sable en cours d’exécution

curl -X POST "https://api.runzivo.dev/v1/customer/tenants/<tenant-id>/sandboxes/<sandbox-id>/exec" \
  -H "Authorization: Bearer $RZV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cmd":"uname -s"}'

Référence de l’API d’exécution et de terminal

Dans le portail

1. Ouvrez « Build & Deploy », puis « Sandboxes », et sélectionnez « New Sandbox ».
2. Saisissez un nom, choisissez une taille offerte et sélectionnez « Create sandbox ».
3. Attendez l’état running, puis utilisez le terminal de la page du bac à sable. La page affiche aussi l’état, le temps restant et les crédits utilisés.
4. Utilisez « Stop » quand vous avez besoin d’une pause, « Start » pour continuer dans la durée de vie, et « Delete » une fois terminé.
Si la page indique « Sandboxes are not available yet », les bacs à sable ne sont pas activés dans votre environnement.

Ouvrir le portail client