Sandboxes par API et MCP

Avec un compte YorkHost, vos scripts et vos assistants IA peuvent gérer des sandboxes sans passer par ssh yorkhost.sh : les créer, y travailler, retrouver leurs adresses, les supprimer ou les garder en VPS. Ce sont les mêmes machines (mêmes limites), mais rattachées à votre compte, avec quelques avantages :

	Sandbox sans compte (`ssh yorkhost.sh`)	Sandbox créée depuis votre compte
Durée de fonctionnement	60 minutes	2 heures
Suppression	24 h après la création, sauf passage en VPS	idem
Sandboxes simultanées	1 par clé SSH	3 par compte
Clés SSH du compte	—	Acceptées sur toutes les sandboxes du compte
Secrets du compte	—	Injectés dans chaque nouvelle sandbox Linux
Commandes et fichiers sans SSH	—	`sandbox_exec`, `sandbox_read_file`…

Une sandbox créée avec ssh yorkhost.sh puis réclamée par votre compte garde les règles d'une sandbox sans compte.

Cette page ne détaille que la partie sandboxes. Pour la mise en route (double authentification, création de clé, connexion d'un assistant), voir :

Démarrer avec l'API
Serveur MCP : connexion de Claude, ChatGPT, Cursor… et liste complète des outils
Endpoints et Permissions

Permissions nécessaires

Permission	Libellé dans l'espace client	Ce qu'elle ouvre
`sandbox:read`	Voir les sandboxes agents	`list_sandboxes`, `sandbox_list_files`, `sandbox_read_file`, `list_sandbox_keys`, `list_sandbox_secrets`
`sandbox:write`	Créer et supprimer des sandboxes agents	`create_sandbox`, `sandbox_links`, `delete_sandbox`, `sandbox_exec`, `sandbox_write_file`, ajout et retrait des clés et des secrets
`orders:write`	Commander des services (facture à régler, plafond journalier)	`keep_sandbox`, `claim_sandbox`, `create_order`
`services:read`	Lister les services	`list_products` (catalogue, prix, offres de sandbox)
`billing:read`	Lire factures et crédit	`get_payment_link` (statut d'une facture et lien de paiement)

sandbox:write et orders:write ne font partie d'aucun modèle de permissions proposé à la création d'une clé : cochez-les explicitement. Chaque commande exige un préflight qui affiche le prix (voir plus bas), mais c'est l'assistant qui vous demande votre accord avant de confirmer : ne donnez orders:write qu'à un assistant de confiance.

Outils MCP

Outil	Rôle	Permission
`list_sandboxes`	Sandboxes du compte : commande SSH, URL de preview, échéances, avancement du passage en VPS	`sandbox:read`
`create_sandbox`	Crée une sandbox gratuite. Arguments : `ssh_public_key` (requis), `kind` (`linux`), `inject_secrets` (`false` pour ne pas injecter les secrets du compte)	`sandbox:write`
`sandbox_links`	Nouveau lien de bureau graphique, l'ancien cesse de fonctionner (sandboxes avec bureau, bientôt disponibles)	`sandbox:write`
`delete_sandbox`	Supprime une sandbox et tous ses fichiers (irréversible)	`sandbox:write`
`sandbox_exec`	Exécute une commande shell dans une sandbox en cours, sans SSH	`sandbox:write`
`sandbox_list_files`	Liste un dossier de la sandbox	`sandbox:read`
`sandbox_read_file`	Lit un fichier de la sandbox	`sandbox:read`
`sandbox_write_file`	Crée ou remplace un fichier dans la sandbox	`sandbox:write`
`list_sandbox_keys`	Clés SSH enregistrées sur le compte	`sandbox:read`
`add_sandbox_key`, `remove_sandbox_key`	Ajoute ou retire une clé SSH du compte	`sandbox:write`
`list_sandbox_secrets`	Noms des secrets du compte (jamais les valeurs)	`sandbox:read`
`set_sandbox_secret`, `delete_sandbox_secret`	Crée, remplace ou supprime un secret du compte	`sandbox:write`
`keep_sandbox`	Transforme une sandbox du compte en VPS (commande + facture)	`orders:write`
`claim_sandbox`	Rattache au compte une sandbox créée avec `ssh yorkhost.sh` (lien ou jeton `yhsc_…`) et la transforme en VPS	`orders:write`
`list_products`	Produits commandables par API, prix par cycle, plafond de dépense et offres de sandbox	`services:read`
`create_order`	Commande un produit du catalogue (crée une vraie facture)	`orders:write`
`get_payment_link`	Statut d'une facture et, si elle est impayée, lien vers la page de paiement sécurisée	`billing:read`

Le serveur MCP ne montre à l'assistant que les outils permis par la clé ou l'autorisation accordée. Les outils de commande exigent toujours un préflight et votre validation (voir plus bas).

Endpoints REST

Base : https://api.yorkhost.fr, en-tête Authorization: Bearer <clé>.

Méthode et route	Rôle	Permission
`GET /client/v1/sandboxes`	Sandboxes actives du compte et offres disponibles	`sandbox:read`
`GET /client/v1/sandboxes/{id}`	Détail d'une sandbox	`sandbox:read`
`POST /client/v1/sandboxes`	Créer une sandbox (3 par minute et par clé)	`sandbox:write`
`DELETE /client/v1/sandboxes/{id}`	Supprimer une sandbox	`sandbox:write`
`POST /client/v1/sandboxes/{id}/links`	Nouveau lien de bureau	`sandbox:write`
`POST /client/v1/sandboxes/{id}/exec`	Exécuter une commande (60 par minute et par compte)	`sandbox:write`
`GET /client/v1/sandboxes/{id}/files?path=&depth=`	Lister un dossier (120 lectures par minute et par compte)	`sandbox:read`
`GET /client/v1/sandboxes/{id}/files/content?path=`	Lire un fichier	`sandbox:read`
`PUT /client/v1/sandboxes/{id}/files/content`	Écrire un fichier	`sandbox:write`
`GET /client/v1/sandbox-keys`	Clés SSH du compte	`sandbox:read`
`POST /client/v1/sandbox-keys`	Ajouter une clé (`{"public_key": "…", "name": "…"}`)	`sandbox:write`
`DELETE /client/v1/sandbox-keys?fingerprint=SHA256:…`	Retirer une clé	`sandbox:write`
`GET /client/v1/sandbox-secrets`	Noms des secrets du compte	`sandbox:read`
`PUT /client/v1/sandbox-secrets/{nom}`	Créer ou remplacer un secret (`{"value": "…"}`)	`sandbox:write`
`DELETE /client/v1/sandbox-secrets/{nom}`	Supprimer un secret	`sandbox:write`
`POST /client/v1/sandboxes/{id}/keep`	Garder une sandbox du compte en VPS	`orders:write`
`POST /client/v1/sandboxes/claim`	Réclamer une sandbox `ssh yorkhost.sh` et la garder en VPS	`orders:write`
`GET /client/v1/catalog`	Catalogue, plafond journalier (`daily_cap_eur`), offres de sandbox	`services:read`
`POST /client/v1/orders`	Commander un produit (5 par minute et par clé)	`orders:write`
`GET /client/v1/invoices/{id}/payment-link`	Statut et lien de paiement d'une facture	`billing:read`

L'identifiant d'une sandbox a la forme sbx suivi de 12 caractères (sbxabcd2345efgh).

Créer une sandbox

curl -X POST https://api.yorkhost.fr/client/v1/sandboxes \
  -H "Authorization: Bearer yhk_client_v1_..." \
  -H "Content-Type: application/json" \
  -d '{"kind": "linux", "ssh_public_key": "ssh-ed25519 AAAA... moi@portable"}'

Réponse 201 :

{
  "sandbox": {
    "id": "sbxabcd2345efgh",
    "kind": "linux",
    "status": "running",
    "ssh": "ssh sbxabcd2345efgh@yorkhost.sh",
    "preview_url": "https://sbxabcd2345efgh-8080.yorkhost.sh",
    "created_at": "2026-09-27T13:32:00Z",
    "run_until": "2026-09-27T15:32:00Z",
    "claim_until": "2026-09-28T13:32:00Z"
  },
  "secrets_injected": 2,
  "message": "Connect with the SSH key you provided (or any SSH key registered on the account with add_sandbox_key): ssh sbxabcd2345efgh@yorkhost.sh …"
}

Connectez-vous avec l'identifiant

Pour une sandbox créée par API ou MCP, utilisez toujours la commande renvoyée, ssh <id>@yorkhost.sh, avec la clé fournie à la création ou une clé enregistrée sur le compte. Un simple ssh yorkhost.sh créerait une autre sandbox, anonyme cette fois.

secrets_injected indique combien de secrets du compte ont été injectés ; un champ warnings apparaît si un réglage du compte n'a pas pu être appliqué (la sandbox est livrée quand même).

Seul le type linux est ouvert pour le moment ; les types desktop (bureau Linux) et windows (bureau Windows) répondent 400 kind_unavailable en attendant leur ouverture.

Travailler dans la sandbox sans SSH

Les assistants connectés par le web (Claude.ai, ChatGPT…) créent des sandboxes mais ne peuvent pas ouvrir de session SSH. Quatre outils leur permettent d'y travailler quand même :

Outil	Ce qu'il fait
`sandbox_exec`	Lance `command` avec `bash -lc` et renvoie `exit_code`, `stdout`, `stderr`, `timed_out`, `duration_ms`. Options : `cwd`, `timeout_seconds`, `stdin`.
`sandbox_list_files`	Liste `path` (par défaut `/home/agent`), sur 1 à 3 niveaux (`depth`), 1 000 entrées au plus.
`sandbox_read_file`	Renvoie le contenu de `path` : texte, ou base64 pour un fichier binaire.
`sandbox_write_file`	Crée ou remplace `path` (dossiers parents créés), texte ou base64, avec des droits optionnels (`mode`, ex. `755`).

Les règles :

Tout s'exécute sous l'utilisateur agent, comme en SSH (sudo sans mot de passe disponible pour apt-get, etc.).
La sandbox doit être en cours (409 not_running si elle est arrêtée ou en passage en VPS) et appartenir au compte. Pas de sandbox Windows.
Chemins sous /home/agent ou /tmp (un chemin relatif part de /home/agent).
Délai : 60 s par défaut, 300 s au plus ; la commande et ses processus enfants sont arrêtés à l'échéance.
Tailles : stdout et stderr coupés au-delà de 256 Kio chacun (stdout_truncated, stderr_truncated) ; fichiers de 1 Mio au plus en lecture comme en écriture.
Débit : 4 commandes simultanées par sandbox, 60 commandes ou écritures et 120 lectures par minute et par compte.

Pour un serveur de dev ou une tâche longue, lancez-la en arrière-plan en redirigeant ses sorties, puis lisez le journal :

nohup npm run dev -- --host 0.0.0.0 --port 8080 > /tmp/dev.log 2>&1 &

Sans redirection, la commande attend jusqu'au délai. Testez ensuite l'application avec curl localhost:8080 ou sur sa preview.

Clés SSH du compte

Enregistrez jusqu'à 10 clés SSH publiques (ed25519, ECDSA ou RSA ≥ 2048 bits) sur votre compte, avec add_sandbox_key ou POST /client/v1/sandbox-keys :

chacune ouvre toutes les sandboxes du compte, y compris celles créées avant son ajout : ssh <id>@yorkhost.sh ;
elles sont aussi ajoutées dans les sandboxes créées ensuite, à côté de la clé fournie à la création ;
une clé retirée (remove_sandbox_key, avec son empreinte SHA256:…) n'est plus acceptée.

Pratique pour rejoindre depuis votre ordinateur une sandbox créée par un assistant. Sans identifiant (ssh yorkhost.sh), une clé du compte ouvre toujours sa propre sandbox anonyme, pas celles du compte.

Uniquement la clé publique

Envoyez le contenu du fichier .pub. Une clé privée collée par erreur est refusée et n'est jamais enregistrée.

Secrets du compte

Les secrets sont des variables d'environnement (ANTHROPIC_API_KEY, OPENAI_API_KEY, GITHUB_TOKEN…) injectées automatiquement dans chaque nouvelle sandbox Linux du compte : les agents préinstallés et vos outils les trouvent sans que vous ayez à les retaper.

Création ou remplacement : set_sandbox_secret ou PUT /client/v1/sandbox-secrets/{nom}. Nom en majuscules (A-Z, 0-9, _), valeur de 4 Kio au plus, 20 secrets par compte.
Chiffrés chez YorkHost et jamais réaffichés : l'API et le MCP ne renvoient que les noms et les dates.
Dans la sandbox, ils sont écrits dans ~/.config/yorkhost/env (lisible par agent seul) et chargés par le shell, y compris pour ssh <id>@yorkhost.sh 'commande' et sandbox_exec.
Un secret modifié ou supprimé vaut pour les sandboxes créées ensuite ; celles qui existent gardent leur fichier jusqu'à leur suppression.
Pour faire tourner du code dont vous n'êtes pas sûr, créez la sandbox avec inject_secrets: false.
Les sandboxes sans compte (ssh yorkhost.sh) ne reçoivent jamais les secrets, même réclamées ensuite.

Des clés dédiées

Tout programme lancé dans la sandbox peut lire ces variables. Préférez des clés dédiées, avec un plafond de dépense et des droits limités, et ne donnez à un assistant que des secrets que vous avez choisis pour cet usage.

Confirmation des commandes

keep_sandbox, claim_sandbox et create_order dépensent votre argent. Aucune commande ne peut être passée en un seul appel : le prix est toujours obtenu d'abord, et les instructions du serveur MCP demandent à l'assistant de vous le montrer et d'attendre votre accord.

Préflight : l'appel sans confirmation_token ne commande rien. Il renvoie le produit, le prix, le cycle et un confirmation_token.
Votre accord : l'agent vous montre le prix et attend votre validation explicite.
Confirmation : le même appel, avec confirmation_token, passe la commande et crée la facture.

# 1. Préflight : rien n'est commandé
curl -X POST https://api.yorkhost.fr/client/v1/sandboxes/sbxabcd2345efgh/keep \
  -H "Authorization: Bearer yhk_client_v1_..." -H "Content-Type: application/json" -d '{}'

{
  "preflight": true,
  "sandbox_id": "sbxabcd2345efgh",
  "kind": "linux",
  "product_id": 123,
  "cycle": "m",
  "price": 3.99,
  "currency": "EUR",
  "recurring": true,
  "confirmation_token": "1790000000.4f1c…",
  "expires_in": 600,
  "message": "Nothing was ordered. …"
}

# 2. Après votre accord : confirmation
curl -X POST https://api.yorkhost.fr/client/v1/sandboxes/sbxabcd2345efgh/keep \
  -H "Authorization: Bearer yhk_client_v1_..." -H "Content-Type: application/json" \
  -d '{"confirmation_token": "1790000000.4f1c…"}'

Réponse 201 : order_id, invoice_id, total, currency, invoice_status (unpaid ou paid si le crédit du compte a couvert la facture) et, si elle est impayée, payment_url à ouvrir pour payer.

Pour une sandbox créée avec ssh yorkhost.sh, le principe est identique avec POST /client/v1/sandboxes/claim et le corps {"claim_token": "yhsc_…"} (le lien complet de réclamation est aussi accepté), puis {"claim_token": "yhsc_…", "confirmation_token": "…"}.

Les garde-fous :

Jeton de confirmation valable 10 minutes, lié à la clé qui a fait le préflight, au produit ou à la sandbox, au cycle et au prix : si le prix change, il faut refaire le préflight.
Usage unique : rejouer une confirmation (après un timeout par exemple) ne commande jamais deux fois.
Plafond de dépense journalier par compte pour les commandes passées par API ou MCP (100 € par défaut ; la valeur est donnée par daily_cap_eur du catalogue). Au-delà, commandez depuis l'espace client.
Liste blanche : seuls les produits renvoyés par list_products peuvent être commandés par create_order.
Paiement hors conversation : la facture se règle sur la page sécurisée YorkHost (payment_url). Ne communiquez jamais vos données de carte à un agent.

Erreurs

HTTP	`code`	Cause
400	`bad_public_key`	Clé SSH absente ou invalide (ed25519, ECDSA ou RSA ≥ 2048 attendue), ou clé privée envoyée
400	`kind_unavailable`	Type de sandbox non ouvert, ou sandbox non convertible en VPS
400	`bad_request`	Commande, dossier, chemin (hors `/home/agent` et `/tmp`), profondeur ou droits invalides
400	`bad_secret_name`, `bad_secret_value`	Nom de secret invalide ou réservé, valeur trop longue
403	`permission_denied`	Fichier inaccessible à l'utilisateur `agent`
404	`not_found`	Sandbox inconnue ou appartenant à un autre compte
404	`file_not_found`	Fichier introuvable dans la sandbox
409	`billed_service`	Suppression impossible : la sandbox est en cours de passage en VPS (annulez la commande ou le service)
409	`not_running`	Commande ou fichier refusé : la sandbox est arrêtée, démarre encore ou passe en VPS
409	`key_exists`, `limit_reached`	Clé déjà enregistrée, ou 10 clés / 20 secrets atteints
413	`too_large`	Fichier de plus de 1 Mio
422	`file_error`	Le chemin n'est pas un fichier (ou pas un dossier pour un listing)
409	`not_claimable`	Sandbox déjà réclamée, expirée ou plus convertible
409	`quote_invalid`	Jeton de confirmation expiré ou ne correspondant plus (prix changé) : refaites le préflight
409	`already_ordered`	Confirmation déjà utilisée : la commande existe, vérifiez vos factures
403	`spend_cap`	Plafond de dépense journalier atteint
429	`sandbox_quota`	Trop de sandboxes actives sur le compte (3) : supprimez-en ou gardez-en une
429	`busy`	4 commandes tournent déjà dans cette sandbox : attendez qu'une se termine
502	`provision_failed`	La sandbox n'a pas pu être créée, rien n'est facturé : réessayez dans quelques minutes
503	`capacity`	Capacité momentanément atteinte ou créations suspendues : réessayez plus tard
503	`guest_unavailable`	La sandbox ne répond pas encore aux commandes : réessayez dans quelques secondes
503	`secrets_disabled`	Secrets du compte momentanément indisponibles
503	`order_unavailable`	Commandes temporairement indisponibles

Les erreurs suivent le format {"error": "...", "code": "..."} ; le message error est rédigé pour être relu tel quel par un agent.

Permissions nécessaires​

Outils MCP​

Endpoints REST​

Créer une sandbox​

Travailler dans la sandbox sans SSH​

Clés SSH du compte​

Secrets du compte​

Confirmation des commandes​

Erreurs​