Nouveau · l'app mobile, second appareil pour relire et signer chaque ordre
kantamaSe connecterCréer un espace

kantama.yaml

kantama.yaml vit à la racine du dépôt du projet. Il déclare ce que la console peut faire, et l'agent refuse tout ce qui n'y figure pas. Clés en anglais, valeurs libres.

6 minutesMis à jour le 18 novembre 2026

Un exemple complet

kantama.yaml
# Exemple : ce que CAS-MARKET déclarerait pour la console.
# Chaque action devient un formulaire dans l'espace du projet ; l'agent
# refuse tout ce qui n'est pas listé ici (ou dans le socle « core. »).
version: 1

project:
  name: cas-market
  label: CAS-MARKET

environments: [production, preproduction]

services:
  # compose : un fichier, ou plusieurs empilés dans l'ordre (« docker compose -f base -f prod »).
  - name: api_core
    kind: compose
    compose: [infra/docker-compose.yml, infra/docker-compose.prod.yml]
    health:
      http: https://api.casmarketgn.com/health
      expect: 200
  - name: api_payment
    kind: compose
    compose: [infra/docker-compose.yml, infra/docker-compose.prod.yml]
    health:
      http: https://api.casmarketgn.com/payment/health
      expect: 200

actions:
  - id: payments.reconcile
    label: Relancer la vérification d'un paiement
    description: Interroge le prestataire et met à jour un paiement resté en attente.
    level: single
    params:
      - name: reference
        label: Référence du paiement
        type: string
        required: true
        pattern: "PAY-[0-9]{1,12}"
    run:
      service: api_payment
      command: [python, -m, app.ops.paiements, reconcile, --reference, "{reference}"]
      timeout: 2m

  - id: escrow.release
    label: Débloquer un séquestre
    description: Libère les fonds d'une livraison bloquée vers le vendeur.
    level: double
    irreversible: true
    environments: [production]
    params:
      - name: delivery_id
        label: Livraison
        type: int
        required: true
        min: 1
      - name: amount
        label: Montant
        type: int
        required: true
        min: 1
        # Montant inhabituel : au-delà, la case « J'ai vérifié ce montant » fait partie de l'ordre signé.
        unusual: {above: 5000000, times_average: 3, unit: GNF}
      - name: reason
        label: Motif
        type: string
        required: true
        max_length: 200
    run:
      service: api_core
      command: [python, -m, app.ops.sequestres, release, --delivery, "{delivery_id}", --amount, "{amount}", --reason, "{reason}"]

  - id: withdrawals.reject
    label: Refuser un retrait
    level: single
    params:
      - name: withdrawal_id
        type: int
        required: true
        min: 1
      - name: motive
        type: choice
        required: true
        choices: [numero_invalide, fraude_suspectee, doublon]
    run:
      service: api_payment
      command: [python, -m, app.ops.retraits, reject, "{withdrawal_id}", "{motive}"]

# Lot J : une procédure, signée en un seul ordre ; l'agent exécute les étapes dans l'ordre et s'arrête à la
# première en échec. Un paramètre écrit ici est fixé ; les autres se choisissent à la préparation.
procedures:
  - id: rattrapage-paiements
    label: Rattrapage des paiements
    description: Redémarre le service de paiement, attend qu'il réponde, puis relance la vérification d'un paiement.
    environments: [production]
    steps:
      - action: core.service.restart
        params: {service: api_payment}
      - action: core.probe.check
        params: {service: api_payment, timeout: 120}
      - action: payments.reconcile     # la référence est choisie à la préparation

Clés de premier niveau

CléRequisRôle
versionouiToujours 1.
project.nameouiNom du projet : [a-z0-9][a-z0-9-]{1,62}.
project.labelnonLibellé affiché.
environmentsouiAu moins un environnement.
servicesnonCe que l'agent pilote.
actionsnonVos actions métier.
backupsnonSauvegardes faites sur le serveur (Sauvegardes testées).
jobsnonTâches planifiées que l'application signale (100 au plus).
connectorsnonPlateformes lues par l'agent (20 au plus).
proceduresnonSuites d'actions signées en un seul ordre, 50 au plus (Procédures).
driftnonOutil d'analyse des vulnérabilités déjà installé sur le serveur (Dérive).
sourcenonLe clone de travail d'un projet docker compose, déployé par un ordre signé (Déploiements).

services

CléRôle
name[a-z][a-z0-9_-]{0,62}, requis.
kindcompose : un service existant de votre docker-compose ; app : construit et déployé par l'agent.
composeVotre fichier docker-compose, ou la liste de vos fichiers (1 à 8, sans doublon) dans l'ordre où vous les empilez (docker compose -f base -f prod). Un chemin relatif part du dossier de kantama.yaml. L'agent passe chaque fichier, dans cet ordre, et prend le dossier du premier comme dossier du projet : il vise les mêmes conteneurs que vous à la main. Si un fichier manque, il ne lance rien.
health.http, health.expectSonde de santé appelée depuis le serveur toutes les 30 s ; code attendu, 200 par défaut.
health.dockerService compose : l'état de santé Docker du conteneur sert de sonde (son healthcheck), pour une API que votre frontal n'expose pas ; unhealthy ou arrêté = échec. L'un ou l'autre, jamais avec health.http.
buildService compose : il se reconstruit au déploiement (Déploiements). Exige le bloc source ; tous les services build partagent les mêmes fichiers compose et env_file.
deploy.repo, deploy.branchDépôt Git et branche : seuls les commits de cette branche sont déployables.
deploy.portPort du conteneur, requis.
deploy.context, deploy.dockerfileDossier de build (.) et Dockerfile (Dockerfile).
deploy.healthChemin du contrôle de santé avant la bascule (/up par défaut).
deploy.hosts, deploy.tlsDomaines par environnement ; certificat Let's Encrypt automatique.
deploy.env_fileChemin absolu d'un fichier de variables sur le serveur.
deploy.previewsPrévisualisations par branche : environment, host (avec {branch}), max (3), ttl (72h).

actions

CléRôle
iddomaine.verbe, 64 caractères au plus ; core. est réservé.
labelLibellé, requis.
descriptionTexte libre.
levelsingle (une passkey) ou double (deux passkeys distinctes), requis.
environmentsOù l'action est permise ; absent : partout.
irreversibleEffet qui ne se défait pas, affiché à la relecture.
signersNombre de membres distincts qui doivent signer, de 1 à 5 : un entier partout (signers: 2) ou par environnement (signers: {production: 2}). Vérifié par l'agent, en plus de level.
run.serviceService où la commande s'exécute, requis.
run.commandargv, jamais de shell. {nom} occupe un élément entier, et le paramètre doit être required.
run.timeoutDurée Go (90s, 2m), 60 s par défaut, 30 min au plus.

actions[].params

CléRôle
name[a-z][a-z0-9_]{0,31}, requis.
typestring, int, bool ou choice, requis.
label, requiredLibellé du champ ; champ obligatoire.
patternExpression régulière, ancrée automatiquement.
min, maxBornes d'un entier.
max_lengthLongueur maximale d'un texte (1 à 4 096).
choicesValeurs permises d'un choice.
unusualGarde « montant inhabituel » d'un entier : above (seuil), times_average (multiple de la moyenne des 30 derniers jours), unit.

backups et jobs

CléRôle
backups[].kindpostgres (pg_dump dans le service) ou files (path ou volume).
backups[].every, at, keepFréquence (1m à 744h), heure UTC, nombre gardé sur le serveur (7 par défaut).
backups[].test_every, checkRestauration d'essai planifiée ; requête témoin.
jobs[].every ou cronPériode, ou 5 champs cron en UTC.
jobs[].graceTolérance avant l'alerte (5m par défaut).

connectors

CléRôle
providervercel, cloudflare, supabase, eas ou github.
tokenLe nom de la variable qui porte le jeton, jamais sa valeur.
envEnvironnement où vit le jeton et où se signent les gestes.
project, team, zones, app, repo, workflowsCe que l'agent lit chez le fournisseur.
costsSource des coûts : api (Vercel), org:… ou user:… (GitHub) ; absent : saisis dans la console.

procedures

CléRôle
id[a-z][a-z0-9_-]{0,47}, unique, requis.
labelLibellé, requis (120 caractères au plus).
descriptionTexte libre (500 caractères au plus).
environmentsOù la procédure est permise ; absent : partout.
steps[].actionUne action de la liste fermée (déclarée ou du socle), de 1 à 10 étapes. Ni confiance, ni politique, ni état du projet, ni core.secrets.apply, ni action à unusual.
steps[].paramsParamètres fixés ; ceux qui manquent se choisissent à la préparation. Mêmes règles que les paramètres de l'action.

L'empreinte de chaque procédure s'affiche avec kantama agent manifeste kantama.yaml : c'est celle que l'ordre signé doit porter.

source

CléRôle
pathChemin absolu du clone de travail sur le serveur (/opt/cas-market), requis.
branchSeuls les commits de cette branche distante se déploient, requis ; le clone doit être dessus.
remoteDépôt distant (origin par défaut).
envEnvironnement où le déploiement se signe ; facultatif s'il n'y en a qu'un.
after_deployActions déclarées lancées après un déploiement sain, dans l'ordre (8 au plus) : sans paramètre, level: single, un seul membre, pas irreversible.
fetch_everyRécupération périodique de la branche, pour proposer les derniers commits : 5m par défaut, de 1m à 24h.
health_timeoutAttente maximale de l'état sain des services reconstruits : 5m par défaut, de 10s à 30m.

drift

CléRôle
scanner.tooltrivy ou grype, déjà installé sur le serveur, avec sa base de vulnérabilités. Requis si scanner est présent.
scanner.pathChemin absolu de l'exécutable ; absent : cherché dans le PATH.
scanner.everyIntervalle entre deux analyses d'une même image, de 1h à 744h (24h par défaut).

La surveillance de la dérive n'a besoin d'aucune clé : elle est toujours active. Ce bloc ne sert qu'à l'analyse des vulnérabilités, que l'agent fait hors ligne, sans jamais télécharger de base.

Cette page vous a-t-elle aidé ?Modifier cette page

Les propositions de modification de la documentation ne sont pas encore ouvertes au public.