Security layers and architecture map
> Defense-in-depth before public bots — then a mental map of entry points and subsystems.
Canonical: https://www.brainyxai.co.za/education/hermes/security-and-architecture
Markdown: https://www.brainyxai.co.za/md/education/hermes/security-and-architecture.md
Course: Hermes Agent Operator Track
Lesson: 9 of 9
Minutes: 20
Author: Brainyx AI
What you will be able to do
- List the major security layers Hermes documents
- Apply allowlisting before public messaging
- Orient using the architecture overview for deeper study
Security is not optional for tool-using agents
Hermes documents a defense-in-depth model. Layers called out in the [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) guide include (paraphrased for teaching):
1. User authorization — who may talk to the agent (allowlists, DM pairing)
2. Dangerous command approval — human-in-the-loop for destructive ops
3. File write safety
4. Further layers around container isolation, production deployment practices, and related controls (read the full page — don’t stop at this summary)
Minimum bar for a messaging bot
- Allowlist your user IDs
- Prefer Docker/SSH backends with least privilege for untrusted prompts
- Keep approval on for destructive commands
- Separate “personal coding agent” profiles from “public support” profiles
- Rotate tokens; never paste them into Discord for debugging
Architecture map (for builders)
When you’re ready to go under the hood, start at [Architecture](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture). Entry points include CLI, Gateway, ACP adapter, batch runner, API server, and library use — feeding the agent loop, prompt assembly, context compression, session storage, and provider runtime.
You do not need the full architecture to operate Hermes daily. You do need it before you fork, embed, or debug weird gateway behavior.
Learning path next steps
Official [Learning Path](https://hermes-agent.nousresearch.com/docs/getting-started/learning-path) branches by experience and use case (CLI assistant, Telegram/Discord bot, automation, research/RL). After this course:
1. Deepen the feature that matches your use case (cron, voice, kanban, browser)
2. Read Tips & Best Practices in the Guides section
3. Keep [FAQ & Troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) bookmarked
Capstone idea
Run Hermes on a VPS with: Portal or OpenRouter model, one messaging platform (allowlisted), one MCP server (scoped), one cron digest, and a written security checklist. That is an operator-grade setup.
Security & capstone lab
1. Open the Security doc and tick each layer that applies to your setup.
2. If a messaging platform is enabled, verify only your account can invoke tools.
3. Draft a one-page runbook: install path, provider, gateway, MCP, backup of ~/.hermes, incident steps (revoke token).
Checkpoints
- Authorization is configured before any public bot
- I know where architecture docs live for deeper work
Layers, because any single control fails
No one control makes an agent safe. The workable posture is several independent layers, each assuming the one before it failed.
Identity — who may talk to it, enforced by allowlist rather than obscurity. Authorisation — which tools each context may reach, so a messaging user does not get the capabilities you use locally. Boundaries — the agent runs as a limited user, in a scoped directory, without production credentials in its environment. Rate and spend limits — enforced in your configuration, not left to the provider dashboard. Audit — every tool invocation and its arguments logged somewhere durable.
Skipping the boring layers is how a useful assistant becomes an incident.
Mapping your entry points
Draw your actual deployment. Every place input can enter is an attack surface: the local CLI, each messaging platform, every MCP server, and any scheduled trigger.
For each, answer three questions. Who can reach it? What tools does that path expose? What is logged? Paths where the answers are "anyone", "everything", and "nothing" are the ones to fix first.
This exercise takes twenty minutes and reliably surfaces something you had forgotten was enabled.
Prompt injection is a real threat here
An agent that reads external content — web pages, emails, documents, tickets — can encounter text written to manipulate it. Instructions hidden in a document telling it to exfiltrate data or take an action are not hypothetical.
The structural defence is that untrusted content must never be able to trigger a consequential action on its own. Keep irreversible actions behind human approval, separate the tools available when processing external content from those available in trusted contexts, and log enough that you could detect it afterwards.
POPIA and operating an agent in South Africa
If your agent touches personal information — and any customer-facing one does — POPIA applies to it exactly as to any other processing system.
Practically: know what personal information it can reach and why, minimise that to what the task requires, keep an audit trail of automated actions taken on customer records, apply retention rules to conversation logs, and understand that sending data to an overseas model provider is a cross-border transfer with its own requirements.
Brainyx AI's [POPIA and AI guide](https://www.brainyxai.co.za/popia-ai-and-data-compliance) covers this in more depth for South African operators.
Reviewing on a schedule
Security posture drifts as you add servers, tools, and platforms. Put a recurring review in the calendar: which tools are enabled and are they all still needed, who is on the allowlist and should they be, which credentials exist and can any be narrowed, and what do the logs show that you did not expect.
Quarterly is enough for personal use. Anything customer-facing deserves more often.
Mini-FAQ
A: Allowlist, per-user rate limits, tool restriction for that path, logging, and a spend cap. All five, not most.
A: Only through logs and spend alerts. If neither exists, you would find out from a customer, which is too late.
A: It removes the cross-border transfer question and adds full responsibility for securing the host. Different trade-off, not automatically better.
Where to go next
You have finished the Hermes Operator Track. Run the entry-point mapping exercise on your own setup this week. If the answer is that this has become business infrastructure, Brainyx AI builds [production agents](https://www.brainyxai.co.za/services/ai-agents) with these controls designed in from the start.
Official reference: https://hermes-agent.nousresearch.com/docs/user-guide/security
Course hub: https://www.brainyxai.co.za/education/hermes · Previous: https://www.brainyxai.co.za/education/hermes/mcp-integrations
Return to the course hub, or explore Brainyx AI services to put the skill into a live system. Markdown: /md/education/hermes/security-and-architecture.md
Book a consultation · joshua@brainyxai.co.za · Markdown mirrors