Skip to content

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.

docs: sync docs with dev, add CHANGELOG/SECURITY, document Windows agent

Juan Deniseab1a35794e1
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 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.md
index 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 archite
Other 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.md
index ae23d22a..fe508663 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -255,10 +255,14 @@ pytest --cov=app # With coverage
```bash
cd 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 Submitting
Run the dev validation suite to check for common issues:
diff --git a/README.md b/README.md
index 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) | [P
curl -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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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 | iex
Install-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 dependencies
go 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 wizard
status Show agent status
config 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 information
help 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 -f
systemctl 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 50
Restart-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.md
index 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.md
index 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.
+
---
## Troubleshooting
diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md
index 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.git
cd ServerKit
```
@@ -158,7 +166,7 @@ sudo apt install -y git curl wget
```bash
# Clone repository
cd /opt
-sudo git clone https://github.com/yourusername/ServerKit.git
+sudo git clone https://github.com/jhd3197/ServerKit.git
sudo chown -R $USER:$USER ServerKit
cd ServerKit
diff --git a/docs/MULTI_ENVIRONMENT.md b/docs/MULTI_ENVIRONMENT.md
index 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.
## Overview
diff --git a/docs/README.md b/docs/README.md
index 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.md
index 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. Mismatch
means 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 |