---
tags: [vps, zeroclaw, install, yunohost, systemd]
type: note
description: "Installation de ZeroClaw 0.8.7 sur datagrandest : user, install.sh, unit systemd, domaine zc.shizendo.ovh, structure de config.toml, sandbox."
nature: documentation
projects:
  - [[03_PROJETS/VPS-IA]]
---

# VPS-IA_ZeroClaw-Installation-2026-11-08

**Date** : 2026-11-08 — **Agent** : vps-admin — **Opérateur** : GRK — **Serveur** : `datagrandest.net` (VPS principal, OVH / Yunohost)

Installation de **ZeroClaw 0.8.7** (`99bd353`) en miroir de l'installation shogun, puis branchement Matrix (voir [[VPS-IA_ZeroClaw-Matrix-2026-11-08]]).

## Récapitulatif

| Élément | Valeur |
|---|---|
| Version | `zeroclaw 0.8.7 (99bd353)` |
| User | `zeroclaw` (uid 1002, gid 1007), HOME `/home/zeroclaw`, shell `/bin/bash` |
| Binaire | `/home/zeroclaw/.cargo/bin/{zeroclaw,zerocode}` (17:57) |
| Config | `/home/zeroclaw/.zeroclaw/config.toml` — dossier **700** (inaccessible à `opencode`) |
| Service | `/etc/systemd/system/zeroclaw.service` (scope **système**, `enabled`) — créé 18:59 |
| Gateway / dashboard | `127.0.0.1:42617` + `~/.local/share/zeroclaw/web/dist` |
| Exposition | `https://zc.shizendo.ovh` via app YNH **`redirect__4` « Zeroclaw (Redirect) »** — SSO, `allowed: [admins]` |
| Compte Matrix | `@zc:matrix.datagrandest.net` (canal `kamio_zc`) |
| Pairing | actif (`require_pairing`), appareil appairé, `gateway.paired_tokens` chiffré |

**Écart notable avec shogun** : unit **system** (ici) vs unit **user-scoped + linger** (shogun, `/opt/zeroclaw`). Ici le daemon est porté par systemd système → pas besoin de linger pour ce service (le doctor signale néanmoins « systemd user lingering enabled » pour le user).

## Installation réalisée

```bash
# 1) user dédié
sudo useradd -m -d /home/zeroclaw -s /bin/bash zeroclaw
sudo su - zeroclaw

# 2) installateur officiel (binaire précompilé, pas de compilation locale)
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | sh

# 3) unit systemd
sudo nano /etc/systemd/system/zeroclaw.service
sudo systemctl daemon-reload && sudo systemctl enable --now zeroclaw
```

**Note d'archéologie** : `.cargo/registry` est **vide** — les binaires ne sont pas compilés sur place. C'est cohérent avec `install.sh` (téléchargement d'une release), et ça explique pourquoi `zeroclaw`/`zerocode` sont dans `~/.cargo/bin/` sans dépôt de sources.

## Unit systemd (contenu exact)

```ini
[Unit]
Description=ZeroClaw
After=network-online.target
Wants=network-online.target

[Service]
User=zeroclaw
WorkingDirectory=/home/zeroclaw
ExecStart=/home/zeroclaw/.cargo/bin/zeroclaw daemon
Restart=on-failure

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

## Exposition web

- App YNH **`redirect__4` « Zeroclaw (Redirect) »** créée via **YunoHost** (GUI/CLI), domaine **`zc.shizendo.ovh`** (record A déjà présent chez OVH), reverse-proxy vers `127.0.0.1:42617`.
- La gateway reste en **loopback uniquement** : aucun port ouvert au firewall.
- **Protection confirmée (GRK, 08/11)** : l'app est **derrière le SSO Yunohost, `allowed: [admins]`** — même barrière que `opencode.datagrandest.net`. Le SSO s'authentifie par **cookie**, il ne consomme donc pas l'en-tête `Authorization` → coexiste avec le Bearer du pairing ZeroClaw.
- ⛔ **Leçon reprise de shogun** : ne jamais mettre `auth_basic` nginx devant le dashboard — un en-tête `Authorization` ne porte qu'une valeur (`Basic` **ou** `Bearer`), ça casse le pairing après `POST /pair`. La protection par cookie SSO coexiste avec le Bearer.

## Structure de `config.toml` (extrait commenté — secrets omis)

Fichier complet sur le serveur. Les valeurs `enc2:…` (clé OpenRouter, `password`, `recovery_key`, `paired_tokens`) sont chiffrées au repos et **volontairement absentes de cette note**.

```toml
schema_version = 3

[tools]
optional = ["*"]

# Peer group Matrix : qui a le droit de parler au bot (deny-by-default)
[peer_groups.matrix]
admin_for_agent_scope = false
output_modality = "mirror"
channel = "matrix.kamio_zc"
external_peers = ["@shizendo:matrix.datagrandest.net"]
agents = ["kamio_zc"]

[providers.models.openrouter.openrouter]
context_window = 1050000
model = "xiaomi/mimo-v2.6-flash"
# api_key = "enc2:…" (omis)

[agents.kamio_zc]
risk_profile = "balanced"
runtime_profile = "unbounded"
model_provider = "openrouter.openrouter"
channels = ["matrix.kamio_zc"]     # ← doit viser l'id RÉEL du canal (piège corrigé le 08/11)

[runtime_profiles.unbounded]        # valeurs saillantes
agentic = true
agentic_timeout_secs = 1800
compact_context = false
max_actions_per_hour = 4294967295   # u32 max = quasi illimité
max_context_tokens = 128000
max_history_messages = 200
max_tool_iterations = 100
shell_timeout_secs = 600
parallel_tools = true

[risk_profiles.balanced]            # sandbox : workspace uniquement
allowed_commands = ["*"]
block_high_risk_commands = true
forbidden_paths = ["/etc", "/root", "/home", "/usr", "/bin", "/sbin", "/lib", "/opt", "/boot", …]
level = "supervised"
require_approval_for_medium_risk = false
sandbox_enabled = true
workspace_only = true

[risk_profiles.balanced.delegation_policy]
mode = "allow"

[gateway]
# paired_tokens = ["enc2:…"] (omis)

[channels.matrix.kamio_zc]
homeserver = "https://matrix.datagrandest.net"
user_id = "@zc:matrix.datagrandest.net"
enabled = true
mention_only = false                # répond sans être taggé
reply_in_thread = false             # réponse dans la timeline
stream_mode = "off"
message_max_bytes = 48000
approval_timeout_secs = 300
# password = "enc2:…", recovery_key = "enc2:…" (omis)
# allowed_rooms non défini = toutes les salles rejointes écoutées

[memory]
backend = "sqlite.sqlite"

[onboard_state]
quickstart_completed = true
```

Sections **vides** mais présentes : `[providers]`, `[providers.models]`, `[providers.models.openrouter]`, `[channels]`, `[channels.matrix]`, `[peer_groups]`, `[risk_profiles]`, `[agents]`, `[runtime_profiles]`.

⚠️ Ce motif (tables parentes vides `[channels]` / `[channels.matrix]`) est **exactement** ce qui déclenchait le warning « malformed » sur shogun. Ici `config migrate --json` répond `{"valid": true}` — mais c'est le point de vigilance n°1 à chaque démarrage : `journalctl -u zeroclaw | grep malformed`.

## Sandbox — conséquences pratiques

- `workspace_only = true` + `forbidden_paths` (dont `/home`, `/tmp` hors workspace) → **`zeroclaw cron` refusera** les scripts lisant `/opt/…/state` ou écrivant `/var/log/…` (constaté sur shogun : `forbidden path argument`). **Arbitrage** : la boucle mécanique (auto-join) vit en **cron OS**, `zeroclaw cron --prompt` reste réservé aux tâches agent.
- `level = "supervised"` + `block_high_risk_commands` : pas d'approval sur le risque moyen, blocage dur sur l'irréversible.

## État validé (08/11, fin de session)

| Contrôle | Résultat |
|---|---|
| `systemctl status zeroclaw` | `active (running)` |
| `doctor` | **29 ok / 1 warning / 0 erreur** (warning = `memory.search_mode=hybrid` sans embedding provider) |
| `config migrate --json` | `{"valid": true, "migrated": false}` |
| Channel | `channel:matrix.kamio_zc fresh`, `starting sync loop`, binding activé |
| Dashboard | `https://zc.shizendo.ovh` (app YNH), gateway loopback |
| Test bout en bout | réponse du bot dans 4 salons Matrix, auto-join cron `*/2` validé |

## Reste à faire

- [x] Accès `zc.shizendo.ovh` protégé par SSO (`allowed: [admins]`, comme `opencode`) — confirmé le 08/11.
- [ ] Activer TOTP ZeroClaw (`security.otp`) après enrôlement au dashboard.
- [x] Clé OpenRouter **dédiée** à ZC dans le coffre `pass` → `opencode/zeroclaw-openrouter-key` **créée le 08/11** par GRK (le `recovery_key` Matrix y était déjà : `opencode/zc-matrix-recovery-key`).
- [ ] **À creuser (reporté)** : enforcement du mot de passe serveur OpenCode — `OPENCODE_SERVER_PASSWORD` injecté et référencé dans le binaire, mais `GET /`, `/config`, `/auth`, `/session` en loopback → **200** avec, sans ou avec un mauvais bearer ; les paths API externes sont bien bloqués par le SSO (302). Trancher « inappliqué » vs « routes/verb non testés ».
- [ ] `memory.search_mode` : passer à `"bm25"` ou brancher un embedding provider.
- [ ] Purger les sessions SQLite des salons de test quittés.
- [ ] Ajouter `zeroclaw`/`zerocode` au PATH (symlink `/usr/local/bin` + `ZEROCLAW_CONFIG_DIR`) si usage CLI fréquent — aujourd'hui : `sudo -u zeroclaw … --config-dir /home/zeroclaw/.zeroclaw`.

## Voir aussi

[[VPS-IA_ZeroClaw-Matrix-2026-11-08]] (canal Matrix, 3 bugs, modèle de sessions) · [[VPS-SHOGUN_ZEROCLAW]] (installation shogun, pièges OAuth/CLI) · [[04_NOTES/VPS-IA_Installation-OpenCode-Chat-Bridge-Matrix]] (le second bot `@bot`) · [[04_NOTES/VPS-IA_Garde-fous-OpenCode-ZeroClaw-20261102]]