Configuration du Raspberry Pi

Ce guide couvre l’installation et l’exécution de ZeroClaw sur Raspberry Pi.

Le runtime est suffisamment léger pour fonctionner confortablement sur n’importe quel Pi. La seule contrainte concerne la compilation depuis les sources sur l’appareil : l’éditeur de liens de Rust est gourmand en mémoire (la LTO complète peut provoquer un OOM sur une carte à faible RAM), donc le processus de compilation sur l’appareil nécessite du swap et un profil plus léger. La plupart des utilisateurs devraient utiliser le binaire précompilé et éviter tout cela.

Compatibilité matérielle

Tout Pi capable d’exécuter Raspberry Pi OS en 64 bits (aarch64) ou en 32 bits (armv7) peut exécuter le binaire précompilé ; il n’y a pas de seuil de mémoire significatif pour l’exécution. Les binaires Pi précompilés proviennent de ces cibles de publication (aarch64 64 bits pour Raspberry Pi OS 64 bits, armv7/arm 32 bits pour l’OS 32 bits) :

• aarch64-unknown-linux-gnu (64 bits)
• arm-unknown-linux-gnueabihf (32 bits)
• armv7-unknown-linux-gnueabihf (32 bits)

Option 1 : Binaire précompilé (recommandé)

Chemin le plus rapide. Pas de compilateur, pas de swap, aucun risque d’OOM.

Utilisation du script d’installation

Chemin rapide Unix

curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | sh

Cette route est non interactive et n’ouvre pas de sélecteur.

Il privilégie un binaire précompilé correspondant et se rabat sur une compilation à partir des sources si nécessaire.

Une archive précompilée peut contenir zerocode ; un repli non interactif vers les sources installe l’application par défaut sans ouvrir de sélecteur.

La commande utilise un ensemble de fonctionnalités fixe.

Si une compilation à partir des sources est nécessaire, l’installateur peut installer Rust automatiquement s’il est absent.

Sous Unix, le programme d’installation met à jour le profil du shell si cela est autorisé ; rechargez le shell parent avant de vous fier au nouveau PATH.

L’installateur ignore la configuration et affiche zeroclaw quickstart comme étape suivante.

Parcours guidé Unix

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./install.sh

Cette route est guidée et peut proposer des choix pris en charge.

Sur les cibles prises en charge, il propose une installation à partir de binaires précompilés ou une compilation depuis les sources.

Une archive précompilée peut contenir zerocode ; le choix de la source le sélectionne par défaut et permet de sélectionner l’application.

Le chemin source vous permet également de sélectionner des fonctionnalités Cargo facultatives.

Si une compilation à partir des sources est nécessaire, l’installateur peut installer Rust automatiquement s’il est absent.

Sous Unix, le programme d’installation met à jour le profil du shell si cela est autorisé ; rechargez le shell parent avant de vous fier au nouveau PATH.

Pour une installation non configurée, il propose zeroclaw quickstart ou le Quickstart dans le navigateur.

Le script détecte automatiquement votre architecture (aarch64, armv7 ou armv6) et installe le binaire de version correspondant dans $CARGO_HOME/bin/zeroclaw (par défaut ~/.cargo/bin/zeroclaw). Assurez-vous que ce répertoire figure dans votre PATH.

Lorsque le script compile depuis les sources au lieu d’utiliser un binaire précompilé, il adapte également la compilation à la mémoire disponible de la carte :

Lorsque install.sh compile à partir des sources sous Linux, il lit MemTotal depuis /proc/meminfo et, sur les hôtes disposant de moins de 12 GiB de RAM, exporte CARGO_PROFILE_RELEASE_LTO=thin avant la compilation. Le LTO complet (la valeur par défaut de [profile.release]) peut dépasser 7 GB de RSS au pic lors de la passe de typage inter-crates et provoquer un OOM sur une carte à faible RAM ; le LTO thin échange une légère augmentation de la taille du binaire contre un pic de mémoire de compilation bien plus faible.

L’option ne s’applique que si vous n’avez pas déjà épinglé la variable. Remplacez explicitement l’une ou l’autre direction :

# Forcer le LTO « fat » même sur un hôte avec peu de RAM (binaire plus petit, consommation de RAM accrue à la compilation)
export CARGO_PROFILE_RELEASE_LTO=fat

# Forcer le thin LTO sur un hôte à RAM élevée (réduit la RAM de compilation)
export CARGO_PROFILE_RELEASE_LTO=fin

Téléchargement manuel

Choisissez l’archive tarball correspondante dans la dernière version :

# 64 bits (Pi 4/5 avec Raspberry Pi OS 64 bits)
curl -LO https://github.com/zeroclaw-labs/zeroclaw/releases/latest/download/zeroclaw-aarch64-unknown-linux-gnu.tar.gz
tar xzf zeroclaw-aarch64-unknown-linux-gnu.tar.gz
sudo install -m 0755 zeroclaw /usr/local/bin/

# 32 bits (Pi Zero 2 W, anciens Pi 3 avec OS 32 bits)
curl -LO https://github.com/zeroclaw-labs/zeroclaw/releases/latest/download/zeroclaw-armv7-unknown-linux-gnueabihf.tar.gz
tar xzf zeroclaw-armv7-unknown-linux-gnueabihf.tar.gz
sudo install -m 0755 zeroclaw /usr/local/bin/

Vérifiez votre architecture

uname -m
# aarch64 → 64 bits (utilisez le binaire aarch64-unknown-linux-gnu)
# armv7l  → 32-bit (use the armv7-unknown-linux-gnueabihf binary)
# armv6l  → Pi 1 / Zero / Zero W (utiliser le binaire arm-unknown-linux-gnueabihf)

Option 2 : Compilation croisée depuis une autre machine

Si vous disposez déjà d’une machine plus puissante, la compilation croisée est plus rapide que la compilation sur le Pi.

# Installer la cible de compilation croisée
rustup target add aarch64-unknown-linux-gnu

# Installer une chaîne d'outils croisée GNU pour Linux — même schéma que celui utilisé dans le guide de l'Arduino Uno Q
brew tap messense/macos-cross-toolchains
brew install aarch64-unknown-linux-gnu

# Construire
CC_aarch64_unknown_linux_gnu=aarch64-unknown-linux-gnu-gcc \
CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-unknown-linux-gnu-gcc \
cargo build --release --target aarch64-unknown-linux-gnu

# Copy to your Pi
scp target/aarch64-unknown-linux-gnu/release/zeroclaw pi@raspberrypi:~/

# Installer la chaîne d'outils de compilation croisée
sudo apt-get install -y gcc-aarch64-linux-gnu

# Ajouter une cible
rustup target add aarch64-unknown-linux-gnu

# Configurer l'éditeur de liens
# [target.aarch64-unknown-linux-gnu]
# linker = "aarch64-linux-gnu-gcc"

# Construire
cargo build --release --target aarch64-unknown-linux-gnu

# Copier vers le Pi
scp target/aarch64-unknown-linux-gnu/release/zeroclaw pi@raspberrypi:~/

Option 3 : Compiler sur le Pi

L’agent se compile lui-même sur l’appareil. Fonctionne sur n’importe quel Pi avec du swap et le bon profil de compilation ; plus lent sur les cartes avec moins de RAM.

Étape 1 : Installer la chaîne d’outils Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Étape 2 : Ajouter le swap

Le Fat LTO atteint son pic de consommation lors de l’édition de liens finale ; sans swap, une carte à faible RAM déclenche un OOM-kill en pleine édition de liens.

# Créer un fichier d'échange de 4 Go
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Vérifier
free -h

# Rendre persistant après les redémarrages
echo /swapfile none swap sw 0 0 | sudo tee -a /etc/fstab

Étape 3 : Compilation

Choisissez un profil selon la RAM disponible. release utilise le fat LTO (meilleur binaire, édition de liens la plus lourde) ; release-fast augmente les codegen-units pour une édition de liens plus légère ; ci utilise le thin LTO pour l’édition de liens consommant le moins de mémoire. (install.sh le choisit automatiquement ; voir Using the install script.)

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw

cargo build --release           # carte avec plus de RAM
cargo build --profile release-fast   # Carte mid-RAM
cargo build --profile ci        # carte contrainte / à faible RAM

# Installez le binaire que vous avez compilé :
sudo install -m 0755 target/release/zeroclaw /usr/local/bin/
# (ou target/release-fast/zeroclaw, ou target/ci/zeroclaw)

Prise en charge GPIO

Pour piloter les GPIO du Pi depuis les skills, compilez avec le drapeau de fonctionnalité peripherals approprié. La plupart des charges de travail d’agent n’en ont pas besoin ; voir Peripherals design.

Déploiement conteneurisé (Podman recommandé plutôt que Docker)

Sur un Pi à mémoire limitée, le choix du runtime de conteneurs compte : tout ce que vous empilez aux côtés de ZeroClaw se dispute le même pool fixe, donc la mémoire non consacrée à l’infrastructure de conteneurs est de la mémoire dont bénéficie l’agent.

Pourquoi Podman plutôt que Docker sur un Pi :

1. Rootless par défaut. Pas de démon root ; les conteneurs s’exécutent sous votre utilisateur, ce qui est important sur un appareil edge exposé.
2. Natif systemd via Quadlets. Fichiers d’unité .container que systemd gère directement, sans docker.service ni couche de journalisation séparés.
3. Pas de démon persistant. Docker garde dockerd résident ; Podman ne le fait pas, libérant ainsi le plus gros bloc de mémoire sans perdre l’isolation.

Le compromis : le réseau rootless de Podman (slirp4netns/pasta) est plus lent que le bridge de Docker. Pour le modèle « un ou deux conteneurs d’agents de longue durée » de ZeroClaw, c’est négligeable, et les économies liées à l’absence de daemon dominent sur du matériel aux ressources limitées.

Installation rapide (Raspberry Pi OS Bookworm/Trixie)

sudo apt-get install -y podman
# Optionnel : alias plus courts — de nombreux flux docker-compose fonctionnent directement avec podman-compose
sudo apt-get install -y podman-compose

Exécuter ZeroClaw avec Podman

L’image OCI publiée fonctionne avec Podman sans modification :

podman pull ghcr.io/zeroclaw-labs/zeroclaw:latest

podman run --rm -d \
  --name zeroclaw \
  -p 42617:42617 \
  -v ~/.zeroclaw:/root/.zeroclaw \
  ghcr.io/zeroclaw-labs/zeroclaw:latest \
  daemon --host 0.0.0.0 --port 42617

Piège de bind : ZeroClaw utilise 127.0.0.1 par défaut pour la passerelle. Dans un conteneur, cela signifie que la passerelle est inaccessible depuis l’hôte. Passez toujours --host 0.0.0.0 (ou définissez ZEROCLAW_BIND=0.0.0.0) lors de l’exécution dans un conteneur.

Exécution en tant qu’unité systemd via Quadlet

Déposez un fichier .container dans /etc/containers/systemd/ (système) ou ~/.config/containers/systemd/ (utilisateur rootless) :

# ~/.config/containers/systemd/zeroclaw.container
[Unit]
Description=ZeroClaw gateway
After=network-online.target
Wants=network-online.target

[Container]
Image=ghcr.io/zeroclaw-labs/zeroclaw:latest
ContainerName=zeroclaw
PublishPort=42617:42617
Environment=ZEROCLAW_BIND=0.0.0.0
Exec=daemon --host 0.0.0.0 --port 42617
Volume=zeroclaw-data:/root/.zeroclaw

[Service]
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target default.target

systemctl --user daemon-reload
systemctl --user start zeroclaw.service

Pour les configurations rootless, exécutez également loginctl enable-linger $USER afin que le service démarre avant votre connexion.

Post-installation : Configuration native (sans conteneur)

1. Initialiser ZeroClaw

zeroclaw quickstart

Ceci vous guide à travers l’authentification du fournisseur et la configuration de la passerelle, puis crée votre configuration ZeroClaw.

2. Vérifiez que cela fonctionne

zeroclaw doctor
zeroclaw agent -a assistant -m « combien font 2+2 ? »

3. Exécuter en tant que service persistant

# Installer et démarrer le service utilisateur systemd
zeroclaw service install
systemctl --user enable --now zeroclaw

# Pour qu'il survive à la déconnexion / au redémarrage :
loginctl enable-linger $USER

4. Exécuter en tant que démon au premier plan

Pour le développement / débogage :

zeroclaw daemon --host 0.0.0.0 --port 42617

5. Activer les canaux

ZeroClaw peut se connecter à des plateformes de messagerie (Matrix, Mattermost, Discord, Telegram, etc.). Voir Canaux → Présentation. La plupart des transports de canaux fonctionnent parfaitement sur un Pi ; le plus lourd est la pile WebRTC utilisée par certains canaux vocaux, qui peut provoquer des pics de CPU lors de l’établissement des appels.

GPIO et périphériques matériels

Si vous souhaitez que les skills contrôlent les broches GPIO (LED, boutons, capteurs, etc.) :

1. Ajoutez votre utilisateur au groupe gpio :

   sh

   sudo usermod -aG gpio $USER
   # Déconnectez-vous et reconnectez-vous pour que le changement de groupe prenne effet
   

2. Utilisez les liaisons GPIO du crate peripherals depuis vos skills. Consultez Hardware → Peripherals design pour le modèle d’abstraction.

Dépannage

• Arrêt forcé par l’OOM-killer pendant la compilation : ajoutez du swap (Option 3, Étape 2), passez à un profil plus léger (release-fast ou ci), ou utilisez le binaire pré-compilé / la compilation croisée.
• Compilation extrêmement lente : comportement attendu sur les cartes avec peu de RAM ; effectuez une compilation croisée (Option 2) si cela est important.
• Erreur « Exec format error » avec un binaire précompilé : incompatibilité d’architecture. Exécutez uname -m et récupérez le binaire correspondant (aarch64 = 64 bits, armv7l = 32 bits).
• Autorisation GPIO refusée : vous ne faites pas partie du groupe gpio ; exécutez sudo usermod -aG gpio $USER, puis reconnectez-vous.
• Le service ne démarre pas après un redémarrage : loginctl enable-linger $USER pour que le service utilisateur survive à la déconnexion.
• Le conteneur ne peut pas atteindre la passerelle depuis l’hôte : la passerelle se lie à 127.0.0.1 ; passez --host 0.0.0.0 (ou ZEROCLAW_BIND=0.0.0.0).

Conseils de performance

• Utilisez un SSD ou une carte SD rapide. La compilation est limitée par les E/S ; un SSD USB 3.0 sur un Pi 4/5 réduit considérablement le temps de compilation.
• Exécuter en mode headless : sudo systemctl set-default multi-user.target.
• tmpfs pour les artefacts de build (avec une marge de RAM + swap) : export CARGO_TARGET_DIR=/tmp/zeroclaw-target.
• Vérifiez que clk_ignore_unused n’est pas présent sur la ligne de commande du noyau si vous utilisez une image personnalisée ; il inhibe le clock gating et augmente la consommation au repos. Raspberry Pi OS d’origine ne le définit pas.

Lié

• Configuration Linux : configuration Linux non spécifique au Pi, applicable ici aussi une fois le binaire installé
• Gestion des services : modèles systemd, plus approfondi que ce qui précède
• Matériel → Conception des périphériques : GPIO et le crate peripherals
• Matériel → Ajout de cartes et d’outils : étendre la prise en charge matérielle