diff --git a/website/docs/reference/profile-commands.md b/website/docs/reference/profile-commands.md index 8c8feafb51..e4f28e8346 100644 --- a/website/docs/reference/profile-commands.md +++ b/website/docs/reference/profile-commands.md @@ -81,6 +81,8 @@ Creates a new profile. | `--clone-from ` | Clone from a specific profile instead of the current one. Used with `--clone` or `--clone-all`. | | `--no-alias` | Skip wrapper script creation. | +Creating a profile does **not** make that profile directory the default project/workspace directory for terminal commands. If you want a profile to start in a specific project, set `terminal.cwd` in that profile's `config.yaml`. + **Examples:** ```bash @@ -129,6 +131,8 @@ hermes profile show Displays details about a profile including its home directory, configured model, gateway status, skills count, and configuration file status. +This shows the profile's Hermes home directory, not the terminal working directory. Terminal commands start from `terminal.cwd` (or the launch directory on the local backend when `cwd: "."`). + | Argument | Description | |----------|-------------| | `` | Profile to inspect. | diff --git a/website/docs/user-guide/profiles.md b/website/docs/user-guide/profiles.md index 67609564f7..aef4d10b21 100644 --- a/website/docs/user-guide/profiles.md +++ b/website/docs/user-guide/profiles.md @@ -4,11 +4,11 @@ sidebar_position: 2 # Profiles: Running Multiple Agents -Run multiple independent Hermes agents on the same machine — each with its own config, API keys, memory, sessions, skills, and gateway. +Run multiple independent Hermes agents on the same machine — each with its own config, API keys, memory, sessions, skills, and gateway state. ## What are profiles? -A profile is a fully isolated Hermes environment. Each profile gets its own directory containing its own `config.yaml`, `.env`, `SOUL.md`, memories, sessions, skills, cron jobs, and state database. Profiles let you run separate agents for different purposes — a coding assistant, a personal bot, a research agent — without any cross-contamination. +A profile is a separate Hermes home directory. Each profile gets its own directory containing its own `config.yaml`, `.env`, `SOUL.md`, memories, sessions, skills, cron jobs, and state database. Profiles let you run separate agents for different purposes — a coding assistant, a personal bot, a research agent — without mixing up Hermes state. When you create a profile, it automatically becomes its own command. Create a profile called `coder` and you immediately have `coder chat`, `coder setup`, `coder gateway start`, etc. @@ -20,7 +20,7 @@ coder setup # configure API keys and model coder chat # start chatting ``` -That's it. `coder` is now a fully independent agent. It has its own config, its own memory, its own everything. +That's it. `coder` is now its own Hermes profile with its own config, memory, and state. ## Creating a profile @@ -104,6 +104,32 @@ The CLI always shows which profile is active: - **Banner**: Shows `Profile: coder` on startup - **`hermes profile`**: Shows current profile name, path, model, gateway status +## Profiles vs workspaces vs sandboxing + +Profiles are often confused with workspaces or sandboxes, but they are different things: + +- A **profile** gives Hermes its own state directory: `config.yaml`, `.env`, `SOUL.md`, sessions, memory, logs, cron jobs, and gateway state. +- A **workspace** or **working directory** is where terminal commands start. That is controlled separately by `terminal.cwd`. +- A **sandbox** is what limits filesystem access. Profiles do **not** sandbox the agent. + +On the default `local` terminal backend, the agent still has the same filesystem access as your user account. A profile does not stop it from accessing folders outside the profile directory. + +If you want a profile to start in a specific project folder, set an explicit absolute `terminal.cwd` in that profile's `config.yaml`: + +```yaml +terminal: + backend: local + cwd: /absolute/path/to/project +``` + +Using `cwd: "."` on the local backend means "the directory Hermes was launched from", not "the profile directory". + +Also note: + +- `SOUL.md` can guide the model, but it does not enforce a workspace boundary. +- Changes to `SOUL.md` take effect cleanly on a new session. Existing sessions may still be using the old prompt state. +- Asking the model "what directory are you in?" is not a reliable isolation test. If you need a predictable starting directory for tools, set `terminal.cwd` explicitly. + ## Running gateways Each profile runs its own gateway as a separate process with its own bot token: @@ -151,6 +177,12 @@ coder config set model.model anthropic/claude-sonnet-4 echo "You are a focused coding assistant." > ~/.hermes/profiles/coder/SOUL.md ``` +If you want this profile to work in a specific project by default, also set its own `terminal.cwd`: + +```bash +coder config set terminal.cwd /absolute/path/to/project +``` + ## Updating `hermes update` pulls code once (shared) and syncs new bundled skills to **all** profiles automatically: @@ -201,6 +233,8 @@ Add the line to your `~/.bashrc` or `~/.zshrc` for persistent completion. Comple ## How it works -Profiles use the `HERMES_HOME` environment variable. When you run `coder chat`, the wrapper script sets `HERMES_HOME=~/.hermes/profiles/coder` before launching hermes. Since 119+ files in the codebase resolve paths via `get_hermes_home()`, everything automatically scopes to the profile's directory — config, sessions, memory, skills, state database, gateway PID, logs, and cron jobs. +Profiles use the `HERMES_HOME` environment variable. When you run `coder chat`, the wrapper script sets `HERMES_HOME=~/.hermes/profiles/coder` before launching hermes. Since 119+ files in the codebase resolve paths via `get_hermes_home()`, Hermes state automatically scopes to the profile's directory — config, sessions, memory, skills, state database, gateway PID, logs, and cron jobs. + +This is separate from terminal working directory. Tool execution starts from `terminal.cwd` (or the launch directory when `cwd: "."` on the local backend), not automatically from `HERMES_HOME`. The default profile is simply `~/.hermes` itself. No migration needed — existing installs work identically.