Démarrage

Prérequis#

Docker, ou Node ≥ 22.12. Le fichier .nvmrc fixe la version 22.12, celle qu'utilise l'image node:22-slim. Le plancher est passé de 20 à 22 avec la passe de qualité : son détecteur exige Node 22.12+, et Node 20 est sorti du support en avril 2026.

Il n'y a ni base de données, ni module natif à compiler.

ffmpeg est le seul binaire externe, et il ne sert qu'à la vidéo au défilement. Sans lui, tout le reste fonctionne, et cette fonctionnalité-là se déclare indisponible au lieu d'échouer.

Installation#

git clone https://github.com/PetitOursManu/Mocky.gitcd Mockydocker compose up -d --build

npm installnpm run dev:all

npm run build          # tsc && vite build  →  dist/npm start              # Express sert dist/, l'API et le proxy sur :8787

Première utilisation#

Le bandeau est le même sur tous les écrans :

12345678910Agrandir

1Mocky1 / 10

Retour à vos projets, de partout.

PrécédentSuivant

1. Mocky Retour à vos projets, de partout.
2. Le projet ouvert Le projet où vous êtes. Son nom est aussi le titre de sa carte à la une sur la page des projets.
3. Accueil Vos projets, leurs dossiers, et Nouveau projet.
4. DESIGN.md Le système de design dont part chaque génération, en Markdown que vous pouvez modifier ou charger.
5. Média Toutes les images, clips et films générés ou importés.
6. Réglages Votre fournisseur de modèle, votre clé et votre modèle, votre compte, et le carillon de fin de génération.
7. Admin Le tableau de bord de l’instance. Visible des seuls administrateurs.
8. Docs Cette documentation, dans un nouvel onglet.
9. Thème Papier ou Encre. L’icône montre où vous allez, pas où vous êtes.
10. Compte Votre image et votre nom ; le menu vous déconnecte.

Le composeur, où l’on décrit un écran :

123456789Agrandir

1Format1 / 9

Mobile, Ordinateur ou Tablette pour un écran. Pour un document, les mêmes puces deviennent des formats de page.

PrécédentSuivant

1. Format Mobile, Ordinateur ou Tablette pour un écran. Pour un document, les mêmes puces deviennent des formats de page.
2. Type d’écran Le genre d’écran ou de document ; sa structure guide la génération. Il reste armé tant que vous ne le retirez pas.
3. Nouvelle direction Cette demande réécrit la direction artistique du projet. La case se décoche après l’écran.
4. Muse Inspiration, direction artistique, vrais textes et images pour le prochain écran.
5. Motion Ultra Un réglage de projet : un storyboard et une série d’images pour chaque nouvel écran.
6. Captures d’un site Joignez des captures d’un site existant pour le reproduire ou le refondre. Elles ne sont jamais conservées.
7. La demande Décrivez l’écran. Ctrl/⌘ + Entrée l’envoie.
8. Améliorer Réécrit vos quelques mots en un brief complet pour le format et le type choisis. Revenir à votre texte l’annule.
9. Générer Crée l’écran — ou Mettre à jour quand des écrans sont sélectionnés.

Un projet garde une seule direction de design, pour que ses écrans aient l’air d’un produit et non de cinq esquisses. Elle est fixée par le premier écran généré, puis laissée tranquille. Nouvelle direction est l’exception : cochez la case et la demande que vous vous apprêtez à envoyer réécrit la direction pour tous les écrans suivants. Elle se décoche toute seule une fois cet écran généré — c’est un geste ponctuel, pas un mode.

Deux autres choses voyagent d’un écran à l’autre sans qu’on ait à le demander : le nom du produit et son logo. Une direction décrit une palette et une voix, donc rien en elle n’empêchait un deuxième écran d’inventer une deuxième marque — c’est précisément ce qui arrivait, jusqu’à ce que le premier écran soit montré au modèle comme l’identité à respecter. La navigation, les sections et la mise en page restent libres ; épinglez un écran comme référence de mise en page (clic droit sur un écran) si vous voulez les figer aussi.

Deux boutons de la barre de zoom naviguent à votre place. Tout afficher cadre tous les écrans et — c’est la partie qui mérite d’être connue — continue de le faire : ouvrez un panneau, redimensionnez la fenêtre, tournez une tablette, et le plan se recadre tout seul. Jusqu’à ce que vous vous déplaciez ou zoomiez à la main, geste qui vous rend la vue pour de bon. Zoomer sur le dernier écran saute vers celui que vous venez de générer, qui n’est pas forcément celui que vous avez sélectionné. Les deux sont dans L’interface, avec le reste de la barre.

L’accueil après une première génération :

123456Agrandir

1Navigation1 / 6

La même sur toutes les pages.

PrécédentSuivant

1. Navigation La même sur toutes les pages.
2. Thème Papier ou Encre, retenu par le navigateur.
3. Compte Connecté : vos projets vous suivent d’un appareil à l’autre.
4. Nouveau projet Un canevas vide, nommé d’après sa première demande.
5. Nouveau dossier Les dossiers sont des noms posés sur les projets ; glissez ou classez un projet pour en remplir un.
6. Le projet à la une Le plus récent, avec ses écrans. Ouvrir y entre ; les autres sont listés dessous, par dossier.

Les règles de compte#

Les trois chemins exigent désormais la même longueur. L'inscription publique acceptait six caractères — c'était le seul chemin qu'un attaquant peut atteindre sans session, et sur une instance vierge le compte qu'il crée est l'administrateur.

Les inscriptions publiques se ferment d'elles-mêmes une fois le premier compte créé. Un administrateur les rouvre depuis l'écran Admin s'il veut inviter quelqu'un.

Les mots de passe sont hachés avec scrypt (node:crypto) et comparés en temps constant. Changer un mot de passe révoque toutes les sessions, y compris celle en cours, qui reçoit immédiatement un jeton neuf.

Configurer un modèle de texte#

Il y a deux modes, et ils s'excluent. Le mode instance l'emporte toujours sur le mode navigateur.

Mode A — par navigateur (le défaut)#

Allez dans Réglages, choisissez un fournisseur, collez votre clé d'API, choisissez un modèle et cliquez sur Tester la connexion. La liste est groupée — les éditeurs de modèles (OpenAI, Anthropic, Google Gemini, Mistral, DeepSeek, xAI, Moonshot), les hébergeurs de modèles ouverts (Ollama Cloud, OpenRouter, Groq, Together, Fireworks, Cerebras, Hugging Face), et Compatible OpenAI pour tout le reste — et chacun remplit sa propre URL de base et un modèle par défaut. Ollama Cloud, sur https://ollama.com, est le défaut.

La clé est conservée dans le localStorage de ce navigateur, sous mocky.settings.v1. Elle n'est jamais écrite côté serveur. Elle traverse /__provider en en-tête Authorization, le temps de chaque requête.

12345Agrandir

1Fournisseur1 / 5

Seize, groupés : les éditeurs de modèles, les hébergeurs de modèles ouverts, et Compatible OpenAI pour le reste.

PrécédentSuivant

1. Fournisseur Seize, groupés : les éditeurs de modèles, les hébergeurs de modèles ouverts, et Compatible OpenAI pour le reste.
2. URL de base Remplie par le fournisseur. Ne la changez que pour votre propre serveur.
3. Clé d’API Gardée dans ce navigateur seulement, envoyée en jeton Bearer avec chaque requête.
4. Modèle Listé depuis le fournisseur une fois la clé saisie ; vous pouvez aussi taper un nom.
5. Tester la connexion Une petite requête qui dit si la clé et le modèle répondent.

Réglages. C’est le mode par navigateur : la clé ne quitte pas cette machine.

Ce mode proposait autrefois un seul fournisseur, Ollama Cloud — non pas parce que les autres ne pouvaient pas fonctionner, mais parce que le navigateur ne disait jamais au serveur quel dialecte parlait son endpoint. Il le dit maintenant (en-tête x-provider-kind), et src/lib/settings.ts offre la même liste que l'écran Admin, moins fal, dont l'authentification Key ne peut pas passer par l'en-tête Bearer qu'envoie un navigateur. Les deux listes sont tenues égales par tests/text-providers-mirror.test.js.

Plus bas sur la même page, Notification décide si Mocky vous prévient quand une génération se termine pendant que vous êtes dans un autre onglet :

12Agrandir

1Son de fin de génération1 / 2

Un carillon bref quand une génération se termine alors que Mocky n’est pas l’onglet affiché, plus grave si elle a échoué, et ✓ ou ⚠ dans le titre de l’onglet.

PrécédentSuivant

1. Son de fin de génération Un carillon bref quand une génération se termine alors que Mocky n’est pas l’onglet affiché, plus grave si elle a échoué, et ✓ ou ⚠ dans le titre de l’onglet.
2. Tester Le joue tout de suite, pour vérifier vos haut-parleurs.

Mode B — pour toute l'instance (administrateur)#

Allez dans Admin → Fournisseurs, section Modèles de texte. La clé est stockée sur le serveur, dans server/data/text-config.json. Elle est utilisée par tous les comptes, et les Réglages personnels de chacun sont alors ignorés.

server/text/config.js déclare seize fournisseurs.

123Agrandir

1Le tableau de bord1 / 3

Vue d’ensemble, activité en direct, utilisateurs, sessions, système, fournisseurs, journal d’audit, annonce, maintenance. Voir Le tableau de bord d’administration.

PrécédentSuivant

1. Le tableau de bord Vue d’ensemble, activité en direct, utilisateurs, sessions, système, fournisseurs, journal d’audit, annonce, maintenance. Voir Le tableau de bord d’administration.
2. Génération des écrans Un fournisseur choisi ici sert à tous les comptes, et les Réglages personnels sont ignorés. Aucun laisse chacun sur sa propre clé.
3. Muse — dossier de design Un second modèle facultatif, moins cher, pour Muse ; Aucun réutilise le modèle de génération.

Admin. Un modèle défini ici sert à tous les comptes, et les Réglages personnels de chacun sont alors ignorés.

openai-compatible couvre le reste — Qwen, Cohere, LM Studio, vLLM — tout ce qui expose l'API de chat d'OpenAI. Une URL de base qui finit déjà par une version (…/v1, ou …/v1beta/openai) est utilisée telle quelle ; les autres reçoivent /v1. C'est pour cela que l'URL que la documentation d'un éditeur vous dit de coller fonctionne telle que collée.

Le bloc Utilisation, sur le même écran#

Sous les deux colonnes de modèles, en pleine largeur, se trouve Utilisation — une ligne par compte, avec une barre. Pleine largeur plutôt que glissé dans la liste des comptes, parce qu'une ligne avec une barre a besoin de la largeur pour rester lisible aux tailles que la grille donne à une colonne.

Par compte : trois décomptes nommés — Projets, Écrans, Médias — et le total sur disque, aligné à droite. La barre sous la ligne porte le détail en infobulle : « {data} de projets · {media} de médias · {avatar} d'avatar ».

C'est une route à part, GET /api/admin/usage, et ce n'est pas un accident de découpage. La produire suppose d'analyser le blob de projets de chaque utilisateur — la seule chose que le serveur traite par ailleurs comme une chaîne opaque — et de parcourir un répertoire par séquence de défilement. Repliée dans la liste des comptes, elle ferait payer ce coût à quiconque ouvre l'onglet Admin, qu'il la regarde ou non.

Trois lectures méritent d'être connues avant d'agir sur ce tableau :

• « Données illisibles » en face d'un compte, et un tiret cadratin là où seraient ses décomptes de projets et d'écrans. Un blob qui ne s'analyse pas n'a pas zéro projet, et un zéro affirmé enverrait un administrateur chasser un problème qui est le sien. Les octets restent comptés ; seul le détail manque.
• « dont {n} supprimé(s) en attente de synchronisation » sous un décompte de projets. Les pierres tombales restent dans le blob pour qu'une suppression puisse voyager jusqu'aux autres appareils de l'utilisateur. Elles coûtent du stockage sans être des projets, ce qui est exactement le genre d'écart qui fait paraître un total faux.
• « Sans propriétaire », sur sa propre ligne en bas. Des médias déposés avant que la propriété ne soit enregistrée, ou appartenant à un compte supprimé. Ces octets sont réels et leur propriétaire est inconnu : ils sont donc rapportés à part, plutôt que devinés ou répartis sur tout le monde. Les médias étant dédupliqués, un fichier déposé par deux personnes est un seul fichier dont la taille est partagée entre elles — c'est ce qui fait que la colonne totalise ce que le volume contient réellement.

En haut à droite de l'en-tête de section, à côté du mot Utilisation, se trouve le total de l'instance rapporté à MOCKY_MAX_STORAGE_MB — ou « sans plafond » quand cette variable vaut 0. Voir le Déploiement.

Configurer OpenRouter#

1. Admin → Modèles de texte → profil Génération → OpenRouter.
2. URL de base : https://openrouter.ai/api. N'ajoutez pas /v1. La couche de traduction ajoute elle-même /v1/chat/completions, donc un /v1 en trop produit un 404 sur /v1/v1/chat/completions.
3. Clé d'API : votre valeur sk-or-…, envoyée en Authorization: Bearer ….
4. Modèle : l'identifiant OpenRouter complet, sous la forme vendeur/modèle. Par exemple openai/gpt-4o-mini, anthropic/claude-3.5-sonnet ou google/gemini-2.5-flash.
5. Cliquez sur Tester. Une vraie requête part, par la même couche de traduction que celle qu'utilise l'application.

Le test distingue trois échecs :

• une réponse HTTP non-2xx ;
• une réponse vide d'un modèle « reasoning » qui a dépensé son budget de jetons à réfléchir ;
• une réponse coupée, signalée par finish_reason: length.

Un HTTP 200 sans texte visible n'est pas un succès, et le test le dit. Ce modèle produirait des écrans vides.

Une erreur fréquente. Coller un identifiant de modèle d'images dans le champ texte. C'est facile avec fal, qui vend les deux sous une seule clé. Le fournisseur répond « is not a valid model ID », ce qui n'explique rien. looksLikeImageModel() reconnaît le motif — text-to-image, flux, seedream, sdxl, dall-e, veo, kling et similaires — et affiche un message qui nomme le problème.

Les deux profils de texte#

Le profil voyage dans un en-tête x-mocky-profile: inspiration. Tout le reste, y compris l'absence d'en-tête, vaut generation.

Laisser le profil inspiration vide le fait retomber sur generation, ce qui est le comportement d'origine à un seul modèle. Le dossier n'écrit pas de code : un modèle moins cher suffit généralement.

Les fichiers de configuration écrits avant l'existence des profils sont un objet plat. liftLegacy() les remonte dans generation à la lecture, clés comprises.

Ce que le proxy accepte#

/__provider ne relaie que deux sous-chemins :

export const ALLOWED_SUBPATHS = new Set(['/api/chat', '/api/tags'])

C'est une liste d'autorisation, pas un filtre. Avant qu'elle existe, un DELETE /__provider/api/delete portant {"name":"llama3"} atteignait l'Ollama configuré et supprimait un modèle. La réécriture du corps ne remplace que model, donc name passait intact.

Les redirections sont signalées, pas suivies (redirect: 'manual'). Une cible qui passe la protection SSRF puis répond 302 → http://169.254.169.254/… la contournerait sinon d'un seul pas.

Configurer la génération d'images#

Allez dans Admin → Génération d'images (Muse). Les clés sont stockées sur le serveur et ne repartent jamais vers le navigateur : publicView() remplace chacune par un booléen hasApiKey ou hasToken.

Le bouton Tester génère réellement une image jetable — une pomme rouge sur fond blanc, en 1024×1024 — et ne la range pas dans la bibliothèque.

Trois profils d'images#

Les trois métiers sont réellement différents, donc ils ont des réglages séparés.

content produit les images posées dans l'écran : visuel principal, produits, fonds. Il peut y en avoir plusieurs par écran, donc ce profil doit être rapide et bon marché. C'est le chemin d'origine, sans configuration, et Pollinations en est le défaut.

inspiration produit l'unique planche de direction artistique montrée au modèle. Elle doit convaincre, donc elle mérite un modèle plus lent et plus cher. Laisser son fournisseur vide le fait retomber sur content.

edit fait de l'image-vers-image : une image existante entre, une dérivée sort. C’est le profil des variantes de Motion Ultra. Facultatif comme inspiration, mais facultatif dans l'autre sens : le laisser vide ne retombe sur rien du tout, cela veut dire que l'image-vers-image est désactivée sur cette instance. Un modèle texte-vers-image à qui l'on donne une image source rendrait une image issue du seul texte, présentée comme une dérivée de la vôtre — et rien en aval ne saurait faire la différence. Emprunter la clé du profil content serait donc exactement le mensonge que ce profil existe pour empêcher.

Sa liste de fournisseurs est plus courte que les autres, et le panneau dit pourquoi : seuls fal, openai-image, cloudflare-workers-ai et sd-webui acceptent une image d'entrée. Pollinations ne le peut pas — son API prend une URL que ses serveurs vont chercher, or les images de Mocky ne sont servies que par votre instance. Les modèles par défaut diffèrent aussi de ceux du texte-vers-image (fal-ai/flux/dev/image-to-image, @cf/runwayml/stable-diffusion-v1-5-img2img) : hériter des autres livrerait un profil configuré pour échouer. Le bouton « Tester » envoie une vraie image source, parce qu'un test texte-vers-image réussit contre un modèle incapable d'éditer.

sd-webui est appelé par le serveur de Mocky et pointe par définition vers une adresse locale. Il contourne donc volontairement la protection SSRF appliquée aux URL non fiables. Seul un administrateur peut le régler.

Vidéo au défilement#

Deux prérequis indépendants. Admin → Génération d'images → Vidéo les signale séparément, parce qu'ils se réparent à des endroits complètement différents.

GET /api/videos/availability renvoie reason: 'no-provider' | 'no-key' | 'no-ffmpeg' | null, ordonné par ce qu'il faut corriger en premier.

Importer votre propre clip ne demande que ffmpeg : pas de fournisseur, pas de clé, aucun coût. Une instance qui n'a jamais configuré fal peut donc utiliser toute la fonctionnalité avec ses propres images.

Motion Ultra#

Une autre fonctionnalité que la précédente, et le singulier est ce qui permet de les distinguer dans le code : server/videos/ découpe des séquences au défilement, server/video/ fabrique des films. Celle-ci transforme des images de la médiathèque en .mp4.

Elle est désactivée par défaut, et son moteur de rendu n'est pas installé par défaut, ce qui relève de la licence plutôt que de la technique. Remotion est gratuit pour les particuliers, les organisations à but non lucratif et les sociétés jusqu'à trois salariés, et sa licence ne traite pas de la redistribution au sein d'un produit auto-hébergé — il vit donc dans une image séparée que personne ne construit par accident. Pourquoi toute la fonctionnalité est bâtie autour de cela est dans Motion Ultra.

Trois étapes, dans cet ordre.

1. Construire et lancer le worker. Depuis la racine du dépôt :

docker compose --profile video-export up -d --build

Sans --profile video-export, rien ici n'est construit, créé ni démarré, et docker compose up -d se comporte exactement comme avant. Construire cette image est le moment où la question de licence devient la vôtre : lisez d'abord https://www.remotion.dev/, et notez que le seuil compte les salariés de votre organisation, pas les comptes de cette instance.

2. L’activer dans Administration → Motion Ultra.

Le panneau sonde le worker et rapporte Disponible avec sa version, Injoignable, Non configuré, ou une adresse qu'il a refusée avant tout appel. Ce dernier cas mérite d'être lu attentivement : rien n'a été contacté, donc redémarrer le worker n'y changera rien — seuls http:// et https:// sont acceptés.

3. S'en servir. Plus → Motion Ultra dans un projet. Vingt scènes au plus, deux minutes au plus, et pas de son.

Les variantes — « Partir d'une image », dans ce panneau — sont la seule partie qui s'appuie sur un autre réglage. Avec un profil d'image « edit » configuré, ce sont de vraies dérivations de votre image ; sans lui, ce sont des sœurs nées du même texte, et le panneau le dit avant que les appels au fournisseur soient dépensés.

Serveurs MCP#

Les serveurs MCP locaux sont déclarés dans mocky.mcp.json, à la racine du dépôt, et lancés par le back-end en stdio. Le fichier livré en déclare un seul :

{  "mcpServers": {    "fetcher": {      "command": "npx",      "args": ["-y", "fetcher-mcp"],      "autoStart": false,      "role": "inspiration-fetch",      "idleTimeoutMs": 300000    }  }}

Le routeur associe des rôles sémantiques au serveur qui expose un outil correspondant, ce qui permet d'en changer sans toucher au code. La santé est rapportée par GET /api/mcp/status. Les détails sont dans la page moteur d'inspiration.

Un fichier absent ou invalide n'est jamais fatal. Il donne une liste de serveurs vide, et Muse retombe sur sa bibliothèque de patterns hors ligne.

Commandes d'entretien#

npm run backup           # → backups/mocky-YYYY-MM-DD-HHmm.zipnpm run backup -- <dir>  # écrire ailleursnpm run check:vendor     # vérifier les bundles copiés contre leurs empreintesnpm test                 # vitest run, la suite complètenpm run test:watch

npm run backup est du Node pur et réutilise l'écrivain ZIP sans dépendance du dépôt. Il se comporte donc identiquement sous Windows, macOS et Linux.

Pour une instance Docker, sortez d'abord les données du volume :

docker compose cp mocky:/app/server/data ./server/datanpm run backup

L'archive contient des empreintes de mots de passe et des jetons de session. backups/ est ignoré par git ; qu'il le reste.

Diagnostic#