ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
docs: sync docs with dev, add CHANGELOG/SECURITY, document Windows agent
Juan Deniseab1a35794e1
diff --git a/CHANGELOG.md b/CHANGELOG.mdnew file mode 100644index 00000000..9a2a8d4b--- /dev/null+++ b/CHANGELOG.md@@ -0,0 +1,76 @@+# Changelog++All notable changes to ServerKit are documented in this file.++The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),+and the project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).++> **Scope:** This changelog tracks the **control panel** (Flask backend + React+> frontend). The cross-platform **agent** ships on its own cadence and is tagged+> separately (`agent-vX.Y.Z`) — see [`agent/README.md`](agent/README.md) for its+> install and release notes.+>+> Commit-level history lives in `git log`; this file curates the user-facing+> changes by theme.++## [Unreleased]++The `dev` branch is well ahead of the last `main` release. The headline work+awaiting a stable release:++### Added++- **Multi-platform agent & fleet management** — native Go agent for Linux,+ Windows, and macOS with HMAC-SHA256 auth and WebSocket + HTTP-poll transports,+ plus a fleet dashboard (inventory, connection status, approval queue,+ discovery, rollouts, and command queue).+- **Native Windows agent** — Windows service, desktop setup wizard (WebView2),+ system tray, and MSI installer; also `.deb`/`.rpm` packages and ARM64 builds.+- **Agent pairing** — short-code and passphrase pairing flows with keypair+ enrollment, the `sk1` connection-string format, and automatic fallback to+ polling when WebSocket connections flap.+- **Remote operations over the agent** — files, packages, services, cron, sudo,+ Docker, Cloudflare tunnels, and streamed job progress on connected servers.+- **Plugin / extension system** — plugin SDK, contribution points, capabilities+ and permissions, marketplace UI, built-in extensions, and a GUI plugin+ (`serverkit-gui`).+- **Status pages** — public status pages with HTTP/TCP/DNS/Ping checks,+ component monitoring, and incident management.+- **Cloud provisioning** — provision servers on DigitalOcean, Hetzner, Vultr,+ and Linode with cost tracking.+- **Git-based services** — GitHub source connections, repository picker,+ manifest detection, and "New Service from repo" (Git extension canonical at+ `/git`).+- **RHEL-family support** — the installer now covers Rocky, AlmaLinux, RHEL, and+ CentOS in addition to Ubuntu/Debian/Fedora.++### Changed++- Overhauled the Docker UI (bulk container stats, compose listing) and migrated+ the frontend design system to SCSS `.ui-*` components.+- Unified the local dev launcher (`dev.sh` / `dev.ps1`).+- Agent capabilities and system info are cached to the database, surfaced in the+ System Status card, and re-sent on a periodic cadence.++### Fixed++- Resolved systemic silent failures: empty logs, dead WebSocket connections, and+ locked-out agents; stale "online" status is now auto-corrected.+- Hardened the installer: Docker install on Fedora/RHEL, SELinux + nginx+ reverse-proxy configuration, and low-RAM swap setup.+- Stopped dropping capability/sysinfo payloads on transient `/poll` failures.++### Testing & Infra++- Added a Vagrant + Hyper-V runner (Debian/Fedora/Rocky) and a Multipass-based+ end-to-end harness that runs on Windows.++---++## Released++Current development version: **1.6.7**. Recent point releases (`1.4.x` → `1.6.7`)+delivered the agent fleet, plugin system, and installer hardening listed above.+Until tagged panel releases land, consult `git log` and the+[GitHub releases page](https://github.com/jhd3197/ServerKit/releases) for the+detailed history.diff --git a/CLAUDE.md b/CLAUDE.mdindex 88447dd7..1e4774e1 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -48,11 +48,16 @@ Flask app factory in `app/__init__.py` using `create_app()`. Three-layer architeOther backend components:- `app/sockets.py` — Socket.IO event handlers for real-time metrics, logs, terminal-- `app/agent_gateway.py` — Multi-server agent communication+- `app/agent_gateway.py` — Defines the Socket.IO `/agent` namespace for the multi-server agent fleet, backed by the in-memory singleton `app/services/agent_registry.py` (HMAC auth, heartbeat/metrics, command routing); `app/api/agent_poll.py` is the HTTP long-poll fallback. The native agent itself is a Go program under `agent/`.- `app/middleware/security.py` — Security headers middleware- `config.py` — Environment-based config (development/production/testing)- `run.py` — Entry point+> **Agent gateway is single-worker.** All connected-agent state lives in-memory+> in one process, so the panel must run a **single** gevent-websocket worker;+> multi-worker deployments silently misroute agent commands. See+> [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [SECURITY.md](SECURITY.md).+### Frontend (`frontend/src/`)React 18 SPA with client-side routing:diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex ae23d22a..fe508663 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -255,10 +255,14 @@ pytest --cov=app # With coverage```bashcd frontend-npm test-npm run test:coverage # With coverage+npm run lint # ESLint+npm run build # Production build (compile check)```+> There is no frontend unit-test suite yet — linting and a clean production+> build are the current gate. See `dev.ps1 validate` / `dev.sh validate` below+> for the full pre-submit check.+### Validate Before SubmittingRun the dev validation suite to check for common issues:diff --git a/README.md b/README.mdindex b2c2ed4c..8bd97693 100644--- a/README.md+++ b/README.md@@ -98,9 +98,13 @@ English | [Español](docs/README.es.md) | [中文版](docs/README.zh-CN.md) | [P### 🖥️ Multi-Server Management-**Agent-Based Architecture** — Go agent with HMAC-SHA256 authentication and real-time WebSocket gateway+**Agent-Based Architecture** — Cross-platform Go agent (Linux, Windows, macOS) with HMAC-SHA256 authentication and a real-time WebSocket gateway (with HTTP-poll fallback). Native Windows service + MSI installer, plus `.deb`/`.rpm` and ARM64 builds. See [agent/README.md](agent/README.md).-**Fleet Management** — Agent inventory, connection status, approval queue, rollouts, discovery, and command queue+**Fleet Management** — Agent inventory, connection status, approval queue, rollouts, LAN auto-discovery (UDP), and command queue++**Windows Desktop Agent** — Native Windows service plus an optional desktop app: WebView2 console, system-tray controls, and a guided pairing wizard for one-click enrollment++**Agent Enrollment** — Two ways to adopt a server: a secure short-code pairing flow (type a rotating code + passphrase into the panel and verify the key fingerprint) or a pre-shared registration token; host credentials are stored AES-GCM-encrypted. See [docs/pairing.md](docs/pairing.md)**Fleet Monitor** — Cross-server heatmaps, metric comparison charts, alert thresholds, anomaly detection, and capacity forecasting@@ -166,7 +170,7 @@ English | [Español](docs/README.es.md) | [中文版](docs/README.zh-CN.md) | [Pcurl -fsSL https://serverkit.ai/install.sh | bash```-> Works on Ubuntu 22.04+ and Debian 12+. Sets up everything automatically.+> Works on Ubuntu 22.04+, Debian 12+, Fedora, and RHEL/Rocky/AlmaLinux 9+. Sets up everything automatically.### Option 2: Docker@@ -310,7 +314,10 @@ Full details: [ROADMAP.md](ROADMAP.md)| [Architecture](docs/ARCHITECTURE.md) | System design, request flow, diagrams || [Installation Guide](docs/INSTALLATION.md) | Complete setup instructions || [Deployment Guide](docs/DEPLOYMENT.md) | CLI commands and production deployment |+| [Agent](agent/README.md) | Install & run the multi-server agent (Linux/Windows/macOS) |+| [Agent Pairing](docs/pairing.md) | Secure short-code agent enrollment || [API Reference](docs/API.md) | REST API endpoints |+| [Changelog](CHANGELOG.md) | Release history and notable changes || [Roadmap](ROADMAP.md) | Development roadmap and planned features || [Contributing](CONTRIBUTING.md) | How to contribute |diff --git a/SECURITY.md b/SECURITY.mdnew file mode 100644index 00000000..624b613d--- /dev/null+++ b/SECURITY.md@@ -0,0 +1,60 @@+# Security Policy++## Supported Versions++ServerKit is under active development. Security fixes are applied to the latest+release line and the `main` branch.++| Version | Supported |+|---------|-----------|+| 1.6.x | ✅ |+| < 1.6 | ❌ (please upgrade) |++The **agent** is versioned independently (`agent-vX.Y.Z`); always run a recent+agent build, as several Windows service and credential-handling fixes landed in+the 1.6.x line.++## Reporting a Vulnerability++Please report security issues **privately** — do not open a public issue for+anything exploitable.++- Preferred: [open a GitHub Security Advisory](https://github.com/jhd3197/ServerKit/security/advisories/new)+- We aim to acknowledge reports within a few days and to provide a remediation+ timeline after triage.++Please include affected version(s), reproduction steps, and impact. Coordinated+disclosure is appreciated — give us a reasonable window to ship a fix before any+public write-up.++## Agent Trust Model++The multi-server agent is powerful by design — operators should understand its+trust boundaries:++- **`agent.key` is a host-equivalent secret.** Agent API credentials are stored+ AES-256-GCM encrypted under a key derived from host-stable identifiers+ (hostname + machine ID on Linux, hostname + computer name on Windows). Anyone+ who can read this file on the host — or recreate the host-derived key — can+ recover the credentials. Protect it like a root/SYSTEM secret.+- **Remote command execution is gated.** Arbitrary command execution+ (`system:exec`) and interactive PTY sessions are controlled by the agent's+ `Features.Exec` flag, which is **off by default**. Enable it only on servers+ where you intend the panel to run shell commands.+- **Transport & connection controls.** Agents authenticate to the panel with+ per-connection HMAC-SHA256 (with nonce/replay protection and a timestamp-skew+ check), and the panel enforces a per-server IP allowlist. Use `wss://`+ (TLS-terminated) in production.+- **`SERVERKIT_INSECURE_TLS=true` disables certificate verification** for all+ agent connections. It is intended for local development/testing only — never+ set it in production.++For a detailed internal audit of the panel, see+[SECURITY_AUDIT.md](SECURITY_AUDIT.md).++## Deployment Note++The agent gateway keeps all connected-agent state in-memory in a single process.+Run the panel with a **single** gevent-websocket worker; multi-worker+deployments can misroute agent commands. See+[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).diff --git a/agent/CHANGELOG.md b/agent/CHANGELOG.mdnew file mode 100644index 00000000..a8f44e01--- /dev/null+++ b/agent/CHANGELOG.md@@ -0,0 +1,55 @@+# ServerKit Agent Changelog++All notable changes to the **ServerKit agent** are documented here.++The agent is versioned and released independently from the control panel. Release+builds are produced by the `Agent Release` workflow and tagged `agent-vX.Y.Z`;+each tag publishes Linux (amd64/arm64) binaries + `.deb`/`.rpm`, Windows+(x64/arm64) `.msi` installers, and a multi-arch Docker image.++The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).++## [Unreleased]++Substantial work has landed since the last tagged release (`agent-v1.0.4`) and+is awaiting the next release cut. Highlights:++### Added++- **Native Windows experience** — Windows service host, native first-run setup+ wizard, system tray, dark-mode aware UI, and an MSI installer that opens the+ pairing wizard right after install (no browser or external WebView2 runtime+ required). ARM64 Windows builds included.+- **Desktop console UI** — embedded React UI (`agent/ui`) served over local IPC+ for status, logs, activity, and actions.+- **Pairing flows** — short-code and passphrase pairing with keypair enrollment+ and the `sk1` connection-string format.+- **Dual transport** — Socket.IO/WebSocket primary transport with automatic,+ permanent fallback to HTTP polling when the WebSocket connection flaps.+- **Remote operations** — handlers for files, packages, services, cron, sudo,+ Docker (incl. extra ops), Cloudflare tunnels, runtime management, and streamed+ job progress.+- **Capability probing** — host capability detection reported to the panel and+ re-sent on a periodic cadence; system info pushed and persisted.+- **Self-update** — built-in updater with periodic version checks.++### Fixed++- Stopped dropping capability/system-info payloads on transient `/poll` failures.+- Resolved silent failures around empty logs, dead WebSocket connections, and+ locked-out agents.+- Windows builds use the `-H=windowsgui` subsystem so Start-menu launches no+ longer flash a stray console window; CLI subcommands still re-hook stdio when+ run from a real terminal.+- Pinned the Go toolchain to 1.23 for CI compatibility; fixed Docker and MSI+ (WiX v5) builds in the release workflow.++## [1.0.4] - 2026-03-28+## [1.0.3] - 2026-03-24+## [1.0.2] - 2026-03-03+## [1.0.1] - 2026-01-24+## [1.0.0] - 2026-01-24++Initial tagged agent releases: cross-platform Go agent with HMAC-SHA256+authentication, Docker integration, system metrics, and auto-reconnect, plus the+multi-platform release pipeline (binaries, `.deb`/`.rpm`, MSI, Docker).diff --git a/agent/README.md b/agent/README.mdindex 86e2d95f..f90265da 100644--- a/agent/README.md+++ b/agent/README.md@@ -10,7 +10,7 @@ A lightweight, cross-platform agent for remote server management. Connects to a- **System Metrics**: Real-time CPU, memory, disk, and network monitoring- **Secure Communication**: TLS encryption with HMAC-SHA256 authentication- **Auto-Reconnect**: Automatic reconnection with exponential backoff-- **Self-Update**: Built-in update mechanism (coming soon)+- **Self-Update**: Built-in auto-update with periodic version checks## Quick Start@@ -29,6 +29,27 @@ irm https://your-serverkit.com/install.ps1 | iexInstall-ServerKitAgent -Token "sk_reg_your_token" -Server "https://your-serverkit.com"```+> **Most Windows users should install the MSI instead** (see *Package+> Installation* below). The MSI registers the `ServerKitAgent` Windows service+> and opens a native pairing wizard right after install — no token handling and+> no browser required.++### Pairing (recommended)++Instead of baking a long registration token into an install command, you can+adopt an agent with a short, human-friendly code:++```bash+serverkit-agent pair --server "https://your-serverkit.com"+```++The agent generates an Ed25519 keypair, prints a short pairing code (and+passphrase), and waits. In the panel's **Add Server** screen, enter the code ++passphrase and verify the displayed key fingerprint to approve the device. On+Windows the MSI launches this wizard automatically. See+[../docs/pairing.md](../docs/pairing.md) for the full flow and security+properties.+### Docker (Recommended for containerized environments)```bash@@ -105,15 +126,15 @@ Start-Service ServerKitAgent### Prerequisites-- Go 1.21 or later+- Go 1.23 or later (matches CI)- Make (optional, for using Makefile)### Build```bash-# Clone the repository-git clone https://github.com/serverkit/agent.git-cd agent+# Clone the repository (the agent lives in the ServerKit monorepo)+git clone https://github.com/jhd3197/ServerKit.git+cd ServerKit/agent# Download dependenciesgo mod download@@ -143,12 +164,20 @@ serverkit-agent [command]Available Commands:start Start the agent service- register Register with a ServerKit instance+ register Register with a ServerKit instance (pre-shared token)+ pair Pair with a panel using a short code (recommended)+ setup Run the guided setup wizardstatus Show agent statusconfig Configuration management+ update Check for and apply self-updates+ tray Run the system-tray app (desktop)+ console Open the desktop console (WebView2)version Show version informationhelp Help about any command+Run with no command to launch the desktop app: the pairing wizard if the agent+is not yet configured, otherwise the system tray.+Flags:-c, --config string config file path-d, --debug enable debug logging@@ -230,9 +259,21 @@ The agent uses HMAC-SHA256 signatures for authentication:### Credentials Storage-Credentials are encrypted at rest using AES-256-GCM with a machine-specific key derived from:+Credentials are encrypted at rest using AES-256-GCM with a **host-stable** key+derived from:- Hostname-- Machine ID (Linux) or computer/user name (Windows)+- Machine ID (Linux) / Computer name (Windows)++The key is deliberately **independent of the logged-in user**. On Windows this+lets the `LocalSystem` service decrypt credentials that were written during+user-context pairing. (Mixing in the Windows username broke exactly this and was+removed in 1.6.14.) Because the key is host-bound, a copied credential file+cannot be reused on another machine.++> **Treat `agent.key` as a host-equivalent secret.** Anyone who can read this+> file on the host (or recreate the host-derived key) can recover the agent's+> API credentials. Combined with remote command execution (see below), a leaked+> key file is equivalent to full control of that host.### Network Security@@ -255,9 +296,13 @@ journalctl -u serverkit-agent -fsystemctl restart serverkit-agent```-## Windows Service+## Windows Service & Desktop App-On Windows, the agent runs as a Windows Service:+On Windows the agent has two cooperating parts:++**1. The background service** — a true Windows Service (`ServerKitAgent`)+registered through the Service Control Manager, running as `LocalSystem` and set+to start automatically. This is what stays connected to the panel.```powershell# Check status@@ -270,6 +315,28 @@ Get-Content "C:\ProgramData\ServerKit\Agent\logs\agent.log" -Tail 50Restart-Service ServerKitAgent```+**2. The desktop app** — an optional per-user UI auto-started via the `HKCU\...\Run`+key:++- **Pairing/setup wizard** — runs after install (or on first launch) to adopt the+ agent into a panel.+- **System tray** — shows connection status and quick actions.+- **Desktop console** — a WebView2-hosted view of status, logs, activity, and+ actions (no external browser required).++> **Windows limitations to be aware of:** system metrics report a single volume+> (`C:\`), and the remote file browser currently lists the agent's working drive+> rather than enumerating all drives. Multi-drive support is tracked for a future+> release.++### Windows environment variables++| Variable | Purpose |+|----------|---------|+| `SERVERKIT_INSECURE_TLS` | Disable TLS certificate verification (**dev/testing only**) |+| `SERVERKIT_WS_COMPRESSION` | Enable WebSocket permessage-deflate (off by default; some tunnels corrupt compressed frames) |+| `SERVERKIT_AGENT_LEGACY_WIZARD` | Use the legacy native setup wizard instead of the WebView2 one |+## Docker Deployment### Building the Image@@ -362,17 +429,31 @@ docker compose down```agent/-├── cmd/agent/ # Main entry point+├── cmd/agent/ # Main entry point (+ Windows service/console glue)├── internal/-│ ├── agent/ # Core agent logic+│ ├── agent/ # Core agent logic & command handlers+│ ├── agentui/ # Desktop console UI (WebView2)│ ├── auth/ # HMAC authentication+│ ├── capabilities/ # Host capability probing+│ ├── cloudflared/ # Cloudflare tunnel management│ ├── config/ # Configuration management+│ ├── cron/ # Remote cron management│ ├── docker/ # Docker client wrapper+│ ├── ipc/ # Local IPC (desktop UI <-> agent)+│ ├── jobs/ # Background job runner│ ├── logger/ # Structured logging│ ├── metrics/ # System metrics collection+│ ├── pairing/ # Pairing client & keypair enrollment+│ ├── setupui/ # First-run setup wizard (Windows)+│ ├── terminal/ # Remote terminal sessions+│ ├── transport/ # WebSocket + HTTP-poll transports+│ ├── tray/ # System tray integration+│ ├── updater/ # Self-update mechanism│ └── ws/ # WebSocket client-├── pkg/protocol/ # Message protocol definitions+├── pkg/protocol/ # Message protocol (shared contract with the panel)+├── packaging/ # MSI / deb / rpm packaging├── scripts/ # Build and install scripts+├── ui/ # Agent desktop UI (React)├── Makefile└── go.mod```diff --git a/docs/API.md b/docs/API.mdindex 9eb0a4f8..1539aea5 100644--- a/docs/API.md+++ b/docs/API.md@@ -1225,5 +1225,5 @@ console.log(`CPU: ${metrics.cpu.percent}%`);<p align="center"><strong>ServerKit API Reference</strong><br>- Version 0.9.0+ Version 1.6.7</p>diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex eb52d3ff..adc4b7cd 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -206,6 +206,13 @@ ServerKit follows a modern 3-tier architecture:2. **Backend:** Flask REST API managing Docker, Nginx, and system services.3. **Agent:** Go-based remote agent for multi-server management.+> **Deployment constraint — single WebSocket worker.** The agent gateway keeps+> all connected-agent state (the registry of live agents, socket↔server index,+> session tokens, and in-flight command queues) **in-memory in one process**.+> Run the panel with a **single** gevent-websocket worker. Scaling to multiple+> workers without a shared backplane (e.g. a Redis message queue) will silently+> misroute or drop commands for agents connected to a different worker.+---## Troubleshootingdiff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.mdindex 50a3c1e6..217dca91 100644--- a/docs/INSTALLATION.md+++ b/docs/INSTALLATION.md@@ -1,6 +1,14 @@# ServerKit Installation Guide-This guide covers installing ServerKit on Ubuntu 22.04/24.04 LTS. ServerKit is a modern server management panel for managing web applications, databases, Docker containers, and more.+This guide covers installing ServerKit on Linux. The one-line installer+(`install.sh`) supports Ubuntu 22.04+, Debian 12+, Fedora, and the RHEL family+(RHEL/Rocky/AlmaLinux/CentOS 9+); on RHEL-family hosts it also enables EPEL and+configures SELinux for the nginx reverse proxy. The manual steps below use+Ubuntu/Debian (`apt`) as the primary example — on Fedora/RHEL substitute `dnf`+and the docker-ce RHEL repo.++To connect additional servers to this panel, install the agent — see+[agent/README.md](../agent/README.md) and [pairing.md](pairing.md). ServerKit is a modern server management panel for managing web applications, databases, Docker containers, and more.## Table of Contents@@ -18,7 +26,7 @@ This guide covers installing ServerKit on Ubuntu 22.04/24.04 LTS. ServerKit is a### Minimum System Requirements-- **OS**: Ubuntu 22.04 LTS or 24.04 LTS (64-bit)+- **OS** (64-bit): Ubuntu 22.04+ / Debian 12+ / Fedora / RHEL / Rocky / AlmaLinux 9+- **CPU**: 1 vCPU (2+ recommended)- **RAM**: 1 GB minimum (2+ GB recommended)- **Disk**: 10 GB free space@@ -77,7 +85,7 @@ docker compose version```bash# Clone the repository-git clone https://github.com/yourusername/ServerKit.git+git clone https://github.com/jhd3197/ServerKit.gitcd ServerKit```@@ -158,7 +166,7 @@ sudo apt install -y git curl wget```bash# Clone repositorycd /opt-sudo git clone https://github.com/yourusername/ServerKit.git+sudo git clone https://github.com/jhd3197/ServerKit.gitsudo chown -R $USER:$USER ServerKitcd ServerKitdiff --git a/docs/MULTI_ENVIRONMENT.md b/docs/MULTI_ENVIRONMENT.mdindex 03b11ef0..0d9a506c 100644--- a/docs/MULTI_ENVIRONMENT.md+++ b/docs/MULTI_ENVIRONMENT.md@@ -1,6 +1,6 @@# Multi-Environment WordPress Setup Guide-ServerKit v1.1 introduces multi-environment support, allowing you to link production and development WordPress instances that share the same database with separate table prefixes.+ServerKit supports multi-environment linking, allowing you to link production and development WordPress instances that share the same database with separate table prefixes.## Overviewdiff --git a/docs/README.md b/docs/README.mdindex 88602394..656d743f 100644--- a/docs/README.md+++ b/docs/README.md@@ -9,9 +9,12 @@ Welcome to the ServerKit documentation. This guide will help you install, config| Document | Description ||----------|-------------|| [Installation Guide](INSTALLATION.md) | Complete setup instructions for Docker and manual installation |+| [Architecture](ARCHITECTURE.md) | System design, request flow, and diagrams || [Deployment Guide](DEPLOYMENT.md) | Production deployment, CLI commands, and configuration |+| [Local Development](LOCAL_DEVELOPMENT.md) | Run the panel locally for development || [API Reference](API.md) | REST API documentation with examples || [Multi-Environment Guide](MULTI_ENVIRONMENT.md) | Set up prod/dev WordPress pairs with shared database |+| [Multi-Server & Agent](../agent/README.md) | Install the agent and connect remote servers (see also [pairing](pairing.md)) |---@@ -23,7 +26,7 @@ Choose your preferred installation method:- **[Docker Installation](INSTALLATION.md#quick-install-docker)** (Recommended) - Get started in minutes- **[Manual Installation](INSTALLATION.md#manual-installation)** - Full control over the setup-- **[One-Line Install](../README.md#option-2-one-line-install-ubuntu)** - Quick Ubuntu script+- **[One-Line Install](../README.md#-quick-start)** - One-line installer for Ubuntu, Debian, Fedora, and RHEL/Rocky/AlmaLinux### 2. Initial Setup@@ -64,7 +67,7 @@ Each application includes:### Multi-Environment Support-ServerKit v1.1 introduces **multi-environment linking** for WordPress and other applications:+ServerKit supports **multi-environment linking** for WordPress and other applications:- **Production/Development Pairs** - Link apps as prod/dev environments- **Shared Database** - Both environments can share the same MySQL database with different table prefixes@@ -267,5 +270,5 @@ See [Installation Guide - Troubleshooting](INSTALLATION.md#troubleshooting) for<p align="center"><strong>ServerKit Documentation</strong><br>- Version 0.9.0+ Version 1.6.7</p>diff --git a/docs/pairing.md b/docs/pairing.mdindex c2005e85..3831406f 100644--- a/docs/pairing.md+++ b/docs/pairing.md@@ -112,11 +112,22 @@ Use that URL as the `--server` flag. For self-signed TLS in dev,(60s → 5 min cap) plus per-IP rate limits (5 claims / 10 minutes).- All claim/lookup events are written to the audit log.- Enrollments expire 24h after creation; un-claimed records are pruned hourly.-- The agent's keypair is encrypted at rest with a key derived from- `/etc/machine-id` + hostname (Linux) or COMPUTERNAME + USERNAME (Windows).+- The agent's keypair is encrypted at rest with a **host-stable** key derived+ from `/etc/machine-id` + hostname (Linux) or hostname + COMPUTERNAME (Windows).+ The key is intentionally independent of the logged-in user so the Windows+ service (running as `LocalSystem`) can decrypt credentials written during+ user-context pairing — mixing in the Windows username broke this and was+ removed in agent 1.6.14 (a legacy USERNAME-based key is retained only for+ one-time migration). Treat the stored key file as a host-equivalent secret;+ see [../SECURITY.md](../SECURITY.md) for the full agent trust model.- Compare the displayed fingerprint side-by-side before claiming. Mismatchmeans the wrong agent — abort and re-run `pair`.+> **Treat the stored credential/key file as a host-equivalent secret.** Combined+> with the agent's remote-execution capability, recovering it is equivalent to+> controlling the host. See [../SECURITY.md](../SECURITY.md) for the full agent+> trust model.+## API reference| Endpoint | Purpose | Auth |