Installation et accès

Prérequis

Raspberry Pi OS 64 bits et utilisateur Linux non-root ;
Docker Engine et plugin Docker Compose accessibles à cet utilisateur ;
Tailscale recommandé pour l'accès distant privé ;
réseau local de confiance pour l'accès direct par IP au port 8765 ;
compte du moteur choisi à authentifier après l’installation (Codex, Claude Code ou fournisseur OpenCode).

Python, Node.js, Django, FastAPI, Uvicorn, tmux, GitHub CLI, Codex CLI, Claude Code et OpenCode sont installés dans l'image. Aucun .venv n'est requis. Les unités systemd fournies ne font tourner aucun code applicatif en root : l’installateur les génère avec les UID/GID numériques du propriétaire de /home/config/CodexPi, puis elles démarrent Compose sous ce compte et surveillent le groupe du socket Docker. Aucun nom d’utilisateur particulier n’est imposé.

Démarrage

cd /home/config/CodexPi
chmod +x scripts/*.sh
./scripts/audit.sh
./scripts/install.sh
./scripts/compose.sh ps

install.sh relève automatiquement l'UID/GID courant, le groupe du socket Docker et le dossier personnel contenant les profils des moteurs. Il construit l'image, applique les migrations Django, démarre les services et installe les unités de démarrage et d’auto-réparation. Le wrapper scripts/compose.sh, également utilisé au démarrage automatique, relève de nouveau le GID du socket à chaque invocation afin de conserver l'accès si Docker recrée le socket avec un autre groupe. Ouvrez ensuite CodexPi : l’assistant crée le premier administrateur sans commande supplémentaire.

L’unité de démarrage codexpi.service suit le cycle de vie de docker.service. Un redémarrage du démon Docker relance donc Compose avec le GID courant du socket au lieu de conserver le groupe d’un ancien conteneur. En complément, codexpi-docker-access.timer vérifie ce GID chaque minute et recrée uniquement l’API lorsqu’il a changé. La réparation est différée tant qu’une tâche Codex est active et ne démarre jamais une pile arrêtée volontairement. Ces unités s’exécutent sous le propriétaire non-root du projet, avec le groupe actuel du socket Docker ; elles ne lancent jamais Codex en root.

Sur une installation existante, activez une fois cette surveillance avec ./scripts/install-boot-service.sh. Si Docker ou son socket est réellement arrêté ou absent, CodexPi attend simplement le prochain contrôle : aucun logiciel ne peut fournir les commandes Docker tant que le daemon lui-même est indisponible.

Les profils .codex, .claude, .config/opencode et .config/gh sont montés depuis le dossier personnel et survivent aux rebuilds. L’authentification d’un moteur reste une action interactive à effectuer dans le terminal CodexPi ; ne collez jamais de mot de passe ou de jeton dans une discussion.

Commandes utiles :

./scripts/compose.sh up -d
./scripts/compose.sh logs -f --tail=100
./scripts/compose.sh restart
./scripts/compose.sh down
curl http://127.0.0.1:8765/proxy-health

L'arrêt avec ./scripts/compose.sh down conserve ./data. N'ajoutez jamais --volumes sans sauvegarde.

Accès direct sur le réseau local

Ouvrez http://IP_DU_PI:8765 depuis un ordinateur du même réseau. Le port 8765 est publié par nginx uniquement ; FastAPI et Django restent privés dans Docker. N'ajoutez aucune redirection du port 8765 sur la box Internet. Si un pare-feu est actif sur le Pi, autorisez ce port uniquement depuis le sous-réseau local de confiance.

Tailscale Serve recommandé

Gardez CODEXPI_HOST=127.0.0.1 dans .env, puis :

./scripts/tailscale-serve.sh --check
./scripts/tailscale-serve.sh --apply

Tailscale Serve termine HTTPS et relaie vers http://127.0.0.1:8765. Le script refuse de remplacer une configuration Funnel. Aucun compte, auth key, UPnP, DMZ ou transfert de port n'est créé.

Si Tailscale est absent, le script affiche les commandes d'installation sans les exécuter. L'association du Pi au tailnet reste une action interactive de l'utilisateur.

Mise à jour

cd /home/config/CodexPi
./scripts/compose.sh build --pull
./scripts/compose.sh up -d
./scripts/security-audit.sh

4.1 KiB Raw Permalink Blame History Unescape Escape