Set up a self-directed AI agent with Hermes

Hermes Agent is a self-directed AI assistant that connects to your local models to execute system tasks, generate code, and manage workflows. It retains memory across sessions and creates reusable skills based on your interactions.

In Olares, you can use the built-in skills that allow your agent to manage your device's files and applications. You can also interact with your agent remotely via messaging platforms like Discord, or integrate it with other applications like Open WebUI.

Learning objectives

In this guide, you will learn how to:

• Install Hermes Agent on Olares.
• Configure Hermes Agent to connect to a local model.
• Interact with your agent directly via the terminal.
• Integrate with Discord for remote chat.
• Use Olares skills to manage files and applications via the agent.
• Enable the Gateway API to connect Hermes Agent with other applications like Open WebUI.

Prerequisites

Before you begin, you need:

• Discord account: Required to create the bot application.

• Discord server: A server where you have permissions to add bots.

• The following model:

  Model type	Model	How to get it
  Chat	Qwen3.6-27B (llama.cpp)	Install from Market

  TIP

  Hermes Agent requires a model with a context window of at least 64K tokens.

Optional: Use a different model

You can use a different model size or provider instead of the one listed above:

• Install a different model app from Market.
• Create a model instance from Engine Base apps to bring your own model.

If your AI agent app has the Olares CLI and Agent Skills installed, ask it to deploy the model and skip the manual setup. For example:

Deploy qwen3.5:9b on my Olares using the Ollama Engine Base.

Install Hermes Agent

1. Open Market and search for "Hermes".

   

2. Click Get, and then click Install. When the installation finishes, two shortcuts appear in the Launchpad:

   • Hermes CLI: The command line interface
   • Dashboard: The graphical dashboard

   

Run multiple Hermes agents

Olares supports app cloning. If you want to run multiple independent AI agents for different tasks, you can clone the Hermes Agent app. For more information, see Clone applications.

Configure Hermes Agent

Run a quick setup to connect Hermes Agent to your local model.

Step 1: Get model connection details

How model connections work

A standalone model on Olares runs as a separate service from the client app. To connect them, the client needs the exact Model name and a Base URL that matches the API format it expects.

You can get both values from the model's console. For more details, see Connect AI apps.

1. Open the model app from Launchpad. Its Model Console opens automatically.

2. Wait until Model shows READY and Engine shows RUNNING.

   

3. Under Model, copy the Model name exactly as shown.

4. Under Engine:

   a. Connection source: Select Apps in Olares.

   b. API format: Select OpenAI-Compatible.

   c. Copy the provided Base URL exactly as shown.

5. Go to the Configuration tab, expand Advanced parameters, and then note down the --ctx-size value, 131072. This is the context size, and you will need it later.

Step 2: Run the setup wizard

1. Open the Hermes CLI app from the Launchpad.

2. Enter the following command to start the configuration wizard:

   hermes setup

3. The wizard guides you through a series of steps. Use the arrow keys to navigate and press Enter to confirm.

   Settings	Option
   How would you like to set up Hermes	Select Full setup — configure every provider, tool & option yourself (bring your own keys).
   Select provider	Select Custom endpoint (enter URL manually).
   API base URL	Enter the Base URL you copied from the Model Console. For example, https://e46e044d.laresprime.olares.com/v1.
   API key	Enter any text as a placeholder value, such as local. The input remains hidden for security.
   Select API compatibility mode	Enter 1 to select Auto-detect [current]. This option uses Hermes URL heuristics and works best for standard OpenAI-compatible endpoints.
   Use this model	Verify that the detected model name is correct, and then enter y.
   Context length in tokens	Leave this field blank to auto-detect. Note: If your model's context window is less than 65536, enter a value greater than 65536. Hermes Agent requires a minimum context window of 64K tokens.
   Display name	Enter a name to identify this model, such as qwen3.6-27b-local.
   Select terminal backend	Select Local - run directly on this machine.
   Select platforms to configure	Press ESC to skip for now.
   Tools for CLI	Press ESC to skip for now.
   Choose a provider	Select Skip - keep defaults / configure later.
   Select Search Provider	Select Skip - keep defaults / configure later.

4. Keep the Hermes CLI window open for the next step.

Interact with Hermes Agent

Option 1: Terminal chat

The Terminal User Interface (TUI) runs directly in the Hermes CLI with no extra setup. It is ideal for quick tests.

1. When the setup wizard completes, it shows Ready to go with the available commands:

   • hermes: Start chatting.
   • hermes gateway: Start the messaging gateway.
   • hermes doctor: Check for issues.

2. Type hermes and press Enter to launch the TUI.

   TIP

   If you exited the wizard, manually start the chat by entering hermes in the Hermes CLI.

3. Send a message, such as what can you do, to verify that the agent responds correctly.

   

4. To close the TUI and return to the standard CLI, type /exit, and then press Enter.

Option 2: Remote chat via Discord

To chat with your agent remotely, connect it to a Discord bot.

Step 1: Create a Discord bot

1. Log in to the Discord Developer Portal with your Discord account.

2. Select Applications from the left sidebar, and then click New Application.

   

3. Enter a name for the new app, agree to the terms, and then click Create.

   

4. From the left sidebar, select Bot.

5. Scroll down to the Privileged Gateway Intents section and enable the following settings:

   • Presence Intent
   • Server Members Intent
   • Message Content Intent

   

6. Click Save Changes.

7. Scroll up to the Token section, click Reset Token, and then copy the generated token for your Discord bot. You need the token for messaging platform configuration later in the Hermes CLI.

   

Step 2: Invite the bot to your server

1. From the left sidebar, select OAuth2, and then find the OAuth2 URL Generator section:

   a. In Scopes, select Bot and applications.commands.

   

   b. Scroll down to Bot Permissions, set the permissions as shown in the following image. You can modify the settings later.

   

2. Copy the Generated URL at the bottom.

3. Paste the URL into a new browser tab, select your Discord server from Add to server, click Continue, and then click Authorize.

   

   The bot is authorized and added to your server.

   

Step 3: Configure the messaging platform

Connect Hermes Agent to your Discord bot by configuring and running the Hermes gateway.

1. Open the Hermes CLI, and then enter the following command to start the configuration wizard:

   hermes gateway setup

2. Select Discord as your messaging platform.

3. Follow the prompts to configure the bot integration:

   • Discord bot token: Enter the bot token generated from your Discord Developer Portal. The input remains hidden.
   • Allowed user IDs or usernames: Enter your Discord user ID to restrict access to yourself.
   • (Optional) Home channel ID: Enter the ID of the Discord channel where the bot operates.

4. Select Done.

5. When prompted to Restart the gateway to pick up changes, enter y.

6. Check your bot status in Discord. A green status icon confirms the bot is online, which means the gateway restarted successfully and the configuration is correct.

Step 4: Authorize your account

For security, the bot does not talk to unauthorized users. You must pair your Discord account with the bot.

1. Send a Direct Message to your new bot. The bot will reply with an error message containing a pairing code.

2. Open the Hermes CLI and enter the following command:

   hermes pairing approve discord {Your-Pairing-Code}

3. Once approved, you can start chatting with your agent in Discord. If you are talking to it in a channel, mention it first.

Manage Olares with your Hermes Agent

Use the pre-installed Olares CLI skills directly in Hermes Agent to manage files and applications on your Olares device. For example, ask it to list files, read logs, or install apps from Olares Market.

1. Open the Hermes CLI from the Launchpad.

2. Run the following commands one by one to confirm that both olares-cli and its skills are properly installed and enabled:

   olares-cli -v
   hermes skills list

3. Before using the skills, run the following command to log in to your Olares account. Replace {your-olares-id} with your Olares ID (e.g. olaresdemo@olares.com):

   olares-cli profile login --olares-id {your-olares-id}

4. Follow the prompt to enter your Olares login password. For security, the password is hidden.

5. You can now enter the TUI, and ask the agent to interact with your Olares environment. For example, ask it to install an app from Olares Market.

Integrate Hermes Agent with other applications

Hermes Agent provides an OpenAI-compatible API, allowing you to integrate it with other applications like Open WebUI or Hermes Workspace.

Step 1: Enable the Gateway API

1. Open Olares Settings, and then go to Applications > Hermes Agent > Manage environment variables.

   

2. Find API_SERVER_ENABLED, click edit_square, and then set its value to true.

3. Click Confirm.

4. Find HERMES_API_SERVER_KEY, click edit_square, and then enter the value. Ensure the key meets the following requirements:

   • It must be at least 8 characters long.
   • It can only contain letters, numbers, and common symbols.
   • It cannot be a predictable placeholder value, such as "your_API_key".

5. Click Confirm, and then click Apply.

Step 2: Get the Gateway API URL

1. Go to Applications > Hermes Agent > Hermes Gateway API.
2. Copy the endpoint URL. For example:

   https://baf3d7172.olaresdemo.olares.com

Step 3: Verify the API is running

Open your browser and go to your gateway URL appended with /health:

https://{your-gateway-url}/health

If the API is enabled successfully, the page displays a response confirming the service is active. For example, {"status": "ok", "platform": "hermes-agent"}.

Step 4: Connect your application

The following steps demonstrate how to connect with Open WebUI.

1. In Open WebUI, click your profile icon and select Admin Panel.

2. Go to Settings > Connections.

3. On the right of Manage OpenAI API Connections, click add to add a new connection.

   

4. Configure the settings as follows:

   • API Base URL: Enter your Hermes Gateway API URL and append /v1. For example, https://baf3d7172.olaresdemo.olares.com/v1.
   • Auth: Select Bearer, and then enter the HERMES_API_SERVER_KEY you set previously.

5. Click refresh to check the connection, and then click Save.

6. Go to the New chat page and verify that hermes-agent appears in the model drop-down list. You can start chatting with it now.

Advanced configuration

To manually adjust parameters, edit the configuration files directly, and then restart the Hermes CLI to apply the changes.

1. Open the Files app from the Launchpad.
2. Go to Data > hermesagent > home, and locate the configuration files, such as config.yaml and .env.

The file structure and configuration options match the official defaults. For detailed parameter descriptions, see the Hermes configuration guide.

FAQs

How to manually restart the Hermes gateway?

You can restart the gateway manually using one of the following methods:

• Use the Hermes CLI

  This is the fastest method. Open the Hermes CLI from the Launchpad, and then run the following command:

  restart-gateway

• Use the Hermes Dashboard

  This is the most intuitive method. Open the Hermes Dashboard from the Launchpad, and then select Restart Gateway in the left sidebar.

• Use Control Hub

  Open Control Hub, and then go to Browse > {username} > hermesagent-{username} > Deployments > hermesagent, and then click Restart in the upper-right corner. This method completely restarts the entire service, which takes slightly longer.

Why does the gateway fail to start after configuring the API?

Your gateway will fail to start if the configured API key does not meet Hermes security requirements. When this happens:

• The Gateway API displays an upstream connect error.
• The system logs show the message [Api_Server] Refusing to start: API_SERVER_KEY is set to a placeholder value.

To resolve this issue, reset your HERMES_API_SERVER_KEY:

1. Open Olares Settings, and then go to Applications > Hermes Agent > Manage environment variables.

2. Set a new key for HERMES_API_SERVER_KEY that meets the following requirements:

   • It must be at least 8 characters long.
   • It can only contain letters, numbers, and common symbols.
   • It cannot be a predictable placeholder value, such as "your_API_key".

3. Click Save, and then click Apply.

Next steps

After you complete the basic setup, explore the official resources to expand your agent's capabilities:

• For advanced terminal commands, see CLI Interface.
• For integration with Slack, Telegram, and other platforms, see Messaging Platforms.
• For installation of skills, see Skills System.
• For installation of tools, see Tools & Toolsets.
• For information about best practices and optimization, see Tips & Best Practices.

Note on sudo commands

The Hermes CLI in the Olares environment does not support sudo commands. Ignore any steps in the official documentation that require sudo privileges.

Learn more

• How do I create a server in Discord
• How to find the Channel ID number
• OpenClaw