64a8462784
All checks were successful
Build and Push Container / build (push) Successful in 27s
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
88 lines
3.5 KiB
Markdown
88 lines
3.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## CI/CD Notes
|
|
|
|
- CI builds take **less than 1 minute** - wait for completion then pull/recreate container
|
|
- After pushing, wait ~1 min then run: `ssh whale "docker pull gitea.voyager.sh/nick/kuma-strapper:latest && cd /opt/docker/kuma-strapper && docker compose up -d --force-recreate"`
|
|
|
|
## Build & Run Commands
|
|
|
|
### Docker (Production)
|
|
```bash
|
|
docker compose up --build # Build and run
|
|
docker compose up -d # Run detached
|
|
```
|
|
|
|
### Local Development
|
|
```bash
|
|
# Backend (Flask + SocketIO on port 5000)
|
|
cd backend
|
|
pip install -r requirements.txt
|
|
python app.py
|
|
|
|
# Frontend (Vite dev server on port 5173, proxies to backend)
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
|
|
# Frontend production build
|
|
npm run build
|
|
```
|
|
|
|
### Environment Setup
|
|
Copy `.env.example` to `.env` and set:
|
|
- `SSH_PRIVATE_KEY` - Base64-encoded SSH key (`base64 -w 0 ~/.ssh/id_rsa`)
|
|
- `UPTIME_KUMA_URL` - Uptime Kuma instance URL
|
|
- `UPTIME_KUMA_API_KEY` - Uptime Kuma API token
|
|
- `CLAUDE_API_KEY` - Anthropic API key
|
|
- `DEV_MODE` - When true, Claude-suggested SSH commands require user approval
|
|
|
|
## Architecture
|
|
|
|
**Stack**: Python Flask backend + React/Vite frontend + WebSocket (Socket.io) for real-time updates
|
|
|
|
### Data Flow
|
|
1. User submits hostname → `POST /api/scan` starts background thread
|
|
2. SSH Manager connects and runs safe discovery commands (docker ps, systemctl, df, etc.)
|
|
3. WebSocket emits `scan_progress` events as commands complete
|
|
4. On completion, Claude Agent analyzes results and suggests monitors
|
|
5. User selects monitors → created in Uptime Kuma via REST API
|
|
|
|
### Backend Services (`backend/services/`)
|
|
- **ssh_manager.py** - Paramiko-based SSH connection pool, supports RSA/Ed25519/ECDSA keys
|
|
- **discovery.py** - Runs safe commands on hosts, defines `SAFE_DISCOVERY_COMMANDS` whitelist
|
|
- **claude_agent.py** - Claude API integration with system prompt for monitor suggestions
|
|
- **kuma_client.py** - Uptime Kuma REST API wrapper
|
|
- **monitors.py** - Creates monitors from discovery data or Claude suggestions
|
|
|
|
### Approval System (`backend/utils/approval.py`)
|
|
When `DEV_MODE=true`, non-whitelisted SSH commands from Claude are queued for user approval. Safe commands (read-only patterns like `cat`, `docker ps`, `systemctl status`) execute immediately.
|
|
|
|
### Frontend Components (`frontend/src/components/`)
|
|
- **Dashboard.jsx** - Scan form and results display
|
|
- **DiscoveryResults.jsx** - Claude analysis, monitor selection checkboxes
|
|
- **ApprovalModal.jsx** - Dev mode command approval UI
|
|
- **DevModeToggle.jsx** - Toggle switch for dev mode
|
|
|
|
### API Routes (defined in `backend/app.py`)
|
|
- `POST /api/scan` - Initiate host scan
|
|
- `GET /api/scan/<id>` - Get scan results
|
|
- `POST /api/scan/<id>/command` - Run additional SSH command
|
|
- `GET/POST /api/approvals/*` - Approval queue management
|
|
- `POST /api/monitors/create-defaults` - Create ping/SSH monitors
|
|
- `POST /api/monitors/create-suggested` - Create Claude-suggested monitors
|
|
|
|
### WebSocket Events
|
|
- `scan_progress`, `scan_complete` - Scan lifecycle
|
|
- `analysis_started`, `analysis_complete`, `analysis_update` - Claude analysis
|
|
- `approval_request`, `approval_resolved` - Dev mode approvals
|
|
|
|
## Key Implementation Details
|
|
|
|
- Flask serves built frontend from `frontend/dist/` in production (see `serve_frontend` route)
|
|
- Vite proxies `/api` and `/socket.io` to Flask in development
|
|
- SSH key is decoded from base64 at runtime, never written to disk
|
|
- Claude uses `claude-sonnet-4-20250514` model with structured JSON responses
|