Cursor rule

1---
2description: Agent-PC project rules and conventions
3globs: **/*.py,**/*.yml,**/*.yaml,**/*.md,**/*.sh,**/*.json,**/Dockerfile
4version: 1.0.0
5alwaysApply: true
6---
7 
8# Agent-PC — Cursor Rules
9 
10## Project Identity
11 
12Agent-PC is an AI-powered remote Linux control system. Users control their Linux machine from any device (iPhone PWA, browser) via natural language. The system uses Open WebUI as the multi-model LLM brain and a Python FastAPI server as the tool execution engine, all orchestrated with Docker Compose behind a Tailscale VPN.
13 
14## Architecture (CRITICAL)
15 
16```
17User Device (PWA) → Tailscale VPN → Open WebUI (port 3000) → Agent-PC (port 8765) → SSH → Host Machine
18```
19 
201. **Agent-PC server is a TOOL EXECUTION ENGINE ONLY** — no LLM, no chat, no WebSocket
212. **Open WebUI handles ALL LLM logic** — multi-model, streaming, tool calling, admin panel
223. Communication between services is HTTP (REST)
234. Auth between Open WebUI and Agent-PC uses `AUTH_SECRET` query parameter
24 
25## Code Conventions
26 
27### Python
28- **Language:** English for all code, comments, and docstrings
29- **Style:** PEP 8, 4 spaces, snake_case, PascalCase for classes
30- **Type hints:** Use where they improve clarity
31- **Tool return format:** `{"ok": bool, "error"?: str, ...}`
32 
33### Files You'll Edit Most
34- `server/main.py` — FastAPI app (3 endpoints only: GET /health, GET /tools, POST /tool)
35- `server/tools.py` — Tool definitions (TOOL_DEFINITIONS + TOOL_MAP + implementations)
36- `server/config.py` — Environment configuration (SSH_HOST, AUTH_SECRET, etc.)
37- `docker-compose.yml` — Service orchestration
38- `docker/agent-pc/Dockerfile` — Container image definition
39 
40### What NOT to Do
41- ❌ Do NOT add chat/streaming/WebSocket endpoints to Agent-PC server
42- ❌ Do NOT add LLM client libraries (openai, anthropic, etc.) to server
43- ❌ Do NOT hardcode API keys — use env vars or Open WebUI admin panel
44- ❌ Do NOT bypass the tool format — always return `{"ok": bool, ...}`
45- ❌ Do NOT modify `ios/` Swift code (legacy, not maintained)
46- ❌ Do NOT use `server/agent.py` (legacy LLM client, no longer imported)
47 
48## Adding a New Tool
49 
501. Add definition to `TOOL_DEFINITIONS` in `server/tools.py`
512. Implement `tool_<name>()` function
523. Register in `TOOL_MAP` dict
534. Add to `open-webui/tools/agent-pc-tools.json`
545. Rebuild Docker: `docker compose build agent-pc && docker compose up -d`
55 
56## Environment Variables
57 
58Key env vars (set in `.env` for Docker Compose):
59- `AUTH_SECRET` — Shared secret between Open WebUI and Agent-PC
60- `SSH_HOST` — Host for SSH (default: `host.docker.internal`)
61- `SSH_USER` — SSH username
62- `WORKSPACE_ROOT` — Root directory agent can access
63- `OPENWEBUI_PORT` — External port for Open WebUI (default: 3000)
64- `AGENTPC_PORT` — External port for Agent-PC (default: 8765)
65 
66## Commands
67 
68```bash
69# Dev (no Docker)
70cd server && pip install -r requirements.txt && python main.py
71 
72# Docker
73docker compose up -d                    # Base services
74docker compose --profile ollama up -d   # With local LLMs
75docker compose logs -f agent-pc         # Agent-PC logs
76docker compose build agent-pc && docker compose up -d  # Rebuild
77 
78# Test
79curl http://localhost:8765/health
80curl &quot;http://localhost:8765/tools?secret=agent-pc-local-secret-change-me&quot;
81```
82