Profile System and Distributions

We can use Hermes to createMultiple independent Agents—one for writing code, one for operations, one for research.

This chapter explains how the Profile system runs multiple fully isolated Agent instances on one machine, and how to package an entire Agent as a distribution to share with others.

Profile system: one machine, multiple independent Agents

What is a Profile

A Profile is a standalone Hermes home directory. Each Profile has its own fully isolated configuration and data:

~/.hermes/profiles/<name>/
├── config.yaml     # 模型、工具、终端后端等所有设置
├── .env            # API Key、Bot Token（各档案各自独立）
├── SOUL.md         # Agent 人格与身份设定
├── memories/       # 独立的持久记忆（MEMORY.md、USER.md）
├── skills/         # 独立的技能目录
├── cron/           # 独立的定时任务
└── state.db        # 独立的会话历史数据库

Key Design: After creating a Profile, it automatically becomes an independent command. Create a Profile named coder and you immediately havecoder chat、coder setup、coder gateway startand all subcommands—just like having a completely independent Hermes instance installed.

Quick start

Create an independent coding assistant in three steps:

Three creation modes

Switching and using Profiles

Determine which Profile you're currently in:

• Command prompt displaycoder ❯(rather than the usual❯）
• Startup banner displayProfile: coder
• Runhermes profileView current Profile name, path, model, gateway status

Differences between Profile, working directory, and sandbox

These are the three most easily confused concepts:

A Profile is not a sandbox—with the default local backend, the Agent still has the same filesystem permissions as you. If you need to restrict access scope, switch the terminal backend (see Chapter 05).

Make a Profile always start working from a specific directory:

Multi-Profile gateway: each Agent connects to a different platform

Each Profile runs its own independent gateway process, using its own Bot Token:

Security protection: if two Profiles accidentally use the same Bot Token, the second gateway will immediately report an error and indicate the conflicting Profile name, so no silent conflict occurs.

Profile management commands

Cannot delete the default profile (~/.hermes). To completely uninstall, use hermes uninstall.

Profile Distribution: share an entire Agent with others

Profile Distribution packages a complete Hermes Agent—persona settings, skills, scheduled tasks, MCP connections, configuration—into a Git repository.

Anyone can install the entire Agent with one command, and receive your updates while keeping their own memories, sessions, and API Key.

Distribution vs Profile backup

Scenarios suitable for distributions

• Distribute specialized Agents to teams (compliance monitoring, code review, research assistants)
• Deploy the same Agent to multiple machines without manually copying files
• Continuously iterate on the Agent, letting recipients get the latest version with one command
• Distribute Agents to the community as products

Creating and publishing distributions

Step 1: Add to an existing Profiledistribution.yaml：

Step 2: Push to a Git repository:

.env and auth.json are automatically excluded—API Keys won't enter the repository. Memory and session history are not included either.

Installing and updating distributions

Common commands quick reference