Démarrer en 10 minutes
Créez votre espace, installez l'agent sur un serveur, déclarez une action et signez votre premier ordre. À la fin, rien ne pourra plus partir en production sans votre signature.
Prérequis
- Un serveur Linux (x86_64 ou arm64) avec un accès
sudo, Docker etcurl(ouwget). - Deux appareils capables de créer une passkey : un ordinateur (Windows Hello, Touch ID) et un téléphone (Face ID, empreinte).
- Un dépôt Git pour le projet, où placer
kantama.yaml.
1Créer l'espace et enregistrer deux passkeys
Créez votre espace depuis la page d'inscription. Kantama vous demande immédiatement une première passkey sur cet ordinateur, puis vous propose de lier votre téléphone en scannant un code.
Notez les codes de secours affichés une seule fois : chacun ouvre une seule session sans passkey, pour ajouter un appareil. Aucun ne signe d'ordre.
2Installer l'agent
Installez le binaire kantama sur le serveur, depuis kantama.app : le script télécharge la dernière version et vérifie son empreinte SHA-256 avant de l'installer (il s'arrête si elle diffère). Choisissez votre plateforme :
# Linux (x86_64 ou arm64) : télécharge le binaire, vérifie son SHA-256, l'installe dans /usr/local/bin curl -fsSL https://kantama.app/installer.sh | sh # une version précise : curl -fsSL https://kantama.app/installer.sh | KANTAMA_VERSION=1.0.0 sh
# Linux · téléchargement manuel (remplacez amd64 par arm64 si besoin) curl -fsSLO https://kantama.app/telecharger/dernier/kantama-linux-amd64 curl -fsSLO https://kantama.app/telecharger/dernier/SHA256SUMS sha256sum --check --ignore-missing SHA256SUMS # doit afficher « kantama-linux-amd64: OK » sudo install -m 755 kantama-linux-amd64 /usr/local/bin/kantama
# Windows (PowerShell) · téléchargement et empreinte Invoke-WebRequest https://kantama.app/telecharger/dernier/kantama-windows-amd64.exe -OutFile kantama.exe Get-FileHash .\kantama.exe -Algorithm SHA256 # à comparer à la ligne kantama-windows-amd64.exe de https://kantama.app/telecharger/dernier/SHA256SUMS
# Docker : aucune image de l'agent n'est publiée # l'agent tourne sur l'hôte et pilote Docker par la commande docker docker version --format "{{.Server.Version}}" # relevée à l'enrôlement docker compose version # services « compose » # puis installez le binaire Linux (onglet x86_64 ou arm64)
Rattachez ensuite le serveur avec le code à usage unique affiché dans la console (Agents › Ajouter un serveur), qui donne la commande complète. Le code ne sert qu'une fois et expire au bout de 15 minutes.
sudo kantama agent enroler --central https://kantama.app --code K7Q-4M2-XP9 Empreinte de cet agent : c41e 9a07 5d2f 7be0 Comparez-la avec celle affichée dans la console. Agent agt_4b92c7e15a3d0832 en attente d'approbation dans la console…
3Comparer l'empreinte
La console affiche l'empreinte reçue ; recopiez celle que l'agent a affichée sur le serveur. « Approuver avec ma passkey » ne s'active que si les deux sont identiques, caractère par caractère. L'agent reçoit alors sa liste de passkeys de confiance, l'affiche, et vous invite à lancer kantama agent connecter.
4Déclarer une première action
Ajoutez kantama.yaml à la racine du dépôt, puis lancez kantama agent connecter --central https://kantama.app --manifeste kantama.yaml. L'agent le lit au démarrage, et chaque action devient un formulaire signé dans la console.
# kantama.yaml · à la racine du dépôt version: 1 project: { name: cas-market } environments: [production, preproduction] services: - { name: api_core, kind: compose, compose: [infra/docker-compose.yml, infra/docker-compose.prod.yml] } actions: - id: escrow.release label: Débloquer un séquestre level: double irreversible: true environments: [production] params: - { name: delivery_id, type: int, required: true, min: 1 } - { name: reason, type: string, required: true, max_length: 200 } run: service: api_core command: [python, -m, app.ops.sequestres, release, --delivery, "{delivery_id}", --reason, "{reason}"]
5Préparer et signer le premier ordre
Dans Actions, choisissez « Débloquer un séquestre », remplissez le formulaire, puis relisez l'ordre : la commande exacte, l'effet attendu, le sceau. Signez avec Windows Hello, puis confirmez sur le téléphone en choisissant le nombre affiché par la console.
L'agent vérifie les deux signatures contre sa liste de confiance, exécute la commande, puis renvoie un reçu signé visible dans Activité.
Référence : kantama.yaml
Les clés principales reconnues par l'agent ; la liste complète est sur la page kantama.yaml. Les clés inconnues sont refusées à la lecture, pour qu'une faute de frappe ne passe jamais en silence.
| Clé | Type | Requis | Rôle | Exemple |
|---|---|---|---|---|
version | entier | oui | Toujours 1. | 1 |
project.name | texte | oui | Nom du projet dans votre espace : [a-z0-9][a-z0-9-]{1,62}. | cas-market |
environments | liste | oui | Au moins un environnement. Un nom qui commence par prod est protégé. | [production, preproduction] |
services[].name, kind | texte | oui | Ce que l'agent pilote : compose (un service existant) ou app (construit et déployé par l'agent). | api_core · compose |
actions[].id | texte | oui | Une action métier, domaine.verbe ; core. est réservé. L'identifiant devient le nom de l'ordre signé. | escrow.release |
actions[].label | texte | oui | Libellé montré dans la console et sur le téléphone. | Débloquer un séquestre |
actions[].level | single · double | oui | Une passkey, ou deux passkeys sur deux appareils distincts. | double |
actions[].environments | liste | non | Où l'action est permise ; absent : partout. | [production] |
actions[].irreversible | booléen | non | Effet qui ne se défait pas : affiché à la relecture ; sur le téléphone, il faut maintenir 1,5 s pour signer. | true |
params[].type | string · int · bool · choice | oui | Type vérifié par le central et par l'agent, avant toute exécution. | int |
params[].required | booléen | non | Champ obligatoire ; exigé pour un paramètre cité dans run.command. | true |
params[].min, max, max_length | nombre | non | Bornes d'un entier, longueur maximale d'un texte. | 200 |
params[].pattern, choices | texte · liste | non | Expression régulière ancrée ; valeurs permises d'un choice. | PAY-[0-9]{1,12} |
params[].unusual | objet | non | Garde « montant inhabituel » : au-delà de above ou de times_average × la moyenne des 30 derniers jours, il faut cocher « J'ai vérifié ce montant ». | {above: 5000000, times_average: 3} |
run.service, command | texte, argv | oui | Service où la commande s'exécute ; commande en argv, jamais de shell : {nom} occupe un élément entier. | api_core |
run.timeout | durée | non | 60 s par défaut, 30 min au plus. | 2m |
Les propositions de modification de la documentation ne sont pas encore ouvertes au public.