Déployer un AI Agent avec OpenShip : guide 2026

Un serveur Linux destiné à OpenShip doit disposer au minimum de 2 cœurs de processeur, 2 Go de mémoire vive et 20 Go de stockage, tandis que la documentation recommande davantage pour un usage confortable. (openship.io) Cela suffit pour comprendre le point essentiel : OpenShip peut prendre en charge un AI Agent conteneurisé, mais le déploiement doit suivre un ordre précis. Commencez par un service minimal, vérifiez sa construction et son redémarrage, ajoutez ensuite la base de données et les tâches en arrière-plan, puis validez le rollback avant d’ouvrir le service au public.

Planning recommandé cette semaine

Jour de préparation : identifier le type de processus, le port, les fichiers nécessaires et les dépendances externes.
Première session : publier uniquement l’API, une route de santé et un appel modèle contrôlé.
Session suivante : ajouter la persistance, le cache et les workers, sans modifier simultanément la logique métier.
Avant la mise en ligne : tester le domaine, les secrets, le redémarrage, les erreurs amont et le retour vers la dernière version saine.

Cet article s’adresse aux développeurs indépendants qui veulent rendre leur prototype accessible, aux petites équipes qui souhaitent déclencher les déploiements depuis un dépôt Git avec une possibilité de retour arrière, ainsi qu’aux ingénieurs AI SaaS qui hésitent entre un environnement de construction distant, un serveur cloud et un Mac distant.

Étape 1 : déterminer le modèle d’exécution de l’AI Agent

Le premier échec courant est trompeur : le prototype répond correctement en local, mais les conversations, les tâches planifiées ou les fichiers temporaires disparaissent dès que le processus est redémarré. Le problème ne vient pas forcément d’OpenShip ; il vient souvent d’un modèle d’exécution mal décrit.

Classez d’abord votre application dans l’une de ces catégories :

API Web : un serveur HTTP reçoit une requête, appelle un modèle, interroge éventuellement une base de données, puis renvoie une réponse.
Worker résident : un processus reste actif pour consommer une file de tâches, traiter des documents, générer de l’audio ou lancer des opérations longues.
Tâche planifiée : une commande s’exécute selon un calendrier, par exemple pour résumer des contenus, nettoyer des sessions ou synchroniser un catalogue.
Application composée de plusieurs services : l’API, le worker, le cache, la base de données et éventuellement le stockage objet communiquent sur un réseau privé.

La documentation officielle décrit OpenShip autour d’images et de conteneurs, avec des cibles cloud ou des serveurs contrôlés par l’équipe, ainsi que des journaux, des métriques et des déploiements réversibles. (openship.io) Il est donc prudent de considérer comme non acquis tout comportement propre à un environnement « serverless » : exécution interrompue après la réponse, système de fichiers temporaire, durée de vie variable du processus ou accès implicite à certains services.

Avant de continuer, vérifiez les éléments suivants :

le serveur écoute sur une variable de port fournie par l’environnement ;
la commande de démarrage ne dépend pas d’un chemin présent uniquement sur l’ordinateur local ;
les fichiers nécessaires à l’agent sont inclus dans l’image ou stockés dans un service persistant ;
les appels vers les modèles et les outils externes disposent d’un délai d’attente ;
un redémarrage ne détruit pas les données que l’application considère comme permanentes.

Attention : une mémoire de conversation conservée uniquement dans un fichier local ou dans la mémoire du processus n’est pas une persistance de production. Pour un agent audio, vidéo ou orienté design, les fichiers générés doivent être stockés dans un emplacement explicitement sauvegardé.

Étape 2 : choisir la source du code et la cible de déploiement

OpenShip accepte deux points de départ utiles pour un projet AI SaaS :

un dossier local contenant le code ;
un dépôt Git relié au projet.

Le dossier local convient à une première mise au point, notamment lorsque l’agent utilise des fichiers audio, des modèles de test ou des outils internes encore absents du dépôt. Le dépôt Git devient préférable dès que plusieurs personnes interviennent, car il permet d’associer chaque déploiement à un état identifiable du code.

La documentation de démarrage indique le flux suivant :

cd chemin/vers/le-projet
openship init
openship deploy

Ces commandes servent à initialiser le projet et à lancer un premier déploiement ; OpenShip peut détecter plusieurs environnements courants, notamment Node, Python et Go. (openship.io) Les noms de dépôt, les domaines, les adresses IP et les secrets doivent toutefois rester des variables ou des valeurs fictives dans les exemples de documentation interne.

Avant de construire, choisissez la cible :

poste local : adapté à l’expérimentation et aux aperçus ;
service cloud : utile si l’équipe ne veut pas administrer le serveur de production ;
serveur détenu par l’équipe : pertinent pour garder la maîtrise du réseau, des données et du stockage ;
Mac distant comme poste de contrôle : pratique lorsqu’il faut conserver un environnement macOS stable pour développer, tester ou superviser, mais il ne remplace pas automatiquement la cible Linux prévue pour le service.

La documentation d’OpenShip distingue le lieu où l’image est construite de la machine qui sert le trafic. Son modèle vise à éviter que le serveur de production compile chaque version directement, ce qui réduit le risque de bloquer le service pendant une construction lourde. (openship.io) Pour un agent qui traite de la vidéo, de l’audio ou des fichiers volumineux, vérifiez donc l’espace disque, la bande passante et les identifiants disponibles avant d’envoyer le premier artefact.

Étape 3 : publier une version minimale et vérifiable

Ne déployez pas immédiatement l’agent complet avec ses outils, ses intégrations, son système de mémoire et ses tâches asynchrones. La première version doit répondre à trois questions distinctes :

le conteneur se construit-il correctement ?
le service démarre-t-il et reste-t-il accessible ?
l’application peut-elle effectuer un appel modèle avec un secret correctement injecté ?

Un squelette d’API peut exposer une route de santé sans révéler de secret :

GET /health

{
  "status": "ok",
  "service": "agent-api",
  "model_key_configured": true
}

La valeur model_key_configured doit seulement indiquer que la variable existe. Elle ne doit jamais renvoyer la clé, sa longueur ou un extrait susceptible d’aider à la reconstituer.

Ajoutez ensuite une route de test limitée, par exemple :

POST /agent/test
{
  "message": "Répondre avec une phrase de contrôle."
}

Cette route doit appliquer un délai d’attente, journaliser un identifiant de requête et distinguer au moins les catégories suivantes :

erreur de configuration ;
dépassement du délai de l’API modèle ;
réponse invalide ;
erreur interne de l’application.

Lancez le déploiement, puis contrôlez dans cet ordre :

le journal de construction ;
l’état du service ;
l’URL d’aperçu ou le domaine temporaire ;
la route /health ;
la route d’appel modèle ;
le journal applicatif après une requête réussie et une requête volontairement invalide.

OpenShip met en avant la diffusion des journaux, les métriques et les retours vers des versions précédentes depuis ses interfaces de gestion. (openship.io) Cela reste différent d’une validation opérationnelle : l’équipe doit vérifier que les messages produits par son propre agent permettent effectivement de localiser une erreur.

Comparaison de la source de construction et de la cible

Option	Quand la choisir	Risque principal	Vérification indispensable
Dossier local vers serveur contrôlé	Prototype, test d’une branche, fichiers non encore publiés	Version difficile à reproduire	Archiver le commit ou l’empreinte de l’artefact
Dépôt Git vers OpenShip Cloud	Petite équipe, déploiement déclenché par poussée de code	Secret ou variable mal associé à l’environnement	Vérifier le commit, le journal et l’environnement utilisé
Dépôt Git vers serveur contrôlé	Données sensibles, réseau privé, contrôle de l’infrastructure	Responsabilité accrue pour les sauvegardes et mises à jour	Tester restauration, accès réseau et redémarrage
Mac distant comme poste de contrôle	Développement macOS, supervision, tests d’outils ou d’interfaces	Confondre le poste de travail avec la cible de production	Confirmer où l’image est construite et où le service s’exécute

Cette distinction évite une confusion fréquente : le contrôle du déploiement et l’hébergement de l’AI Agent sont deux fonctions différentes. Le choix d’un environnement distant dépend du cycle de développement, tandis que la cible doit être dimensionnée pour l’API, les workers, la base et les fichiers persistants.

Étape 4 : ajouter les secrets, la base de données et les workers

Une fois la version minimale validée, ajoutez les dépendances dans un ordre qui permet d’identifier la cause d’un incident.

1. Configurer les variables d’environnement

Utilisez des noms génériques :

MODEL_API_KEY=<secret-modele>
DATABASE_URL=<url-base-de-donnees>
REDIS_URL=<url-cache>
AGENT_ENV=production

La clé d’API du modèle ne doit pas figurer dans le dépôt, dans un fichier de construction versionné, dans une commande shell copiée dans les journaux ou dans une capture d’écran. OpenShip présente un coffre de secrets chiffré et des variables liées à l’environnement ; la documentation MCP recommande également des jetons limités aux ressources nécessaires lorsqu’un agent pilote la plateforme. (openship.io)

2. Créer le schéma de données

La base doit être ajoutée avant les fonctions qui en dépendent : historique des conversations, comptes, tâches, facturation ou stockage des résultats. Préparez une commande de migration reproductible et notez si elle est exécutée au démarrage ou dans une étape séparée.

Ne considérez pas la base comme fiable uniquement parce que la première requête a fonctionné. Testez :

une nouvelle connexion après redémarrage ;
une migration sur une base vide ;
une migration sur une base contenant déjà une conversation ;
l’absence de données sensibles dans les journaux ;
la restauration d’un jeu de données de test.

3. Ajouter le cache et les tâches asynchrones

Redis ou un service équivalent peut servir à limiter les doublons, gérer les files d’attente ou conserver un état temporaire. Un worker doit disposer d’une commande de démarrage distincte si son cycle de vie n’est pas celui de l’API.

Pour un agent qui génère des vidéos, transcrit des fichiers audio ou construit des visuels, la file d’attente doit stocker un identifiant de tâche et un état, pas nécessairement le fichier complet. Les gros fichiers doivent être placés dans un stockage persistant adapté, avec une politique d’expiration et une procédure de récupération.

La page officielle d’OpenShip mentionne PostgreSQL, Redis, MongoDB, MySQL, les workers, les tâches planifiées et le stockage objet parmi les composants disponibles ou intégrables à la plateforme. (openship.io) La responsabilité de vérifier les sauvegardes, la conservation après redémarrage et la restauration reste néanmoins liée à la cible et au mode choisi.

Rappel d’exploitation : « le service démarre » ne signifie pas « les données sont protégées ». L’acceptation doit inclure un redémarrage, une création de donnée, une vérification après redémarrage et un scénario de restauration.

Étape 5 : connecter le domaine, HTTPS et les frontières d’accès

Lorsque l’API et ses dépendances fonctionnent, configurez le domaine public. Le contrôle doit couvrir à la fois le DNS, le routage et le port réellement exposé par l’application.

Procédez ainsi :

associez le domaine ou le sous-domaine au projet ;
vérifiez que le DNS pointe vers la cible attendue ;
confirmez que le certificat est émis et renouvelé automatiquement ;
appelez le domaine en HTTPS ;
vérifiez que les services internes ne sont pas directement accessibles depuis Internet ;
contrôlez les en-têtes, les limites de requêtes et les délais d’attente.

OpenShip indique gérer les domaines personnalisés, le routage et les certificats TLS automatiques dans son flux de déploiement. (openship.io) La vérification reste indispensable, surtout si l’agent expose des outils qui peuvent lire des documents, envoyer des messages ou déclencher une opération externe.

Séparez au minimum :

le domaine public de l’API ;
les interfaces d’administration ;
les endpoints internes entre services ;
les clés utilisées par l’application ;
les jetons utilisés par l’équipe ou par un client MCP.

Un agent de déploiement ne devrait pas recevoir un jeton donnant accès à tous les projets si un périmètre limité suffit. La documentation MCP d’OpenShip décrit des permissions par projet, serveur et dépôt ; ce principe doit être appliqué aux intégrations automatisées. (openship.io)

Étape 6 : organiser les journaux, les métriques et le rollback

Avant l’ouverture au public, provoquez volontairement trois incidents :

une indisponibilité ou un délai dépassé du fournisseur de modèle ;
une erreur de démarrage provoquée par une variable absente ;
un déploiement contenant une modification incorrecte de la réponse API.

Pour chaque incident, l’équipe doit pouvoir répondre à quatre questions :

quel déploiement était actif ?
quelle requête ou tâche a échoué ?
quel composant est responsable ?
quelle action permet de rétablir le service ?

Conservez dans les journaux :

un identifiant de requête ;
l’identifiant de tâche ;
le nom du service ;
le niveau d’erreur ;
la durée de l’opération ;
le code de réponse ;
une cause résumée sans données confidentielles.

Évitez d’écrire les en-têtes complets, les paramètres d’authentification, les prompts contenant des données personnelles et les réponses brutes si elles peuvent contenir des informations sensibles.

OpenShip décrit chaque déploiement comme une version immuable pouvant être restaurée, avec suivi des journaux et des métriques. (openship.io) Pour que cette capacité soit utile, testez réellement le retour arrière :

1. Déployer la version A.
2. Vérifier /health et une requête métier.
3. Déployer la version B avec une modification contrôlée.
4. Simuler une erreur.
5. Revenir à la version A.
6. Vérifier l’API, la base et un nouveau traitement asynchrone.

Le point sensible concerne les migrations de base. Une ancienne version de l’application peut ne pas comprendre un schéma modifié par la nouvelle version. Utilisez des migrations compatibles avec les deux versions lorsque cela est possible, ou documentez séparément la restauration du schéma et des données.

Liste de validation avant remise à l’équipe

[ ] Le modèle d’exécution est documenté : API, worker, tâche planifiée ou application composée.
[ ] Le port d’écoute et la commande de démarrage sont reproductibles.
[ ] La construction fonctionne depuis le dossier local et depuis le dépôt prévu.
[ ] La route de santé ne révèle aucun secret.
[ ] Un appel modèle contrôlé fonctionne avec la clé injectée par l’environnement.
[ ] La base survit à un redémarrage et une migration est documentée.
[ ] Les tâches asynchrones peuvent être relancées sans doublon dangereux.
[ ] Les fichiers audio, vidéo ou graphiques sont stockés hors du système temporaire.
[ ] Le domaine HTTPS répond et les services internes restent privés.
[ ] Les journaux permettent de retrouver une requête sans enregistrer de secret.
[ ] Le redémarrage de l’API, du worker et de la base a été vérifié.
[ ] Une ancienne version a été restaurée avec succès.
[ ] La responsabilité des sauvegardes et de la récupération des données est écrite.
[ ] Le commit, la version déployée et la procédure de rollback sont remis à l’équipe.

Questions fréquentes sur OpenShip et les AI Agents

Les points ci-dessous couvrent les décisions qui provoquent le plus souvent un déploiement incomplet : fichiers manquants, secrets exposés, services non persistants et retour arrière non testé.

Choisir un poste de construction et un environnement distant

OpenShip est adapté lorsque le projet reste un service conteneurisé classique, avec une commande de démarrage claire, des dépendances explicites et une séparation entre construction et exécution. Il devient moins prudent de l’utiliser sans vérification lorsque l’agent dépend d’un runtime propriétaire, d’un système de fichiers local permanent, d’un processus qui doit rester attaché à une session graphique ou d’un comportement serverless particulier.

Dans ce cas, l’équipe doit comparer le coût d’une cible cloud, d’un serveur contrôlé et d’un poste distant utilisé pour le développement. Un Mac distant peut être intéressant pour maintenir une chaîne de test macOS, travailler sur des outils audio et vidéo, contrôler une interface native ou permettre la collaboration à distance. Les offres de location de Mac mini aux États-Unis peuvent servir de piste pour ce poste de travail, tandis que la cible de production doit rester validée séparément.

Le déploiement d’un AI Agent avec OpenShip ne doit donc pas être jugé uniquement sur la première publication. Une chaîne fiable est celle qui prouve la construction, l’accès HTTPS, la persistance, le redémarrage et le retour vers une version saine.

Pour aller plus loin sur le choix d’un environnement macOS distant, consultez la présentation de Vuncloud et de ses environnements Mac. Si l’équipe doit clarifier un besoin de poste de développement, de contrôle ou de test isolé, elle peut également utiliser la page de contact Vuncloud.

Dans la pratique, une solution actuelle fondée sur un poste local non permanent ou sur un serveur configuré à la main présente trois limites réelles : la construction peut dépendre d’un environnement impossible à reproduire, les secrets peuvent finir dans des scripts ou des journaux, et la récupération après une erreur repose souvent sur une intervention manuelle. Pour un projet qui nécessite un poste macOS toujours disponible, des tests isolés ou une collaboration à distance pendant le cycle de déploiement, louer un environnement Mac auprès de Vuncloud peut offrir une organisation plus prévisible. Le bon choix reste toutefois conditionnel : pour une charge de production continue ou un besoin de périphériques physiques, une infrastructure dédiée demeure plus appropriée ; pour une période de développement, d’intégration et de validation, l’environnement loué peut éviter d’immobiliser une machine personnelle.