/ README.md
README.md
1 <p align="center"> 2 <img src="docs/images/logo.png" alt="EasyShell Logo" width="200" /> 3 </p> 4 5 # EasyShell 6 7 **AI-Native Server Operations Platform** 8 9 Let AI write your scripts, orchestrate multi-host tasks, and analyze your infrastructure — while you focus on what matters. 10 11 [](./LICENSE) 12 [](https://docs.easyshell.ai) 13 [](https://discord.gg/akQqRgNB6t) 14 15 **Language**: English | [简体中文](./README.zh-CN.md) | [繁體中文](./README.zh-TW.md) | [한국어](./README.ko.md) | [Русский](./README.ru.md) | [日本語](./README.ja.md) 16 17 --- 18 19 ## Why EasyShell? 20 21 Traditional server management tools expect you to write every script, SSH into every box, and interpret every output yourself. EasyShell flips that model: **AI is the operator, you are the decision-maker.** 22 23 - **Describe what you need in plain language** → AI writes production-ready shell scripts with diff review 24 - **Set a goal across multiple hosts** → AI plans the execution steps, runs them, and synthesizes the results 25 - **Schedule automated inspections** → AI analyzes output and decides whether to alert your team via bot channels 26 - **Connect via Web SSH** → Full terminal with file manager, multi-tab, search — no local client needed 27 28 --- 29 30 ## Core Features 31 32 ### 1. AI Script Assistant 33 34 > Describe what you want. AI writes the script. Review the diff. One click to apply. 35 36 The AI Script Workbench is a split-panel editor where you describe requirements in natural language, and AI generates (or modifies) shell scripts targeting your chosen OS. Real-time streaming shows the script being written. A built-in diff view highlights exactly what changed. A summary tab explains the modifications in your language. 37 38 <p align="center"> 39 <img src="docs/images/AI%20Script%20helper.png" alt="AI Script Assistant — live code generation with diff review" width="90%" /> 40 </p> 41 42 **How it works:** 43 1. **Describe** — write your requirements in natural language, choose the target OS 44 2. **Generate** — AI streams a production-ready script in real time 45 3. **Review** — built-in diff view highlights every change; summary tab explains modifications 46 4. **Apply** — one click to save the script to your library or dispatch it immediately 47 48 ### 2. AI Task Orchestration 49 50 > "Check disk and memory on all hosts, flag anything over 80%, and suggest fixes." — Done. 51 52 The AI Chat interface lets you issue high-level operational goals. AI decomposes them into a multi-step execution plan (explore → analyze → report), dispatches scripts to target hosts, collects results, and delivers a structured analysis with risk assessment and actionable recommendations — all in a single conversation turn. 53 54 <p align="center"> 55 <img src="docs/images/AI%20task%20orchestration.png" alt="AI Task Orchestration — multi-step execution plan with analysis" width="90%" /> 56 </p> 57 58 **How it works:** 59 1. **Instruct** — describe a high-level goal in the AI Chat (e.g. "check disk on all hosts") 60 2. **Plan** — AI decomposes the goal into a multi-step execution plan (explore → analyze → report) 61 3. **Execute** — scripts are dispatched to target hosts in parallel; results collected automatically 62 4. **Report** — AI delivers a structured analysis with risk assessment and actionable recommendations 63 64 ### 3. AI Scheduled Inspections 65 66 > **Cron → Script → AI Analysis → Intelligent Alert** — AI analyzes output and decides whether to alert your team. 67 68 Schedule inspection tasks with cron expressions and select scripts from the built-in script library. EasyShell dispatches them to agents on schedule, collects output (disk, memory, services, logs), sends it to your AI model for intelligent analysis, and **lets AI decide whether the results warrant an alert** — pushing notifications only when they matter. 69 70 <p align="center"> 71 <img src="docs/images/schedule_task.png" alt="AI Scheduled Inspections — cron-based tasks with AI-powered output analysis and intelligent alerting" width="90%" /> 72 </p> 73 74 **How it works:** 75 1. **Configure** — cron expression + script (from library or custom) + AI analysis prompt + notification rules 76 2. **Execute** — EasyShell dispatches to target agents on schedule 77 3. **Analyze** — Output sent to AI model (OpenAI / Gemini / GitHub Copilot / Custom) for intelligent analysis 78 4. **Notify** — AI determines severity and pushes alerts via bot channels when action is needed 79 80 **Notification modes:** Always push, push on failure, push on warning, or **AI decides** — the AI model evaluates the output and autonomously determines if an alert is necessary. 81 82 **Supported Bot Channels** ([Configuration Guide](https://docs.easyshell.ai/configuration/bot-channels/)): 83 84 | Bot | Status | 85 |-----|--------| 86 | [Telegram](https://docs.easyshell.ai/configuration/bot-channels/) | ✅ Supported | 87 | [Discord](https://docs.easyshell.ai/configuration/bot-channels/) | ✅ Supported | 88 | [Slack](https://docs.easyshell.ai/configuration/bot-channels/) | ✅ Supported | 89 | [DingTalk (钉钉)](https://docs.easyshell.ai/configuration/bot-channels/) | ✅ Supported | 90 | [Feishu (飞书)](https://docs.easyshell.ai/configuration/bot-channels/) | ✅ Supported | 91 | [WeCom (企业微信)](https://docs.easyshell.ai/configuration/bot-channels/) | ✅ Supported | 92 93 ### 4. Fully Functional Web SSH 94 95 > Real terminal. Real file manager. No SSH client required. 96 97 A production-grade web terminal with multi-tab sessions, integrated file manager (upload, download, create, delete, navigate), full-text search within terminal buffer, and persistent connections via WebSocket. Manage files and run commands side by side. 98 99 <p align="center"> 100 <img src="docs/images/Fully%20functional%20web%20SSH.png" alt="Web SSH — terminal with file manager and multi-tab" width="90%" /> 101 </p> 102 103 ### 5. Host Management & Monitoring 104 105 > Unified view of all servers with real-time status, batch operations, and agent lifecycle management. 106 107 Manage hosts individually or in bulk — add via form or CSV import, organize into clusters, monitor connection status, and deploy/upgrade agents with one click. The unified dashboard shows health metrics at a glance. 108 109 <p align="center"> 110 <img src="docs/images/host-management.png" alt="Host Management — unified server dashboard with batch operations" width="90%" /> 111 </p> 112 113 ### 6. Real-Time Streaming Logs 114 115 > Watch script execution unfold live across all target hosts. 116 117 When you dispatch a script, EasyShell streams output from every agent in real time. Color-coded logs, timestamps, and per-host filtering help you spot issues instantly — no more waiting for batch jobs to complete. 118 119 <p align="center"> 120 <img src="docs/images/realtime-logs.png" alt="Real-Time Logs — live streaming output from multiple hosts" width="90%" /> 121 </p> 122 123 ### 7. Security & Risk Controls 124 125 > Built-in safeguards: approval workflows, audit trails, and operation restrictions. 126 127 Configure which operations require approval before execution. All actions are logged for compliance. Role-based access control limits who can do what, and sensitive commands can be flagged or blocked entirely. 128 129 <p align="center"> 130 <img src="docs/images/security-controls.png" alt="Security Controls — approval workflows and audit logging" width="90%" /> 131 </p> 132 133 --- 134 135 ## Quick Start 136 137 ```bash 138 git clone https://github.com/easyshell-ai/easyshell.git 139 cd easyshell 140 cp .env.example .env # Edit .env if needed 141 docker compose up -d 142 ``` 143 144 No local build required — pre-built images are pulled automatically from [Docker Hub](https://hub.docker.com/u/laolupaojiao). 145 146 Open `http://localhost:18880` → login with `easyshell` / `easyshell@changeme`. 147 148 > **Want to use GHCR instead?** Set in `.env`: 149 > ``` 150 > EASYSHELL_SERVER_IMAGE=ghcr.io/easyshell-ai/easyshell/easyshell-server:latest 151 > EASYSHELL_WEB_IMAGE=ghcr.io/easyshell-ai/easyshell/easyshell-web:latest 152 > ``` 153 154 > **Developer? Build from source:** 155 > ```bash 156 > docker compose -f docker-compose.build.yml up -d 157 > ``` 158 159 --- 160 161 ## Full Feature Set 162 163 | Category | Features | 164 |----------|----------| 165 | **AI Intelligence** | AI Script Assistant (generate / modify / diff / summary), AI Task Orchestration (multi-step plans, parallel execution, analysis), AI Scheduled Inspections (cron-based, AI output analysis, intelligent alert decisions, multi-channel bot push), AI Chat, Inspection Reports, Operation Approvals | 166 | **Operations** | Script library, batch execution, real-time streaming logs, Web SSH terminal with file manager | 167 | **Infrastructure** | Host management, real-time monitoring, cluster grouping, agent auto-deployment | 168 | **Administration** | User management, system config, AI model settings (OpenAI / Gemini / Copilot / Custom), risk control | 169 | **Platform** | i18n (EN / ZH), dark/light theme, responsive design, audit logging | 170 171 --- 172 173 ## Architecture 174 175 ``` 176 ┌──────────────┐ HTTP/WS ┌──────────────────┐ 177 │ EasyShell │◄─────────────────────►│ EasyShell │ 178 │ Agent │ register / heartbeat │ Server │ 179 │ (Go 1.24) │ script exec / logs │ (Spring Boot 3.5)│ 180 └──────────────┘ └────────┬─────────┘ 181 │ 182 ┌────────┴─────────┐ 183 │ EasyShell Web │ 184 │ (React + Ant Design)│ 185 └──────────────────┘ 186 ``` 187 188 ## Tech Stack 189 190 | Component | Technology | 191 |-----------|-----------| 192 | Server | Java 17, Spring Boot 3.5, Gradle, JPA/Hibernate, Spring AI, Spring Security | 193 | Agent | Go 1.24, single binary, zero runtime dependencies | 194 | Web | React 19, TypeScript, Vite 7, Ant Design 6 | 195 | Database | MySQL 8.0 | 196 | Cache | Redis 7 | 197 198 ## Project Structure 199 200 ``` 201 easyshell/ 202 ├── easyshell-server/ # Central management server (Java / Spring Boot) 203 ├── easyshell-agent/ # Agent client (Go, single binary) 204 ├── easyshell-web/ # Web frontend (React + Ant Design) 205 ├── docker-compose.yml # Production deployment (pulls pre-built images) 206 ├── docker-compose.build.yml # Development (local build from source) 207 ├── Dockerfile.server # Server + Agent multi-stage build 208 ├── Dockerfile.web # Web frontend multi-stage build 209 ├── .github/workflows/ # CI/CD: build & publish Docker images 210 └── .env.example # Environment configuration template 211 ``` 212 213 ## Documentation 214 215 Visit **[docs.easyshell.ai](https://docs.easyshell.ai)** for: 216 217 - Installation & deployment guide 218 - Getting started walkthrough 219 - Configuration reference 220 - Development guide 221 222 ## Community 223 224 [](https://discord.gg/akQqRgNB6t) 225 226 Join our Discord community for support, discussions, and updates: 227 **[https://discord.gg/akQqRgNB6t](https://discord.gg/akQqRgNB6t)** 228 229 ## License 230 231 This project is licensed under the [MIT License](./LICENSE).