open-agent-setup
/open-agent-setup
Use when someone wants to install, set up, configure, run or deploy Open Agent Harness (a self-hosted Hermes + Slack team assistant) for their team, including cloning it, filling in .env, describing their team in SOUL.md, creating the Slack app, connecting Telegram, Jira, GitHub, Notion or Jev routing, moving it to a server, or fixing a setup that won't start. Use it even when they only say "set up Open Agent", "get it running" or "deploy the agent".
- Author
- globalmpc ↗
- Repository
- open-agent-harness ↗
- Licence
- MIT
- Last repository change
- 06.11.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 3
No signals detected. Repository changed on 06.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when someone wants to install, set up, configure, run or deploy Open Agent Harness (a self-hosted Hermes + Slack team assistant) for their team, including cloning it, filling in .env, describing their team in SOUL.md, creating the Slack app, connecting Telegram, Jira, GitHub, Notion or Jev routing, moving it to a server, or fixing a setup that won't start. Use it even when they only say "set up Open Agent", "get it running" or "deploy the agent".
Triggers from the description
Original author description
Use when someone wants to install, set up, configure, run or deploy Open Agent Harness (a self-hosted Hermes + Slack team assistant) for their team, including cloning it, filling in .env, describing their team in SOUL.md, creating the Slack app, connecting Telegram, Jira, GitHub, Notion or Jev routing, moving it to a server, or fixing a setup that won't start. Use it even when they only say "set up Open Agent", "get it running" or "deploy the agent".
How it works
- 0. Get the repository
- How to work
- Filling .env
- Start and verify
- Steps only the user can do
- Final message
SKILL.md preview
---
name: open-agent-setup
description: Use when someone wants to install, set up, configure, run or deploy Open Agent Harness (a self-hosted Hermes + Slack team assistant) for their team, including cloning it, filling in .env, describing their team in SOUL.md, creating the Slack app, connecting Telegram, Jira, GitHub, Notion or Jev routing, moving it to a server, or fixing a setup that won't start. Use it even when they only say "set up Open Agent", "get it running" or "deploy the agent".
---
# Set up Open Agent for a team
You are helping a team run their own copy of Open Agent Harness: a Hermes agent that answers questions in Slack
from the team's Slack and Telegram history, Jira, Notion and GitHub. Get them from nothing to a bot that answers in
Slack, changing only what their setup needs.
Paths in this file: `references/...` is next to this SKILL.md. Every other path (`README.md`, `.env`, `hermes/...`,
`docker-compose.yml`) is in the repository clone.
## 0. Get the repository
If the current directory is not a clone (no `docker-compose.yml` and `hermes/SOUL.md`), clone it where the user
wants it (default: `./open-agent`) and work from there:
```bash
git clone --recurse-submodules https://github.com/globalmpc/open-agent-harness.git open-agent
cd open-agent
```
If `hermes-agent/` is empty, run `git submodule update --init`; the build fails without it. Check that `git` and
`docker compose version` work; if Docker is missing, tell the user to install Docker Desktop (laptop) or see
`references/deploy-server.md` (server). Then read `README.md` once; it has the exact command for every step.
## How to work
1. **Collect what you need, once.** From the request, work out: model provider, API key and model id; which
sources (Slack is required; Telegram, Jira, GitHub, Notion, Jev are optional); who may use the bot; team time
zone; laptop or server; and facts about the team for SOUL.md (product, people and roles, internal words). Ask
only for what is missing, in one message. A source the user didn't mention stays off.
2. **Write `.env`** from `.env.example` (see "Filling .env").
3. **Describe the team** in the "About the project" block at the top of `hermes/SOUL.md`. Replace the Example
placeholders with their facts. Delete the GitHub, Notion and request-list lines they don't use. If the team
writes in a language other than English, add search synonyms in that language to step 2 of
`hermes/skills/team-history/SKILL.md`.
4. **Configure each chosen integration** and switch off the rest. Read `references/integrations.md` for the
files each one touches. When you remove an integration, also delete the lines about it in `hermes/SOUL.md`
and `hermes/skills/team-history/SKILL.md`, so the agent doesn't reach for a tool it no longer has.
5. **Start and verify** (see "Start and verify"). On a server, read `references/deploy-server.md` first.
6. **Report back** with the format in "Final message".
## Filling .env
- Copy `.env.example` to `.env`; never edit `.env.example` with real values. `.env` is git-ignored, and secrets
must stay out of git, chat messages and Slack. If the user pasted a key in chat, use it, but suggest rotating it
once setup works.
- Generate the three database passwords yourself with `openssl rand -hex 24`. Hex keeps them URL-safe, which
matters because they go into connection URLs.
- `LLM_BASE_URL` is always required, OpenAI included (`https://api.openai.com/v1`; OpenRouter is
`https://openrouter.ai/api/v1`). `AGENT_MODEL` is the provider's exact model id.
- `TEAM_TIMEZONE` is an IANA name such as `Europe/Berlin`. It sets "yesterday" for the nightly summary.
- Access: `SLACK_ALLOWED_USERS` takes Slack member IDs (they start with `U`). Leave `SLACK_ALLOW_ALL_USERS=false`
unless the user asks for the whole workspace. With both empty, nobody can use the bot; say so if you leave it
that way.
- Never invent a token. Leave unknown values empty and list them in the final message.
**Placeholder trap.** `docker-compose.yml` marks the model and Slack values as required (`${VAR:?}`), so every
`docker compose` command fails while they are empty, including the one that generates the Slack manifest. Before
the user has real Slack tokens, set `SLACK_BOT_TOKEN=pending` and `SLACK_APP_TOKEN=pending`, generate the manifest,
and replace them before starting the stack. The manifest command also mounts `data/hermes`, so run the first-run
`mkdir`/`touch` line (below) before it.
**Shell variables win.** Docker Compose prefers variables exported in the shell over `.env`. Don't `export` or
`source` `.env` in the user's shell; an exported empty value hides the real one.
## Start and verify
Run in this order from the repo root. Ask before running anything on a server or anything that starts the bot.
```bash
mkdir -p data/hermes/skills/team-history && touch data/hermes/config.yaml # first run only
docker compose up -d --build
docker compose ps # postgres, teamdb, jira (if kept), hermes, collector: all "running"
docker compose logs --tail 50 hermes # look for the Slack connection and connectors connecting
./db/check_permissions.sh # every line "ok"
docker compose exec hermes hermes cron create "0 1 * * *" "$(cat hermes/cron/nightly-summaries.md)" \
--name nightly-summaries --skill team-history
```
The `mkdir`/`touch` line exists because Docker Desktop cannot bind-mount a file whose host path is missing.
**Upgrading an older install** (compose project `pm-hermes`, database `pm`): follow "Upgrading from pm-hermes" in
`README.md` before the first `up`, or two stacks share `data/postgres` and the Slack app.
Reloading after a change:
| Changed | Run |
|---|---|
| `.env` | `docker compose up -d` (recreates containers whose values changed; `restart` keeps the old values) |
| `hermes/config.yaml`, `SOUL.md`, skills, plugins | `docker compose restart hermes` (`up -d` alone does not reload mounted files) |
| `docker-compose.yml` | `docker compose up -d` |
Finish with a live test: the user invites the bot (`/invite @Open-Agent`, or the name they gave it) and asks it
something in a channel. The history is empty until the collector has run (Slack every 5 minutes, Telegram backfills
on start), so a first answer of "nothing found" is expected. Check `docker compose logs collector` shows messages
being saved.
If a container keeps restarting, read its logs before changing anything. Common causes: an empty required
variable, a wrong `LLM_BASE_URL`, a model id the provider doesn't know, or `data/postgres` left over from an
earlier run with different passwords (the init script runs only on an empty `data/postgres`).
## Steps only the user can do
Some steps need the user's browser, phone or accounts. Give them the exact command or click path from
`README.md` and wait:
- creating and installing the Slack app, and copying its two tokens
- the Telegram login (`collector.login`) asks for a phone code
- the GitHub device-flow approval and the Notion OAuth login
- anything on a server you have no shell on
## Final message
End with these parts, in this order:
1. **Status:** one line saying what runs now and what is still off.
2. **What I changed:** each file and the change, one line each. Mention generated secrets only by name.
3. **Your next steps:** numbered, with exact commands or click paths, starting with anything blocking.
4. **Missing values:** each empty `.env` key you still need from them.
5. **Check it works:** the live test above.
Files in this package (3)
- SKILL.md 7 KB
- references/deploy-server.md 3 KB
- references/integrations.md 5 KB
Versions
The database has no other skills named open-agent-setup.
Database snapshot: 13.11.2026 · package version 29027ce831d9 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 96hermes-agent-factory
Use when creating or cloning a Hermes agent profile. - 100hermes-bot-team-design
Use this skill when an agent needs to design a team of specialist Hermes bots from a project specification. Covers role assignment, SOUL.md authoring, MCP wiring, and group chat setup. - 100open-swe
Open SWE is LangChain's open-source asynchronous coding agent: a self-hosted service that takes tasks from a dashboard, GitHub, Slack or Linear, works in an isolated sandbox and opens pull requests. Use when a user asks to deploy or run Open SWE, set up its GitHub App and Slack… - 100hermes2dsh
Migrate Hermes Agent (~/.hermes) data into DeepSeek Harness / DSH (~/.dsh) using the hermes2dsh CLI — preview dry-run first, then apply. Use when the user asks to import Hermes, migrate from Hermes to DSH, copy SOUL/memories/skills into ~/.dsh, or run hermes2dsh. - 100hermes-soul
Give a self-hosted Hermes v0.22.5 agent a name and personality by writing ~/.hermes/SOUL.md directly over SSH. Backs up the previous file, needs no gateway reload (new sessions read it from disk), and checks the result with a one-shot native call. Use when setting or updating… - 100gc-provider-install
Install, repair, or configure the GrowthCircle.id gc-provider for OpenClaw and Hermes Agent. Use this whenever a user asks to connect GrowthCircle AI Console keys, install gc-provider, install the Hermes GrowthCircle model-provider plugin, configure GrowthCircle as an…