Install & First Run — ติดตั้งแล้วรันได้ในครั้งแรกInstall & First Run — From Download to Your First Message

🤔 If the installer file is only 6.8 MB, but you still wait several minutes after clicking Install — what is your machine actually doing, and how would you know it succeeded?

In the Hermes Agent in Practice series, post ten — #10 Desktop & Fleet — I looked at the desktop app from an organisation's vantage point: the anatomy of an Electron shell talking to hermes serve, the platform support tiers, and the question of how you look after twenty laptops from one screen. This new series walks the other way — back down to a single machine, yours, one screen at a time.

The one-line answer of this post is that Hermes Desktop is not a new product; it is the same agent in an app window — the official docs call it "a native app built around the same agent you get from the CLI and the gateway".^[1] The file you download is therefore not the app: it is a small bootstrap installer whose only job is to build the real app on your machine, and when it finishes, everything lands in the same directory the CLI uses, ~/.hermes. This post walks from the download page, through onboarding and your first message, to the three commands that prove the install really worked.

1. What You Are Installing — One Window, the Same Agent

What you are about to install is the Electron + React app that lives in the apps/desktop/ directory of the NousResearch/hermes-agent repository — not a separate repo and not a separate product.^[1] It is free software under the MIT license, free to download and use — the product page's FAQ puts it as "Hermes Desktop is the open-source Hermes Agent under an MIT license, free to download and use".^[4] All of its state lives in ~/.hermes on macOS and Linux, or %LOCALAPPDATA%\hermes on Windows.^[1]

There is exactly one sentence from the official docs I would ask you to remember, and it answers the most frequently asked question at the same time:

"The Hermes desktop app is a native app built around the same agent you get from the CLI and the gateway — same config, same API keys, same sessions, same skills, same memory. It is not a separate product or a lightweight clone."^[1]

The hardest-working word in that paragraph is same, repeated five times, because it means that if you have already configured Hermes in a terminal, installing this app does not start you back at one — a session left open in the CLI shows up in the app, and a session started in the app can be picked up again in the terminal. This is not two programs synchronising data. It is two front ends reading and writing the same set of files from the outset.

The three-layer architecture worth knowing before you click Install

Technically the app is an Electron shell wrapping a React surface, and that surface does not run the agent itself. It talks to a headless backend called hermes serve, which the app launches for you, over JSON-RPC on a WebSocket. The docs are explicit that the app is self-contained — it runs its own backend and never opens or requires the web dashboard.^[1]

The details of that anatomy, including the boundary people confuse most often between hermes serve and the API server you use to put Hermes behind other applications, I already wrote up in #10 Desktop & Fleet, so I will not repeat it here. I will stress only the one part that bears on installing: because the backend is a separate process the app starts, boot problems usually are not in the window — they are in a backend that failed to come up. That is exactly why section 7 sends you to the desktop log first.

💡 A version-number trap to avoid: Hermes Desktop has no version number of its own. It ships with the agent, which is why the official product page's footer reads "Hermes Agent v0.21.0"^[4] and the latest GitHub release is "Hermes Agent v0.21.0 (v2026.8.31)", published 31 August 2026 with zero attached assets^[5] — meaning the desktop installers are not served from the GitHub Releases page at all. When you write or cite a version, write "Hermes Agent v0.21.0 (tag v2026.8.31)", not "Hermes Desktop v0.21.0" — and treat any site advertising "Hermes Desktop version such-and-such" with suspicion.

2. Before You Start — the Machine, the Time, and What You Do Not Need

Three things are required: a machine on the supported list — macOS 12 or later on Apple Silicon, Windows 10/11, or any Linux distribution^[4]; git on the machine; and a network connection that holds long enough for the build to finish. What you do not need is a Nous Portal account — the product page's FAQ answers it flatly: "No account is needed to run the base app."^[4]

The prerequisites are lighter than most people expect. The installation docs say that on non-Windows platforms the only thing you need in advance is Git; Python 3.11, Node.js v26, ripgrep and ffmpeg are all handled by the installer. On Linux you also need curl and xz-utils (the installer downloads Node as a .tar.xz archive), and if you want the desktop app you additionally need g++ — on Debian/Ubuntu the build-essential package — because native modules have to be compiled.^[2]

A comment inside install.sh spells out that the "Build desktop app" stage is added only when the --include-desktop option is present, and that "the signed bootstrap installer (Hermes-Setup) passes it so a GUI install ends up with a launchable app".^[10] That is precisely why people installing from the .dmg/.exe wait longer than people installing with the one-line terminal command — the latter have not built the app at that point yet.

3. Install — Screen by Screen on macOS, Windows and Linux

There are three official install paths, and all three land in the same directory. On macOS and Windows the path the docs call "recommended" is to download the graphical installer and double-click it. On Linux there is no graphical installer — you install the CLI with a single command first, then run hermes desktop to build and launch the app.^[2]

# macOS (Apple Silicon, macOS 12+) — the graphical installer
# Download it from the "Download desktop app" button under Mac OS
https://hermes-assets.nousresearch.com/Hermes-Setup.dmg

# Windows 10/11 — the graphical installer, or one PowerShell line (no admin rights)
https://hermes-assets.nousresearch.com/Hermes-Setup.exe
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

# Linux / WSL2 / macOS — no graphical installer: install the CLI, then build the app
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc            # or: source ~/.zshrc
hermes desktop

macOS — five steps

1. Open the product page at hermes-agent.nousresearch.com/desktop and click Download desktop app under Mac OS (that card is labelled macOS 12+). The link goes to hermes-assets.nousresearch.com/Hermes-Setup.dmg, with the page appending a ?build=<commit> parameter automatically.^[4] — What you should see: a file of roughly 6.8 MB, not a several-hundred-megabyte download.
2. Open the .dmg and launch the installer inside it. macOS asks the usual confirmation for a file downloaded from the internet, but it will not raise an "unidentified developer" warning — I checked this file with spctl on 7 September 2026 and it came back accepted, source Notarized Developer ID: it is signed with a Developer ID certificate and notarized by Apple, with the ticket stapled to the file.^[11]
3. Click the install button in the installer window. It then works through the stage list quoted in section 2. — What you should see: stages ticking past one line at a time, from System prerequisites down to Build desktop app.
4. Wait out the Build desktop app stage. This is the longest one, because it fetches the roughly 114 MB Electron runtime before assembling the app. If it hangs and you see retrying attempt=… repeating, your network cannot reach github.com/electron/electron/releases; the installer tries to self-heal in two steps — clearing a corrupt cached zip and retrying, then retrying once more through npmmirror.com.^[1]
5. Once Finish install passes, open the app. If you later use voice mode, macOS will prompt once for microphone access.^[1] — What you should see: a chat window with a sidebar on the left and a composer at the bottom.

Windows 10/11 — two paths to the same place

1. The graphical path: download Hermes-Setup.exe from the Download desktop app button under Windows^[4] and double-click it. — What you should see: no UAC elevation dialog, because the Windows guide states "No admin rights required".^[9]
2. The PowerShell path: if you would rather type than double-click, the one-liner is iex (irm https://hermes-agent.nousresearch.com/install.ps1).^[2] Both paths call the same script — the docs say of the graphical installer that "on first launch the GUI calls install.ps1 under the hood".^[9]
3. Let it install Python via uv, Node.js 26, PortableGit and the repo clone, all underneath %LOCALAPPDATA%\hermes\ — without touching Program Files and without touching the machine-wide registry.^[9]
4. When it finishes, open a new terminal window. The docs warn about this exact point: the installer adds hermes to your User PATH, which an already-open window will not see.^[9] — What you should see: typing hermes --version in the new window prints a version.
5. After that first run, the app and the CLI use one place. The docs say both "share the same %LOCALAPPDATA%\hermes\hermes-agent install and %LOCALAPPDATA%\hermes data directory — switch between the GUI and the CLI freely".^[9]

Linux — terminal first, window second

1. Install the packages you need up front. On Debian/Ubuntu that is curl, xz-utils and build-essential for compiling the desktop app's native modules.^[2]
2. Install the CLI with curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash. The code lands in ~/.hermes/hermes-agent/, the command is a symlink at ~/.local/bin/hermes, and the data lives in ~/.hermes/.^[2]
3. Reload the shell with source ~/.bashrc (or ~/.zshrc). — What you should see: the hermes command resolves. If you get command not found, the docs tell you to check PATH before anything else.^[2]
4. Run hermes desktop. That command (alias hermes gui), in the official description, "installs workspace Node dependencies, builds the current OS's unpacked Electron app, then launches that packaged artifact".^[1] The first run is therefore the slowest; later ones are faster, because it rebuilds only when the content stamp changes.
5. After the first run the CLI writes a system menu entry for you: a file named hermes.desktop placed in ~/.local/share/applications/ per the XDG convention, so you can launch the app from your desktop's app menu without a terminal.^[15] — What you should see: a Hermes icon appearing in the system's application list.

Two extra flags I reach for often: hermes desktop --cwd <path> sets the initial project directory for desktop sessions (it sets HERMES_DESKTOP_CWD for you), and hermes desktop --skip-build skips the build step and launches the already-packaged app, which helps a great deal when you are opening and closing it repeatedly.^[1]

4. First Run — Onboarding and Choosing a Provider

The first screen after launch is onboarding, which the docs say is designed so that it "gets you to your first message in seconds". It has one job: give the agent a model to call. The easiest route is signing in over OAuth; the second is entering an API key yourself; the third is clicking Choose provider later and skipping ahead.^[1]

One thing to say plainly: the official docs do not enumerate this wizard's screens one by one. What they do state is that a "Choose provider later" option exists to skip it, and that Settings → Providers is where every provider is managed afterwards, with an Accounts section for signing in and per-provider API-key storage beside it.^[1] So if the sequence of screens you meet does not match some article on the internet exactly, do not assume you installed it wrong.

Four documented ways to sign in

Nous Portal is the route the docs call "the recommended way", and its CLI equivalent is hermes setup --portal, which "logs you in, sets Nous as your provider, and turns on the Tool Gateway in one command".^[2] The other three are OAuth as well: Anthropic (a Claude Pro/Max account), OpenAI Codex, and xAI — of which the desktop docs say "Grok is a first-class OAuth provider in the launcher; sign in through the browser flow like the other OAuth providers".^[1]

Every OAuth credential is stored in ~/.hermes/auth.json, while API keys you type yourself go to ~/.hermes/.env — two different files.^[6] That separation is not a footnote, because post #3 of this series will have you creating several profiles, and there we will find that the two files meet very different fates.

If you pick Choose provider later, the app drops you into the chat with no model configured yet. The model picker lives in the composer, just left of the microphone icon; click it and you can set the model, the reasoning effort and fast mode from one dropdown. Setting the profile's default, by contrast, happens in Settings → Model, which the docs stress is "the only place that writes it".^[1] Put differently: picking a model in the composer is an ad-hoc choice, and it does not change the default that crons and subagents start from.

💡 My advice if you plan to read post #2: click Choose provider later and do not put a card down with anyone yet, because #2 Local Models will set you up with a model running on your own machine, through the Settings → Providers pane whose Local Models view, in the docs' words, "installs and manages an on-device llama.cpp runtime".^[1] Leaving this slot empty lets post #2 start from a clean zero.

5. Your First Message, and What You See

Once there is a model, type something simple that genuinely needs a tool — ask it to look through a folder and summarise what is there, for instance. What you will see is not just text flowing out, but tool activity flowing alongside it; and if the agent reaches for a command the system considers risky, an approval prompt appears for you to decide.

The docs list what the chat surface gives you, and the first three are what you meet in the first minute.^[1]

• Streaming responses — the answer streams with live tool activity and structured tool-call summaries as the agent works.
• The same conversation history as every other surface — sessions started here resume in the CLI/TUI, and the other way round.
• Drag-and-drop — drop files anywhere in the chat area to attach them to your next message (clipboard paste works too).
• A right-hand preview rail — render web pages, files and tool outputs side by side while you keep chatting.
• The status bar along the bottom — a per-session YOLO toggle, a context-usage meter showing how full the window is (click it for a token breakdown by category), cache hit rate, and tokens per second.

Why an approval prompt shows up at all

Because the approval system's default is smart mode. The security docs give approvals.mode a default of smart and describe its behaviour: an auxiliary LLM assesses risk — low-risk commands are auto-approved for that command only, genuinely dangerous ones are auto-denied, and the uncertain cases escalate to a manual prompt.^[8]

I think that design is cleverer than it looks, because the box that interrupts you is the case the system could not decide for you — not the case where it is being jumpy. If you meet this prompt on your first message, it means the agent is about to do something worth reading before you click. The two other modes are manual, which prompts every time, and off, which the docs say plainly is equivalent to running with --yolo.^[8]

6. The Desktop Map — Screen, Command, File

This table is the map I would keep beside the screen, because it is the concrete form of the "same config, same sessions" sentence from section 1. Every row reads left to right as: here is where this lives on screen, here is the command that gets you the same result, and here is the file it lands in on disk.

The last two rows are the ones people overlook most. Gateways matters because it decides which machine actually runs the agent's commands — the default is the backend the app starts on this machine, but you can point it at another one, and when you do, everything else in this table moves with it. Logs matters because it is the first command to type when something misbehaves, which is exactly what the next section is about.

Three more panes are missing from the table only because it is not yet time to use them: MCP for attaching external tools, and Agents and Command Center for multi-agent work.^[1] All three get a post of their own, in #5 and #6.

7. Check That It Worked — Three Things That Prove the Install

A window that opens is not evidence that the install is complete. There are three things I do every time I set up a new machine. All three run in an ordinary terminal, take under a minute together, and answer different questions — is the version right, did it boot, and did the files land where they should?

hermes --version              # the agent version the app is running on
hermes doctor                 # check config and dependencies (add --fix to attempt repairs)
hermes logs desktop -n 50     # the last fifty lines of the desktop app's boot
ls ~/.hermes                  # the agent's home directory — expect everything listed below

1. Version and health — hermes --version prints version information,^[7] and hermes doctor is the command the installation docs point you at when you suspect something is missing: "it will tell you exactly what's missing and how to fix it", with --fix to let it attempt repairs.^[2] I have to say plainly that the docs do not show a sample of what hermes doctor prints. If you want output you can paste into a support thread, use hermes dump instead, which the docs do document in full — its example runs from the version:, hermes_home:, model: and provider: lines down to the count of installed skills.^[7]
2. The boot log — hermes logs desktop reads desktop.log, which the CLI reference describes as holding "Electron desktop app — boot, backend spawn output, and recent Python tracebacks".^[7] The phrase backend spawn is the heart of it, because that is the record of the app launching hermes serve for itself. The desktop docs tell you to read this file first when the app reports a boot failure, and you can also follow it live with hermes logs gui -f.^[1]
3. The home directory — ls ~/.hermes should show config.yaml (settings), .env (keys and secrets), auth.json (OAuth credentials), SOUL.md (the agent's primary identity), and the directories memories/, skills/, cron/, sessions/ and logs/.^[6] On Windows look in %LOCALAPPDATA%\hermes instead.^[1] — What you should see: every name on that list. If config.yaml is missing, the "Prepare config and skills" stage did not complete.

If check two says the boot genuinely failed, the docs give two reset lines that clear most of it: delete the marker file ~/.hermes/hermes-agent/.hermes-bootstrap-complete to force the whole first-launch setup to run again, and delete ~/.hermes/hermes-agent/venv to rebuild the Python virtual environment.^[1] Notice that neither command touches your data — the data sits on a different layer from the code.

💡 My favourite test of all: open a terminal and type hermes chat while the app is still running. If the install is correct, you will see the same session you were just talking to in the app, because both read the same ~/.hermes — the docs describe the relationship as "the same layout a CLI install uses, which is why the two are interchangeable".^[1] That is the best proof there is that you installed Hermes, and not merely a window.

8. The Road Ahead — the Seven-Step Ladder of This Series

At this point you have an app that opens, a model it can call, and a way to prove that everything landed in one place. The remaining six posts build on that base one step at a time — from choosing who does the thinking for you, all the way to an agent that checks its own work, runs itself, and can recover.

• #2 Local Models — three roads to a model running on your own machine, and the context-size rule you cannot skip.
• #3 Profiles — one agent per role, each with its own memory, skills and working folder.
• #4 The Council — several models answering separately before one synthesises, with an independent reviewer before the answer reaches you.
• #5 Skills, MCP & Memory — the three drawers that make the agent know more, and how to see what each costs you in context.
• #6 Automation & Agents — work that runs on schedule, fans out to subagents, and refuses to say "done" without evidence.
• #7 Safety, Remote & Recovery — setting the boundaries right, attaching to another machine, and recovering when it breaks, including the YOLO toggle we left alone.

That order is not sorted by difficulty. It is sorted by trust. Every step adds something the agent can do without you watching, and every step therefore has to arrive with a matching increase in how you check it. That is why the safety post sits at the end — not because it matters least, but because it is the step at which you finally have something real to protect.

9. Summary

If one picture survives from this post, it is Figure 1 — three different install paths on three operating systems, flowing down into a build step on your own machine, and coming out as a window that talks to hermes serve, with both standing on the same ~/.hermes directory the CLI uses. Everything the later posts do is adding things into that directory.

There are three things I would do before reading post #2, and none of them costs a thing. One — run the three commands from section 7 and keep the output, because when something breaks later you will want to know what it looked like when it was healthy. Two — open ~/.hermes/config.yaml and read it once without editing anything, just to learn where things are. Three — type hermes chat in a terminal while the app is open, and watch whether the same conversation really shows up in both places.