feat(upload): configurable attachment directory separate from active workspace root

[linkendr]

Feature description

Hermes WebUI currently saves chat attachments directly into the active session workspace root:

session.workspace / filename

This works functionally, but it creates clutter in the project/workspace directory when users attach reference documents, PDFs, screenshots, logs, or temporary files.

Motivation

In SSH/WebUI workflows, the active workspace is often a real project directory. When attaching files from a remote client, those files land in the project root even if they are only temporary context for the agent.

Example workflow:

• WebUI is accessed remotely, e.g. from Windows over SSH/Tailscale.
• Active workspace is a project directory.
• User attaches a document to a chat message.
• The attachment is written into the workspace root.
• The project directory accumulates unrelated uploaded files.

A cleaner approach would let operators keep uploads in a dedicated attachment inbox while still making them readable by the agent.

Proposed solution

Add a configurable upload/attachment directory separate from the active workspace root.

Possible configuration:

• Environment variable: HERMES_WEBUI_ATTACHMENT_DIR
• Or: HERMES_WEBUI_UPLOAD_DIR
• Optional setting in WebUI preferences.

Possible modes:

1. Global attachment directory:
   • ~/.hermes/webui/attachments/
2. Per-session attachment directory:
   • ~/.hermes/webui/attachments/<session_id>/
3. Per-workspace hidden directory:
   • <workspace>/.attachments/
   • or <workspace>/.hermes-webui/attachments/

The important behavior is:

• uploaded files should not be forced into the visible workspace root;
• the agent should still receive absolute paths to uploaded files;
• the UI can continue showing clean filenames;
• existing workspace-root behavior can remain the default for backward compatibility.

Current workaround

Users can switch the whole session workspace to a dedicated upload workspace, but that also changes the agent working directory. That is not ideal when the user wants to work inside a project while keeping attachments separate.

Related behavior

Existing upload handling already returns full paths for agent use. This request is specifically about making the upload destination configurable, not about attachment visibility or model access.

[nesquena-hermes]

@linkendr clean writeup — the workspace-clutter problem is real, and the existing "switch the whole session workspace" workaround forces a choice between project access and clean uploads, which isn't reasonable.

Direction

Going with a variant of your option 1 + global default:

• Add HERMES_WEBUI_ATTACHMENT_DIR env var. When set, all uploads land at <HERMES_WEBUI_ATTACHMENT_DIR>/<session_id>/<filename>.
• When unset, default to ~/.hermes/webui/attachments/<session_id>/ (your option 2). Keep the per-session subdir even in the global case — session-scoped cleanup is the obvious next thing users will want.
• Agent still receives absolute paths (no behavior change in how the model sees attachments).
• Add a Settings → System or Settings → Storage option exposing the same path so it's discoverable without docs-spelunking.

Default change is the important call here. Today the default is "uploads go to workspace root" which is the wrong default for SSH/Tailscale users with real project workspaces. Switching the default to ~/.hermes/webui/attachments/<sid>/ is the right thing, but it's a backward-compat break. Two options:

1. Switch default immediately (your option 2 as default). New behavior is strictly cleaner. Old behavior is recoverable via HERMES_WEBUI_ATTACHMENT_DIR=$WORKSPACE_ROOT or a setting toggle. This is what I'd ship.
2. Keep workspace-root as default, add the env var as opt-in. Safer migration but most users won't discover the cleaner mode.

Going with 1 — switching the default — is what I'd recommend. The cleanup path (delete the attachment dir when the session is archived/deleted) becomes free and obvious, and the workspace stays clean.

Implementation notes

• Upload handler currently writes to session.workspace / filename. Replace with a resolve_attachment_dir(session) helper that consults the env var → fallback chain.
• Per-session subdirectory must be created on first upload (not at session-create time — avoids empty dirs).
• Cleanup hook: on session archive/delete, the attachment dir should be removed too (with a guard so the helper never deletes anything outside HERMES_WEBUI_ATTACHMENT_DIR / ~/.hermes/).
• Existing sessions: keep working with their on-workspace attachments. Don't migrate. New uploads land in the new location.

Sprint shape

Labeling enhancement + workspace, Milestone 2 (Power user features). Probably ~150 LOC including the cleanup hook + tests + Settings UI. Reasonable pickup for any contributor — if you (@linkendr) want to drive it, that'd be great.

[nesquena-hermes]

Shipped — closing as resolved

HERMES_WEBUI_ATTACHMENT_DIR was implemented in api/upload.py and is now the documented way to move chat attachments out of the active workspace root. Both the single-file upload path and the archive-extraction path honor it:

Single-file uploads

api/upload.py:65-77 — _attachment_root():

def _attachment_root() -> Path:
    """Return the configured upload inbox root.

    Plain chat attachments are transient context for the agent, not project
    source files.  Keep them out of the active workspace by default while still
    allowing operators to move the inbox with HERMES_WEBUI_ATTACHMENT_DIR.
    """
    override = os.getenv('HERMES_WEBUI_ATTACHMENT_DIR', '').strip()
    if override:
        return Path(override).expanduser().resolve()
    return (STATE_DIR / 'attachments').resolve()

_session_attachment_dir(session_id) then writes uploads to <HERMES_WEBUI_ATTACHMENT_DIR>/<session_id>/<filename> (when set) or ~/.hermes/webui-state/attachments/<session_id>/<filename> by default — matching the design proposed here.

Archive extraction

Shipped in v0.51.91 via PR #2520 (@OneFat3): /api/upload/extract was routed through _session_attachment_dir so extracted archives land at <attachment_root>/<session_id>/<archive_stem>/ instead of being hardcoded into Path(s.workspace). Per-session isolation is preserved when HERMES_WEBUI_ATTACHMENT_DIR is configured.

How to use it

# Recommended for remote/SSH workflows where the workspace is a real project dir
export HERMES_WEBUI_ATTACHMENT_DIR=~/hermes-attachments

# Or unset for the default (~/.hermes/webui-state/attachments/<session_id>/)
unset HERMES_WEBUI_ATTACHMENT_DIR

Closing as resolved. Thanks @linkendr for the clean writeup.