From 97792892098ca1ae94380d158825031495d732ac Mon Sep 17 00:00:00 2001 From: Sebastian Legarraga <64795732+slegarraga@users.noreply.github.com> Date: Wed, 20 May 2026 02:00:55 -0400 Subject: [PATCH] docs(xurl): clarify Docker auth HOME --- skills/social-media/xurl/SKILL.md | 14 +++++++++++++- website/docs/user-guide/docker.md | 15 +++++++++++++++ .../bundled/social-media/social-media-xurl.md | 14 +++++++++++++- 3 files changed, 41 insertions(+), 2 deletions(-) diff --git a/skills/social-media/xurl/SKILL.md b/skills/social-media/xurl/SKILL.md index 2fe23ef8575ad..9c81fe5e0ad95 100644 --- a/skills/social-media/xurl/SKILL.md +++ b/skills/social-media/xurl/SKILL.md @@ -1,7 +1,7 @@ --- name: xurl description: "X/Twitter via xurl CLI: post, search, DM, media, v2 API." -version: 1.1.1 +version: 1.1.2 author: xdevplatform + openclaw + Hermes Agent license: MIT platforms: [linux, macos] @@ -48,6 +48,8 @@ Forbidden flags in agent commands (they accept inline secrets): App credential registration and credential rotation must be done by the user manually, outside the agent session. After credentials are registered, the user authenticates with `xurl auth oauth2` — also outside the agent session. Tokens persist to `~/.xurl` in YAML. Each app has isolated tokens. OAuth 2.0 tokens auto-refresh. +When Hermes itself runs in Docker, remember that `~/.xurl` means the HOME of the process running `xurl`. Hermes tool subprocesses use `$HERMES_HOME/home` as HOME, so in the official Docker image (`HERMES_HOME=/opt/data`) agent-run `xurl` commands read credentials from `/opt/data/home/.xurl`, not `/opt/data/.xurl`. Run manual auth with `HOME=/opt/data/home` so the OAuth files land where Hermes will look. + --- ## Installation @@ -83,6 +85,16 @@ If `xurl` is installed but `auth status` shows no apps or tokens, the user needs These steps must be performed by the user directly, NOT by the agent, because they involve pasting secrets. Direct the user to this block; do not execute it for them. +:::tip Dockerized Hermes +If Hermes is running inside the official Docker image with `/opt/data` mounted as the data directory, run the setup commands with the same HOME Hermes tool subprocesses use: + +```bash +export HOME=/opt/data/home +``` + +This stores xurl credentials in `/opt/data/home/.xurl`. If you instead authenticate with `HOME=/opt/data`, the OAuth flow can succeed but Hermes-run `xurl` commands will still report no apps or tokens because they read `$HERMES_HOME/home/.xurl`. +::: + 1. Create or open an app at https://developer.x.com/en/portal/dashboard 2. Set the redirect URI to `http://localhost:8080/callback` 3. Copy the app's Client ID and Client Secret diff --git a/website/docs/user-guide/docker.md b/website/docs/user-guide/docker.md index 00720bcfa4889..6a777d6c2ff57 100644 --- a/website/docs/user-guide/docker.md +++ b/website/docs/user-guide/docker.md @@ -125,6 +125,21 @@ The `/opt/data` volume is the single source of truth for all Hermes state. It ma Never run two Hermes **gateway** containers against the same data directory simultaneously — session files and memory stores are not designed for concurrent write access. ::: +### Tool auth files and subprocess HOME + +Some CLI tools store OAuth state below `~`, not directly in `/opt/data`. Hermes tool subprocesses run with `HOME=$HERMES_HOME/home`; in this Docker layout that resolves to `/opt/data/home`. When a tool's docs mention `~/.tool-name`, create or verify that state under `/opt/data/home`, not `/opt/data`. + +For example, the bundled [`xurl` skill](./skills/bundled/social-media/social-media-xurl.md) stores X/Twitter OAuth state in `~/.xurl`. Inside the official Hermes container, run manual xurl setup yourself, outside an agent session, with: + +```sh +HOME=/opt/data/home xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET +HOME=/opt/data/home xurl auth oauth2 --app my-app YOUR_USERNAME +HOME=/opt/data/home xurl auth default my-app YOUR_USERNAME +HOME=/opt/data/home xurl auth status +``` + +Replace the placeholders in your own shell; do not paste client IDs, client secrets, or tokens into chat. If those commands are run with `HOME=/opt/data`, the OAuth flow can succeed but Hermes-run `xurl` commands will look in `/opt/data/home/.xurl` and report no apps or tokens. + ## Multi-profile support Hermes supports [multiple profiles](../reference/profile-commands.md) — separate `~/.hermes/` directories that let you run independent agents (different SOUL, skills, memory, sessions, credentials) from a single installation. **When running under Docker, using Hermes' built-in multi-profile feature is not recommended.** diff --git a/website/docs/user-guide/skills/bundled/social-media/social-media-xurl.md b/website/docs/user-guide/skills/bundled/social-media/social-media-xurl.md index 15ab18eea7f9f..1e5682b6893d0 100644 --- a/website/docs/user-guide/skills/bundled/social-media/social-media-xurl.md +++ b/website/docs/user-guide/skills/bundled/social-media/social-media-xurl.md @@ -16,7 +16,7 @@ X/Twitter via xurl CLI: post, search, DM, media, v2 API. |---|---| | Source | Bundled (installed by default) | | Path | `skills/social-media/xurl` | -| Version | `1.1.1` | +| Version | `1.1.2` | | Author | xdevplatform + openclaw + Hermes Agent | | License | MIT | | Platforms | linux, macos | @@ -62,6 +62,8 @@ Forbidden flags in agent commands (they accept inline secrets): App credential registration and credential rotation must be done by the user manually, outside the agent session. After credentials are registered, the user authenticates with `xurl auth oauth2` — also outside the agent session. Tokens persist to `~/.xurl` in YAML. Each app has isolated tokens. OAuth 2.0 tokens auto-refresh. +When Hermes itself runs in Docker, remember that `~/.xurl` means the HOME of the process running `xurl`. Hermes tool subprocesses use `$HERMES_HOME/home` as HOME, so in the official Docker image (`HERMES_HOME=/opt/data`) agent-run `xurl` commands read credentials from `/opt/data/home/.xurl`, not `/opt/data/.xurl`. Run manual auth with `HOME=/opt/data/home` so the OAuth files land where Hermes will look. + --- ## Installation @@ -97,6 +99,16 @@ If `xurl` is installed but `auth status` shows no apps or tokens, the user needs These steps must be performed by the user directly, NOT by the agent, because they involve pasting secrets. Direct the user to this block; do not execute it for them. +:::tip Dockerized Hermes +If Hermes is running inside the official Docker image with `/opt/data` mounted as the data directory, run the setup commands with the same HOME Hermes tool subprocesses use: + +```bash +export HOME=/opt/data/home +``` + +This stores xurl credentials in `/opt/data/home/.xurl`. If you instead authenticate with `HOME=/opt/data`, the OAuth flow can succeed but Hermes-run `xurl` commands will still report no apps or tokens because they read `$HERMES_HOME/home/.xurl`. +::: + 1. Create or open an app at https://developer.x.com/en/portal/dashboard 2. Set the redirect URI to `http://localhost:8080/callback` 3. Copy the app's Client ID and Client Secret