knowhunters/hermesdeckx

[!CAUTION] Beta Preview — This is an early preview release. It has not undergone comprehensive testing. Do not use in production environments.

[!TIP] Using https://github.com/openclaw/openclaw instead? Check out https://github.com/ClawDeckX/ClawDeckX — a sister project offering the same visual management experience for OpenClaw.

Quick Navigation

• Screenshots
• Why HermesDeckX?
• Quick Start
• Docker Install
• Features
• Tech Stack

📸 Screenshots

✨ Why HermesDeckX?

macOS-Grade Visual Experience

The interface faithfully recreates the macOS design language — refined glassmorphism, rounded cards, and smooth animation transitions. Managing AI agents feels as natural as using a native desktop app.

Beginner-Friendly Setup

Guided wizards and pre-built templates let you complete HermesAgent's initial configuration and model setup without memorizing a single command.

Deep Configuration

Fine-tune every HermesAgent parameter — model switching, memory management, plugin loading, channel routing — all through a beautiful visual editor.

Real-Time Observability

Built-in monitoring dashboard with live execution status, resource consu***ion, and task history — full visibility into every agent's behavior.

Cross-Platform

Single ***ary, zero dependencies. Runs natively on Windows, macOS (Intel & Apple Silicon), and Linux (amd64 & arm64). Download and run — that's it.

Responsive & Mobile-Ready

Fully responsive layout that adapts seamlessly from large desktop monitors to tablets and mobile phones. Manage your AI agents on the go — no compromise on functionality.

Multilingual Support

Full i18n architecture with 13 built-in languages. Adding a new language requires only a translated JSON folder and a two-line code change.

Local & Remote Gateway

Seamlessly manage both local and remote HermesAgent gateways. Switch between gateway profiles with one click — perfect for multi-environment setups like dev, staging, and production.

🚀 Quick Start

Deployment Options

Choose the deployment method that best fits your needs:

1️⃣ Local Deployment (Recommended)

Install HermesDeckX on the same server as HermesAgent for full feature access and direct command execution.

✅ Advantages:

• Full feature support including direct HermesAgent command execution
• Lower latency and faster response times
• No network dependency between HermesDeckX and HermesAgent

2️⃣ Remote Gateway

Install HermesDeckX on your local machine and connect to remote HermesAgent instances via WebSocket.

⚠️ Limitations:

• Some features requiring direct HermesAgent command execution are unavailable
• Depends on stable network connection between HermesDeckX and HermesAgent Gateway
• Slightly higher latency for operations

---

One-Click Install & Maintain

The unified installer detects existing installations and lets you install, update, manage, or uninstall both ***ary and Docker deployments from a single adaptive menu.

macOS / Linux

bash
curl -fsSL https://raw.githubusercontent.com/HermesDeckX/HermesDeckX/main/install.sh | bash

Windows (PowerShell)

powershell
irm https://raw.githubusercontent.com/HermesDeckX/HermesDeckX/main/install.ps1 | iex

Manual Download

Download from https://github.com/HermesDeckX/HermesDeckX/releases. Single file, no dependencies. Just run.

bash
# Run with default settings (localhost:19788)
./HermesDeckX

# Specify port and bind address
./HermesDeckX --port 19788 --bind 0.0.0.0

# Create initial admin user on first run
./HermesDeckX --user admin --pass your_password

# All options combined
./HermesDeckX --bind 0.0.0.0 --port 19788 --user admin --pass your_password

CLI Commands

[!TIP] Forgot your credentials? Run HermesDeckX list-users to find your username, then HermesDeckX reset-password <username> <new_password> to reset your password. If your password contains special characters (e.g. !, `

HermesDeckX

Complexity within, simplicity without.
繁于内，简于形。

English | 简体中文

https://img.shields.io/github/v/release/HermesDeckX/HermesDeckX?style=for-the-badge&logo=rocket](https://github.com/HermesDeckX/HermesDeckX/releases) https://img.shields.io/badge/Build-Passing-success?style=for-the-badge&logo=github-actions](https://github.com/HermesDeckX/HermesDeckX/actions) https://img.shields.io/badge/License-MIT-green?style=for-the-badge](LICENSE)

---

HermesDeckX is an open-source web visual management platform built for https://github.com/NousResearch/hermes-agent. It is designed to lower the barrier to entry, making installation, configuration, monitoring, and optimization simpler and more efficient, while providing a more accessible onboarding experience for users worldwide, especially beginners.

[!CAUTION] Beta Preview — This is an early preview release. It has not undergone comprehensive testing. Do not use in production environments.

[!TIP] Using https://github.com/openclaw/openclaw instead? Check out https://github.com/ClawDeckX/ClawDeckX — a sister project offering the same visual management experience for OpenClaw.

Quick Navigation

• Screenshots
• Why HermesDeckX?
• Quick Start
• Docker Install
• Features
• Tech Stack

📸 Screenshots

✨ Why HermesDeckX?

macOS-Grade Visual Experience

The interface faithfully recreates the macOS design language — refined glassmorphism, rounded cards, and smooth animation transitions. Managing AI agents feels as natural as using a native desktop app.

Beginner-Friendly Setup

Guided wizards and pre-built templates let you complete HermesAgent's initial configuration and model setup without memorizing a single command.

Deep Configuration

Fine-tune every HermesAgent parameter — model switching, memory management, plugin loading, channel routing — all through a beautiful visual editor.

Real-Time Observability

Built-in monitoring dashboard with live execution status, resource consu***ion, and task history — full visibility into every agent's behavior.

Cross-Platform

Single ***ary, zero dependencies. Runs natively on Windows, macOS (Intel & Apple Silicon), and Linux (amd64 & arm64). Download and run — that's it.

Responsive & Mobile-Ready

Fully responsive layout that adapts seamlessly from large desktop monitors to tablets and mobile phones. Manage your AI agents on the go — no compromise on functionality.

Multilingual Support

Full i18n architecture with 13 built-in languages. Adding a new language requires only a translated JSON folder and a two-line code change.

Local & Remote Gateway

Seamlessly manage both local and remote HermesAgent gateways. Switch between gateway profiles with one click — perfect for multi-environment setups like dev, staging, and production.

🚀 Quick Start

Deployment Options

Choose the deployment method that best fits your needs:

1️⃣ Local Deployment (Recommended)

Install HermesDeckX on the same server as HermesAgent for full feature access and direct command execution.

✅ Advantages:

• Full feature support including direct HermesAgent command execution
• Lower latency and faster response times
• No network dependency between HermesDeckX and HermesAgent

2️⃣ Remote Gateway

Install HermesDeckX on your local machine and connect to remote HermesAgent instances via WebSocket.

⚠️ Limitations:

• Some features requiring direct HermesAgent command execution are unavailable
• Depends on stable network connection between HermesDeckX and HermesAgent Gateway
• Slightly higher latency for operations

---

One-Click Install & Maintain

The unified installer detects existing installations and lets you install, update, manage, or uninstall both ***ary and Docker deployments from a single adaptive menu.

macOS / Linux

bash
curl -fsSL https://raw.githubusercontent.com/HermesDeckX/HermesDeckX/main/install.sh | bash

Windows (PowerShell)

powershell
irm https://raw.githubusercontent.com/HermesDeckX/HermesDeckX/main/install.ps1 | iex

Manual Download

Download from https://github.com/HermesDeckX/HermesDeckX/releases. Single file, no dependencies. Just run.

bash
# Run with default settings (localhost:19788)
./HermesDeckX

# Specify port and bind address
./HermesDeckX --port 19788 --bind 0.0.0.0

# Create initial admin user on first run
./HermesDeckX --user admin --pass your_password

# All options combined
./HermesDeckX --bind 0.0.0.0 --port 19788 --user admin --pass your_password

CLI Commands

[!TIP] Forgot your credentials? Run HermesDeckX list-users to find your username, then HermesDeckX reset-password <username> <new_password> to reset your password. If your password contains special characters (e.g. !, , #, &), wrap it in single quotes to prevent shell interpretation: `HermesDeckX reset-password admin 'P@ss!w0rd#.

[!WARNING] Account lockout: After 5 consecutive failed login atte***s, the account is automatically locked for 15 minutes. During this period, login is blocked even with the correct password. To unlock immediately, run HermesDeckX unlock <username>.

[!IMPORTANT] Security Reminder: On first run, if no --user and --pass are provided, the auto-generated admin credentials will be printed to the console. Please change your username and password in the settings page immediately after logging in.

Docker Install

Recommended: Use the one-click installer above — choose Docker when pro***ed. It handles download, port configuration, mirror detection, and shows credentials automatically.

Manual method:

bash
curl -fsSL https://raw.githubusercontent.com/HermesDeckX/HermesDeckX/main/docker-compose.yml -o docker-compose.yml
docker compose up -d

After updating the image, recreate the container to apply Dockerfile and entrypoint changes:

bash
docker compose up -d --force-recreate

Open your browser at http://localhost:19700 (Docker) or http://localhost:19788 (native). The first run will auto-generate an admin account — credentials will be shown in the container logs.

HermesDeckX and HermesAgent run in the same container. HermesAgent is preinstalled in the official Docker image with version-pinned compatibility. On startup, the container entrypoint auto-starts the HermesAgent Gateway if a configuration file exists. If HermesAgent is not yet configured, complete the Setup Wizard in the web UI — no manual installation is needed.

The official Docker image also preinstalls common skill/runtime dependencies including go, python3, uv, ffmpeg, jq, ripgrep, wget, and make, so many HermesAgent skills can run out of the box without extra system package installation.

By default, the bundled HermesDeckX service connects to the local in-container Gateway at 127.0.0.1:8642. If you need to use a host or external Gateway instead, override OHD_HERMES_AGENT_GATEWAY_HOST and OHD_HERMES_AGENT_GATEWAY_PORT in docker-compose.yml.

bash
# View credentials
docker logs hermesdeckx

Docker Configuration

Ports:

To expose the Gateway port, add - "8642:8642" under ports in docker-compose.yml.

Note that exposing 8642 alone does not guarantee host access to the Gateway. The generated minimal HermesAgent config ***ds the Gateway to loopback by default, so you may also need to adjust the Gateway ***d setting for external access.

Environment Variables:

Preinstalled Runtime Tools:

• go
• python3
• uv
• ffmpeg
• jq
• ripgrep
• wget
• make

[!NOTE] The Docker image is larger than a minimal runtime because it includes the full runtime toolchain for HermesAgent skills. This ensures many skills can run out of the box without requiring you to install system packages inside the container.

Volumes:

[!TIP] HermesAgent is bundled in the image and its configuration is persisted via Docker volumes. After docker pull and recreate, HermesAgent remains available and your configuration is preserved.

Persistent Paths:

HermesAgent is preinstalled in the Docker image. If it is not yet configured, HermesDeckX will guide you through the Setup Wizard to complete the initial configuration.

The container health check uses /api/v1/health for liveness. For diagnostics, you can call /api/v1/health?detailed=true to inspect HermesDeckX, HermesAgent, Gateway, and bootstrap state together.

Resource Limits:

The default docker-compose.yml sets memory limit to 2 GB and CPU limit to 2 cores. Adjust deploy.resources.limits as needed.

✨ Features

🛠️ Tech Stack

🤝 Contributing

We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

💬 A Note from the Author

This is my first open-source project, and I hope it will continue to improve with the help of the community. If you run into any issues or have ideas for improvement, feel free to open an https://github.com/HermesDeckX/HermesDeckX/issues or submit a https://github.com/HermesDeckX/HermesDeckX/pulls. Thank you for your support. Every piece of feedback helps this project grow.

An AI predicted this project would go viral. But as we all know, AIs do hallucinate sometimes 😅

📄 License

This project is licensed under the MIT License — free to use, modify, and distribute for both personal and commercial purposes.

⭐ Star History

![Star History Chart]([***]

`.

[!WARNING] Account lockout: After 5 consecutive failed login atte***s, the account is automatically locked for 15 minutes. During this period, login is blocked even with the correct password. To unlock immediately, run CODE_TOKEN_31.

[!IMPORTANT] Security Reminder: On first run, if no CODE_TOKEN_32 and CODE_TOKEN_33 are provided, the auto-generated admin credentials will be printed to the console. Please change your username and password in the settings page immediately after logging in.

Docker Install

Recommended: Use the one-click installer above — choose Docker when pro***ed. It handles download, port configuration, mirror detection, and shows credentials automatically.

Manual method:

bash
curl -fsSL https://raw.githubusercontent.com/HermesDeckX/HermesDeckX/main/docker-compose.yml -o docker-compose.yml
docker compose up -d

After updating the image, recreate the container to apply Dockerfile and entrypoint changes:

bash
docker compose up -d --force-recreate

Open your browser at CODE_TOKEN_34 (Docker) or CODE_TOKEN_35 (native). The first run will auto-generate an admin account — credentials will be shown in the container logs.

HermesDeckX and HermesAgent run in the same container. HermesAgent is preinstalled in the official Docker image with version-pinned compatibility. On startup, the container entrypoint auto-starts the HermesAgent Gateway if a configuration file exists. If HermesAgent is not yet configured, complete the Setup Wizard in the web UI — no manual installation is needed.

The official Docker image also preinstalls common skill/runtime dependencies including CODE_TOKEN_36, CODE_TOKEN_37, CODE_TOKEN_38, CODE_TOKEN_39, CODE_TOKEN_40, CODE_TOKEN_41, CODE_TOKEN_42, and CODE_TOKEN_43, so many HermesAgent skills can run out of the box without extra system package installation.

By default, the bundled HermesDeckX service connects to the local in-container Gateway at CODE_TOKEN_44. If you need to use a host or external Gateway instead, override CODE_TOKEN_45 and CODE_TOKEN_46 in CODE_TOKEN_47.

bash
# View credentials
docker logs hermesdeckx

Docker Configuration

Ports:

To expose the Gateway port, add CODE_TOKEN_51 under CODE_TOKEN_52 in CODE_TOKEN_53.

Note that exposing CODE_TOKEN_54 alone does not guarantee host access to the Gateway. The generated minimal HermesAgent config ***ds the Gateway to CODE_TOKEN_55 by default, so you may also need to adjust the Gateway ***d setting for external access.

Environment Variables:

Preinstalled Runtime Tools:

• CODE_TOKEN_86
• CODE_TOKEN_87
• CODE_TOKEN_88
• CODE_TOKEN_89
• CODE_TOKEN_90
• CODE_TOKEN_91
• CODE_TOKEN_92
• CODE_TOKEN_93

[!NOTE] The Docker image is larger than a minimal runtime because it includes the full runtime toolchain for HermesAgent skills. This ensures many skills can run out of the box without requiring you to install system packages inside the container.

Volumes:

[!TIP] HermesAgent is bundled in the image and its configuration is persisted via Docker volumes. After CODE_TOKEN_98 and recreate, HermesAgent remains available and your configuration is preserved.

Persistent Paths:

HermesAgent is preinstalled in the Docker image. If it is not yet configured, HermesDeckX will guide you through the Setup Wizard to complete the initial configuration.

The container health check uses CODE_TOKEN_106 for liveness. For diagnostics, you can call CODE_TOKEN_107 to inspect HermesDeckX, HermesAgent, Gateway, and bootstrap state together.

Resource Limits:

The default CODE_TOKEN_108 sets memory limit to 2 GB and CPU limit to 2 cores. Adjust CODE_TOKEN_109 as needed.

✨ Features

🛠️ Tech Stack

🤝 Contributing

We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

💬 A Note from the Author

This is my first open-source project, and I hope it will continue to improve with the help of the community. If you run into any issues or have ideas for improvement, feel free to open an https://github.com/HermesDeckX/HermesDeckX/issues or submit a https://github.com/HermesDeckX/HermesDeckX/pulls. Thank you for your support. Every piece of feedback helps this project grow.

An AI predicted this project would go viral. But as we all know, AIs do hallucinate sometimes 😅

📄 License

This project is licensed under the MIT License — free to use, modify, and distribute for both personal and commercial purposes.

⭐ Star History

![Star History Chart]([***]