docs: Add comprehensive project documentation from claude-projects scan
Added: - PROJECTS_INDEX.md - Master catalog of 7 active projects - GURURMM_API_ACCESS.md - Complete API documentation and credentials - clients/dataforth/dos-test-machines/README.md - DOS update system docs - clients/grabb-durando/website-migration/README.md - Migration procedures - clients/internal-infrastructure/ix-server-issues-2026-01-13.md - Server issues - projects/msp-tools/guru-connect/README.md - Remote desktop architecture - projects/msp-tools/toolkit/README.md - MSP PowerShell tools - projects/internal/acg-website-2025/README.md - Website rebuild docs - test_gururmm_api.py - GuruRMM API testing script Modified: - credentials.md - Added GuruRMM database and API credentials - GuruRMM agent integration files (WebSocket transport) Total: 38,000+ words of comprehensive project documentation Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
338
projects/gururmm-agent/INTEGRATION_CHECKLIST.md
Normal file
338
projects/gururmm-agent/INTEGRATION_CHECKLIST.md
Normal file
@@ -0,0 +1,338 @@
|
||||
# GuruRMM Agent - Claude Integration Quick Checklist
|
||||
|
||||
**Use this checklist to integrate the Claude task executor into your GuruRMM agent project.**
|
||||
|
||||
---
|
||||
|
||||
## Pre-Integration
|
||||
|
||||
- [ ] Read `IMPLEMENTATION_SUMMARY.md` for complete overview
|
||||
- [ ] Review `agent/src/claude.rs` to understand implementation
|
||||
- [ ] Verify Claude Code CLI is installed on AD2: `claude --version`
|
||||
- [ ] Verify working directory exists: `Test-Path C:\Shares\test`
|
||||
- [ ] Backup existing GuruRMM agent binary
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Copy Core Implementation
|
||||
|
||||
- [ ] Copy `agent/src/claude.rs` to your project's `agent/src/` directory
|
||||
- [ ] Verify file size: 684 lines, ~23 KB
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Update Cargo.toml
|
||||
|
||||
- [ ] Open your `agent/Cargo.toml`
|
||||
- [ ] Add under `[dependencies]` section:
|
||||
```toml
|
||||
tokio = { version = "1.35", features = ["full"] }
|
||||
serde = { version = "1.0", features = ["derive"] }
|
||||
serde_json = "1.0"
|
||||
once_cell = "1.19"
|
||||
```
|
||||
- [ ] Save file
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Modify commands.rs
|
||||
|
||||
Open your `agent/src/commands.rs` and make these changes:
|
||||
|
||||
### 3A: Add Module Declaration
|
||||
- [ ] Find other `mod` declarations at top of file
|
||||
- [ ] Add: `mod claude;`
|
||||
|
||||
### 3B: Add Imports
|
||||
- [ ] Find import section (lines with `use`)
|
||||
- [ ] Add:
|
||||
```rust
|
||||
use crate::claude::{ClaudeExecutor, ClaudeTaskCommand};
|
||||
use once_cell::sync::Lazy;
|
||||
```
|
||||
|
||||
### 3C: Create Global Executor
|
||||
- [ ] Add after imports, before functions:
|
||||
```rust
|
||||
static CLAUDE_EXECUTOR: Lazy<ClaudeExecutor> = Lazy::new(|| ClaudeExecutor::new());
|
||||
```
|
||||
|
||||
### 3D: Add execute_claude_task Function
|
||||
- [ ] Add this function to file:
|
||||
```rust
|
||||
async fn execute_claude_task(command: &serde_json::Value) -> Result<String, String> {
|
||||
let task_cmd: ClaudeTaskCommand = serde_json::from_value(command.clone())
|
||||
.map_err(|e| format!("[ERROR] Failed to parse Claude task command: {}", e))?;
|
||||
let result = CLAUDE_EXECUTOR.execute_task(task_cmd).await?;
|
||||
serde_json::to_string(&result)
|
||||
.map_err(|e| format!("[ERROR] Failed to serialize result: {}", e))
|
||||
}
|
||||
```
|
||||
|
||||
### 3E: Update Command Dispatcher
|
||||
- [ ] Find your `match command_type` block
|
||||
- [ ] Add new arm (before the `_` default case):
|
||||
```rust
|
||||
"claude_task" => execute_claude_task(&command).await,
|
||||
```
|
||||
|
||||
### 3F: Save commands.rs
|
||||
- [ ] Save file
|
||||
- [ ] Verify no syntax errors (editor should show)
|
||||
|
||||
**Need detailed examples?** See `commands_modifications.rs`
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Build & Test Locally
|
||||
|
||||
- [ ] Run: `cargo build --release`
|
||||
- Should compile without errors
|
||||
- Look for: `[OK] Finished release [optimized] target`
|
||||
|
||||
- [ ] Run: `cargo test`
|
||||
- Should pass 5 unit tests
|
||||
- Look for: `test result: ok. 5 passed`
|
||||
|
||||
- [ ] Run: `cargo clippy -- -D warnings`
|
||||
- Should show no warnings or errors
|
||||
|
||||
- [ ] Run: `cargo fmt -- --check`
|
||||
- Should show no formatting issues
|
||||
|
||||
**If any step fails:** Review error messages and check file modifications
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Pre-Deployment Verification
|
||||
|
||||
- [ ] Binary exists: `agent\target\release\gururmm-agent.exe`
|
||||
- [ ] Binary size reasonable: ~5-15 MB (depends on existing code)
|
||||
- [ ] No compilation warnings in build output
|
||||
- [ ] All tests passing
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Deploy to AD2
|
||||
|
||||
### 6A: Stop Service
|
||||
- [ ] Connect to AD2 (RDP or SSH)
|
||||
- [ ] Open PowerShell as Administrator
|
||||
- [ ] Run: `Stop-Service -Name "gururmm-agent" -Force`
|
||||
- [ ] Verify: `Get-Service -Name "gururmm-agent"` shows "Stopped"
|
||||
|
||||
### 6B: Backup Current Binary
|
||||
- [ ] Run:
|
||||
```powershell
|
||||
$timestamp = Get-Date -Format 'yyyy-MM-dd-HHmmss'
|
||||
$backupPath = "C:\Program Files\GuruRMM\backups\gururmm-agent-$timestamp.exe"
|
||||
New-Item -ItemType Directory -Path "C:\Program Files\GuruRMM\backups" -Force
|
||||
Copy-Item "C:\Program Files\GuruRMM\gururmm-agent.exe" -Destination $backupPath
|
||||
Write-Output "[OK] Backup: $backupPath"
|
||||
```
|
||||
- [ ] Verify backup exists
|
||||
|
||||
### 6C: Deploy New Binary
|
||||
- [ ] Copy `agent\target\release\gururmm-agent.exe` from dev machine to AD2
|
||||
- [ ] Run:
|
||||
```powershell
|
||||
Copy-Item "<path-to-new-binary>" -Destination "C:\Program Files\GuruRMM\gururmm-agent.exe" -Force
|
||||
Write-Output "[OK] New binary deployed"
|
||||
```
|
||||
|
||||
### 6D: Start Service
|
||||
- [ ] Run: `Start-Service -Name "gururmm-agent"`
|
||||
- [ ] Verify: `Get-Service -Name "gururmm-agent"` shows "Running"
|
||||
|
||||
### 6E: Check Logs
|
||||
- [ ] Run: `Get-Content "C:\Program Files\GuruRMM\logs\agent.log" -Tail 50`
|
||||
- [ ] Look for:
|
||||
- `[OK] GuruRMM Agent started successfully`
|
||||
- `[OK] WebSocket connection established`
|
||||
- `[OK] Claude task executor initialized` (if you added logging)
|
||||
- [ ] Verify no `[ERROR]` messages
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Integration Testing
|
||||
|
||||
**Replace `{AD2_AGENT_ID}` with actual agent ID in all commands**
|
||||
|
||||
### Test 1: Simple Task
|
||||
- [ ] Run:
|
||||
```bash
|
||||
curl -X POST "http://172.16.3.30:3001/api/agents/{AD2_AGENT_ID}/command" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"command_type":"claude_task","task":"Echo test message"}'
|
||||
```
|
||||
- [ ] Verify response has `"status": "completed"`
|
||||
- [ ] Verify no errors in response
|
||||
|
||||
### Test 2: Working Directory
|
||||
- [ ] Run:
|
||||
```bash
|
||||
curl -X POST "http://172.16.3.30:3001/api/agents/{AD2_AGENT_ID}/command" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"command_type":"claude_task","task":"List PowerShell files","working_directory":"C:\\\\Shares\\\\test"}'
|
||||
```
|
||||
- [ ] Verify response shows file list
|
||||
- [ ] Verify `duration_seconds` is reasonable
|
||||
|
||||
### Test 3: Security (Should Fail)
|
||||
- [ ] Run:
|
||||
```bash
|
||||
curl -X POST "http://172.16.3.30:3001/api/agents/{AD2_AGENT_ID}/command" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"command_type":"claude_task","task":"test; echo malicious"}'
|
||||
```
|
||||
- [ ] Verify response has error about forbidden character `;`
|
||||
- [ ] Confirm task was blocked (security working)
|
||||
|
||||
**More tests:** See `TESTING_AND_DEPLOYMENT.md` for 7 comprehensive tests
|
||||
|
||||
---
|
||||
|
||||
## Step 8: Production Verification
|
||||
|
||||
- [ ] Service is running: `Get-Service -Name "gururmm-agent"` = "Running"
|
||||
- [ ] No errors in logs since deployment
|
||||
- [ ] WebSocket connection active to GuruRMM server
|
||||
- [ ] Simple test task completes successfully
|
||||
- [ ] Security test properly rejects malicious input
|
||||
- [ ] Agent responds to non-claude commands (shell, powershell, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Rollback (If Needed)
|
||||
|
||||
**Only if deployment fails or critical issues found**
|
||||
|
||||
- [ ] Stop service: `Stop-Service -Name "gururmm-agent" -Force`
|
||||
- [ ] Find latest backup:
|
||||
```powershell
|
||||
$latest = Get-ChildItem "C:\Program Files\GuruRMM\backups\" |
|
||||
Sort-Object LastWriteTime -Descending |
|
||||
Select-Object -First 1
|
||||
```
|
||||
- [ ] Restore: `Copy-Item $latest.FullName -Destination "C:\Program Files\GuruRMM\gururmm-agent.exe" -Force`
|
||||
- [ ] Start service: `Start-Service -Name "gururmm-agent"`
|
||||
- [ ] Verify service running and functional
|
||||
|
||||
---
|
||||
|
||||
## Post-Deployment
|
||||
|
||||
### Documentation
|
||||
- [ ] Note deployment date and time
|
||||
- [ ] Record any issues encountered during integration
|
||||
- [ ] Document any configuration changes made
|
||||
- [ ] Update internal deployment log
|
||||
|
||||
### Monitoring (First 24 Hours)
|
||||
- [ ] Check logs every 4 hours: `Get-Content "C:\...\agent.log" -Tail 100`
|
||||
- [ ] Monitor task execution count (should be <10 per hour)
|
||||
- [ ] Watch for any unexpected errors
|
||||
- [ ] Verify Main Claude can successfully invoke tasks
|
||||
|
||||
### Long-Term Maintenance
|
||||
- [ ] Set up automated weekly test (see `TESTING_AND_DEPLOYMENT.md`)
|
||||
- [ ] Configure log rotation (logs can grow large)
|
||||
- [ ] Add task execution metrics to monitoring dashboard
|
||||
- [ ] Review rate limit hits monthly and adjust if needed
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Quick Reference
|
||||
|
||||
| Issue | Check | Solution |
|
||||
|-------|-------|----------|
|
||||
| Service won't start | Event logs | Check dependencies with `dumpbin /dependents` |
|
||||
| "claude not found" | PATH variable | Add Claude to system PATH |
|
||||
| Timeout on all tasks | Claude working? | Test: `claude --version` on AD2 |
|
||||
| Rate limit too strict | Task frequency | Increase `MAX_TASKS_PER_WINDOW` in code |
|
||||
| Wrong directory access | Path validation | Review `validate_working_directory()` logic |
|
||||
|
||||
**Detailed troubleshooting:** See `TESTING_AND_DEPLOYMENT.md` section 9
|
||||
|
||||
---
|
||||
|
||||
## Success Indicators
|
||||
|
||||
You've successfully integrated when:
|
||||
|
||||
- [OK] Service starts without errors
|
||||
- [OK] Logs show "Claude task executor initialized"
|
||||
- [OK] Simple test task completes in <30 seconds
|
||||
- [OK] Security test properly rejects malicious input
|
||||
- [OK] Agent handles both claude_task and existing commands
|
||||
- [OK] Main Claude can invoke tasks remotely
|
||||
- [OK] No errors in logs after 1 hour of operation
|
||||
|
||||
---
|
||||
|
||||
## Reference Files
|
||||
|
||||
- **Implementation:** `agent/src/claude.rs` (684 lines)
|
||||
- **Integration Guide:** `commands_modifications.rs` (detailed examples)
|
||||
- **Dependencies:** `Cargo_dependencies.toml` (what to add)
|
||||
- **Testing Guide:** `TESTING_AND_DEPLOYMENT.md` (497 lines)
|
||||
- **Documentation:** `README.md` (450 lines)
|
||||
- **Summary:** `IMPLEMENTATION_SUMMARY.md` (overview)
|
||||
- **This Checklist:** `INTEGRATION_CHECKLIST.md` (you are here)
|
||||
|
||||
---
|
||||
|
||||
## Help & Support
|
||||
|
||||
**Stuck on integration?**
|
||||
1. Review error messages carefully
|
||||
2. Check `commands_modifications.rs` for detailed examples
|
||||
3. Verify all 3 modifications to commands.rs were made
|
||||
4. Ensure Cargo.toml dependencies are correct
|
||||
5. Try `cargo clean && cargo build --release`
|
||||
|
||||
**Deployment issues?**
|
||||
1. Check `TESTING_AND_DEPLOYMENT.md` troubleshooting section
|
||||
2. Review agent logs for specific error messages
|
||||
3. Verify Claude Code CLI is installed and in PATH
|
||||
4. Test Claude manually: `claude --version`
|
||||
5. Rollback to previous version if critical issue
|
||||
|
||||
**Still stuck?**
|
||||
- Review all files in `projects/gururmm-agent/` directory
|
||||
- Check README.md for API reference
|
||||
- Look at unit tests in claude.rs for usage examples
|
||||
- Verify AD2 environment meets prerequisites
|
||||
|
||||
---
|
||||
|
||||
## Completion
|
||||
|
||||
**Once all checkboxes are marked:**
|
||||
|
||||
You have successfully integrated Claude Code invocation into the GuruRMM agent!
|
||||
|
||||
Main Claude can now remotely execute tasks on AD2 using:
|
||||
|
||||
```json
|
||||
{
|
||||
"command_type": "claude_task",
|
||||
"task": "Your task description",
|
||||
"working_directory": "C:\\Shares\\test",
|
||||
"timeout": 300,
|
||||
"context_files": ["optional-file.log"]
|
||||
}
|
||||
```
|
||||
|
||||
**Congratulations!** [OK] Integration Complete
|
||||
|
||||
---
|
||||
|
||||
**Project:** GuruRMM Agent Claude Integration
|
||||
**Version:** 1.0.0
|
||||
**Date:** 2026-01-21
|
||||
**Status:** [OK] Ready for Integration
|
||||
|
||||
---
|
||||
|
||||
**End of Integration Checklist**
|
||||
Reference in New Issue
Block a user