Imported from frd21313123123/panel (AGENTS.md). Install upstream with npx skills add frd21313123123/panel. Copyright stays with the author.

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Running the project

Windows (dev):

run.bat        # creates .venv, installs deps, starts on http://localhost:8080

Linux/Ubuntu:

./run.sh                   # dev mode
sudo ./install-ubuntu.sh   # production: systemd + nginx

Manual start:

cd backend
python main.py             # listens on 0.0.0.0:8080

Default credentials on first boot: admin / admin (created automatically if no users exist).

Docker must be running for power actions and console to work. Without Docker, the UI loads but container operations return 503.

Architecture

Request flow

Browser → FastAPI (backend/main.py) → SQLite via SQLAlchemy → Docker SDK

There is no build step. Frontend is pure HTML/JS/CSS served by Jinja2 (frontend/templates/) and static files (frontend/static/). No bundler, no npm.

Backend modules

Data layout on disk

data/
  servers/srv_{id}/     ← mounted as /home/container inside each Docker container
  backups/srv_{id}/     ← tar.gz backup archives
panel.db                ← SQLite database

WebSocket endpoints

• /ws/servers/{sid}/console — stats polling + docker exec (non-interactive, JSON protocol)
• /ws/servers/{sid}/term — interactive PTY via docker exec + xterm.js (binary/JSON mixed protocol)

Auth on WS: token from ?token= query param or panel_token cookie.

Key conventions

• Server.ports and Server.env_vars are stored as JSON strings in SQLite, parsed by _parse_json() in main.py.
• _server_for(db, sid, user, perm=None) enforces both ownership and subuser permission checks. Always use this — never query Server directly in routes.
• Subuser permissions are comma-separated strings: console, files, backups, schedules.
• Egg = runtime template (Docker image + default command). Seeded on first boot in database.py:init_db().

Frontend

Each page is a self-contained HTML file with inline <script>. Shared utilities are in frontend/static/js/app.js (api, toast, fmtBytes, loadSidebar, logout). xterm.js is loaded from CDN in server.html.