Guide de l’outil Shell et de l’API Files d’OpenRouter (bêta)

Le workflow Shell d’OpenRouter prend tout son sens lorsqu’un modèle doit lire un fichier, exécuter du code, analyser une erreur, puis renvoyer un artefact. Attention toutefois : openrouter:shell, les conteneurs et l’API Files sont encore en bêta. Mieux vaut donc commencer par un traitement bien délimité plutôt que de l’intégrer directement à un parcours critique en production.

En bref : dans quels cas utiliser Shell avec OpenRouter ?

openrouter:shell fournit à un modèle capable d’appeler des outils un environnement Linux hébergé. Le modèle peut y lancer des commandes, récupérer stdout, stderr et le code de sortie, puis corriger son travail. L’API Files sert de passerelle pour transmettre les fichiers d’entrée et récupérer les résultats.

C’est une bonne option si vous cherchez :

• Un agent indépendant du modèle, capable d’exécuter du code en dehors de votre serveur applicatif.
• Un traitement de fichiers reproductible, par exemple pour analyser un CSV, extraire le contenu d’un PDF ou générer un rapport.
• Une exécution d’outils côté serveur sans devoir construire votre propre sandbox au préalable.

Ne le considérez pas comme un simple remplacement d’un shell local. Le réseau est désactivé par défaut, les conteneurs ne sont pas persistants automatiquement et l’API peut encore évoluer pendant la bêta.

L’architecture à comprendre avant de se lancer

openrouter:bash est l’alternative compatible avec Anthropic. Par défaut, son chemin d’exécution demande à l’application de lancer les commandes localement ; définissez engine: "openrouter" pour imposer une exécution distante, comme l’explique l’annonce de Shell.

Le parcours d’un fichier dans le système

1. Envoyer le fichier et le joindre à la requête

Envoyez le fichier avec POST /api/v1/files au format multipart. La référence de l’envoi indique une taille maximale de 100 MB par fichier, ainsi qu’un paramètre de requête facultatif workspace_id.

curl -X POST https://openrouter.ai/api/v1/files \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -F "file=@data/sales.csv"

La réponse renvoie notamment l’identifiant du fichier, son nom, son type MIME, sa taille en octets, sa date de création et un indicateur downloadable. Ajoutez ensuite l’identifiant reçu au tableau file_ids de l’environnement Shell.

Les fichiers joints sont copiés dans le conteneur sous forme de copies accessibles en écriture. Un conteneur peut recevoir jusqu’à 20 fichiers joints, selon l’annonce de Shell. Modifier cette copie ne change pas le fichier original stocké dans l’espace de travail.

Un développeur a d’ailleurs salué l’arrivée de la prise en charge de l’API Files après avoir décrit les difficultés rencontrées auparavant avec les PDF et l’OCR. Ce retour, modeste mais concret, montre que la gestion des fichiers constituait bien un point de friction lors de l’intégration (publication).

2. Exécuter, vérifier, corriger

Le modèle envoie un lot de commandes au conteneur. Chaque appel renvoie la sortie et le statut d’exécution, ce qui lui permet de corriger un script défaillant au lieu de se baser uniquement sur la requête initiale (annonce de Shell).

Par défaut, la politique réseau bloque tout. Si le traitement doit télécharger des paquets ou effectuer des requêtes externes, configurez une liste d’autorisation lors de la création du conteneur. OpenRouter documente les ports 80 et 443 pour les hôtes autorisés ; cette politique ne peut plus être modifiée après le démarrage. Les requêtes vers des domaines absents de la liste peuvent échouer avec une erreur HTTP 520 (annonce de Shell).

Seuls les fichiers situés sous /workspace/home sont capturés dans les résultats Shell. Placez-y vos artefacts si vous voulez que l’API les signale. Les fichiers créés ou modifiés par Shell reçoivent des identifiants commençant par cfile_ (annonce de Shell).

3. Télécharger ou promouvoir le résultat

Un fichier produit par Shell peut être récupéré via le endpoint de contenu des fichiers du conteneur :

GET /api/v1/containers/{container_id}/files/{file_id}/content

L’identifiant cfile_ appartient au conteneur. Si l’artefact doit survivre à la durée de vie du conteneur, promouvez-le dans le stockage de l’espace de travail. Cette opération crée un nouvel identifiant or_file_, qui pourra être joint à un traitement ultérieur (annonce de Shell).

Les fichiers des conteneurs sont conservés pendant 30 jours. Promouvez tout ce qui doit être conservé plus longtemps (annonce de Shell). Le endpoint général de téléchargement renvoie les octets bruts et documente une erreur HTTP 400 pour les fichiers envoyés par l’utilisateur. Un fichier envoyé directement doit donc être considéré comme une entrée, pas comme un objet de stockage générique.

Les coûts et limites qui influencent vraiment la conception

L’annonce de Shell d’OpenRouter indique que le temps actif de la sandbox coûte $0.0001 par seconde. Un conteneur lancé à froid est facturé au minimum 30 secondes, soit un coût minimal de sandbox de $0.003 par calcul. La consommation de tokens est facturée séparément.

Réutilisez un conteneur encore actif pour les étapes liées, évitez les boucles inutiles entre le modèle et les outils, et consignez séparément le coût des tokens et celui de la sandbox. L’annonce précise que la vue Logs affiche l’activité du modèle et l’exécution de la sandbox sur deux lignes distinctes de la timeline.

Structure de requête de base

Le schéma exact de l’environnement peut évoluer pendant la bêta, mais le parcours documenté suit cette logique : envoyer d’abord le fichier, puis transmettre l’identifiant obtenu à une requête compatible avec Shell. Gardez l’adaptateur de requête minimal afin de pouvoir le mettre à jour si le schéma bêta change.

{
  "model": "your/tool-capable-model",
  "tools": [
    {
      "type": "openrouter:shell",
      "environment": {
        "type": "container_auto",
        "file_ids": ["or_file_your_uploaded_file_id"]
      }
    }
  ],
  "input": "Analyze the attached CSV and write a summary to /workspace/home/report.md"
}

Envoyez cette structure au endpoint Responses documenté dans l’annonce. Avant toute utilisation en production, vérifiez le schéma actuel des requêtes et les champs de réponse dans la documentation en ligne des outils serveur.

Pour une première intégration, procédez ainsi :

1. Envoyez un petit fichier d’entrée et notez l’identifiant renvoyé.
2. Créez une requête destinée à un modèle compatible avec les outils, en ajoutant openrouter:shell dans tools.
3. Joignez explicitement le fichier via file_ids.
4. Demandez au modèle d’écrire les résultats sous /workspace/home.
5. Vérifiez le code de sortie et la liste des fichiers avant de considérer le traitement comme réussi.
6. Téléchargez l’artefact du conteneur ou promouvez-le s’il doit être réutilisé.
7. Enregistrez séparément la consommation de tokens et la durée d’utilisation de la sandbox.

Pour un workflow composé de plusieurs requêtes, transmettez un session_id ou une référence explicite de conteneur. Sans cela, la requête suivante peut recevoir un conteneur vierge, dépourvu de l’état précédent.

Les premiers points de rupture — et comment les éviter

FAQ sur OpenRouter Shell et l’API Files

OpenRouter Shell exécute-t-il des commandes sur mon ordinateur ?

Non. openrouter:shell est conçu pour exécuter les commandes dans une sandbox hébergée par OpenRouter. La version compatible avec Anthropic, openrouter:bash, applique d’autres valeurs par défaut ; utilisez engine: "openrouter" pour une exécution distante (annonce de Shell).

Comment conserver des fichiers entre plusieurs requêtes ?

Réutilisez une session ou une référence de conteneur. Sans ce mécanisme de réutilisation explicite, la requête suivante peut démarrer dans un conteneur vierge.

Quelle différence entre or_file_ et cfile_ ?

or_file_ désigne un objet de l’API Files stocké dans l’espace de travail. cfile_ désigne un fichier créé ou modifié dans un conteneur. La promotion transforme un artefact du conteneur en un nouvel identifiant de fichier dans l’espace de travail.

L’API Files entraîne-t-elle des frais d’utilisation supplémentaires ?

L’annonce de Shell indique que l’utilisation de l’API Files n’entraîne pas de frais distincts, tandis que le stockage de l’espace de travail est limité à 10 GiB. Le temps de sandbox et la consommation de tokens du modèle restent facturés selon les tarifs applicables.

L’outil Shell est-il prêt pour la production ?

Il est documenté comme étant en bêta et l’annonce précise que l’API peut évoluer. Avant de l’intégrer à un workflow de production sans supervision, prévoyez des limites explicites, des commandes bornées, des restrictions au niveau de l’application et une solution de repli.

À choisir si votre workflow produit un véritable artefact

Shell et l’API Files d’OpenRouter s’intègrent bien à un pipeline par étapes qui produit un CSV nettoyé, un rapport, une image transformée ou un artefact compilé. Utilisez des identifiants de fichiers explicites, une politique réseau définie à l’avance, la réutilisation des conteneurs et la promotion pour les résultats durables.

Si la tâche consiste uniquement à générer une réponse textuelle, le coût supplémentaire de la sandbox et la gestion de son cycle de vie ne se justifient pas. Si elle nécessite des identifiants locaux, un accès réseau sans restriction ou de solides garanties de production, conservez l’exécution sur une infrastructure que vous contrôlez jusqu’à ce que la bêta soit suffisamment mature pour ce niveau de risque.

Sources : annonce OpenRouter sur Shell et l’API Files, référence de l’envoi via l’API Files, référence du téléchargement du contenu des fichiers.