---
title: "Démarrage rapide Kodema : installer et lancer un pipeline"
description: "Installez Kodema en une commande, démarrez-le en local sur Podman, lancez un pipeline, approuvez une demande, démarrez une tâche et connectez un client MCP."
canonical_url: https://optimi.com/fr/docs/kodema/premiers-pas
md_url: https://optimi.com/fr/docs/kodema/premiers-pas.md
language: fr
alternates:
  - lang: en
    url: https://optimi.com/en/docs/kodema/getting-started
    md_url: https://optimi.com/en/docs/kodema/getting-started.md
last_updated: 2026-11-14
---

# Démarrage rapide

`kodema up` démarre un Kodema complet sur une seule machine, et `kodactl run` y
exécute un fichier de pipeline. C’est le moyen le plus court d’essayer
Kodema 0.2.1.

Ce n’est **pas une installation de production** : un seul hôte, un fichier de
clés local et une connexion intégrée qui ne demande aucun mot de passe. Pour la
production, lisez **[Exploitation](/fr/docs/kodema/exploitation)**.

## Avant de commencer

- **Linux avec Podman 5 ou plus récent en mode rootless**, et son socket d’API
  utilisateur : `systemctl --user enable --now podman.socket`, et `podman info`
  réussit.
- **`curl` et `tar`**, pour l’installateur.
- **Le port 8443 libre.**

Docker n’est pas pris en charge, car Kodema démarre les charges de travail par
l’API de Podman. macOS avec une machine Podman devrait fonctionner et n’a pas
été essayé.

## Installer et démarrer

```sh
curl -fsSL https://raw.githubusercontent.com/optimiware/kodema/master/install.sh | sh
kodema up
source ~/.kodema/instances/default/env.sh
kodactl whoami
```

L’installateur place `kodema` et `kodactl` dans `~/.local/bin`, qui doit
figurer dans votre `PATH`. Il télécharge les deux archives de la dernière
version pour votre système d’exploitation et votre architecture, et n’installe
rien si elles ne correspondent pas toutes deux au fichier `SHA256SUMS` de la
version. Relancez-le pour effectuer une mise à niveau.

| Variable de l’installateur | Effet |
| --- | --- |
| `KODEMA_VERSION` | Installer une autre version (0.2.1 ou plus récente) au lieu de la dernière |
| `KODEMA_INSTALL_DIR` | Installer dans un autre répertoire que `~/.local/bin` |

`kodema up` télécharge l’image de conteneur de sa propre version et peut être
relancé sans risque. Cette commande :

1. Démarre PostgreSQL, NATS, le serveur Kodema et le service Git sous forme de
   conteneurs, ainsi qu’une passerelle sur `https://127.0.0.1:8443` qui sert
   l’API, MCP (`/mcp`), la connexion (`/auth/`) et Git (`/git/`).
2. Crée une autorité de certification locale et des certificats, le tenant
   `tenant-local` et le projet `project-local`.
3. Attribue aux quatre personas intégrés leurs rôles de projet : `admin` (tous
   les rôles), `engineer`, `reviewer` et `operator`.
4. Écrit `env.sh`, qui fait pointer `kodactl` vers cette installation en tant
   qu’`admin`.

Tout est conservé dans `~/.kodema/instances/default`. `kodactl whoami` doit
répondre avec les rôles `admin,engineer,reviewer,operator`.

## Lancer votre premier pipeline

Le runtime local ne télécharge jamais d’image. Téléchargez celle que le
pipeline désigne, et désignez-la par son empreinte :

```sh
podman pull docker.io/library/alpine:3.24@sha256:0f49f331d9212aff11b932863be4eb01cdf962969aa86dab7d1ee21ac6f5f52b

cat > hello.yaml <<'EOF'
actions:
  - name: hello
    image: docker.io/library/alpine@sha256:0f49f331d9212aff11b932863be4eb01cdf962969aa86dab7d1ee21ac6f5f52b
    timeout: 2m
    commands:
      - echo "hello from a Kodema workload"
EOF

kodactl run hello.yaml
```

```text
execution execution-… started
hello from a Kodema workload
execution execution-… succeeded
```

`kodactl run` démarre le fichier, attend la fin de l’exécution et affiche la
sortie de ses actions. La commande se termine avec le code 0 quand l’exécution
a réussi et 1 quand elle a échoué, avec la raison indiquée par le serveur. La
sortie apparaît à la fin de l’exécution, pas pendant son déroulement. Rien
n’est stocké : le YAML est envoyé directement dans la requête.

## Demander une approbation

Une action peut demander une décision à un rôle au lieu d’exécuter un
conteneur :

```sh
cat > review.yaml <<'EOF'
actions:
  - name: prepare
    image: docker.io/library/alpine@sha256:0f49f331d9212aff11b932863be4eb01cdf962969aa86dab7d1ee21ac6f5f52b
    timeout: 2m
    commands:
      - echo prepared
  - name: review
    request: role/reviewer
    subject:
      operation: local.approve
      resource: local-demo
    timeout: 10m
EOF

kodactl run review.yaml
```

`run` s’arrête lorsque l’exécution attend une personne, et nomme l’exécution.
Répondez-y depuis la boîte de réception :

```sh
kodactl inbox
kodactl approve <execution-id>      # or: kodactl reject <execution-id> --reason "…"
kodactl watch <execution-id>
kodactl logs <execution-id> --action prepare
```

Aucun conteneur ne s’exécute pendant que la demande attend. Après une
acceptation, l’exécution se poursuit avec son action suivante dans le même
espace de travail ; un rejet ou un délai dépassé la fait échouer.

## Enregistrer un pipeline et le démarrer depuis une tâche

Pour conserver un pipeline dans le projet et le démarrer depuis une tâche :

```sh
kodactl pipeline apply hello.yaml          # prints the pipeline id
kodactl task run --title "First task" --pipeline <pipeline-id>
kodactl task list
```

Une tâche conserve un titre, une conversation et l’historique de ses
exécutions. Elle est `done` lorsque son exécution courante réussit.

## Se connecter en tant que personne

`env.sh` utilise un jeton d’administrateur écrit par `kodema up`. Pour agir en
tant que l’un des personas, connectez-vous :

```sh
unset KODEMA_CREDENTIAL_FILE
kodactl login            # or: kodactl login --device, without a browser
kodactl whoami
```

La page de connexion propose les quatre personas et ne demande aucun mot de
passe. Elle ne répond qu’à cette machine.

L’administration des projets et des appartenances exige à la place le jeton
d’administrateur valable pour tout le tenant :

```sh
kodactl --credential-file "$KODEMA_TENANT_ADMIN_CREDENTIAL_FILE" member list
```

## Utiliser Git

Le dépôt d’administration du tenant est servi sous `/git/`. Authentifiez-vous
avec un fichier credential-store, jamais avec un argument :

```sh
creds=~/.kodema/instances/default/git-credentials
(
  umask 077
  printf 'protocol=https\nhost=127.0.0.1:8443\nusername=kodema\npassword=%s\n\n' \
    "$(cat ~/.kodema/instances/default/admin-token)" |
    git credential-store --file "$creds" store
)
git -c http.sslCAInfo="$KODEMA_CA_FILE" -c credential.helper="store --file=$creds" \
  clone https://127.0.0.1:8443/git/admin
```

Le dépôt d’administration contient `conf/git.conf`, les règles d’accès de tous
les dépôts du tenant. **[Concepts](/fr/docs/kodema/concepts)** les explique.

## Connecter un client MCP

```sh
kodactl mcp install claude --print     # or cursor, codex; without --print it writes the client’s config
```

Le client voit alors chaque opération de Kodema comme un outil. Consultez
**[API et MCP](/fr/docs/kodema/api)**.

## Exploiter l’installation locale

```sh
kodema status
kodema up              # again: renews the credentials below
kodema down            # stops it and keeps the state
kodema down --purge    # removes the containers, volumes and state
```

- Le jeton d’administrateur de `env.sh` dure 24 heures et l’identifiant du
  service Git 8 heures. Relancez `kodema up` pour renouveler les deux.
- `kodema up --name <name>` exécute une seconde installation ; donnez-lui un
  autre port `--listen`.

## Autres façons d’installer

**Sans le script.** Téléchargez les archives `kodema` et `kodactl`
correspondant à votre système ainsi que `SHA256SUMS` depuis la
[dernière version](https://github.com/optimiware/kodema/releases/latest), puis :

```sh
sha256sum --check --ignore-missing SHA256SUMS    # macOS: shasum -a 256 --check --ignore-missing SHA256SUMS
tar -xzf kodema_*.tar.gz && tar -xzf kodactl_*.tar.gz
install -m 0755 kodema_*/kodema kodactl_*/kodactl ~/.local/bin/
```

**Depuis une copie de travail du dépôt.** Avec Go (la version indiquée dans
`.go-version`), `git` et `make` :

```sh
git clone https://github.com/optimiware/kodema && cd kodema
make build image
bin/kodema up
source ~/.kodema/instances/default/env.sh
```

`make build` compile `bin/kodema` et `bin/kodactl`. `make image` construit
l’image de conteneur de la même version, qui est l’image que `kodema up`
démarre.

## Dépannage

| Symptôme | À vérifier |
| --- | --- |
| `kodema: command not found` après l’installateur | `~/.local/bin` ne figure pas dans votre `PATH` |
| `kodema up` refuse le moteur de conteneurs | Il lui faut Podman et il refuse un moteur Docker. Vérifiez `podman info` et le socket utilisateur |
| `kodema up` ne peut pas écouter | Le port 8443 est occupé. Libérez-le, ou démarrez avec une autre adresse `--listen` |
| L’exécution échoue dès son démarrage, en nommant une image | L’image est absente du stockage local de Podman. Téléchargez-la avec `podman pull`, par son empreinte |
| Une commande est lue comme un mapping | Une commande qui contient `: ` doit être mise entre guillemets en YAML |
| `kodactl` répond `unauthenticated` au bout d’un jour | Le jeton d’administrateur a expiré. Relancez `kodema up`, puis exécutez `source` sur `env.sh` |
| `kodactl run` se termine avec le code 1 sans échec | L’exécution attend sur une demande. Utilisez `kodactl inbox` et `kodactl approve` |
| Aucune sortie pendant qu’une action longue s’exécute | `kodactl run` affiche la sortie d’une charge de travail à la fin de l’exécution |

## Limites de cette installation

- Un seul hôte, un seul tenant, un fichier de clés local. Toute personne
  pouvant utiliser cette machine peut se connecter sous n’importe quel persona.
- Sous Linux, la passerelle écoute sur toutes les adresses, car les conteneurs
  joignent l’hôte par son adresse externe. Elle refuse tout pair qui n’est pas
  cette machine : l’installation n’est donc pas joignable depuis un autre hôte.
- Podman uniquement, et `kodema up` n’a été exécuté que sous Linux.
- Le [bundle Podman](https://github.com/optimiware/kodema/blob/master/docs/runbooks/podman-quickstart.md)
  est une seconde installation à hôte unique, avec un fournisseur d’identité
  distinct. Le test de fumée de la version s’exécute dessus.

Ensuite : **[Concepts](/fr/docs/kodema/concepts)**, puis
**[Écrire des pipelines](/fr/docs/kodema/guide-developpeur)**.
