From 5e69c247532eb3df65fa017aaad6a6890f2a18fb Mon Sep 17 00:00:00 2001
From: aydnOktay <xaydinoktay@gmail.com>
Date: Wed, 11 Mar 2026 23:39:56 +0300
Subject: [PATCH] docs: add terminal backend and windows troubleshooting

---
 website/docs/guides/tips.md              | 19 ++++++++++++++
 website/docs/user-guide/configuration.md | 33 ++++++++++++++++++++++++
 2 files changed, 52 insertions(+)

diff --git a/website/docs/guides/tips.md b/website/docs/guides/tips.md
index af4b8fce4..32a8cfcbe 100644
--- a/website/docs/guides/tips.md
+++ b/website/docs/guides/tips.md
@@ -181,6 +181,25 @@ TERMINAL_BACKEND=docker
 TERMINAL_DOCKER_IMAGE=hermes-sandbox:latest
 ```
 
+### Avoid Windows Encoding Pitfalls
+
+On Windows, some default encodings (such as `cp125x`) cannot represent all Unicode characters, which can cause `UnicodeEncodeError` when writing files in tests or scripts.
+
+- Prefer opening files with an explicit UTF-8 encoding:
+
+```python
+with open("results.txt", "w", encoding="utf-8") as f:
+    f.write("✓ All good\n")
+```
+
+- In PowerShell, you can also set UTF-8 as the default output encoding for your session:
+
+```powershell
+$PSStyle.OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
+```
+
+This matches how the CI environment behaves and helps avoid Windows-only failures.
+
 ### Review Before Choosing "Always"
 
 When the agent triggers a dangerous command approval (`rm -rf`, `DROP TABLE`, etc.), you get four options: **once**, **session**, **always**, **deny**. Think carefully before choosing "always" — it permanently allowlists that pattern. Start with "session" until you're comfortable.
diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md
index 8ca0f0726..74fd7f9f6 100644
--- a/website/docs/user-guide/configuration.md
+++ b/website/docs/user-guide/configuration.md
@@ -407,6 +407,39 @@ terminal:
   container_persistent: true         # Persist filesystem across sessions
 ```
 
+### Common Terminal Backend Issues
+
+If terminal commands fail immediately or the terminal tool is reported as disabled, check the following:
+
+- **Local backend**
+  - No special requirements. This is the safest default when you are just getting started.
+
+- **Docker backend**
+  - Ensure Docker Desktop (or the Docker daemon) is installed and running.
+  - The `docker` CLI must be available in your `$PATH`. Run:
+    ```bash
+    docker version
+    ```
+    If this fails, fix your Docker installation or switch back to the local backend:
+    ```bash
+    hermes config set terminal.backend local
+    ```
+
+- **SSH backend**
+  - Both `TERMINAL_SSH_HOST` and `TERMINAL_SSH_USER` must be set, for example:
+    ```bash
+    export TERMINAL_ENV=ssh
+    export TERMINAL_SSH_HOST=my-server.example.com
+    export TERMINAL_SSH_USER=ubuntu
+    ```
+  - If either value is missing, Hermes will log a clear error and refuse to use the SSH backend.
+
+- **Modal backend**
+  - You need either a `MODAL_TOKEN_ID` environment variable or a `~/.modal.toml` config file.
+  - If neither is present, the backend check fails and Hermes will report that the Modal backend is not available.
+
+When in doubt, set `terminal.backend` back to `local` and verify that commands run there first.
+
 ### Docker Volume Mounts
 
 When using the Docker backend, `docker_volumes` lets you share host directories with the container. Each entry uses standard Docker `-v` syntax: `host_path:container_path[:options]`.