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, retrouver leurs adresses, les supprimer ou les garder en VPS. Ce sont les mêmes sandboxes (mêmes durées, mêmes limites), mais rattachées à votre 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`, `GET /client/v1/sandboxes`
`sandbox:write`	Créer et supprimer des sandboxes agents	`create_sandbox`, `sandbox_links`, `delete_sandbox`
`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`)	`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`
`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}/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-27T14:32:00Z",
    "claim_until": "2026-09-28T13:32:00Z"
  },
  "message": "Connect with the SSH key you provided: 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. Un simple ssh yorkhost.sh créerait une autre sandbox, anonyme cette fois.

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.

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)
400	`kind_unavailable`	Type de sandbox non ouvert, ou sandbox non convertible en VPS
404	`not_found`	Sandbox inconnue ou appartenant à un autre compte
409	`billed_service`	Suppression impossible : la sandbox est en cours de passage en VPS (annulez la commande ou le service)
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 : supprimez-en ou gardez-en une
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	`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​

Confirmation des commandes​

Erreurs​