# Hermes Web UI (Simplified) / 简化版说明

> **Repository / 仓库**: [https://github.com/adv-org/agent-frontend-shell](https://github.com/adv-org/agent-frontend-shell)

A lightweight web interface for Hermes Agent. No build step, no framework — just Python and vanilla JS.

Hermes Agent 的轻量级 Web 界面。无需构建步骤，无框架依赖 —— 仅使用 Python 和原生 JavaScript。

---

## Quick Start / 快速开始

### 1. Clone / 克隆

```bash
git clone https://github.com/adv-org/agent-frontend-shell.git
cd agent-frontend-shell
```

### 2. Local Run / 本地运行

**Requirements / 环境要求:** Python 3.12+

```bash
# Option 1: Direct Python / 方式一：直接运行 Python
python3 bootstrap.py

# Option 2: Shell wrapper (same as above) / 方式二：包装脚本（效果相同）
./start.sh
```

Access at / 访问地址: **http://127.0.0.1:8787**

---

## Docker Run / Docker 运行

### Single container / 单容器模式

```bash
# Edit .env first / 先编辑 .env
cp .env.example .env
# Modify HERMES_HOME, HERMES_WORKSPACE, UID, GID as needed
# 按需修改 HERMES_HOME、HERMES_WORKSPACE、UID、GID

docker compose -f docker-compose.local.yml up -d --build
```

### Two-container (WebUI + Agent) / 双容器模式

```bash
docker compose -f docker-compose.two-container.yml up -d
```

### Three-container (WebUI + Agent + DB) / 三容器模式

```bash
docker compose -f docker-compose.three-container.yml up -d
```

---

## Configuration / 配置

Key environment variables / 关键环境变量:

| Variable | Description / 说明 | Default / 默认值 |
|---|---|---|
| `HERMES_WEBUI_PORT` | Server port / 服务端口 | `8787` |
| `HERMES_WEBUI_PASSWORD` | Access password / 访问密码 | (none) |
| `HERMES_HOME` | Hermes data dir / 数据目录 | `~/.hermes` |
| `HERMES_WORKSPACE` | Workspace path / 工作区路径 | `~/workspace` |
| `UID` / `GID` | User/Group ID for permissions / 权限映射 | `1000` |

Full config reference / 完整配置参考: [README.md](README.md) → Configuration section

---

## Common Commands / 常用命令

```bash
# Check health / 健康检查
curl http://127.0.0.1:8787/health

# View logs / 查看日志
docker logs -f hermes-webui-custom

# Stop / 停止
docker compose -f docker-compose.local.yml down

# Rebuild / 重新构建
docker compose -f docker-compose.local.yml up -d --build
```

---

## Architecture / 架构

- **Backend / 后端**: Python (Flask-like), file-based state
- **Frontend / 前端**: Vanilla JS, no bundler
- **State / 状态**: Local filesystem (`~/.hermes`)

For full details / 完整详情: [ARCHITECTURE.md](ARCHITECTURE.md) | [TESTING.md](TESTING.md)
