From 767b5463f970111b487cdfd13b22a2781b583df6 Mon Sep 17 00:00:00 2001 From: aydnOktay Date: Wed, 11 Mar 2026 23:39:56 +0300 Subject: [PATCH 1/2] 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 1de46644b..cdee7158c 100644 --- a/website/docs/user-guide/configuration.md +++ b/website/docs/user-guide/configuration.md @@ -436,6 +436,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]`. From dd6a5732e70b68815e1410bc5c6ca6b7a2d7dfb4 Mon Sep 17 00:00:00 2001 From: teknium1 Date: Sat, 14 Mar 2026 06:02:57 -0700 Subject: [PATCH 2/2] docs: fix salvaged PR #980 troubleshooting details Correct the PowerShell UTF-8 snippet in the new Windows encoding tip and soften the Docker CLI wording to match Hermes' actual lookup behavior. --- website/docs/guides/tips.md | 6 +++--- website/docs/user-guide/configuration.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/website/docs/guides/tips.md b/website/docs/guides/tips.md index 32a8cfcbe..4cdf11941 100644 --- a/website/docs/guides/tips.md +++ b/website/docs/guides/tips.md @@ -192,13 +192,13 @@ 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: +- In PowerShell, you can also switch the current session to UTF-8 for console and native command output: ```powershell -$PSStyle.OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new($false) +$OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new($false) ``` -This matches how the CI environment behaves and helps avoid Windows-only failures. +This keeps PowerShell and child processes on UTF-8 and helps avoid Windows-only failures. ### Review Before Choosing "Always" diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md index cdee7158c..c5d6d45a7 100644 --- a/website/docs/user-guide/configuration.md +++ b/website/docs/user-guide/configuration.md @@ -445,7 +445,7 @@ If terminal commands fail immediately or the terminal tool is reported as disabl - **Docker backend** - Ensure Docker Desktop (or the Docker daemon) is installed and running. - - The `docker` CLI must be available in your `$PATH`. Run: + - Hermes needs to be able to find the `docker` CLI. It checks your `$PATH` first and also probes common Docker Desktop install locations on macOS. Run: ```bash docker version ```