letsbe-sysadmin/CLAUDE.md

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