122 lines
2.8 KiB
Markdown
122 lines
2.8 KiB
Markdown
# CLAUDE.md — LetsBe SysAdmin Agent
|
|
|
|
## Purpose
|
|
|
|
You are the engineering assistant for the LetsBe SysAdmin Agent.
|
|
This is an autonomous automation worker installed on each tenant server.
|
|
|
|
It performs tasks received from the LetsBe Orchestrator, including:
|
|
|
|
- Heartbeats
|
|
- Task polling
|
|
- Shell command execution
|
|
- Editing environment files
|
|
- Managing Docker Compose
|
|
- Running Playwright flows (stubbed for MVP)
|
|
- Sending back task results + events
|
|
|
|
The agent communicates exclusively with the Orchestrator's REST API.
|
|
|
|
---
|
|
|
|
## Tech Stack
|
|
|
|
- Python 3.11
|
|
- Async I/O (asyncio + httpx)
|
|
- Playwright (installed via separate container or OS-level)
|
|
- Shell command execution via subprocess (safe wrappers)
|
|
- Docker Compose interaction (subprocess)
|
|
- File edits via python
|
|
|
|
This repo is separate from the orchestrator.
|
|
|
|
---
|
|
|
|
## Target File Structure
|
|
|
|
letsbe-sysadmin-agent/
|
|
app/
|
|
__init__.py
|
|
main.py
|
|
config.py # Settings: ORCHESTRATOR_URL, AGENT_TOKEN, etc.
|
|
agent.py # Agent lifecycle: register, heartbeat
|
|
task_manager.py # Task polling + dispatch logic
|
|
executors/
|
|
__init__.py
|
|
shell_executor.py # Run allowed OS commands
|
|
file_executor.py # Modify files/env vars
|
|
docker_executor.py # Interact with docker compose
|
|
playwright_executor.py # Stub for now
|
|
clients/
|
|
orchestrator_client.py # All API calls
|
|
utils/
|
|
logger.py
|
|
validation.py
|
|
tasks/
|
|
base.py
|
|
echo.py # MVP sample task: ECHO payload
|
|
|
|
docker-compose.yml (optional for dev)
|
|
requirements.txt
|
|
|
|
---
|
|
|
|
## MVP Task Types
|
|
|
|
1. ECHO task
|
|
- Payload: {"message": "..."}
|
|
- Agent just returns payload as result.
|
|
|
|
2. SHELL task
|
|
- Payload: {"cmd": "ls -la"}
|
|
- Agent runs safe shell command.
|
|
|
|
3. FILE_WRITE task
|
|
- Payload: {"path": "...", "content": "..."}
|
|
- Agent writes file.
|
|
|
|
4. DOCKER_RELOAD task
|
|
- Payload: {"compose_path": "..."}
|
|
- Agent runs `docker compose up -d`.
|
|
|
|
More complex tasks (Poste, DKIM, Keycloak, etc.) come later.
|
|
|
|
---
|
|
|
|
## API Flow
|
|
|
|
- Register:
|
|
POST /agents/register
|
|
- Heartbeat:
|
|
POST /agents/{id}/heartbeat
|
|
- Fetch next task:
|
|
GET /tasks/next?agent_id=...
|
|
- Submit result:
|
|
PATCH /tasks/{id}
|
|
|
|
All API calls use httpx async.
|
|
|
|
---
|
|
|
|
## Coding Conventions
|
|
|
|
- Everything async
|
|
- Use small, testable executors
|
|
- Never run shell commands directly in business logic
|
|
- All exceptions must be caught and submitted as FAILED tasks
|
|
- Use structured logging
|
|
- The agent must never crash — only tasks can crash
|
|
|
|
---
|
|
|
|
## Your First Instructions for Claude Code
|
|
|
|
When asked, generate a complete scaffold for the agent as described above:
|
|
- app/main.py with startup loop
|
|
- Basic heartbeat cycle
|
|
- orchestrator client
|
|
- simple task manager
|
|
- simple executors
|
|
- ECHO and SHELL tasks implemented
|
|
- requirements.txt + Dockerfile
|