Per-User vs Root Installs: When Each Makes Sense

+15 Mana ✨
Installation Modes: Per-User and Root(DOCUMENTATION)

Introduction

The Hermes installer detects whether you ran it as your normal user or with sudo and lays things out differently in each case. Most users never need to think about this, the per-user install is correct for almost everyone. But on shared servers, build images, and multi-user dev boxes, the root layout is the right choice.

Key Concepts

  • Per-user install: Code in ~/.hermes/hermes-agent/, binary in ~/.local/bin/hermes, data in ~/.hermes/. Isolated to one user account.
  • Root install: Code in /usr/local/lib/hermes-agent/, binary in /usr/local/bin/hermes, data in /root/.hermes/ or $HERMES_HOME. System-wide.
  • $HERMES_HOME: Override variable that lets you point Hermes' data dir at a custom location.

Real World Context

A solo developer on their laptop should always pick per-user, it requires no admin rights, does not pollute system paths, and one user's Hermes cannot touch another's. A team building a Docker image that bakes in Hermes for CI should pick root, every container user gets the same hermes on PATH, and there is no per-user data to manage. A shared dev box where five engineers all want their own Hermes should be a mix: one root install of the binary, per-user data dirs via $HERMES_HOME.

Deep Dive

Decision criteria

text
Situation                               Pick
─────────────────────────────────────   ──────────
Personal laptop                         Per-user
Cloud dev container with one user       Per-user
Server with multiple human users        Root binary + per-user data
CI image / Dockerfile                   Root
Shared workstation, no admin rights     Per-user

The shared-machine pattern

On a shared box, you want every user to have their own conversations, credentials, and skills, but you want exactly one binary. The pattern:

bash
# Sysadmin installs once as root
sudo curl ... | sh

# Each user runs Hermes with their own data dir
export HERMES_HOME="$HOME/.hermes"
hermes

This way /usr/local/bin/hermes is shared, but state.db, credentials, and skills are isolated per user.

Why root mode follows FHS

The root layout (/usr/local/lib, /usr/local/bin) follows the Filesystem Hierarchy Standard, which is what package managers and sysadmins expect. This is what makes Hermes drop cleanly into a Dockerfile or a server provisioning script.

Common Pitfalls

  1. Running the installer with sudo to be safe, On a personal machine this just makes the install harder to manage. Per-user is the safer default.
  2. Mixing root and per-user installs, If you have installed both, you will have two binaries on PATH and confusing behavior. Pick one.

Best Practices

  1. Default to per-user, If in doubt, do not sudo. You can always add a root install later.
  2. Use $HERMES_HOME for shared boxes, One binary, many isolated data dirs is the cleanest multi-user pattern.

Summary

  • Per-user installs live entirely under your home directory and need no admin rights.
  • Root installs follow FHS conventions and are right for Docker images and shared servers.
  • $HERMES_HOME lets you separate the binary from the data dir for multi-user setups.

Code Examples

bash
# Shared dev box: one binary, isolated per-user data
sudo curl -fsSL https://hermes-agent.nousresearch.com/install.sh | sh

# In each user's shell profile (~/.zshrc, ~/.bashrc, ...)
export HERMES_HOME="$HOME/.hermes"

# Now /usr/local/bin/hermes is shared, but every user's state.db is isolated
hermes
✓ Completed