Hermes Agent (NousResearch) running inside NVIDIA OpenShell.

OpenShell is NVIDIA's kernel-level sandbox for AI agents — it gates every outbound network call, filesystem touch, and risky syscall from outside the agent's process, so a compromised tool or skill cannot punch through. HermesShell drops NousResearch's Hermes Agent into that sandbox and adds a multi-sandbox lifecycle CLI, composable policy presets, and persistent per-sandbox memory on top. Hermes keeps its full toolset; the kernel keeps the blast radius bounded.

---

Table of Contents

• Architecture
• Quick Start
  • Recommended — one-command install
  • Build from source
  • OpenShell sandbox (full hardware enforcement)
• What OpenShell Enforces
• Policy Tiers & Presets
• Hermes Features
• Skills Library
• Use Cases
• HermesShell vs NemoClaw
• CLI Reference
• Personalise Hermes
• Project Structure
• Diagnostics & Testing
• Contributing
• Related Projects

---

Architecture

The hermesshell CLI runs on the host and manages a fleet of isolated Hermes sandboxes — each with its own persona, credentials, persistent memory, skills, and policy tier. OpenShell wraps every sandbox with Landlock (filesystem), seccomp (syscalls), and an OPA + L7 proxy (network egress). Inside the sandbox, the agent talks to a single virtual endpoint, inference.local; OpenShell intercepts that call and routes it to whichever backend each sandbox was configured for. Hermes never knows it is sandboxed.

flowchart TB
User(["User input<br/>chat - messaging - API"]) --> CLI
subgraph host [Host machine]
CLI["hermesshell CLI<br/>onboard - chat - policy - snapshot - destroy - ..."]
Reg[("~/.hermesshell/<br/>registry.json + credentials")]
CLI --- Reg
end
CLI --> sbA
CLI --> sbB
CLI --> sbC
subgraph sbA [mybot - tier balanced]
AgentA[Hermes Agent]
StateA[("MEMORY.md - USER.md - skills/")]
AgentA --- StateA
end
subgraph sbB [support - tier open]
AgentB[Hermes Agent]
StateB[("MEMORY.md - USER.md - skills/")]
AgentB --- StateB
end
subgraph sbC [privacy - tier restricted]
AgentC[Hermes Agent]
StateC[("MEMORY.md - USER.md - skills/")]
AgentC --- StateC
end
sbA -->|"inference.local"| Router
sbB -->|"inference.local"| Router
sbC -->|"inference.local"| Router
Router["Inference router<br/>(OpenShell, per-sandbox config)"]
Router --> Local["Local: llama.cpp - Ollama - vLLM"]
Router --> Cloud["Cloud: NVIDIA NIM - OpenAI - Anthropic - Gemini"]

Loading

---

Quick Start

Recommended — one-command install

Clones the repo to ~/.hermesshell, installs Node.js (via nvm) if needed, builds the hermesshell CLI, and launches the interactive onboard wizard which walks you through provider selection, model configuration, policy tier, and sandbox creation:

curl -fsSL https://raw.githubusercontent.com/ppritcha/hermesshell/main/scripts/install.sh | bash

Prerequisites: docker, git, curl. Docker Desktop (macOS / Windows) or dockerd (Linux) must be running. Node.js >= 20 is installed automatically if missing.

The onboard wizard configures everything interactively. Once complete:

hermesshell mybot chat "hello"
hermesshell list # see all sandboxes
hermesshell mybot snapshot create # point-in-time backup

To re-run onboard later (e.g. switch providers): hermesshell onboard.

---

Build from source (if you want to modify HermesShell itself)

git clone https://github.com/ppritcha/hermesshell
cd hermesshell
cd cli && npm install && npm run build && npm link &&cd ..
hermesshell onboard

---

OpenShell sandbox (full hardware enforcement)

Requires Linux + NVIDIA GPU + OpenShell installed.

# Install OpenShell (requires NVIDIA account)
curl -fsSL https://www.nvidia.com/openshell.sh | bash
# Install HermesShell via the one-liner above — the onboard wizard# detects OpenShell and configures the sandbox automatically.
hermesshell mybot chat "hello"
hermesshell list # see all sandboxes
hermesshell mybot snapshot create # point-in-time backup

Full CLI reference: hermesshell CLI. Diagnostics: hermesshell doctor.

---

What OpenShell Enforces

Layer	Mechanism	Rule
Network	OPA + HTTP CONNECT proxy	Egress to approved hosts only — all else blocked
Filesystem	Landlock LSM	~/.hermes/ + /sandbox/ + /tmp/ only
Process	Seccomp BPF	ptrace, mount, kexec_load, perf_event_open, process_vm_* blocked
Inference	Privacy router	Credentials stripped from agent; backend credentials injected by OpenShell

All four layers are enforced out-of-process — even a fully compromised Hermes instance cannot override them.

---

Policy Tiers & Presets

The onboard wizard selects a policy tier which determines the default set of network presets. You can add or remove individual presets at any time without restarting the sandbox:

hermesshell mybot policy add github # allow GitHub API access
hermesshell mybot policy remove slack # revoke Slack access
hermesshell mybot policy list # show active presets

Tiers (selected during onboard)

Tier	Default Presets	Description
restricted	(none)	Inference only — no external network access
balanced	npm, pypi, huggingface, brave, github	Development + research
open	balanced + slack, discord, telegram	Full messaging + development

Available Presets

Preset	Access Granted
npm	npm / Yarn registries
pypi	PyPI package index
huggingface	Hugging Face Hub + CDN
brave	Brave Search API
github	GitHub API + raw content
slack	Slack API + websocket gateway
discord	Discord API + gateway + CDN
telegram	Telegram Bot API

Presets are composable YAML fragments in openshell/presets/. Each is merged with openshell/baseline.yaml to produce the active policy.

---

Hermes Features Inside the Sandbox

Feature	Status	Notes
hermes chat	✅	Routes via inference.local → configured backend (Ollama, llama.cpp, NIM, …)
Persistent state under ~/.hermes/	✅	SOUL.md, memories/MEMORY.md, memories/USER.md, skills, sessions; survives sandbox recreation
Skills library	✅	Stored in ~/.hermes/skills/; manage with hermes skills
Built-in toolsets	✅	web, browser, terminal, file, code_execution, vision, image_gen, … (hermes tools)
Cron / scheduled tasks	✅	hermes cron create
MCP server integration	✅	hermes mcp (add / list / serve)
IDE integration (ACP)	✅	hermes acp — VS Code, Zed, JetBrains
Python SDK	✅	from run_agent import AIAgent
Telegram / Discord	✅	open tier (includes telegram + discord presets); integrate via hermes gateway
Slack	✅	open tier (includes slack preset); helpers via hermes slack
WhatsApp	✅	hermes whatsapp; add a custom egress policy for Meta endpoints (no built-in preset)
Web search	✅	balanced or open tier (brave preset → Brave Search API)
Voice notes (incoming messages)	✅	Auto-transcribed by the voice built-in toolset before reaching the model

---

Skills Library

Pre-built skills that encode recurring workflows. Install with one command, invoke via chat:

./skills/install.sh research-digest # weekly arXiv digest → Telegram
./skills/install.sh code-review # local code review (CLI or VS Code ACP)
./skills/install.sh anomaly-detection # daily DB anomaly detection → Slack/Telegram
./skills/install.sh market-alerts # watchlist price alerts → Telegram
./skills/install.sh slack-support # Slack support bot with knowledge base
./skills/install.sh home-assistant # natural language smart home control
./skills/install.sh --all # install everything

After installing, invoke from chat or any connected messaging platform:

hermesshell mybot chat "run research-digest"# or in Telegram: "run the anomaly-detection skill"

Full index: skills/README.md

---

Use Cases

Seven end-to-end guides covering real deployment scenarios — each with prerequisites, setup steps, automated tests, and a NemoClaw comparison:

Who	Setup	Guide
Researcher / writer	Docker + Telegram + weekly arXiv digest	01-researcher
Developer	Docker + VS Code ACP	02-developer
Home automation	Docker + Home Assistant MCP + Telegram	03-home-automation
Data analyst	Docker + Postgres MCP + anomaly alerts	04-data-analyst
Small business	Docker + Slack support bot + knowledge base	05-small-business
Privacy-regulated	OpenShell sandbox + strict policy (HIPAA/legal)	06-privacy-regulated
Trader / quant	Docker + local model + Telegram price alerts	07-trader

Full index and NemoClaw compatibility table: docs/use-cases/

---

---

hermesshell CLI

Sandboxes are named. Use hermesshell <name> <command> or omit the name to use the default.

GLOBAL COMMANDS
hermesshell onboard First-time setup wizard (provider, model, policy, sandbox)
hermesshell list List registered sandboxes
hermesshell backup-all Snapshot every registered sandbox
hermesshell doctor [--quick] End-to-end diagnostic
hermesshell credentials [list|reset] Manage stored API keys
hermesshell version Print version
hermesshell uninstall Remove HermesShell (data preserved)
SANDBOX COMMANDS (hermesshell [<name>] <command>)
start [--gpu] Create and start sandbox via OpenShell
stop Stop sandbox (memories + skills preserved)
status Show inference config + memory/skill counts
connect Open interactive shell inside sandbox
logs [--follow] Stream sandbox logs
destroy Remove sandbox (memories preserved in snapshots)
chat "prompt" One-shot message to Hermes
POLICY COMMANDS (hermesshell [<name>] policy <subcommand>)
policy list Show active presets for this sandbox
policy add PRESET Enable a network preset (e.g. github, slack)
policy remove PRESET Disable a network preset
LIFECYCLE COMMANDS (hermesshell [<name>] <command>)
snapshot [create|list|restore [PREFIX]] Manage point-in-time snapshots
backup Alias for snapshot create
restore [PREFIX] Alias for snapshot restore
rebuild Snapshot → destroy → recreate → restore
EXAMPLES
hermesshell onboard
hermesshell mybot chat "Hello Hermes"
hermesshell mybot policy add github
hermesshell mybot snapshot create
hermesshell mybot rebuild
hermesshell list
hermesshell backup-all

---

Personalise Hermes

cp configs/persona.yaml.example configs/persona.yaml

Edit configs/persona.yaml — set your name, role, expertise, ticker watchlist, and response style. Hermes loads this into every session. For deeper personalisation, edit ~/.hermes/SOUL.md — this goes directly into the system prompt.

---

Project Structure

hermesshell/
├── .github/
│ └── workflows/
│ └── ci.yml # Syntax, lint, and test CI
├── Dockerfile # Hermes Agent (pinned base image + build ARGs)
├── .env.example # CTX_SIZE (llama-server only, ignored by Ollama), bot tokens
├── cli/ # Node.js/TypeScript CLI (hermesshell command)
│ ├── package.json # hermesshell npm package
│ ├── tsconfig.json
│ ├── vitest.config.ts
│ └── src/
│ ├── index.ts # Commander entry point
│ ├── commands/ # onboard, chat, policy, doctor, etc.
│ └── lib/ # registry, credentials, policy, providers, etc.
├── openshell/
│ ├── baseline.yaml # Base sandbox policy (filesystem, process, inference)
│ ├── tiers.yaml # Tier definitions (restricted, balanced, open)
│ ├── presets/ # Composable network presets
│ │ ├── npm.yaml # npm / Yarn registries
│ │ ├── pypi.yaml # PyPI
│ │ ├── brave.yaml # Brave Search API
│ │ ├── huggingface.yaml # Hugging Face Hub
│ │ ├── github.yaml # GitHub API
│ │ ├── slack.yaml # Slack API + websocket
│ │ ├── discord.yaml # Discord API + gateway
│ │ └── telegram.yaml # Telegram Bot API
│ ├── hermesshell-policy.yaml # Legacy default policy
│ └── hermesshell-profile.yaml # Sandbox profile
├── configs/
│ ├── hermes.yaml.example # Full Hermes config
│ └── persona.yaml.example # User persona
├── skills/
│ ├── install.sh # Skill installer
│ ├── anomaly-detection/ # DB anomaly detection (detect.py)
│ ├── market-alerts/ # Price threshold alerts (monitor.py)
│ ├── code-review/ # Code review prompts
│ ├── slack-support/ # FAQ + escalation bot
│ ├── home-assistant/ # HA MCP control
│ └── research-digest/ # Weekly arXiv digest
├── scripts/
│ └── install.sh # One-command installer (curl | bash)
├── docs/
│ ├── use-cases/ # 7 end-to-end use-case guides
│ └── features.md # Full feature reference
├── knowledge/ # Drop documents here (RAG context, read-only mount)
└── models/ # Drop .gguf model weights here

---

Diagnostics & Testing

# Check your environment (provider-aware inference health, policy validation, etc.)
hermesshell doctor # full diagnostic
hermesshell doctor --quick # skip slow checks (chat smoke test, DNS probe)# Run CLI unit testscd cli && npm test

---

Contributing

HermesShell welcomes contributions — especially:

• OpenShell policy corrections — if you have access to a real OpenShell environment, correctness fixes are the highest-value contribution
• New policy presets — homeassistant, coding, research, etc.
• New skills — follow the SKILL.md format in any existing skill as a template
• Real-world test reports — if you've run HermesShell on NVIDIA hardware, share your hermesshell doctor output

Quick contributor setup:

git clone https://github.com/ppritcha/hermesshell
cd hermesshell
cd cli && npm install && npm test&&cd .. # build + test the CLI
hermesshell doctor --quick # verify your environment

Full guide: CONTRIBUTING.md · Code of Conduct · Changelog

---

Related

• HermesClaw — Earlier sibling project exploring the same Hermes-on-OpenShell idea in bash. No longer actively maintained; HermesShell supersedes it.
• Hermes Agent — NousResearch's agent (18k ⭐)
• NemoClaw — NVIDIA's OpenClaw + OpenShell reference implementation
• OpenShell — NVIDIA's hardware-enforced AI sandbox