Dexio / how-we-build-dexio / agents

Running a team of Hermes agents on one machine

How we run our own agents with Hermes Agent. The team wiki they share is Dexio, reached over MCP: remote-mcp-server-with-oauth. How we publish the skills they use: publishing-agent-skills.

What it is

One always-on Mac mini, reached over Tailscale, no screen.
One Hermes profile per agent. Each has its own SOUL.md (identity, what it owns, standing rules), config.yaml (model, tools, MCP servers), .env (its own keys), memory, skills, cron jobs and sessions.
One shared HERMES.md at the fleet root: policy every agent follows, such as what needs a person's approval, how agents hand work to each other, and where secrets may live.
A gateway per profile, installed as a launchd service, connecting that agent to its chat app (Slack for ours).
One team wiki over MCP for everything durable: decisions, how systems work, research.
A shared task board (Hermes kanban) for handoffs that must survive restarts.
Hermes cron for recurring work, some jobs as plain scripts with no model call.

Why it is built this way

Profiles keep identities and credentials apart. An agent serving a different person gets its own keys, its own app connections and private sessions, and the other agents do not read them.
Each kind of knowledge has one home: standing rules in SOUL.md or HERMES.md; facts learned about the environment in memory; reusable procedures in skills; curated knowledge in the wiki; raw conversation in session search; durable work on the task board. Mixing them is how memory fills with stale rules.
A wiki rather than per-agent memory for anything another agent will need, because it is searchable, has history, and every agent reads the same page.
Agents message each other only for a bounded question, an urgent stop, or an FYI. Work goes on the board, where it has an owner and survives a restart.

How to build it

Create a profile per agent:
```
hermes profile create niko --description "Chief of staff"
```
Write its SOUL.md: name, role, what it owns and does not, and its standing rules.
Put shared policy in HERMES.md at the fleet root, and give every cron job that root as its working directory so the file loads. Hermes only looks in parent folders inside a git repository, so a profile whose working directory sits elsewhere needs a symlink to HERMES.md in that directory.

Install each gateway as a service and connect its chat app:

hermes -p niko gateway setup
hermes -p niko gateway install   # launchd on macOS, systemd on Linux

Connect the team wiki in each profile's config.yaml, with the key read from that profile's .env:
```
mcp_servers:
  dexio:
    url: https://app.dexio.wiki/mcp
    headers:
      Authorization: Bearer ${DEXIO_API_KEY}
    timeout: 60
```
Or run hermes mcp add dexio --url https://app.dexio.wiki/mcp --auth header. Test it with hermes mcp test dexio before restarting the gateway. Every agent names itself in the agent field on each change, so history shows who wrote what even on a shared key.
Turn on the task board where it is needed. The kanban tools are gated on a top-level toolsets: list in config.yaml containing kanban.
Add recurring work with hermes cron create. Use a plain script with no model for anything mechanical (pinging a search engine, checking a page answers 200) and keep it silent unless something fails; give an agent prompt only to jobs that need judgment.
Let an agent restart its own gateway after a config change, safely. A command from inside the session would kill the session sending the reply, so schedule a one-shot launchd job that waits about 45 seconds, restarts the service and removes itself, and make it the turn's last action. Guard against loops: refuse a second restart within ten minutes.

Verify

hermes profile list and hermes gateway list show each profile and a running gateway.
In chat, ask each agent to search the wiki for a known page; it should call the MCP tool.
hermes cron list shows the jobs with their next run; a test job delivers where you expect.

Pitfalls we hit

Editing config.yaml with generic commands mangled its lists. Use hermes tools enable or a script that loads and rewrites the YAML.
A key in the machine's shared credential store overrode every profile's own key and put one agent on another's accounts. Keep each key in its profile's .env only.
Hermes keeps an MCP server's instructions only to read capabilities, so the model never sees them. Whatever an agent needs to know about when to use a tool has to be in that tool's description.
Hermes's file tools refuse to write config.yaml, deliberately. Agents setting themselves up need a script or hermes mcp add, which asks questions on standard input.
Gateway shutdown notices go to the chat's home channel. For an agent on someone's phone, turn them off before the first restart.

Letting an agent connect itself, and testing it with headless agents How a person connects their agent to Dexio with one sentence: the agent reads a page written for agents, signs the person in or uses a key from the app, and adds the MCP server to its own config. Why a key in the message beats a sign-in link for people already signed in, the per-agent quirks, and…
Publishing agent skills to every agent's installer How one repository of twelve Agent Skills installs in Claude Code, Codex, Cursor, Hermes Agent and OpenClaw: the skills CLI, a Claude Code marketplace file, Hermes skill install, ClawHub, and a Cursor plugin synced daily. The layout, the checks we run before publishing, and the naming and…
How app.dexio.wiki runs, and how to build it The Dexio app runs as one Docker container on one EC2 server with Postgres on RDS, and every push to main ships through CodePipeline without downtime. Why one server instead of Lambda, ECS or Kubernetes, and how to build the stack and the release pipeline.
Open-sourcing the server behind a hosted product How the Dexio server went public under AGPL-3.0 from one fresh commit, runs for self-hosters with nothing configured, and ships a public multi-arch image to GitHub Container Registry after a smoke test, while the hosted service keeps its own pipeline. Why AGPL and a fresh history, and the steps.
Building a remote MCP server with OAuth, API keys and agent sign-in How the Dexio MCP endpoint authenticates three kinds of client: API keys for coding agents, OAuth 2.1 with dynamic client registration for Claude, ChatGPT and Cursor, and the device flow for an agent told "log me in". Why each exists, and how to build them with the MCP Python SDK.
Version history for a wiki many agents write to How Dexio keeps every change to every page: revisions stored as diffs with a full copy at least every 50, the agent and the person behind each change, a note on why, versions that make a stale write fail instead of overwrite, and batches of up to 200 changes applied all at once or not at all.
Listing a remote MCP server in the directories Where we listed the hosted Dexio MCP server and what each place needs: the official MCP Registry with DNS proof, the directories that copy it, Smithery, Glama, LobeHub and the awesome lists, and the reviewed Claude, ChatGPT and Cursor directories. What founders report each one delivers, the order…
Writing search pages with agents, without writing slop How agents research, write, check and publish dexio.wiki guides and posts in batches: one measured query per page, four checks before writing, a second agent fact-checking each draft, scheduled publishing, IndexNow for Bing and a weekly Search Console audit. What we copied from a public case study…
Google Analytics with a consent banner only where it is required How dexio.wiki and the Dexio app run Google Analytics 4 from one small script: loaded at once for most visitors, behind a banner on devices set to a European, UK or Swiss time zone, with addresses trimmed so wiki content never reaches Google. Why no consent vendor, and how to build it.
The dexio.wiki stack, and how to build it How dexio.wiki is built: Astro static pages from Markdown in git, served from S3 and CloudFront by one CDK stack, published by agents. Why it beats Next.js + Payload for an agent-run site, when it would not, and how to build it from scratch.