hermes - 💡(How to fix) Fix [Bug]: Docker xurl docs can lead auth to be stored outside Hermes subprocess HOME [2 pull requests]

Bug Description

The Docker and xurl docs can lead users to store xurl auth in a location Hermes tool subprocesses will not read.

Docker docs describe /opt/data as the persistent state volume. The xurl docs say tokens persist to ~/.xurl. In Docker, users may reasonably run xurl auth with HOME=/opt/data, creating /opt/data/.xurl.

However, Hermes tool subprocesses can use the isolated subprocess HOME at $HERMES_HOME/home, which is /opt/data/home in the official Docker layout. So Hermes-run xurl commands look for /opt/data/home/.xurl.

The result is a successful OAuth flow followed by Hermes reporting no xurl apps/tokens.

Relevant docs:

• Docker docs, overview: https://hermes-agent.nousresearch.com/docs/user-guide/docker/#hermes-agent--docker
• Docker docs, quick start: https://hermes-agent.nousresearch.com/docs/user-guide/docker/#quick-start
• Docker docs, gateway mode: https://hermes-agent.nousresearch.com/docs/user-guide/docker/#running-in-gateway-mode
• Docker docs, persistent volumes: https://hermes-agent.nousresearch.com/docs/user-guide/docker/#persistent-volumes
• xurl docs, secret safety: https://hermes-agent.nousresearch.com/docs/user-guide/skills/bundled/social-media/social-media-xurl/#secret-safety-mandatory
• xurl docs, one-time setup: https://hermes-agent.nousresearch.com/docs/user-guide/skills/bundled/social-media/social-media-xurl/#one-time-user-setup-user-runs-these-outside-the-agent
• xurl docs, agent workflow: https://hermes-agent.nousresearch.com/docs/user-guide/skills/bundled/social-media/social-media-xurl/#agent-workflow
• xurl docs, notes: https://hermes-agent.nousresearch.com/docs/user-guide/skills/bundled/social-media/social-media-xurl/#notes
• Related subprocess HOME issue: https://github.com/NousResearch/hermes-agent/issues/12260

Steps to Reproduce

1. Run Hermes in Docker with /opt/data as the persistent data volume.

2. Install or include xurl in the image/container.

3. Authenticate xurl manually with the profile/state root as HOME:

   HOME=/opt/data xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
   HOME=/opt/data xurl auth oauth2 --app my-app USERNAME
   HOME=/opt/data xurl auth default my-app USERNAME

4. Verify this succeeds:

   HOME=/opt/data xurl auth status

5. Check from the HOME Hermes tool subprocesses use:

   HOME=/opt/data/home xurl auth status

6. It reports no registered apps/tokens.

Expected Behavior

The docs should make it clear that, for Dockerized Hermes, xurl auth must be created under the same HOME Hermes tool subprocesses use.

In the official Docker layout, that means xurl auth should land at:

/opt/data/home/.xurl

or more generally:

$HERMES_HOME/home/.xurl

Actual Behavior

The OAuth flow can succeed while storing credentials at:

/opt/data/.xurl

Hermes-run xurl commands then fail to see the app/token because they read:

/opt/data/home/.xurl

Affected Component

• Setup / Installation
• Tools (terminal, file ops, web, code execution, etc.)
• Skills (skill loading, skill hub, skill guard)

Messaging Platform

N/A (CLI only)

Debug Report

N/A - documentation/setup-path issue. The behavior is reproducible by comparing xurl auth status with HOME=/opt/data versus HOME=/opt/data/home.

Operating System

Ubuntu 24.04 / Docker

Python Version

N/A - Dockerized Hermes docs issue

Hermes Version

Observed on Dockerized Hermes v0.12-era checkout; related to #12260 subprocess HOME semantics.

Additional Logs / Traceback

N/A

Root Cause Analysis

The root cause is ambiguous documentation around ~/.xurl in Docker.

The xurl docs say tokens persist to ~/.xurl, while the Docker docs describe /opt/data as the persistent state volume. But Hermes tool subprocesses can run with HOME=$HERMES_HOME/home, so the effective ~/.xurl for Hermes-run tools is:

$HERMES_HOME/home/.xurl

not necessarily:

$HERMES_HOME/.xurl

This is related to the broader subprocess HOME behavior discussed in #12260.

Proposed Fix

Clarify this in the xurl skill docs and/or Docker docs.

Suggested wording:

When Hermes runs in Docker, run xurl auth with the same HOME used by Hermes tool subprocesses. In the official Docker layout this is /opt/data/home, so xurl credentials should exist at /opt/data/home/.xurl.

Example:

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 USERNAME
HOME=/opt/data/home xurl auth default my-app USERNAME
HOME=/opt/data/home xurl auth status

Also mention that ~/.xurl for Hermes-run tool commands resolves to $HERMES_HOME/home/.xurl, not necessarily $HERMES_HOME/.xurl.

Are you willing to submit a PR for this?

Not currently.