Hermes Desktop exists for one simple reason: not everyone wants to manage an AI agent from the terminal. Hermes Agent is powerful, but a persistent agent has a lot of moving parts. There are model providers, API keys, tools, memory, sessions, schedules, gateways, logs, and profiles. A CLI can handle all of that, but it is not the friendliest onboarding path. Hermes Desktop gives you a native app for installing, configuring, and chatting with Hermes Agent on macOS, Windows, and Linux. This guide walks through the practical setup path. ## What you are installing Hermes Desktop is a desktop companion for Hermes Agent. It can either: 1. run Hermes locally on your machine, or 2. connect to a remote Hermes API server using a URL and API key. Local mode is the easiest choice if you want everything on your computer. Remote mode is better if you already run Hermes on a server and only want the desktop app as a control surface. The desktop app manages the user-facing parts: - chat - sessions - profiles - models - providers - tools - skills - memory - schedules - gateways - logs - backup and import - settings The agent itself still does the real work underneath. ## Step 1: Download Hermes Desktop Start from the official Hermes Desktop release page or the Hermes Agent documentation. Look for the build that matches your operating system: - macOS - Windows - Linux On Windows, the public project notes that the installer may not be code-signed. That means Windows SmartScreen can show a warning on first launch. If you trust the source and downloaded it from the official release page, use **More info → Run anyway**. On Linux, you may see AppImage, `.deb`, `.rpm`, or similar packaging depending on the current release. ## Step 2: Launch the app Open Hermes Desktop after installation. On first launch, the app should ask whether you want to use a local Hermes install or connect to a remote server. You have two paths. ### Option A: Local mode Choose local mode if you want Hermes Agent installed and run on your own computer. In local mode, Hermes Desktop checks whether Hermes already exists under: ```bash ~/.hermes ``` If Hermes is not installed, the app can run the official Hermes installer for you. The installer handles the required runtime pieces. Depending on your system, this can include Python, Node.js, Git, uv, ripgrep, ffmpeg, Playwright dependencies, and other tools Hermes needs. This is the main advantage of the desktop app: you do not have to manually assemble the stack before you can start. ### Option B: Remote mode Choose remote mode if you already run Hermes somewhere else, such as a VPS, home server, or workstation. You will need: - the remote Hermes API URL - an API key or token The app validates the connection and then uses the remote backend for chat and tool execution. Remote mode is useful when you want Hermes to keep running even when your laptop is closed, or when the server has access to resources your desktop does not. ## Step 3: Pick a model provider After choosing local or remote mode, configure your model provider. Hermes Desktop supports several provider paths, including: - Nous Portal - OpenRouter - Anthropic - OpenAI - Google Gemini - xAI - Qwen - Hugging Face - Groq - local OpenAI-compatible servers such as Ollama, LM Studio, vLLM, and llama.cpp For most users, OpenRouter or Nous Portal is the easiest multi-model option. If you already have an OpenAI, Anthropic, or Gemini key, you can use those directly. If you want a local-only setup, run a compatible local model server first, then choose the local/custom provider option in Hermes Desktop. A typical local model setup might look like this: ```bash # Example only: start a local Ollama model first ollama run llama3.1 ``` Then point Hermes Desktop at the local OpenAI-compatible endpoint if your local stack exposes one. ## Step 4: Confirm the main workspace opens After provider setup, Hermes Desktop should open the main workspace. The first screen to test is chat. Send a simple message: ```text What model are you using, and what tools are enabled? ``` A working setup should produce a normal streaming response. Hermes Desktop should also show tool progress when tools run, token usage in the chat footer, and session state in the sidebar or session area. If chat fails immediately, check provider configuration first. The most common problems are: - missing API key - wrong base URL - unsupported model name - local model server is not running - remote Hermes URL is unreachable ## Step 5: Learn the key screens Hermes Desktop is easier to use if you understand the main screens. ### Chat This is the day-to-day interface. It supports streaming responses, markdown, code rendering, tool progress, and slash commands. Useful slash commands may include commands for status, tools, memory, model switching, usage, debugging, clearing, retrying, and starting new sessions. ### Sessions The Sessions screen lets you browse and resume previous conversations. This matters because Hermes is designed around continuity. You should not have to start every workflow from scratch. ### Profiles Profiles let you create separate Hermes environments. Use profiles when you want isolation between contexts. For example: - personal assistant - coding agent - research agent - work agent Each profile can have separate memory, provider config, persona, and tools. ### Models and Providers This is where you configure model access. If responses are slow, expensive, or low quality, this is the first place to inspect. You can switch providers, adjust saved model configs, or move between local and cloud models. ### Memory The Memory screen is one of the most important parts of Hermes Desktop. A persistent agent is only useful if you can inspect what it remembers. Use this area to view, edit, or correct memory entries and configure memory providers. Bad memory creates bad behavior. Keep it clean. ### Skills Skills are reusable workflows the agent can use or improve over time. The Skills screen lets you browse, install, edit, and manage them. This is where Hermes starts to feel less like a chatbot and more like a system that accumulates capability. ### Tools The Tools screen controls what the agent is allowed to do. Start conservative. Enable only what you need. Common tool categories include: - web search - browser automation - terminal - file operations - code execution - vision - image generation - text-to-speech - memory - delegation - planning If a tool is powerful, treat it with respect. Terminal and file tools can change real things on your machine. ### Schedules Schedules let Hermes run jobs later or repeatedly. Examples: - daily briefing - weekly project summary - nightly backup check - recurring website audit - morning inbox scan Hermes Desktop provides a GUI for these scheduled tasks so you do not have to hand-edit cron files. ### Gateway The Gateway screen is where messaging integrations live. Hermes can connect to platforms such as Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email, SMS, iMessage, and more depending on your setup. This is where Hermes becomes more than a desktop app. Once messaging is configured, the agent can meet you where you already work. ### Settings and Logs Use Settings when something breaks. Look for: - provider config - network settings - backup and import - debug dumps - gateway logs - agent logs Logs are boring until they save you two hours. ## Step 6: Configure a safe first toolset Before enabling everything, create a safe starting point. Recommended first setup: - chat enabled - web search enabled - memory enabled - skills enabled - schedules disabled until needed - terminal disabled unless you know why you need it - file tools disabled or scoped carefully - browser automation disabled until needed Then test gradually. Ask Hermes to perform harmless tasks first: ```text Summarize what tools are currently enabled. ``` ```text Create a short checklist for setting up my first profile. ``` ```text Remember that this profile is for AI research experiments. ``` Then inspect whether the memory entry appears correctly. ## Step 7: Create your first useful workflow A good first Hermes Desktop workflow should be simple and low risk. Try a daily research briefing: ```text Every weekday morning, search for the top three AI agent development updates and summarize them in this chat. ``` If Hermes asks for confirmation, review the schedule carefully. Then check the Schedules screen. You should be able to inspect or edit the job from the GUI. This teaches you the core loop: 1. ask in natural language 2. review the planned action 3. confirm if appropriate 4. inspect the created schedule 5. edit or disable it from the app That is the Hermes Desktop value proposition in miniature. ## Troubleshooting common setup issues ### The app cannot find Hermes If local mode cannot detect Hermes, check whether `~/.hermes` exists. On macOS/Linux: ```bash ls -la ~/.hermes ``` If the folder does not exist, rerun the guided installer from the app or install Hermes Agent directly using the official docs. ### Provider key is missing Open the Providers or Models screen and verify your API key is saved. If you use a local model, verify the local server is running. ### Remote mode will not connect Check three things: - URL is correct - API key is correct - server firewall allows the connection If the server is behind a proxy, confirm the proxy forwards streaming responses correctly. Chat uses streaming, and broken proxy buffering can make the app feel stuck. ### Windows SmartScreen warning appears If the installer is not code-signed, Windows may warn on first launch. Only continue if you downloaded the installer from the official source. ### WSL install stalls Some WSL install paths can stall if a dependency step expects a sudo password but has no interactive terminal. If that happens, use the official Hermes troubleshooting docs for the current workaround rather than guessing. ## Practical setup checklist Use this checklist after installation: - [ ] App opens without crashing - [ ] Local or remote backend selected - [ ] Model provider configured - [ ] First chat response works - [ ] Session appears in history - [ ] Memory screen opens - [ ] Tools screen shows enabled tools - [ ] Logs are accessible - [ ] Backup/export path is understood - [ ] Gateway setup is skipped until needed - [ ] Schedules are disabled until intentionally created ## Final advice Do not enable every feature on day one. Hermes Desktop exposes a serious agent stack. Treat it like a control panel, not a toy. Start with chat, memory, sessions, and one provider. Add tools only when you need them. Add schedules only when you trust the workflow. Add messaging gateways after the local experience is stable. That path gives you the benefit of Hermes without turning setup into chaos. Hermes Desktop makes open-source agents easier to run. The smart move is to make them safe and useful first, then powerful.