Profile Distributions: 전체 agent 공유

profile distribution은 완성된 Hermes agent 전체를 git repository로 package하는 방식입니다. personality, skills, cron jobs, MCP connections, config를 한 repo에 담습니다. repo에 접근할 수 있는 사람은 한 command로 agent를 설치하고, 제자리에서 update하며, 자신의 memories, sessions, API keys는 그대로 유지할 수 있습니다.

profile이 local agent라면, distribution은 그 agent를 shareable하게 만든 형태입니다.

What this means

distribution이 없을 때 Hermes agent를 공유하려면 보통 다음을 따로 보내야 했습니다.

1. SOUL.md
2. 설치해야 할 skills 목록
3. secret을 제거한 config.yaml
4. 연결한 MCP server 설명
5. 예약해 둔 cron jobs
6. 설정해야 할 env vars 안내

그리고 상대방이 그것을 제대로 조립하기를 기대해야 했습니다. version bump나 bug fix가 있을 때마다 같은 handoff를 반복해야 했습니다.

distribution을 쓰면 이 모든 것이 하나의 git repo에 들어갑니다.

my-research-agent/
|-- distribution.yaml    # manifest: name, version, env-var requirements
|-- SOUL.md              # the agent's personality / system prompt
|-- config.yaml          # model, temperature, reasoning, tool defaults
|-- skills/              # bundled skills that come with the agent
|-- cron/                # scheduled tasks the agent runs
`-- mcp.json             # MCP servers the agent connects to

받는 사람은 다음 command를 실행합니다.

hermes profile install github.com/you/my-research-agent --alias

그러면 전체 agent가 설치됩니다. 각 사용자는 자기 API key를 채웁니다(.env.EXAMPLE -> .env). 이후 my-research-agent chat으로 실행하거나 Telegram / Discord / Slack / gateway platform을 통해 호출할 수 있습니다. author가 새 version을 push하면 installer는 hermes profile update my-research-agent를 실행해 변경 사항을 가져옵니다. installer의 memories와 sessions는 그대로 유지됩니다.

Why git?

tarball, HTTP archive, custom format도 고려했지만 git보다 나은 선택은 없었습니다.

• author에게 build step이 없습니다. GitHub에 push하면 consumer가 install합니다. "pack this, upload that, update the index" loop가 없습니다.
• tags, branches, commits가 이미 versioning system입니다. tag push가 다른 tool의 "pack + upload a release" 역할을 합니다.
• update는 fetch입니다. 전체 archive를 다시 download하지 않습니다.
• transparent합니다. 사용자는 repo를 browse하고, version 간 diff를 읽고, issue를 열고, fork해 customize할 수 있습니다.
• private repo도 별도 비용 없이 동작합니다. SSH keys, git credential helpers, GitHub CLI stored credentials 등 terminal에 이미 설정된 auth가 그대로 적용됩니다.
• reproducibility는 commit SHA입니다. pip와 npm이 기록하는 방식과 같습니다.

tradeoff는 installer에게 git이 필요하다는 점입니다. 하지만 2026년에 Hermes를 실행하는 machine이라면 git은 사실상 이미 설치되어 있습니다.

When should you use a distribution?

잘 맞는 경우:

• specialized agent를 공유할 때. 예: compliance monitor, code reviewer, research assistant, customer-support bot을 team이나 community에 배포.
• 같은 agent를 여러 machine에 배포하고 싶고 매번 file을 수동 copy하고 싶지 않을 때.
• agent를 계속 개선하고 있고 recipient가 한 command로 새 version을 받게 하고 싶을 때.
• agent를 product처럼 제공할 때. opinionated defaults, curated skills, tuned prompts를 다른 사람이 starting point로 쓰게 만들 수 있습니다.

맞지 않는 경우:

• 자기 machine의 profile을 backup하려는 목적. 이때는 hermes profile export / import를 사용하세요.
• agent와 함께 API key를 공유하려는 목적. auth.json과 .env는 distribution에서 의도적으로 제외됩니다. installer가 자신의 credential을 제공합니다.
• memories / sessions / conversation history를 공유하려는 목적. 이들은 user data이며 distribution content가 아닙니다. 절대 함께 배포되지 않습니다.

The lifecycle: author to installer to update

아래는 authoring부터 install, update까지의 end-to-end flow입니다. 본인에게 필요한 쪽을 보면 됩니다.

---

For authors: publishing a distribution

Step 1 - Start from a working profile

다른 profile과 마찬가지로 agent를 만들고 다듬습니다.

hermes profile create research-bot
research-bot setup                    # configure model, API keys
# Edit ~/.hermes/profiles/research-bot/SOUL.md
# Install skills, wire up MCP servers, schedule cron jobs, etc.
research-bot chat                     # dogfood until it feels right

Step 2 - Add a distribution.yaml

~/.hermes/profiles/research-bot/distribution.yaml을 만듭니다.

name: research-bot
version: 1.0.0
description: "Autonomous research assistant with arXiv and web tools"
hermes_requires: ">=0.12.0"
author: "Your Name"
license: "MIT"

# Tell installers which env vars the agent needs. These are checked against
# the installer's shell and existing .env file so they don't get nagged
# about keys they already have configured.
env_requires:
  - name: OPENAI_API_KEY
    description: "OpenAI API key (for model access)"
    required: true
  - name: SERPAPI_KEY
    description: "SerpAPI key for web search"
    required: false
    default: ""

manifest는 이것이 전부입니다. name을 제외한 모든 field에는 reasonable default가 있습니다.

Step 3 - Push to a git repo

cd ~/.hermes/profiles/research-bot
git init
git add .
git commit -m "v1.0.0"
git remote add origin git@github.com:you/research-bot.git
git tag v1.0.0
git push -u origin main --tags

이제 repo가 distribution입니다. 접근 권한이 있는 사람은 설치할 수 있습니다.

노트

git repo에는 distribution에서 이미 제외되는 항목을 뺀 profile directory 전체가 들어갑니다. 제외 항목은 auth.json, .env, memories/, sessions/, state.db*, logs/, workspace/, *_cache/, local/입니다. 이들은 author machine에 남습니다. 추가로 제외하고 싶은 path가 있으면 .gitignore를 넣어도 됩니다.

Step 4 - Tag versioned releases

agent가 안정적인 지점에 도달할 때마다 version을 올리고 tag를 붙입니다.

# Edit distribution.yaml: version: 1.1.0
git add distribution.yaml SOUL.md skills/
git commit -m "v1.1.0: tighter research SOUL, add arxiv skill"
git tag v1.1.0
git push --tags

recipient가 hermes profile update research-bot를 실행하면 latest version을 pull합니다.

What the repo looks like

완성된 authored distribution 예시:

research-bot/
|-- distribution.yaml            # required
|-- SOUL.md                      # strongly recommended
|-- config.yaml                  # model, provider, tool defaults
|-- mcp.json                     # MCP server connections
|-- skills/
|   |-- arxiv-search/SKILL.md
|   |-- paper-summarization/SKILL.md
|   `-- citation-lookup/SKILL.md
|-- cron/
|   `-- weekly-digest.json       # scheduled tasks
`-- README.md                    # human-facing description (optional)

Distribution-owned vs user-owned

installer가 새 version으로 update할 때 어떤 것은 교체되고(author의 영역), 어떤 것은 그대로 유지됩니다(installer의 영역). 기본값은 다음과 같습니다.

Category	Paths	On update
Distribution-owned	SOUL.md, config.yaml, mcp.json, skills/, cron/, distribution.yaml	새 clone의 내용으로 교체
Config override	config.yaml	실제로는 기본적으로 보존됩니다. installer가 model이나 provider를 조정했을 수 있기 때문입니다. update 때 초기값으로 되돌리려면 --force-config를 사용하세요.
User-owned	memories/, sessions/, state.db*, auth.json, .env, logs/, workspace/, plans/, home/, *_cache/, local/	절대 건드리지 않음

manifest에서 distribution-owned list를 override할 수도 있습니다.

distribution_owned:
  - SOUL.md
  - skills/research/            # only my research skills; other installed skills stay
  - cron/digest.json

생략하면 위 기본값이 적용됩니다. 대부분의 distribution에는 이 기본값이 맞습니다.

---

For installers: using a distribution

Install

hermes profile install github.com/you/research-bot --alias

실행 시 처리되는 일:

1. repo를 temporary directory로 clone합니다.
2. distribution.yaml을 읽고 manifest(name, version, description, author, required env vars)를 보여줍니다.
3. 각 required env var를 shell environment와 target profile의 기존 .env에서 확인합니다. 각 항목을 set 또는 needs setting으로 표시하므로 무엇을 설정해야 하는지 바로 알 수 있습니다.
4. confirmation을 요청합니다. -y / --yes를 주면 건너뜁니다.
5. distribution-owned files를 ~/.hermes/profiles/research-bot/ 또는 manifest의 name이 resolve되는 위치로 copy합니다.
6. 필요한 key가 주석으로 들어 있는 .env.EXAMPLE을 씁니다. 이를 .env로 copy해 값을 채우면 됩니다.
7. --alias를 주면 research-bot chat처럼 바로 실행할 수 있는 wrapper를 만듭니다.

Source types

git URL이면 어떤 형식이든 사용할 수 있습니다.

# GitHub shorthand
hermes profile install github.com/you/research-bot

# Full HTTPS
hermes profile install https://github.com/you/research-bot.git

# SSH
hermes profile install git@github.com:you/research-bot.git

# Self-hosted, GitLab, Gitea, Forgejo - any Git host
hermes profile install https://git.example.com/team/research-bot.git

# Private repo using your configured git auth
hermes profile install git@github.com:your-org/internal-bot.git

# Local directory during development (no git push needed)
hermes profile install ~/my-profile-in-progress/

Override the profile name

같은 distribution을 서로 다른 local profile name으로 설치할 수 있습니다.

# Alice
hermes profile install github.com/acme/support-bot --name support-us --alias
# Bob (same distribution, different local name)
hermes profile install github.com/acme/support-bot --name support-eu --alias

Fill in env vars

설치 후 agent profile에는 .env.EXAMPLE이 생깁니다.

# Environment variables required by this Hermes distribution.
# Copy to `.env` and fill in your own values before running.

# OpenAI API key (for model access)
# (required)
OPENAI_API_KEY=

# SerpAPI key for web search
# (optional)
# SERPAPI_KEY=

copy한 뒤:

cp ~/.hermes/profiles/research-bot/.env.EXAMPLE ~/.hermes/profiles/research-bot/.env
# Edit .env, paste your real keys

이미 shell environment에 있는 required key, 예를 들어 ~/.zshrc에서 export한 OPENAI_API_KEY는 install 중 set으로 표시됩니다. 이런 key는 .env에 중복해서 넣을 필요가 없습니다.

Check what you installed

hermes profile info research-bot

출력 예:

Distribution: research-bot
Version:      1.0.0
Description:  Autonomous research assistant with arXiv and web tools
Author:       Your Name
Requires:     Hermes >=0.12.0
Source:       https://github.com/you/research-bot
Installed:    2026-05-08T17:04:32+00:00

Environment variables:
  OPENAI_API_KEY (required) - OpenAI API key (for model access)
  SERPAPI_KEY (optional) - SerpAPI key for web search

hermes profile list에는 Distribution column도 표시되므로 어떤 profile이 repo에서 왔고 어떤 profile을 직접 만들었는지 한눈에 볼 수 있습니다.

Profile       Model              Gateway   Alias         Distribution
default       claude-sonnet-4    stopped   -             -
coder         gpt-5              stopped   coder         -
research-bot  claude-opus-4      stopped   research-bot  research-bot@1.0.0
telemetry     claude-sonnet-4    running   telemetry     telemetry@2.3.1

Update

hermes profile update research-bot

실행 시 처리되는 일:

1. recorded source URL에서 repo를 다시 clone합니다.
2. distribution-owned files(SOUL, skills, cron, mcp.json)를 교체합니다.
3. 사용자의 config.yaml은 보존합니다. model, temperature, 기타 setting을 installer가 조정했을 수 있기 때문입니다. overwrite하려면 --force-config를 사용하세요.
4. user data는 절대 건드리지 않습니다. memories, sessions, auth, .env, logs, state가 여기에 포함됩니다.

전체 archive를 다시 download하지 않습니다. local config 변경을 덮어쓰지 않습니다. conversation history를 삭제하지 않습니다.

Remove

hermes profile delete research-bot

delete prompt는 confirmation 전에 distribution info를 보여줍니다.

Profile: research-bot
Path:    ~/.hermes/profiles/research-bot
Model:   claude-opus-4 (anthropic)
Skills:  12
Distribution: research-bot@1.0.0
Installed from: https://github.com/you/research-bot

This will permanently delete:
  - All config, API keys, memories, sessions, skills, cron jobs
  - Command alias (~/.local/bin/research-bot)

Type 'research-bot' to confirm:

따라서 agent가 어디에서 설치되었는지, 다시 설치할 수 있는지 모른 채 실수로 삭제하는 일을 줄일 수 있습니다.

---

Use cases and patterns

Personal: sync one agent across machines

laptop에서 만든 research assistant를 workstation에서도 쓰고 싶은 경우:

# Laptop
cd ~/.hermes/profiles/research-bot
git init && git add . && git commit -m "initial"
git remote add origin git@github.com:you/research-bot.git
git push -u origin main

# Workstation
hermes profile install github.com/you/research-bot --alias
# Fill in .env. Done.

laptop에서 iteration한 뒤 git commit && push를 하면 workstation에서 hermes profile update research-bot로 가져옵니다. memories는 machine별로 유지됩니다. laptop은 laptop의 conversation을 기억하고, workstation은 workstation의 conversation을 기억합니다. 서로 충돌하지 않습니다.

Team: ship a reviewed internal agent

engineering team이 특정 SOUL, specific skills, 모든 PR을 검토하는 cron을 가진 shared PR-review bot을 원한다고 가정합니다.

# Engineering lead
cd ~/.hermes/profiles/pr-reviewer
# ... build and tune ...
git init && git add . && git commit -m "v1.0 PR reviewer"
git tag v1.0.0
git push -u origin main --tags    # push to your company's internal Git host

# Each engineer
hermes profile install git@github.com:your-org/pr-reviewer.git --alias
# Fill in .env with their own API key (billed to them), .env.EXAMPLE points at what's required
pr-reviewer chat

lead가 v1.1을 ship하면, 예를 들어 더 나은 SOUL이나 새 skill이 추가되면, engineers는 hermes profile update pr-reviewer를 실행하고 몇 분 안에 모두 같은 version을 사용하게 됩니다.

Community: publish a public agent

"Polymarket trader", "academic paper summarizer", "Minecraft server ops assistant"처럼 공유할 만한 agent를 만들었다고 가정합니다.

# You
cd ~/.hermes/profiles/polymarket-trader
# Write a solid README.md at the repo root - GitHub shows it on the repo page
git init && git add . && git commit -m "v1.0"
git tag v1.0.0
# Publish to a public GitHub repo
git remote add origin https://github.com/you/hermes-polymarket-trader.git
git push -u origin main --tags

# Anyone
hermes profile install github.com/you/hermes-polymarket-trader --alias

install command를 공개하면 사용자가 써 보고 issues와 PRs를 보낼 수 있습니다. customize하고 싶은 사람은 fork하면 됩니다. 모두가 이미 아는 git workflow입니다.

Product: ship an opinionated agent

Hermes 위에 compliance-monitoring harness, customer-support stack, domain-specific research platform 같은 product를 만들었다고 가정합니다.

# distribution.yaml
name: telemetry-harness
version: 2.3.1
description: "Compliance telemetry harness - monitors and reviews regulated workflows"
hermes_requires: ">=0.13.0"
author: "Acme Compliance Inc."
license: "Commercial"

env_requires:
  - name: ACME_API_KEY
    description: "Your Acme Compliance license key (email support@acme.com)"
    required: true
  - name: OPENAI_API_KEY
    description: "OpenAI API key for model access"
    required: true
  - name: GRAPHITI_MCP_URL
    description: "URL for your Graphiti knowledge graph instance"
    required: false
    default: "http://127.0.0.1:8000/sse"

customer는 한 command로 설치합니다. install preview가 준비해야 할 key를 정확히 알려 줍니다. 새 release에 tag를 붙이면 update가 rollout됩니다. customer의 compliance data(memories/, sessions/)는 machine 밖으로 나가지 않습니다.

Ephemeral: one-off scripts on shared infra

ops lead가 production incident를 진단하는 temporary agent를 만들고 싶다고 가정합니다. 적절한 tools와 MCP connections가 있는 canned SOUL을 준비해, 다음 주 동안 세 명의 on-call engineer laptop에서 실행하는 형태입니다.

# You
# Build the profile, commit, push a private repo
git push -u origin main

# Each on-call
hermes profile install git@github.com:your-org/incident-2026-q2.git --alias

# Incident resolved - tear it down
hermes profile delete incident-2026-q2

install-delete cycle이 충분히 가볍기 때문에 disposable하게 사용할 수 있습니다.

---

Recipes

Pin to a specific version

노트

Git ref pinning(#v1.2.0)은 planned feature이지만 initial release에는 포함되지 않았습니다. 현재 install은 default branch를 tracking합니다. 설치된 version은 hermes profile info <name>으로 확인하고, 준비되기 전까지 update를 보류하세요.

Check what version you're on vs. latest

# Your installed version
hermes profile info research-bot | grep Version

# Latest upstream (without installing)
git ls-remote --tags https://github.com/you/research-bot | tail -5

Keep local config customizations through updates

기본 update behavior가 이미 local config.yaml을 보존합니다. 더 안전하게 관리하려면 distribution이 소유하지 않는 file에 local tweak를 적어 두세요.

# ~/.hermes/profiles/research-bot/local/my-overrides.yaml
# (distribution never touches local/)

그리고 필요하면 config.yaml이나 SOUL에서 참조하세요.

Force a clean re-install

# Nuke and re-install from scratch (loses memories/sessions too)
hermes profile delete research-bot --yes
hermes profile install github.com/you/research-bot --alias

# Update to current main but reset config.yaml to the distribution's default
hermes profile update research-bot --force-config --yes

Fork and customize

distribution은 그냥 repo이므로 표준 git workflow를 사용합니다.

# Fork the repo on GitHub, then install your fork
hermes profile install github.com/yourname/forked-research-bot --alias

# Iterate locally in ~/.hermes/profiles/forked-research-bot/
# Edit SOUL.md, commit, push to your fork
# Upstream changes: pull them into your fork the usual way

Test a distribution before pushing

author machine에서 local directory로 설치해 test할 수 있습니다.

# Install from a local directory (no git push needed)
hermes profile install ~/.hermes/profiles/research-bot --name research-bot-test --alias

# Tweak, delete, re-install until it's right
hermes profile delete research-bot-test --yes
hermes profile install ~/.hermes/profiles/research-bot --name research-bot-test

---

What's NOT in a distribution (ever)

author가 실수로 포함해도 installer는 다음 path를 hard-exclude합니다. 이 safety guard는 regression-tested invariant이며 override할 수 있는 config option이 없습니다.

• auth.json - OAuth tokens, platform credentials
• .env - API keys, secrets
• memories/ - conversation memory
• sessions/ - conversation history
• state.db, state.db-shm, state.db-wal - session metadata
• logs/ - agent and error logs
• workspace/ - generated working files
• plans/ - scratch plans
• home/ - Docker backend의 user home mount
• *_cache/ - image / audio / document caches
• local/ - user-reserved customization namespace

distribution을 clone하면 이들은 아예 들어 있지 않습니다. update할 때도 그대로 유지됩니다. 같은 distribution을 다섯 machine에 설치하면 machine마다 별도 data set을 가집니다.

Security and trust

profile distributions는 기본적으로 unsigned입니다. 사용자는 다음을 신뢰하는 것입니다.

• git host(GitHub / GitLab / 기타)가 author가 push한 bytes를 그대로 제공한다는 점.
• author가 malicious SOUL, skills, cron jobs를 넣지 않았다는 점.

distribution의 cron jobs는 자동으로 schedule되지 않습니다. installer는 hermes -p <name> cron list 출력으로 확인한 뒤 명시적으로 enable해야 합니다. 반면 SOUL.md와 skills는 profile로 chat을 시작하는 즉시 active입니다. 모르는 사람의 distribution을 설치한다면 첫 실행 전에 읽어보세요.

비유하자면 distribution 설치는 browser extension이나 VS Code extension 설치와 비슷합니다. friction은 낮고 power는 큽니다. source를 신뢰해야 합니다. company 내부 distribution이라면 private repo와 기존 git auth를 쓰면 됩니다. 새로 설정할 것은 없습니다.

future version에서는 signing, resolved commit SHA가 들어 있는 lockfile(.distribution-lock.yaml), update 적용 전 diff를 보여주는 --dry-run flag가 추가될 수 있습니다. 아직 shipping되지는 않았습니다.

Under the hood

implementation detail, 정확한 CLI behavior, 모든 flag는 Profile Commands reference를 참고하세요.

짧게 요약하면:

• install, update, info는 별도 command tree가 아니라 hermes profile 안에 있습니다.
• manifest format은 YAML이며 required schema는 아주 작습니다. name만 필수입니다.
• installer는 local git binary로 clone합니다. 따라서 shell에서 이미 처리되는 auth(SSH keys, credential helpers)가 그대로 동작합니다.
• clone 후 .git/은 제거됩니다. 설치된 profile 자체가 git checkout이 아니므로 "실수로 .env를 distribution git history에 commit"하는 사고를 줄입니다.
• reserved profile names(hermes, test, tmp, root, sudo)는 common binary와 충돌하지 않도록 install time에 거부됩니다.

See also

• Profiles: Running Multiple Agents - base concept
• Profile Commands reference - every flag, every option
• hermes profile export / import - local backup / restore(distribution 아님)
• Using SOUL with Hermes - authoring personalities
• Personality & SOUL - SOUL이 agent에 적용되는 방식
• Skills catalog - bundle할 수 있는 skills