server-manager/README.md

# ServerManager

<p align="center">
  <strong>Desktop GUI for managing remote servers</strong><br>
  CustomTkinter + Paramiko | Dark Theme | Claude Code Integration
</p>

<p align="center">
  <a href="#english">English</a> |
  <a href="#русский">Русский</a> |
  <a href="#中文">中文</a>
</p>

---

## English

### Features

- **Server CRUD** — add, edit, delete servers (SSH, Telnet, RDP, MariaDB, MSSQL, PostgreSQL)
- **SSH Terminal** — execute commands with auto-sudo (password via stdin, invisible in `ps`)
- **SFTP Transfer** — upload/download files with progress bar
- **SSH Keys** — generate ed25519, install on server, copy to clipboard
- **Status Monitor** — background check every 60 sec (online/offline badges)
- **Claude Code Integration** — one-click setup, shared config with `/ssh` skill
- **TOTP / 2FA** — Google Authenticator compatible codes with live countdown, one-click copy
- **Encryption** — servers.json encrypted with Fernet (passwords never stored in plaintext)
- **Backups** — manual and automatic backups with one-click restore
- **Configurable Config Path** — change servers.json location via GUI
- **Localization** — GUI in English, Russian, Chinese with language switcher
- **About Dialog** — app info, features, quick start guide
- **Dark Theme** — modern CustomTkinter interface

### Installation

#### From source
```bash
git clone https://git.sensey24.ru/aibot777/server-manager.git
cd server-manager
pip install -r requirements.txt
python main.py
```

#### Pre-built binary
Download from [`releases/`](releases/) folder — standalone `.exe` (Windows) or binary (Linux/Mac).
No Python installation required.

### Building

Build for your current platform:
```bash
pip install pyinstaller
python build.py
```

Output goes to `releases/ServerManager-vX.Y.Z-{platform}.exe`

### Usage

1. **Launch** — `python main.py` or run the executable
2. **Add server** — click "+ Add" in sidebar, fill alias, IP, port, user, password, type
3. **Terminal** — select server → Terminal tab → type command → Run
4. **Files** — select server → Files tab → set paths → Upload/Download
5. **Keys** — Keys tab → Generate Key → Install on Server
6. **Setup** — Setup tab → "Install Everything" → Claude Code ready
7. Status badges update automatically (green = online, red = offline)

### Claude Code Integration

ServerManager and Claude Code share the same config file: `~/.server-connections/servers.json`

**How it works:**
```
ServerManager GUI  ←→  ~/.server-connections/servers.json  ←→  ssh.py (Claude Code)
      ↕                                                          ↕
  Add/edit/delete                                           /ssh skill
  servers in GUI                                         executes commands
```

- Add a server in GUI → Claude Code sees it immediately via `/ssh list`
- Both use the same `ssh.py` + `servers.json`
- Passwords **never** pass through the AI API

**New SSH Commands:**
- `ssh.py --info ALIAS` — safe server information (no credentials)
- `ssh.py --set-note ALIAS "desc"` — update server notes
- `ssh.py --list` now shows Notes column
- Fuzzy alias search: search by keyword (e.g., "tor" finds "API TOR contabo..."), word-boundary priority
- SFTP path fix: remote path normalization for Windows/Git Bash with double slash //
- `--no-sudo` flag for commands that don't need elevation
- Upload/download progress: files >=1MB show 25/50/75% milestones with size, time, and speed

**Setup on a new machine:**
1. Install ServerManager (clone repo or download binary)
2. Open Setup tab → click "Install Everything"
3. Done. Claude Code now has `/ssh` skill and access to your servers

The Setup tab installs:
- `ssh.py` → `~/.server-connections/` (SSH utility)
- `encryption.py` → `~/.server-connections/` (encryption module for CLI)
- `/ssh` skill → `~/.claude/commands/ssh.md` (Claude Code skill)
- SSH key (ed25519) — if not exists
- Checks for duplicates — safe to run multiple times

### Configuration

Shared config location: `~/.server-connections/servers.json` (encrypted with Fernet).

The config path can be changed via Setup tab → Configuration → "Change Path".

Settings are stored in `~/.server-connections/settings.json`.

**Backups:**
- Automatic backups every 10 minutes (on save)
- Manual backup via Setup tab → "Backup Now"
- Restore from any backup via dropdown + "Restore"
- Backups stored in `~/.server-connections/backups/`
- Pre-encryption backup created automatically on first migration

### Auto-sudo

The app automatically handles privilege escalation:

- If `user: "root"` — commands execute directly, no sudo needed
- If `user` is non-root — the app automatically wraps the command in `sudo -S` and feeds the password from `servers.json` via stdin
- The password is **never** passed as a command-line argument (invisible in `ps aux`)
- You just type the command (e.g. `systemctl restart nginx`) — the app decides whether sudo is needed and handles it
- In the GUI terminal, the "sudo" checkbox is enabled by default for non-root users; uncheck it for commands that don't need elevation

```
You type:     systemctl restart nginx
App executes: sudo -S -p '' bash -c 'systemctl restart nginx'
              (password fed automatically via stdin from servers.json)
```

### Security

- `servers.json` is **encrypted** (Fernet symmetric encryption) — passwords not readable in plaintext
- `servers.json` is in `.gitignore` — never committed
- Passwords stored locally only, **never sent to any AI/API**
- SSH keys (ed25519) — recommended auth method
- sudo password sent via stdin (not visible in process list)
- When used with Claude Code: only alias + command are passed through the AI API, passwords stay in the local encrypted file
- Automatic pre-encryption backup on first migration

### Project Structure

```
ServerManager/
├── main.py              # Entry point
├── version.py           # Version info
├── build.py             # PyInstaller build script
├── core/                # Business logic
│   ├── server_store.py  # CRUD + encrypted JSON + observer + backups
│   ├── encryption.py    # Fernet encryption module
│   ├── ssh_client.py    # Paramiko SSH/SFTP wrapper
│   ├── claude_setup.py  # Claude Code integration installer
│   ├── status_checker.py # Background monitoring
│   ├── totp.py          # TOTP/2FA module (pyotp)
│   ├── logger.py        # Rotating file logger
│   └── connection_factory.py
├── gui/                 # CustomTkinter UI
│   ├── app.py           # Main window
│   ├── sidebar.py       # Server list + search
│   ├── server_dialog.py # Add/Edit modal
│   ├── tabs/            # Terminal, Files, Info, Keys, Setup
│   └── widgets/         # StatusBadge
├── tools/               # CLI tools (installed to ~/.server-connections/)
│   ├── ssh.py           # SSH utility for Claude Code
│   └── skill-ssh.md     # /ssh skill template
├── config/              # Example configs
├── releases/            # Built executables
└── README.md            # This file (EN/RU/ZH)
```

### Deploy on a new machine

```bash
# 1. Clone
git clone https://git.sensey24.ru/aibot777/server-manager.git
cd server-manager

# 2. Install deps
pip install -r requirements.txt

# 3. Launch and setup
python main.py
# → Setup tab → Install Everything
# → Add your servers via + Add
# → Done! Both GUI and Claude Code are ready
```

---

## Русский

### Возможности

- **Управление серверами** — добавление, редактирование, удаление (SSH, Telnet, RDP, MariaDB, MSSQL, PostgreSQL)
- **SSH-терминал** — выполнение команд с авто-sudo (пароль через stdin, не виден в `ps`)
- **SFTP** — загрузка и скачивание файлов с прогресс-баром
- **SSH-ключи** — генерация ed25519, установка на сервер, копирование
- **Мониторинг** — фоновая проверка каждые 60 сек (бейджи online/offline)
- **Интеграция с Claude Code** — установка в один клик, общий конфиг со скиллом `/ssh`
- **TOTP / 2FA** — коды Google Authenticator с обратным отсчётом, копирование в один клик
- **Шифрование** — servers.json зашифрован Fernet (пароли не хранятся в открытом виде)
- **Бэкапы** — ручные и автоматические с восстановлением в один клик
- **Настраиваемый путь конфига** — смена расположения servers.json через GUI
- **Локализация** — интерфейс на английском, русском, китайском с переключателем
- **О программе** — информация о приложении, возможности, быстрый старт
- **Тёмная тема** — современный интерфейс CustomTkinter

### Установка

#### Из исходников
```bash
git clone https://git.sensey24.ru/aibot777/server-manager.git
cd server-manager
pip install -r requirements.txt
python main.py
```

#### Готовый бинарник
Скачайте из папки [`releases/`](releases/) — автономный `.exe` (Windows) или бинарник (Linux/Mac).
Python не требуется.

### Сборка

Сборка под текущую платформу:
```bash
pip install pyinstaller
python build.py
```

Результат в `releases/ServerManager-vX.Y.Z-{платформа}.exe`

### Использование

1. **Запуск** — `python main.py` или запустите скомпилированный файл
2. **Добавить сервер** — нажмите "+ Add" в боковой панели, заполните alias, IP, порт, пользователь, пароль, тип
3. **Терминал** — выберите сервер → вкладка Terminal → введите команду → Run
4. **Файлы** — выберите сервер → вкладка Files → укажите пути → Upload/Download
5. **Ключи** — вкладка Keys → Generate Key → Install on Server
6. **Настройка Claude** — вкладка Setup → "Install Everything" → Claude Code готов
7. Бейджи статуса обновляются автоматически (зелёный = online, красный = offline)

### Интеграция с Claude Code

ServerManager и Claude Code используют **один и тот же файл конфигурации**: `~/.server-connections/servers.json`

**Как это работает:**
```
ServerManager GUI  ←→  ~/.server-connections/servers.json  ←→  ssh.py (Claude Code)
      ↕                                                          ↕
  Добавил/изменил                                           скилл /ssh
  сервер в GUI                                          выполняет команды
```

- Добавил сервер в GUI → Claude Code сразу видит его через `/ssh list`
- Оба используют один `ssh.py` + `servers.json`
- Пароли **никогда** не проходят через API нейронки

**Новые SSH команды:**
- `ssh.py --info ALIAS` — безопасная информация о сервере (без учетных данных)
- `ssh.py --set-note ALIAS "desc"` — обновление заметок сервера
- `ssh.py --list` теперь показывает колонку Notes
- Нечеткий поиск по алиасу: поиск по ключевому слову (например, "tor" находит "API TOR contabo..."), приоритет границ слова
- Исправление пути SFTP: нормализация удаленного пути для Windows/Git Bash с двойным слешем //
- Флаг `--no-sudo` для команд, не требующих повышения привилегий
- Прогресс upload/download: файлы >=1MB показывают 25/50/75% с размером, временем и скоростью

**Настройка на новой машине:**
1. Установить ServerManager (клонировать репо или скачать бинарник)
2. Открыть вкладку Setup → нажать "Install Everything"
3. Готово. Claude Code теперь имеет скилл `/ssh` и доступ к серверам

Вкладка Setup устанавливает:
- `ssh.py` → `~/.server-connections/` (SSH-утилита)
- `encryption.py` → `~/.server-connections/` (модуль шифрования для CLI)
- скилл `/ssh` → `~/.claude/commands/ssh.md` (скилл Claude Code)
- SSH-ключ (ed25519) — если ещё не создан
- Проверяет дубли — безопасно запускать повторно

### Конфигурация

Общий конфиг: `~/.server-connections/servers.json` (зашифрован Fernet).

Путь к конфигу можно изменить: вкладка Setup → Configuration → "Change Path".

Настройки хранятся в `~/.server-connections/settings.json`.

**Бэкапы:**
- Автоматические бэкапы каждые 10 минут (при сохранении)
- Ручной бэкап: вкладка Setup → "Backup Now"
- Восстановление из любого бэкапа через dropdown + "Restore"
- Бэкапы хранятся в `~/.server-connections/backups/`
- Пред-шифровальный бэкап создаётся автоматически при первой миграции

### Авто-sudo

Приложение автоматически повышает привилегии:

- Если `user: "root"` — команды выполняются напрямую, sudo не нужен
- Если пользователь не root — приложение автоматически оборачивает команду в `sudo -S` и само вводит пароль из `servers.json` через stdin
- Пароль **никогда** не передаётся как аргумент командной строки (не виден в `ps aux`)
- Вы просто вводите команду (например `systemctl restart nginx`) — приложение само решает, нужен sudo или нет, и само всё делает
- В GUI-терминале checkbox "sudo" включён по умолчанию для non-root; отключите для команд, не требующих повышения

```
Вы вводите:         systemctl restart nginx
Приложение делает:  sudo -S -p '' bash -c 'systemctl restart nginx'
                    (пароль подставляется автоматически из servers.json через stdin)
```

### Безопасность

- `servers.json` **зашифрован** (Fernet симметричное шифрование) — пароли не читаемы в открытом виде
- `servers.json` в `.gitignore` — никогда не коммитится
- Пароли хранятся только локально, **никогда не передаются в AI/API**
- SSH-ключи (ed25519) — рекомендуемый метод аутентификации
- sudo-пароль передаётся через stdin (не виден в списке процессов)
- При использовании с Claude Code: через API нейронки проходят только alias + команда, пароли остаются в зашифрованном локальном файле
- Автоматический пред-шифровальный бэкап при первой миграции

### Развёртывание на новой машине

```bash
# 1. Клонировать
git clone https://git.sensey24.ru/aibot777/server-manager.git
cd server-manager

# 2. Установить зависимости
pip install -r requirements.txt

# 3. Запустить и настроить
python main.py
# → Вкладка Setup → Install Everything
# → Добавить серверы через + Add
# → Готово! GUI и Claude Code работают с одним конфигом
```

---

## 中文

### 功能特点

- **服务器管理** — 添加、编辑、删除服务器（SSH、Telnet、RDP、MariaDB、MSSQL、PostgreSQL）
- **SSH终端** — 自动sudo执行命令（密码通过stdin传递，在`ps`中不可见）
- **SFTP传输** — 带进度条的文件上传/下载
- **SSH密钥** — 生成ed25519、安装到服务器、复制到剪贴板
- **状态监控** — 每60秒后台检查（在线/离线徽标）
- **Claude Code集成** — 一键设置，与`/ssh`技能共享配置
- **TOTP / 2FA** — 兼容Google Authenticator的验证码，实时倒计时，一键复制
- **加密** — servers.json使用Fernet加密（密码不再以明文存储）
- **备份** — 手动和自动备份，一键恢复
- **可配置路径** — 通过GUI更改servers.json位置
- **多语言** — 支持英语、俄语、中文界面切换
- **关于对话框** — 应用信息、功能特点、快速入门
- **深色主题** — 现代CustomTkinter界面

### 安装

#### 从源码安装
```bash
git clone https://git.sensey24.ru/aibot777/server-manager.git
cd server-manager
pip install -r requirements.txt
python main.py
```

#### 预编译版本
从 [`releases/`](releases/) 文件夹下载 — 独立的 `.exe`（Windows）或二进制文件（Linux/Mac）。
无需安装Python。

### 编译

为当前平台编译：
```bash
pip install pyinstaller
python build.py
```

输出至 `releases/ServerManager-vX.Y.Z-{平台}.exe`

### 使用方法

1. **启动** — `python main.py` 或运行可执行文件
2. **添加服务器** — 点击侧栏 "+ Add"，填写别名、IP、端口、用户名、密码、类型
3. **终端** — 选择服务器 → Terminal标签 → 输入命令 → Run
4. **文件** — 选择服务器 → Files标签 → 设置路径 → Upload/Download
5. **密钥** — Keys标签 → Generate Key → Install on Server
6. **设置Claude** — Setup标签 → "Install Everything" → Claude Code就绪
7. 状态徽标自动更新（绿色 = 在线，红色 = 离线）

### Claude Code集成

ServerManager和Claude Code共享**同一个配置文件**：`~/.server-connections/servers.json`

**工作原理：**
```
ServerManager GUI  ←→  ~/.server-connections/servers.json  ←→  ssh.py (Claude Code)
      ↕                                                          ↕
  在GUI中添加/编辑                                           /ssh技能
  服务器                                                   执行命令
```

- 在GUI中添加服务器 → Claude Code立即通过 `/ssh list` 看到
- 两者使用相同的 `ssh.py` + `servers.json`
- 密码**绝不**通过AI API传递

**在新机器上设置：**
1. 安装ServerManager（克隆仓库或下载二进制文件）
2. 打开Setup标签 → 点击 "Install Everything"
3. 完成。Claude Code现在拥有 `/ssh` 技能并可访问您的服务器

Setup标签安装：
- `ssh.py` → `~/.server-connections/`（SSH工具）
- `encryption.py` → `~/.server-connections/`（CLI加密模块）
- `/ssh` 技能 → `~/.claude/commands/ssh.md`（Claude Code技能）
- SSH密钥（ed25519）— 如果不存在
- 检查重复 — 可安全重复运行

### 配置

共享配置位置：`~/.server-connections/servers.json`（Fernet加密）。

可通过 Setup标签 → Configuration → "Change Path" 更改配置路径。

设置存储在 `~/.server-connections/settings.json`。

**备份：**
- 每10分钟自动备份（保存时）
- 手动备份：Setup标签 → "Backup Now"
- 从任何备份恢复：下拉菜单 + "Restore"
- 备份存储在 `~/.server-connections/backups/`
- 首次迁移时自动创建加密前备份

### 自动sudo

应用自动处理权限提升：

- 如果 `user: "root"` — 命令直接执行，无需sudo
- 如果用户不是root — 应用自动将命令包装在 `sudo -S` 中，并从 `servers.json` 通过stdin自动输入密码
- 密码**绝不**作为命令行参数传递（在 `ps aux` 中不可见）
- 您只需输入命令（例如 `systemctl restart nginx`）— 应用自动判断是否需要sudo并处理
- 在GUI终端中，"sudo"复选框默认为非root用户启用；对于不需要提权的命令可以取消勾选

```
您输入:      systemctl restart nginx
应用执行:    sudo -S -p '' bash -c 'systemctl restart nginx'
            (密码从servers.json通过stdin自动输入)
```

### 安全性

- `servers.json` **已加密**（Fernet对称加密）— 密码无法以明文读取
- `servers.json` 在 `.gitignore` 中 — 永不提交
- 密码仅存储在本地，**绝不发送到任何AI/API**
- SSH密钥（ed25519）— 推荐的认证方式
- sudo密码通过stdin传递（在进程列表中不可见）
- 与Claude Code配合使用时：只有别名和命令通过AI API传递，密码保留在本地加密文件中
- 首次迁移时自动创建加密前备份

### 在新机器上部署

```bash
# 1. 克隆
git clone https://git.sensey24.ru/aibot777/server-manager.git
cd server-manager

# 2. 安装依赖
pip install -r requirements.txt

# 3. 启动并设置
python main.py
# → Setup标签 → Install Everything
# → 通过 + Add 添加服务器
# → 完成！GUI和Claude Code使用同一个配置
```

---

## License

MIT

## Author

[aibot777](https://git.sensey24.ru/aibot777)