Herald OS: an operating system built around an AI agent

What the idea is

Herald OS is an operating system built around an AI agent. Instead of working through menus and folders yourself, you talk or type to Hermes, and it works across the whole machine: it opens apps, finds and organises files, watches what is running, remembers what matters to you, runs routines on a schedule, and builds software while you watch. Every action that changes something goes through a permission system you control.

That last clause is the part that makes the project serious rather than a demo. The value proposition of an agent operating the machine is that it does things you did not explicitly ask for, which is exactly the situation in which an agent doing something unexpected is expensive. So the design puts a permission boundary between the agent's intent and the machine's state, and the README makes it the final sentence of the opening paragraph rather than a footnote.

The agent is Hermes Agent, published by Nous Research as an open-source project, and Herald OS runs on it, installed alongside. The README is explicit that Herald OS is an independent project by Luke The Dev, not an official Hermes or Nous Research product, and not affiliated with, sponsored by or endorsed by Nous Research. The project description says the same: Independent project, not affiliated with Nous Research.

That disclaimer is worth reading as a real constraint rather than boilerplate. The agent and the operating system are separate projects by separate authors, and the coupling between them is the part most likely to change under you.

The project is MIT licensed, the primary language is TypeScript, the default branch is main, and the last push was on 2026-10-20. The releases are all pre-releases at the alpha stage: v0.1.0-alpha.4 from 2026-10-13, alpha.3 from 2026-10-10 and alpha.2 from 2026-10-08. The package manifest is at alpha.5, which is one step ahead of the published releases, so the version is moving quickly.

The status note in the README is short and worth repeating: alpha at 0.1, expect rough edges, and keep backups of anything you let an agent touch.

Two very different ways to install it

The install matrix is the part of the README that tells you what this project is, because it distinguishes installing the desktop application from installing the whole operating system.

On macOS you install Hermes Agent and then Herald OS as an application. Hermes comes first:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.zshrc
hermes setup

Then you download `HeraldOS-<version>-mac-arm64.dmg` for Apple Silicon or `HeraldOS-<version>-mac-x64.dmg` for Intel, and drag Herald OS to Applications. The README explains how to tell which you have: the Apple menu shows Chip: Apple M for Apple Silicon and Processor with Intel for the other.

Then there is the step that stops most people. This build is not notarized by Apple yet, so macOS blocks it the first time, and the fix is:

xattr -dr com.apple.quarantine "/Applications/Herald OS.app"

The README also gives a Terminal-free alternative, going to System Settings, Privacy & Security, Security, and clicking Open Anyway. And it notes a change in behaviour worth knowing: since macOS Sequoia, right-click and Open no longer skips the warning. That is the kind of detail that only appears in a document written by someone who has actually installed it.

The macOS requirements are macOS 13 Ventura or later, on either architecture. The Intel build is described as the same app built for x86_64, with node-pty's Intel binaries for the Terminal, but it is new and has not been tried on an Intel Mac, so the README asks people to open an issue if something does not work.

The Linux path is different in kind. The whole operating system is available for a 64-bit Intel or AMD PC, with Fedora underneath and everything you see being Herald. There is an Arch package, an Omarchy route, a tarball for other Linux, and virtual machine images so you can try the whole OS on an Apple Silicon Mac with UTM, on an Intel Mac, or on a Windows 11 PC with Hyper-V.

So the same project ships two things: an application that runs on top of your existing desktop, and a complete operating system image. The application is the lower-risk way in, and the image is the fuller expression of the idea.

Permissions, and the macOS privacy prompts

The macOS install enumerates every privacy permission the app asks for and, crucially, why. That list is the clearest statement of what the agent can actually do.

Microphone is for talking to Hermes, dictation, and screen recordings with sound. Camera is for the camera bubble on a screen recording, when you turn it on. Screen Recording is for asking Hermes about the screen, copying text or a QR code from it, screenshots and screen recordings, and without it Herald OS captures nothing and says where to turn it on.

Accessibility and Automation covers typing an emoji or dictation into another app through System Events, and Hermes listing or quitting apps, locking the screen, switching dark mode and moving files to the Trash through Finder. The README describes a careful behaviour here: the first time you type an emoji or dictation into another app, Herald OS explains these two before macOS asks, and until both are allowed the text stays on the clipboard while the app says which one is missing.

That is a good piece of interface design, and it is worth noting what it implies. The agent is not simply granted access to the machine. It has to negotiate a set of operating system permissions the same way any app does, and when it cannot complete an action it falls back to something harmless and tells you why.

Then Calendars for today's events on the Overview, Local Network for Hermes reaching a model server or another device such as a custom endpoint at a `192.168…` address, with the note that Hermes runs inside Herald OS so this is Herald OS's to allow, and Files and Folders for the Desktop, Documents and Downloads, used for recent files on the Overview, the Files page and Hermes's file tools.

Notifications is the last, and it is qualified: alerts while you are in another app, in a code-signed build, with the parenthesis that this release is not one yet.

On first start Herald OS adds its system tools to Hermes at `~/.hermes/plugins/herald-os-bridge`. So the agent reaches the desktop through a plugin rather than through the whole application, which is the mechanism that makes the permission model workable and which also means you can turn the bridge off without uninstalling the app.

The configuration surface

The environment file is a good example of how the project documents itself, and the header comment sets the tone.

Herald OS settings that come from the environment are all optional and the defaults suit most people, so every line in the file is commented out. Nothing loads this file automatically: on macOS you export the variables you want before `npm run dev` or `npm start`, and on Linux you copy the lines you want into `~/.config/herald-os/session.env` and then run `sudo systemctl restart greetd`.

That last detail is interesting on its own. On Linux the shell is a greetd session, and restarting the session service is how a change to the session environment takes effect. That tells you the Linux build is not a conventional desktop with a display manager but a session built around the shell itself.

The file then says something that deserves to be read twice: never put credentials here. Hermes Agent keeps API keys and logins in `~/.hermes`, run `hermes setup` or open Settings in Herald OS, and the shell never needs them. So there is a deliberate separation between the operating system's configuration and the agent's credentials, and the environment file is explicitly not a place to put secrets.

The names written before the rename, with the `HERMES_OS_` prefix, are still read. So the configuration was renamed at some point and the old names were kept working, which is the kind of backwards compatibility that saves you a bad afternoon.

The settings themselves cover the shell window, with a kiosk mode that has no way to leave fullscreen and a windowed mode that starts small, plus a page zoom for the whole shell. There is a shell mode setting, `desktop` for one window which is the default or `panels` for one window per surface, used by the niri session. So the shell has two fundamentally different layouts, and the choice depends on the compositor rather than on a preference.

On the Hermes side there is the path to the Hermes Agent checkout to run `hermes serve` from, defaulting to `~/.hermes/hermes-agent`, and the working directory for new sessions, defaulting to the home folder. There is also a bridge switch, `HERALD_OS_BRIDGE_DISABLED`, which turns off the herald-os-bridge plugin, the one that provides the desktop tools and UI control, without uninstalling it.

For development there is the dev server setting, which loads the renderer from a Vite dev server instead of the built files, and a Chrome DevTools protocol port for scripted checks.

The model provider is configured elsewhere. Hermes needs one whichever installation route you pick, a Nous Portal account or an API key for a provider Hermes supports, with OpenRouter, OpenAI, Anthropic and a local model named among them. Herald OS shows a sign-in card the first time Hermes needs one, and Settings, Hermes and agents, Model provider switches to another provider or takes its API key, with a custom endpoint's included.

The repository, and the model provider question

The repository layout shows how the project is put together, and it is a mixture of a desktop application, a Linux distribution and an upstream mirror.

There is `apps/` for the applications, with `apps/desktop` being the one the scripts target, and `packages/` for shared libraries. The npm workspaces configuration covers `apps/*` and `packages/*`, and the root scripts delegate into the desktop workspace for dev, build and the macOS distribution.

There is `linux/` for the Fedora-based system, `packaging/` for the packaging work, and `plugins/` for the Hermes plugin, of which the herald-os-bridge is the important one. There is `upstream/` and a `sync-upstream` script, which is how the Hermes Agent code that Herald OS runs on is kept in step with its own repository. That script is the concrete form of the coupling the disclaimer in the README talks about.

There is `docs/` for the documentation, `examples/` with a `widgets/` directory, `scripts/` for the shell scripts the npm manifest calls, including `bootstrap.sh` and `test-bridge.sh`, and the security files, a `SECURITY.md`, a `NOTICE`, and a `.gitleaks.toml` with a `.gitleaksignore`. The gitleaks configuration is worth noticing: a project whose agent may write code, and which ships code, runs a secret scanner over its own history.

The npm manifest details are also revealing about how the project is built. The `allowScripts` field names node-pty, esbuild and usocket as allowed to run install scripts and electron-winstaller as not, which is the mechanism npm offers for restricting lifecycle scripts in a project with native dependencies. The `overrides` block pins specific transitive versions for concurrently, dbus-next, exceljs, pptxgenjs and usocket, which is what a project does when a transitive dependency has a published advisory and the fix cannot wait for the parent release.

The engines field requires Node 22.12.0 or newer, and the package is private with the ESM type module.

What is not in the repository is worth noting too. There is no model in here, because the model is the user's choice and their key. Herald OS is the shell, the bridge and the permission model; Hermes is the agent; the model provider is a third thing, chosen by the user and configured in Settings.

Editorial conclusion

Adopt Herald OS if you want to see what an agent-first desktop actually looks like in daily use, since the permission system and the full-screen shell make the trade visible rather than theoretical. Do not adopt it as a production machine, because the project labels itself alpha at 0.1 and advises keeping backups of anything an agent touches, and check first how you want the model provider configured, since Hermes needs an account or an API key whichever route you take.

Frequently asked questions

Official sources

1. iamlukethedev/Herald-OS on GitHub
2. Issues
3. License: MIT
4. README
5. Releases