How to Install Hermes Agent

According to a 2026 developer tools survey, 43% of engineers setting up local autonomous AI runtimes report installation failures due to missing binary dependencies rather than runtime code errors [TechJack 2026 Guide]. The gap between a successful script run and a production-grade agent is where this guide lives.

Nous Research Hermes Agent is an open-source, self-improving autonomous AI agent with a closed learning loop and persistent memory. Developers deploy it locally or on remote servers to run task cycles, create custom skills, and coordinate operations. The framework is licensed under the MIT license, positioning it as a peer ecosystem alongside open standards like OpenClaw. For teams building on the OpenClaw standard, see Fastio storage for OpenClaw to learn how it supports persistent agent output.

While automated installation scripts handle core Node.js or Python packages, they often crash when local processes require native system binaries. The agent depends on system-level tools to parse local files, extract text, and handle multimedia streams. Without these tools, the agent will throw unhandled exceptions during execution.

Furthermore, local deployments are inherently ephemeral. Running the agent on a local workstation, a Docker container, or serverless hosts like Modal works for individual tests, but it fails when team collaboration is required. To build a reliable system, developers must pair the local agent runtime with a persistent cloud workspace. Fastio provides the persistent storage layer where agents and humans collaborate. The agent writes files to the workspace, while humans edit them, review logs, and manage project workflows in a shared environment.

The installation process for macOS, Linux, and Windows Subsystem for Linux (WSL2) uses a single command line interface entry. The installer script downloads the necessary packages, configures the environment paths, and sets up a local repository. The installer automatically creates a virtual environment to isolate the agent dependencies from your system packages, preventing version conflicts.

To begin the installation, open your terminal and run the following command, as documented in the Nous Research Hermes Agent installation guide:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

The script performs several actions. First, it verifies that your system has compatible versions of Python and Node.js. Second, it clones the core files to the folder path ~/.hermes/hermes-agent. Finally, it adds the runtime binary to your path variable.

After the installation script completes, you must reload your terminal configuration for the changes to take effect. Run the command that matches your shell, such as source ~/.bashrc or source ~/.zshrc. If you skip this step, your terminal will not recognize the hermes command.

Once the command is available, run the interactive configuration wizard:

hermes setup

The wizard prompts you to select your language model provider, such as OpenAI, Anthropic, or OpenRouter. You then input your API keys and select the tools you want to enable, including web search and browser automation. For a faster setup, running hermes setup --portal configures your models and default tool settings automatically via OAuth. The configuration parameters are written to ~/.hermes/config.yaml. To verify that the installation succeeded and all paths are correct, run the diagnosis command:

hermes doctor

This checks your local environment and outputs a status report detailing any missing components.

Setting up the agent on a native Windows workstation requires a different installation process. Rather than using bash scripts, Nous Research provides a dedicated PowerShell installer that configures the Windows environment variables and folder structures.

To install the agent on Windows, open an elevated PowerShell window as an Administrator. You must adjust your script execution policy before running the command, as Windows blocks unsigned scripts by default. Execute the following commands in sequence:

Set-ExecutionPolicy RemoteSigned -Scope Process
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

The installer verifies your local system configuration, downloads the Windows-specific binaries, and places the config files in %LOCALAPPDATA%\hermes\config.yaml.

After the installation completes, restart your PowerShell session to load the new environment variables. You can then run hermes setup or hermes doctor to verify your environment. If you prefer a graphical user interface instead of the command line, you can download the Hermes Desktop application installer directly from the official website. The desktop app wraps the core agent process in a native window, making it easier to configure and monitor without terminal commands.

Common Windows issues include path limits and registry restrictions. If the installation fails to write files, confirm that your user account has write permissions to %LOCALAPPDATA% and that your antivirus software is not blocking the installation script. The PowerShell script creates a dedicated folder path for logs, which you can monitor by running hermes logs in a separate command window.

If you are using Windows Subsystem for Linux (WSL2), you should use the macOS and Linux curl installation path instead of the PowerShell script. WSL2 runs inside a virtualized Linux kernel, meaning the Windows system variables will not map to your Linux terminal. Using the bash installer inside your WSL2 distribution ensures the agent runs within the correct environment boundaries.

Persist Hermes Agent files across sessions

Deploy a shared workspace with a Model Context Protocol server endpoint for your agent's reads and writes, complete with version history and semantic search. Starts with a 14-day free trial.

Start 14-Day Trial

Most installation guides skip the step of configuring local tool dependencies, leading to runtime failures. When the agent attempts to perform local file operations or media processing, it relies on system-level binaries. If these binaries are missing, the agent halts.

The two most critical dependencies are ripgrep and ffmpeg. The agent uses ripgrep to search local folder paths and index files quickly. Without it, the agent's file retrieval capabilities are slow or disabled. To install ripgrep on your system:

• On macOS: Run brew install ripgrep.
• On Ubuntu/Debian: Run sudo apt install -y ripgrep.
• On Windows: Run winget install BurntSushi.ripgrep.

The second dependency, ffmpeg, is required for media file processing. When the agent connects to messaging systems like Telegram or Discord to receive audio messages or generate voice bubbles, it uses ffmpeg to transcode files. It also uses it to extract video frames for multimodal analysis. To install ffmpeg:

• On macOS: Run brew install ffmpeg.
• On Ubuntu/Debian: Run sudo apt install -y ffmpeg.
• On Windows: Run winget install Gyan.FFmpeg.

After installing these tools, run hermes doctor to verify that the paths are registered.

Another common failure occurs when using browser automation tools. The agent uses Playwright to drive headless browsers, which requires specific system libraries. If browser tools fail, navigate to the installation directory and install the required components manually:

cd ~/.hermes/hermes-agent
npx playwright install --with-deps

This command downloads the headless browsers and configures the native system dependencies required to run them. Finally, if you suspect several agent instances are running and locking resources, check the active processes by running ps aux | grep hermes on Unix systems, and terminate duplicate processes. If you run the agent as a background service, check the logs regularly with hermes logs or view active console outputs. This reveals hidden dependency errors that do not appear in the primary chat interface.

Once your local installation is stable, you must address the storage layer. Local agent environments are ephemeral. Files written to local folders are isolated, and running several agent runtimes can result in data fragmentation. Furthermore, human team members cannot easily collaborate with an agent that only exists on a local computer.

Fastio solves this problem by providing shared workspaces where humans and agents collaborate. Fastio is not just a storage service. It is an intelligent workspace platform. When you create an organization-owned workspace, you can enable Intelligence Mode. This automatically indexes all uploaded files for semantic search and RAG chat. Your agent can read and write files using Fastio's Model Context Protocol (MCP) server, which supports Streamable HTTP at /mcp and legacy SSE at /sse. See the Fastio MCP server guide for details on tool-surface integration.

This setup enables several advanced workflows:

• File Version History: Every file in Fastio keeps a full version history, allowing you to restore prior versions and audit agent edits.
• Collaborative Notes: Humans and agents can edit documents simultaneously using live multiplayer cursors.
• Metadata Views: Fastio turns your files into a queryable database. You can describe the fields you want to extract in natural language (such as invoice totals or contract dates), and the platform populates a structured data grid. Learn more about document data extraction on the Metadata Views product page (/product/document-data-extraction/).
• Ownership Transfer: An agent can set up workspaces, build custom structures, and then transfer the organization to a human manager via a claim link when the handoff is complete.

When the agent finishes its tasks, it can hand files off to humans using branded shares. For instance, the agent can create an Exchange share that allows clients to upload documents without having to sign up for an account.

Fastio operates on a credit-based billing system, offering plans tailored to different needs: the Solo plan costs $29/month, the Business plan is $99/month, and the Growth plan is $299/month. Every organization starts with a 14-day free trial, which requires a credit card. There is no permanent free plan. You can view plan structures on the Fastio pricing page. When your agent sets up a new workspace, it can run its initial flows during the trial, allowing you to verify the entire pipeline before committing to a plan.