The Hermes Agent OS GitHub repo you're looking for is github.com/iamlukethedev/Herald-OS, and it holds Herald OS, a free, open-source operating system that uses Hermes Agent as its whole interface.
I installed it on my Mac this week, and honestly, I didn't type most of the commands myself.
I asked Claude to set it up for me, and it was done in about two minutes.
But you should know what Claude actually ran, so this is the full operator walkthrough.
You'll get the exact repo, what's inside it, the licence, the status, every install route with the real commands, the first-run steps, how to update and roll back, the traps I hit, and how to report a bug.
If you're wondering whether it's official, whether it's safe, or whether it costs anything, I'll answer all three as we go.
What Is The Hermes Agent OS GitHub Repo?
The Hermes Agent OS GitHub repo is Herald OS, which its README describes as an agent-native operating system with Hermes Agent as the interface.
Instead of clicking through menus and folders, you talk or type to Hermes, and it works across the whole machine.
It opens apps, finds and organises files, remembers what matters to you, runs routines on a schedule and builds software while you watch.
Here are the hard facts I pulled from the repo and the GitHub API on 8 October 2026.
| Fact | What the repo says |
|---|---|
| Repo URL | github.com/iamlukethedev/Herald-OS |
| Author | Luke The Dev, who publishes as iamlukethedev |
| Licence | MIT, with Hermes Agent by Nous Research also MIT |
| Status | Alpha (0.1), so the README tells you to expect rough edges |
| Latest release | v0.1.0-alpha.1, published on 6 October 2026 |
| Created | 6 October 2026 |
| Stars and forks | 155 stars and 20 forks when I checked |
| Platforms | macOS 13 or later on Apple Silicon, a Fedora-based Linux for PCs, Arch, Omarchy, other Linux and a VM |
| Built with | Electron and React for the shell, plus a Python Hermes plugin for the system tools |
Is Herald OS an official Nous Research product?
No, and the README is very clear about it.
Herald OS is an independent project by Luke The Dev, and it isn't affiliated with, sponsored by or endorsed by Nous Research.
Hermes Agent itself lives in a separate repo, github.com/NousResearch/hermes-agent, and Herald OS installs alongside it rather than replacing it.
Herald OS doesn't fork Hermes either.
It runs a standard Hermes install and adds its system abilities as a normal Hermes plugin called herald-os-bridge.
What's Inside The Herald OS Repo?
You don't need to read the code to use Herald OS, but the layout is simple.
The apps/desktop folder holds the Electron and React shell, plugins/herald-os-bridge holds the Hermes plugin with the system tools and audit log, linux holds Herald OS Linux, and packaging/arch holds the Arch packages.
The docs folder has a Linux guide and a full manual, and both cover far more than the README.
🔥 Want my full Hermes setups, not just the install? Inside the AI Profit Boardroom, I've got step-by-step Hermes Agent trainings, from first install to automations and Agent OS builds. You'll be learning alongside 3,400+ members, with four coaching calls a week where you can ask about your own setup. → Get access here
Step 1: Install Hermes Agent First
Every Herald OS route needs Hermes Agent and a model provider, so start here on a Mac.
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.zshrc
hermes setup
The hermes setup command walks you through picking a model provider and signing in.
You can use a Nous Portal account, or an API key for a provider Hermes supports, such as OpenRouter, OpenAI, Anthropic or a local model.
Before you go any further, check Hermes works on its own.
hermes doctor
hermes
Say hello, then exit with Ctrl+D.
If you build Herald OS from source, the README asks for Hermes Agent 0.21.3 or later.
On the Linux installer and the VM, the first start sets Hermes up for you, so you can skip this step there.
If you've never touched Hermes before, my guide on setting up Hermes Agent in one click is the gentlest place to start.
Step 2: Pick Your Install Route
There are six ways to install Herald OS, and every download is on the releases page.
| Your machine | Route | File from the release |
|---|---|---|
| A Mac with Apple Silicon | The Mac app | HeraldOS-0.1.0-alpha.1-mac-arm64.dmg, about 148 MB |
| A spare 64-bit PC | Herald OS Linux | The x86_64 ISO in two parts, about 3.6 GB joined |
| Arch Linux | The Arch package | It downloads the release tarball for you |
| Omarchy | The Arch package plus one command | It downloads the release tarball for you |
| Any other Linux | The tarball | The linux-x64 or linux-arm64 tarball, about 140 MB |
| An Apple Silicon Mac, for the full OS | The virtual machine | The aarch64 VM disk in two parts, about 2.7 GB |
Route A: Herald OS on a Mac
You need macOS 13 Ventura or later on Apple Silicon, and the README says Intel Macs are untested.
First, download the DMG from the releases page, open it and drag Herald OS into Applications.
Second, clear the quarantine flag, because this alpha build isn't notarized by Apple yet.
xattr -dr com.apple.quarantine "/Applications/Herald OS.app"
Third, open Herald OS from Applications.
It takes over the whole screen, so remember that Cmd+Ctrl+F leaves or re-enters fullscreen and Cmd+Q quits.
On its first start, it adds its system tools to Hermes as a plugin.
macOS will ask for Screen Recording, Accessibility or Microphone access the first time a feature needs it, such as asking about the screen or talking to Hermes.
Route B: Herald OS Linux on a PC
This is the whole operating system for a 64-bit Intel or AMD PC, with Fedora underneath and Herald on top.
GitHub only accepts files up to 2 GB, so the ISO comes in two parts that you join yourself.
cat herald-os-0.1.0-alpha.1-x86_64.iso.part* > herald-os-0.1.0-alpha.1-x86_64.iso
shasum -a 256 -c herald-os-0.1.0-alpha.1-x86_64.iso.sha256
On Linux you use sha256sum -c instead, and on Windows the README gives a copy /b command that joins part0 and part1.
Write the ISO to a USB stick of 8 GB or more with Fedora Media Writer or balenaEtcher.
Boot the PC from the stick and follow the installer.
Its disk screen lets you erase the disk or install next to Windows, and you can encrypt the disk too.
Secure Boot can stay on.
The first start sets up Hermes Agent, then Herald OS asks for your name, a password and Wi-Fi.
One honest warning from the repo's own known limits is that the ISO has been tested in a virtual machine but not yet on real PC hardware.
Route C: The Arch package
git clone https://github.com/iamlukethedev/Herald-OS.git
cd Herald-OS/packaging/arch/herald-os-bin
makepkg -si
herald-os setup
The herald-os setup command runs once per user and installs Hermes Agent plus Herald's system tools.
Then you pick Herald OS on your login screen for the full session, which needs the niri compositor, or you run herald-os-app to use it as an app inside your current desktop.
Route D: Omarchy
Install the Arch package first, then run one command.
herald-os omarchy install
Herald OS becomes an app inside Omarchy, follows Omarchy's theme and gets a row on the Omarchy menu.
herald-os omarchy remove takes it all out again.
The README says this was tested against Omarchy 4's own configuration and scripts, but not yet on an actual Omarchy machine, so reports are welcome.
Route E: Any other Linux
The tarball carries the app and its command-line tools.
sudo mkdir -p /opt/herald-os
sudo tar -xzf herald-os-0.1.0-alpha.1-linux-x64.tar.gz -C /opt/herald-os --strip-components=1
sudo chown root:root /opt/herald-os/chrome-sandbox && sudo chmod 4755 /opt/herald-os/chrome-sandbox
sudo ln -sf /opt/herald-os/resources/herald-os-linux/bin/* /usr/local/bin/
herald-os setup
herald-os-app
Route F: The whole OS in a virtual machine
On an Apple Silicon Mac, one script downloads the latest VM disk and boots it with Apple's virtualisation.
brew install qemu zstd
git clone https://github.com/iamlukethedev/Herald-OS.git && cd Herald-OS
bash linux/vm/try.sh
The first start sets itself up in a few minutes, Hermes Agent included.
Step 3: First Run And Model Setup
When Herald OS opens, the first thing to check is that Hermes actually answers.
Open the Hermes page with Cmd+2 on a Mac and ask it something simple.
If it asks you to sign in, use the sign-in card it shows, or run hermes setup again in Terminal.
You can change your model later with hermes model, or inside Herald OS under Settings.
In my install, the preferred model in Settings was GPT-6 Astra, which I had plugged in through a CLI.
Next, test the system tools by asking what's using the most memory right now.
The README says Hermes should answer with its system_processes tool rather than a shell command.
Julian's Shortcut: Let Claude Do The Install
I'll be straight with you about how I really did it.
I gave Claude the repo link and asked it to set Herald OS up on my Mac.
It installed everything in about two minutes, and I didn't have to fight with a single command.
🚀 Ready to put Hermes Agent OS GitHub to work in your business? Inside the AI Profit Boardroom you get step-by-step video trainings, my installable Agent OS and four coaching calls a week with 3,400+ members building real automations. → Join the AI Profit Boardroom
How To Update And Roll Back Herald OS
Each route updates in a slightly different way.
| Route | How to update | How to go back |
|---|---|---|
| Herald OS Linux | Run herald-os update, or use Update in the Herald OS menu |
Run herald-os rollback |
| Mac app | Download the new DMG and replace the app in Applications | Keep the old DMG until you're happy |
| Arch and Omarchy | Run git pull and makepkg -si again in packaging/arch/herald-os-bin |
Reinstall the older package |
| From source on a Mac | Run git pull, then npm run bootstrap |
Check out an older commit |
| Development VM | Run git pull on the Mac, then bash linux/dev/push.sh |
Check out an older commit |
The new version starts on the next restart, and the previous one stays in the boot menu.
To update Hermes on a Mac, run hermes update whenever you like.
The Traps I Hit, And The Fixes
There are three traps every operator should know about before installing from the Hermes Agent OS GitHub repo.
The first trap is the unnotarized build.
If macOS says Herald OS is damaged or can't be opened, run the xattr command from Route A and open it again.
The second trap is Connections.
The Connections page, where tools, apps and external connections live, didn't work or sync for me.
That's normal for open-source alpha software, and I could have asked Claude to dig into it.
The third trap is the alpha status itself.
The README tells you to keep backups of anything you let an agent touch, and I'd take that seriously.
I also noticed the sidebar is resizable but the interface was cut off slightly at the top of my screen.
| Problem | Fix from the README |
|---|---|
| "No Hermes runtime found", or the boot screen never finishes | Run hermes doctor, and check the Herald OS log in your Hermes logs folder. |
| Hermes uses shell commands instead of its system tools | Run hermes plugins list, then hermes plugins enable herald-os-bridge, and restart Herald OS. |
| The microphone does nothing on a Mac | Check System Settings, then Privacy and Security, then Microphone. |
How To Contribute Or Report An Issue
Herald OS is open source, so you can help shape it.
For bugs, open an issue on the repo, and the bug template asks what happened, the steps to reproduce, your platform, your versions and your logs.
If the problem is with models, providers, the hermes command or the gateway, the issue template sends you to the Nous Research hermes-agent repo instead.
Security problems should never go in a public issue.
The SECURITY.md file asks you to use the repo's Security tab and choose Report a vulnerability.
If you want to send code, CONTRIBUTING.md asks you to run these checks before a pull request.
npm run typecheck
npm test
npm run test:bridge
bash scripts/check-secrets.sh
For interface changes, it also asks you to add a screenshot to the pull request.
A Quick Tour Once Herald OS Is Running
My full feature walkthrough is in the Herald OS guide, so this is the short version.
- The dashboard greets you with "Good morning, Julian. Your day already in motion", with voice input, today's schedule and a list of what needs attention.
- "Pick up where you left off" suggests where to continue from the names of recent documents, projects, chats and calendar events, and you can toggle it on or off.
- Recent desktop screenshots appear on the dashboard, and the chat is normal Hermes chat with Preview, Sources and a new conversation button.
- Spaces split work into Ideas, Work and Personal, and you can add a space per client and set a default.
- Missions let Hermes plan a goal like building out a new website step by step.
- Memory shows everything Hermes remembers, and my Telegram details were there, so be careful what you screen-share.
- Files covers recent, favourites, projects, downloads, shared and deleted.
- Automations synced straight across from Hermes Desktop and my Agent OS, including a 6am to-do recap, a daily Japanese lesson and morning inbox triage.
- Settings cover your preferred model, runtimes including Docker, background agents, remember preferences, auto-approve and activity history.
- General settings cover fullscreen, the default space and folder, do not disturb for the bell sound, stay awake, the screen saver, dictation and quitting the session.
- You also get themes, software access for Claude Code, Codex and LM Studio, plugins from a GitHub link, a Hermes Agent section, Usage, Voice with engine, speed, local or live voice and voice commands, plus privacy, notifications, networks, storage and accessibility.
The old way of running Hermes, back in March and April, was a messy terminal, and this new way looks nicer than Hermes Desktop to me.
If you want to add more abilities later, my post on the Hermes Agent plugins marketplace shows how plugins install in one click.
🔥 Want help choosing which Hermes automations to run first? The AI Profit Boardroom has my Hermes Agent courses, automation blueprints and Agent OS trainings, plus four live coaching calls every week. → Join the AI Profit Boardroom
My Verdict On The Hermes Agent OS GitHub Install
Herald OS is super clean, and my automations synced across quickly.
It's a great pick if you want a beautiful interface for Hermes but don't love Hermes Desktop.
It's also alpha software, so back up anything important and start with approvals switched on.
If you'd like a hand planning which agents are worth running in your business, you can book a free SEO strategy session with my team.
Related Reading
- My Herald OS feature guide walks through every screen in more detail.
- How to set up Hermes Agent in one click gets Hermes running before you add Herald OS.
- The Solar Mini 4 Hermes setup shows you a free model you can plug into Hermes.
Also On Our Network
- 🌐 How a business can put the Herald OS repo to work
- 🌐 My scored review of the Hermes Agent OS GitHub project
- 🌐 A Herald OS quick start inside an Agent OS workflow
- 🌐 The best benchmarked models to connect after installing Herald OS
FAQ: Hermes Agent OS GitHub
Where is the Hermes Agent OS GitHub repo?
The Hermes-powered operating system most people mean is Herald OS, at github.com/iamlukethedev/Herald-OS.
Hermes Agent itself is a separate Nous Research repo at github.com/NousResearch/hermes-agent.
Is Herald OS made by Nous Research?
No, it's an independent project by Luke The Dev, and the README says it isn't affiliated with Nous Research.
It runs on a normal Hermes install and adds its tools through the herald-os-bridge plugin.
Is Herald OS free?
Yes, it's free under the MIT License.
You still need a model provider, and model usage can cost money unless you pick free models.
Why does macOS say Herald OS is damaged?
The alpha build isn't notarized by Apple yet.
Run xattr -dr com.apple.quarantine "/Applications/Herald OS.app" once and open it again.
How do I update or roll back Herald OS?
On Herald OS Linux, run herald-os update, and run herald-os rollback to go back.
On a Mac, replace the app with the new DMG, and from source, run git pull and npm run bootstrap.
📺 Video notes + links to the tools 👉
🎥 Learn how I make these videos 👉
🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉
About Julian
I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.
I help business owners scale with AI agents, automation and SEO.
- I've built a 7-figure agency, Goldie Agency, with a team of around 50 people.
- I've grown a YouTube channel to 400,000+ subscribers.
- I wrote the Amazon best-sellers "SEO Link Building Mastery" and "Agency Marketing Mastery".
- My Udemy courses have taught over 50,000 students.
→ Get my best AI training inside the AI Profit Boardroom
Install Hermes, pick your route, clear the quarantine flag, and you'll have Herald OS running from the Hermes Agent OS GitHub repo today.
