---
name: zimaos-quirks
description: ZimaOS-Eigenheiten — read-only Root-FS, DOCKER_CONFIG, HOME=/DATA, Systemd-Service-Namen und andere Fallstricke.
version: 1.0.0
author: Hermes Agent (from Claude handover 2026-06-04)
license: MIT
metadata:
  hermes:
    tags: [zimaos, quirks, pitfalls, read-only, docker]
    related_skills: [zimaos-administration, zimaos-app-install]
---

# ZimaOS Quirks (Server-Eigenheiten)

ZimaOS hat einige ungewöhnliche Eigenschaften, die bei fast jeder Admin-Aufgabe zu Problemen führen können. Diese Seite dokumentiert sie zentral.

## Read-Only Root-Filesystem

- `/` ist **squashfs read-only** (Immutable-OS-Prinzip)
- `/root/` kann NICHTS persistent speichern — alle Schreibversuche schlagen fehl mit "Read-only file system"
- Betroffene Pfade die NICHT schreibbar sind: `/root/.docker/`, `/root/.hermes/`, `/root/.git/`, `/root/.ssh/`, `/root/.cache/`

**Workaround für Docker CLI:**
```bash
export DOCKER_CONFIG=/tmp/docker-config
# ODER
export DOCKER_CONFIG=/DATA/.docker-build
```

**Workaround für Tools die nach `/root/` schreiben wollen:**
```bash
HOME=/DATA <befehl>
# ODER
env HOME=/DATA XDG_CACHE_HOME=/DATA/.cache <befehl>
```

## Schreibbare Bereiche

Nur diese Pfade sind persistent schreibbar:
- `/DATA/` — Hauptdatenpartition (ext4)
- `/media/` — Zusätzliche Laufwerke
- `/tmp/` — Temporär (nicht persistent über reboots)
- `/var/lib/docker/` — Docker-Daten
- `/var/lib/casaos/` — CasaOS-App-Definitionen

## Docker-Besonderheiten

- **`DOCKER_CONFIG` immer setzen**, sonst schlägt `docker` CLI fehl
- **`docker compose` nur aus dem App-Verzeichnis** (`/var/lib/casaos/apps/<name>/`)
- **Niemals `docker run -d`** — erzeugt Legacy-Container ohne Compose

## Systemd-Service-Name

- Der ZimaOS-App-Management-Service heißt **`zimaos-app-management`** (NICHT `casaos-app-management`)
- Nach Änderungen an Compose-Files in `/var/lib/casaos/apps/`:
  ```bash
  systemctl restart zimaos-app-management
  ```
- Das informiert die ZimaOS-UI über neue/geänderte Apps

## Bei eigenen Tool-Aufrufen

Wenn du (Hermes) selbst Commands auf dem ZimaOS-Server ausführst:
- **Immer `HOME=/DATA`** setzen, bevor du was machst das CWD oder Home scannt
- **`cd /DATA`** vor Operationen die relative Pfade nutzen
- Grund: `/root/` ist read-only, und viele Tools versuchen `~/.config/`, `~/.cache/` etc. anzulegen

## Hermes-eigene Invocation

```bash
cd /DATA && sudo -u az-a env \
  HOME=/DATA \
  HERMES_HOME=/DATA/.hermes \
  XDG_STATE_HOME=/DATA/.hermes/state \
  XDG_DATA_HOME=/DATA/.hermes/share \
  XDG_CACHE_HOME=/DATA/.hermes/cache \
  /DATA/AppData/hermes/venv/bin/python -m hermes_cli.main -z "<prompt>" --yolo
```

## Weitere Quirks

- **Kein `unattended-upgrades`** — Sicherheitsupdates müssen manuell gemacht werden
- **Kein `ufw`** — iptables default policy ACCEPT, Router-Firewall als Schutz
- **Kein `make`** — Build-Schritte manuell ausführen
- **Network mode `host`** wird für Tailscale und Home Assistant verwendet (Ports direkt exponiert)
- **Samba + Btrfs rename corruption**: Samba greift in Datei-Groups ein — Prozesse die als `az-a` laufen, erzeugen Dateien mit Group `samba` statt `users`. Das verursacht `[Errno 2] No such file or directory` bei Rename-Operationen auf Btrfs (betrifft yt-dlp `.part`-Fragmente). Workaround: `--no-part` Flag bei yt-dlp (direkt schreiben, keine Fragmente). Siehe `media-file-management` Skill.