# ZimaOS/CasaOS Environment Quirks

ZimaOS is a Linux-container-based NAS/self-hosting OS with CasaOS as the app orchestrator. It shares the host's storage under `/DATA/`. Running Hermes on ZimaOS involves several non-standard paths and permission patterns that differ from a normal Linux desktop.

## Common Issues

### 1. `/DATA/AppData` is the real working directory, not `$HOME`

The `az-a` user's `$HOME` resolves to `/DATA`, but Hermes actually runs from `/DATA/AppData/hermes`. Configs, `.env`, and skills live there.

- Config: `/DATA/AppData/hermes/config.yaml`
- Env: `/DATA/AppData/hermes/.env`
- venv: `/DATA/AppData/hermes/venv/`
- CLI: `/DATA/AppData/hermes/venv/bin/hermes` (not in PATH)

**Fix:** Symlink or PATH export:
```bash
ln -s /DATA/AppData/hermes/venv/bin/hermes ~/.local/bin/hermes  # may fail on root-owned parent
# OR just use the absolute path every time
```

### 2. Root-owned directories under `/DATA/AppData`

Some directories (e.g., `.cache`, `.config`) may be owned by `root` even though Hermes runs as `az-a`. Attempting to `mkdir`, `chmod`, or write there results in `PermissionError: [Errno 13]`.

**Fix:** Create directories under `/DATA/AppData/hermes/` instead, where the user has write access. Example:
```python
import os
# This fails:
# os.makedirs("/DATA/AppData/.config/himalaya")
# This succeeds:
os.makedirs("/DATA/AppData/hermes/.config/himalaya")
```

### 3. CasaOS app directories

Apps managed by CasaOS live under `/DATA/.casaos/apps/<name>/`, typically with a `docker-compose.yml`:
```
/DATA/.casaos/apps/openclaw/
/DATA/.casaos/apps/plex/
/DATA/.casaos/apps/audiobookshelf/
```

These run as Docker containers or Systemd services. Predecessor bots (OpenClaw) may still be running as `root` in a separate container while the new Hermes agent runs as `az-a`.

### 4. Systemd gateway service runs as root

`hermes-gateway.service` is a system-level unit, not a user unit. The agent can't `sudo systemctl restart` without a password/askpass helper.

**Workaround:** Provide the user the exact command to run in a separate terminal, or ask them to do it.

### 5. Missing basic shell tools in sandbox

Hermes' Python sandbox may not have `mkdir`, `chmod`, `cp` in the PATH. Use Python's `os.makedirs()`, `os.chmod()`, and `shutil` instead of shell commands for file operations.

### 6. CasaOS app list

```bash
ls /DATA/.casaos/apps/
```

Useful for discovering what services the user already runs (Plex, Navidrome, Immich, etc.).

### 7. Media paths

User media is typically on an external HDD mounted under:
```
/mnt/user/HDD_1TB/
# BUT paths may change if drives are re-mounted
# Always verify with ls -d before assuming
```

## Environment Scan Commands

```bash
# Hermes health
/DATA/AppData/hermes/venv/bin/hermes status --all
/DATA/AppData/hermes/venv/bin/hermes doctor
/DATA/AppData/hermes/venv/bin/hermes tools list

# Processes
ps aux | grep -iE 'hermes|openclaw'

# CasaOS apps
ls /DATA/.casaos/apps/

# Network listeners
ss -tlnp

# Storage mounts
lsblk && df -h
```

## When to use this reference

Load this during onboarding whenever the environment scan reveals:
- `HERMES_HOME=/DATA/AppData/hermes`
- System name contains `ZimaOS`
- CasaOS directories exist
- Permission errors on standard paths
- Predecessor bot running as `root`

## Why sudo fails even with terminal access

A common misconception: "Terminal works, so I should be able to restart a service." In reality:

| What you can do | What requires sudo |
|---|---|
| `python script.py` (as az-a) | `systemctl restart` |
| `mkdir` in your home | `systemctl start/stop` |
| `curl` to the internet | Installing to `/usr/bin` |
| Most file operations in `/DATA/AppData/` | Modifying `/etc/sudoers.d/` |

The Hermes agent runs as user `az-a`. The gateway runs as root via systemd. To restart it:
1. Either the user gives `NOPASSWD` sudo rights (see the main SKILL.md section "Gateway Systemd Service")
2. Or the user must run the command themselves

This is not a bug — it's Linux permissions working correctly.