diff --git a/cli-config.yaml.example b/cli-config.yaml.example index 355b6bb75..fb6912642 100644 --- a/cli-config.yaml.example +++ b/cli-config.yaml.example @@ -163,7 +163,7 @@ model: # ----------------------------------------------------------------------------- # Working directory behavior: # - CLI (`hermes` command): Uses "." (current directory where you run hermes) -# - Messaging (Telegram/Discord): Uses MESSAGING_CWD from .env (default: home) +# - Gateway/messaging/cron: Uses terminal.cwd here; legacy .env cwd values are deprecated terminal: backend: "local" cwd: "." # For local backend: "." = current directory. Ignored for remote backends unless a backend documents otherwise. diff --git a/nix/nixosModules.nix b/nix/nixosModules.nix index f5c067a63..19abc81a3 100644 --- a/nix/nixosModules.nix +++ b/nix/nixosModules.nix @@ -242,7 +242,7 @@ type = types.str; default = "${cfg.stateDir}/workspace"; defaultText = literalExpression ''"''${cfg.stateDir}/workspace"''; - description = "Working directory for the agent (MESSAGING_CWD)."; + description = "Working directory for the agent."; }; # ── Declarative config ─────────────────────────────────────────────── diff --git a/optional-skills/migration/openclaw-migration/SKILL.md b/optional-skills/migration/openclaw-migration/SKILL.md index 4d8734f52..3bceba872 100644 --- a/optional-skills/migration/openclaw-migration/SKILL.md +++ b/optional-skills/migration/openclaw-migration/SKILL.md @@ -38,7 +38,7 @@ It uses `scripts/openclaw_to_hermes.py` to: - import `SOUL.md` into the Hermes home directory as `SOUL.md` - transform OpenClaw `MEMORY.md` and `USER.md` into Hermes memory entries - merge OpenClaw command approval patterns into Hermes `command_allowlist` -- migrate Hermes-compatible messaging settings such as `TELEGRAM_ALLOWED_USERS` and `MESSAGING_CWD` +- migrate Hermes-compatible messaging settings such as `TELEGRAM_ALLOWED_USERS`, and map OpenClaw workspace settings to Hermes working-directory configuration - copy OpenClaw skills into `~/.hermes/skills/openclaw-imports/` - optionally copy the OpenClaw workspace instructions file into a chosen Hermes workspace - mirror compatible workspace assets such as `workspace/tts/` into `~/.hermes/tts/` diff --git a/website/docs/getting-started/nix-setup.md b/website/docs/getting-started/nix-setup.md index ea2beb1fb..3cfdd86fd 100644 --- a/website/docs/getting-started/nix-setup.md +++ b/website/docs/getting-started/nix-setup.md @@ -583,7 +583,7 @@ Host Container │ ├── state.db, sessions/, memories/ (runtime state) │ └── mcp-tokens/ (OAuth tokens for MCP servers) ├── home/ ──► /home/hermes (rw) - └── workspace/ (MESSAGING_CWD) + └── workspace/ (agent working directory) ├── SOUL.md (from documents option) └── (agent-created files) @@ -831,7 +831,7 @@ nix build .#checks.x86_64-linux.config-roundtrip # merge script preserves use | `group` | `str` | `"hermes"` | System group | | `createUser` | `bool` | `true` | Auto-create user/group | | `stateDir` | `str` | `"/var/lib/hermes"` | State directory (`HERMES_HOME` parent) | -| `workingDirectory` | `str` | `"${stateDir}/workspace"` | Agent working directory (`MESSAGING_CWD`) | +| `workingDirectory` | `str` | `"${stateDir}/workspace"` | Agent working directory | | `addToSystemPackages` | `bool` | `false` | Add `hermes` CLI to system PATH and set `HERMES_HOME` system-wide | ### Configuration @@ -918,7 +918,7 @@ nix build .#checks.x86_64-linux.config-roundtrip # merge script preserves use │ ├── cron/ │ └── logs/ ├── home/ # Agent HOME -└── workspace/ # MESSAGING_CWD +└── workspace/ # Agent working directory ├── SOUL.md # From documents option └── (agent-created files) ``` diff --git a/website/docs/guides/build-a-hermes-plugin.md b/website/docs/guides/build-a-hermes-plugin.md index 3341b4a97..2e144c7e9 100644 --- a/website/docs/guides/build-a-hermes-plugin.md +++ b/website/docs/guides/build-a-hermes-plugin.md @@ -770,7 +770,7 @@ def register(ctx): **Runtime behavior:** - **CLI mode:** `parent_agent` is resolved from the active CLI agent so workspace hints, spinner, and model selection inherit as expected. -- **Gateway mode:** There is no CLI agent, so tools degrade gracefully — workspace is read from `TERMINAL_CWD` and no spinner is shown. +- **Gateway mode:** There is no CLI agent, so tools degrade gracefully — workspace is read from the configured terminal working directory and no spinner is shown. - **Explicit override:** If the caller passes `parent_agent=` explicitly, it is respected and not overwritten. This is the public, stable interface for tool dispatch from plugin commands. Plugins should not reach into `ctx._cli_ref.agent` or similar private state. diff --git a/website/docs/guides/migrate-from-openclaw.md b/website/docs/guides/migrate-from-openclaw.md index b2f3c953c..eda670576 100644 --- a/website/docs/guides/migrate-from-openclaw.md +++ b/website/docs/guides/migrate-from-openclaw.md @@ -160,7 +160,7 @@ TTS settings are read from **two** OpenClaw config locations with this priority: | Browser headless | `browser.headless` | `config.yaml` → `browser.headless` | | | Brave search key | `tools.web.search.brave.apiKey` | `.env` → `BRAVE_API_KEY` | Requires `--migrate-secrets` | | Gateway auth token | `gateway.auth.token` | `.env` → `HERMES_GATEWAY_TOKEN` | Requires `--migrate-secrets` | -| Working directory | `agents.defaults.workspace` | `.env` → `MESSAGING_CWD` | | +| Working directory | `agents.defaults.workspace` | `config.yaml` → `terminal.cwd` | Legacy migrations may still emit `MESSAGING_CWD` as a compatibility fallback | ### Archived (no direct Hermes equivalent) diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.md index 391e067dc..664a4f068 100644 --- a/website/docs/reference/environment-variables.md +++ b/website/docs/reference/environment-variables.md @@ -197,7 +197,7 @@ These variables configure the [Tool Gateway](/user-guide/features/tool-gateway) | `TERMINAL_DAYTONA_IMAGE` | Daytona sandbox image | | `TERMINAL_TIMEOUT` | Command timeout in seconds | | `TERMINAL_LIFETIME_SECONDS` | Max lifetime for terminal sessions in seconds | -| `TERMINAL_CWD` | Working directory for terminal sessions (gateway/cron only; CLI uses launch dir) | +| `TERMINAL_CWD` | Deprecated direct override for gateway/cron terminal sessions. Prefer `terminal.cwd` in `config.yaml`; CLI still uses the launch directory. | | `SUDO_PASSWORD` | Enable sudo without interactive prompt | For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETIME_SECONDS` controls when Hermes cleans up an idle terminal session, and later resumes may recreate the sandbox rather than keep the same live processes running. @@ -412,7 +412,7 @@ For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETI | `API_SERVER_MODEL_NAME` | Model name advertised on `/v1/models`. Defaults to the profile name (or `hermes-agent` for the default profile). Useful for multi-user setups where frontends like Open WebUI need distinct model names per connection. | | `GATEWAY_PROXY_URL` | URL of a remote Hermes API server to forward messages to ([proxy mode](/user-guide/messaging/matrix#proxy-mode-e2ee-on-macos)). When set, the gateway handles platform I/O only — all agent work is delegated to the remote server. Also configurable via `gateway.proxy_url` in `config.yaml`. | | `GATEWAY_PROXY_KEY` | Bearer token for authenticating with the remote API server in proxy mode. Must match `API_SERVER_KEY` on the remote host. | -| `MESSAGING_CWD` | Working directory for terminal commands in messaging mode (default: `~`) | +| `MESSAGING_CWD` | Deprecated compatibility fallback for gateway working directory. Prefer `terminal.cwd` in `config.yaml`. | | `GATEWAY_ALLOWED_USERS` | Comma-separated user IDs allowed across all platforms | | `GATEWAY_ALLOW_ALL_USERS` | Allow all users without allowlists (`true`/`false`, default: `false`) | diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md index d19f48cb8..ecde153a9 100644 --- a/website/docs/user-guide/configuration.md +++ b/website/docs/user-guide/configuration.md @@ -1726,12 +1726,14 @@ See also: | Context | Default | |---------|---------| | **CLI (`hermes`)** | Current directory where you run the command | -| **Messaging gateway** | Home directory `~` (override with `MESSAGING_CWD`) | +| **Messaging gateway** | `terminal.cwd` from `~/.hermes/config.yaml`; if unset, home directory `~` | | **Docker / Singularity / Modal / SSH** | User's home directory inside the container or remote machine | Override the working directory: -```bash -# In ~/.hermes/.env or ~/.hermes/config.yaml: -MESSAGING_CWD=/home/myuser/projects # Gateway sessions -TERMINAL_CWD=/workspace # All terminal sessions +```yaml +# In ~/.hermes/config.yaml: +terminal: + cwd: /home/myuser/projects ``` + +`MESSAGING_CWD` and direct `TERMINAL_CWD` entries in `~/.hermes/.env` are legacy compatibility fallbacks. New configurations should use `terminal.cwd`. diff --git a/website/docs/user-guide/features/cron.md b/website/docs/user-guide/features/cron.md index 53e03fe63..cbefde68a 100644 --- a/website/docs/user-guide/features/cron.md +++ b/website/docs/user-guide/features/cron.md @@ -117,12 +117,12 @@ cronjob( When `workdir` is set: - `AGENTS.md`, `CLAUDE.md`, and `.cursorrules` from that directory are injected into the system prompt (same discovery order as the interactive CLI) -- `terminal`, `read_file`, `write_file`, `patch`, `search_files`, and `execute_code` all use that directory as their working directory (via `TERMINAL_CWD`) +- `terminal`, `read_file`, `write_file`, `patch`, `search_files`, and `execute_code` all use that directory as their working directory - The path must be an absolute directory that exists — relative paths and missing directories are rejected at create / update time - Pass `--workdir ""` (or `workdir=""` via the tool) on edit to clear it and restore the old behaviour :::note Serialization -Jobs with a `workdir` run sequentially on the scheduler tick, not in the parallel pool. This is deliberate — `TERMINAL_CWD` is process-global, so two workdir jobs running at the same time would corrupt each other's cwd. Workdir-less jobs still run in parallel as before. +Jobs with a `workdir` run sequentially on the scheduler tick, not in the parallel pool. This is deliberate: the cron worker applies the job workdir through process-global terminal state, so two workdir jobs running at the same time would corrupt each other's cwd. Workdir-less jobs still run in parallel as before. ::: ## Running cron jobs in a specific profile diff --git a/website/docs/user-guide/git-worktrees.md b/website/docs/user-guide/git-worktrees.md index 33d29506e..fdaf7e3de 100644 --- a/website/docs/user-guide/git-worktrees.md +++ b/website/docs/user-guide/git-worktrees.md @@ -21,7 +21,7 @@ This page shows how to combine worktrees with Hermes so each session has a clean Hermes treats the **current working directory** as the project root: - CLI: the directory where you run `hermes` or `hermes chat` -- Messaging gateways: the directory set by `MESSAGING_CWD` +- Messaging gateways: the directory set by `terminal.cwd` in `~/.hermes/config.yaml` If you run multiple agents in the **same checkout**, their changes can interfere with each other: @@ -171,4 +171,3 @@ This combination gives you: - Strong guarantees that different agents and experiments do not step on each other. - Fast iteration cycles with easy recovery from bad edits. - Clean, reviewable pull requests. - diff --git a/website/docs/user-guide/security.md b/website/docs/user-guide/security.md index 2bc088ab9..54dae3f83 100644 --- a/website/docs/user-guide/security.md +++ b/website/docs/user-guide/security.md @@ -586,7 +586,7 @@ Blocked files show a warning: 4. **Store secrets securely** — keep API keys in `~/.hermes/.env` with proper file permissions 5. **Enable DM pairing** — use pairing codes instead of hardcoding user IDs when possible 6. **Review command allowlist** — periodically audit `command_allowlist` in config.yaml -7. **Set `MESSAGING_CWD`** — don't let the agent operate from sensitive directories +7. **Set `terminal.cwd`** — don't let the agent operate from sensitive directories 8. **Run as non-root** — never run the gateway as root 9. **Monitor logs** — check `~/.hermes/logs/` for unauthorized access attempts 10. **Keep updated** — run `hermes update` regularly for security patches diff --git a/website/docs/user-guide/skills/optional/migration/migration-openclaw-migration.md b/website/docs/user-guide/skills/optional/migration/migration-openclaw-migration.md index 74b44ff23..5837b1051 100644 --- a/website/docs/user-guide/skills/optional/migration/migration-openclaw-migration.md +++ b/website/docs/user-guide/skills/optional/migration/migration-openclaw-migration.md @@ -56,7 +56,7 @@ It uses `scripts/openclaw_to_hermes.py` to: - import `SOUL.md` into the Hermes home directory as `SOUL.md` - transform OpenClaw `MEMORY.md` and `USER.md` into Hermes memory entries - merge OpenClaw command approval patterns into Hermes `command_allowlist` -- migrate Hermes-compatible messaging settings such as `TELEGRAM_ALLOWED_USERS` and `MESSAGING_CWD` +- migrate Hermes-compatible messaging settings such as `TELEGRAM_ALLOWED_USERS`, and map OpenClaw workspace settings to Hermes working-directory configuration - copy OpenClaw skills into `~/.hermes/skills/openclaw-imports/` - optionally copy the OpenClaw workspace instructions file into a chosen Hermes workspace - mirror compatible workspace assets such as `workspace/tts/` into `~/.hermes/tts/`