Cline rules

1# Agent-PC — Cline Rules
2 
3## Project Identity
4 
5- **Name:** Agent-PC
6- **Type:** AI-powered remote Linux control system
7- **Language:** Python 3.11 (server), Docker Compose (orchestration)
8- **Framework:** FastAPI (tool engine), Open WebUI (LLM brain)
9 
10## Architecture Rules
11 
121. Agent-PC server is a **TOOL EXECUTION ENGINE ONLY** — no LLM client, no chat endpoints
132. Open WebUI handles ALL LLM logic (chat, streaming, multi-model, tool calling)
143. Communication: Open WebUI → HTTP POST → Agent-PC `/tool` endpoint
154. Authentication between services: `AUTH_SECRET` shared secret via query param
165. SSH from container to host for command execution (with local fallback)
17 
18## Code Conventions
19 
20- **All code and comments:** English
21- **PEP 8** with 4-space indentation
22- Type hints where they add clarity
23- Tool functions return `{"ok": bool, ...}` dict
24- Errors return `{"ok": false, "error": "message"}`
25 
26## File Locations
27 
28- `server/main.py` — FastAPI app (3 endpoints: health, tools, tool)
29- `server/tools.py` — Tool definitions + implementations
30- `server/config.py` — Environment variable configuration
31- `docker-compose.yml` — Service orchestration
32- `docker/agent-pc/Dockerfile` — Container image
33- `open-webui/tools/` — Open WebUI function definitions
34- `AI/` — Project documentation for AI agents
35- `ios/` — Legacy SwiftUI app (not actively maintained)
36 
37## Key Constraints
38 
39- **NO** `openai` library in server — removed in v2.0
40- **NO** WebSocket or chat endpoints in Agent-PC server
41- **NO** hardcoded API keys — use env vars or Open WebUI admin panel
42- **NO** direct `subprocess` from container to host without SSH as option
43- Docker volumes MUST use named volumes (not bind mounts for data)
44 
45## When Adding Features
46 
471. New tools: add to `TOOL_DEFINITIONS` + `TOOL_MAP` in `tools.py`
482. Update `open-webui/tools/agent-pc-tools.json`
493. Rebuild: `docker compose build agent-pc && docker compose up -d`
504. Re-import tools in Open WebUI admin panel
51 
52## When Modifying Docker
53 
541. Update `docker-compose.yml` for service changes
552. Update `docker/agent-pc/Dockerfile` for dependencies
563. Update `.env.docker` for new variables
574. Test: `docker compose up -d --build`
585. Verify health: `curl http://localhost:8765/health`
59 
60## Testing
61 
62```bash
63# Local testing (no Docker)
64cd server && python -m venv venv && source venv/bin/activate
65pip install -r requirements.txt && python main.py
66 
67# Test endpoints
68curl http://localhost:8765/health
69curl "http://localhost:8765/tools?secret=agent-pc-local-secret-change-me"
70curl -X POST "http://localhost:8765/tool?secret=agent-pc-local-secret-change-me" \
71  -H "Content-Type: application/json" \
72  -d '{"name":"execute_command","args":{"command":"echo test"}}'
73```
74