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
Add agent capability probing and reporting
Juan Denisa93697c7f6b9
diff --git a/agent/internal/agent/agent.go b/agent/internal/agent/agent.goindex e57dc1af..2266aaa2 100644--- a/agent/internal/agent/agent.go+++ b/agent/internal/agent/agent.go@@ -18,6 +18,7 @@ import ("time""github.com/serverkit/agent/internal/auth"+ "github.com/serverkit/agent/internal/capabilities""github.com/serverkit/agent/internal/config""github.com/serverkit/agent/internal/docker""github.com/serverkit/agent/internal/events"@@ -55,6 +56,11 @@ type Agent struct {// Command handlershandlers map[string]CommandHandler+ // Capabilities probed once at startup. Sent to the panel each time+ // the transport reconnects (so a panel restart picks them up+ // without waiting for the agent to also restart).+ capabilities protocol.CapabilitiesMessage+// Lifecycle trackingstartTime time.TimerestartCh chan struct{}@@ -127,6 +133,14 @@ func New(cfg *config.Config, log *logger.Logger) (*Agent, error) {restartCh: make(chan struct{}),}+ // Probe capabilities up-front so connectionWatcher can ship them on+ // every reconnect without re-probing. Docker availability is taken+ // from whether NewClient succeeded above; the capability layer+ // doesn't redo that work.+ probeCtx, probeCancel := context.WithTimeout(context.Background(), 5*time.Second)+ agent.capabilities = capabilities.Probe(probeCtx, log, dockerClient != nil)+ probeCancel()+// Register command handlersagent.registerHandlers()@@ -378,6 +392,10 @@ func abs(x int64) int64 {// connectionWatcher polls the WS connection flag and emits Activity events// on each transition. Avoids dragging events.Store into the ws package or// adding a new callback API for one consumer.+//+// Also doubles as the "send capabilities on connect" hook: each time the+// transport flips from down→up, we re-ship the capability map so the+// panel's record stays current after a panel restart.func (a *Agent) connectionWatcher(ctx context.Context) {ticker := time.NewTicker(1 * time.Second)defer ticker.Stop()@@ -398,6 +416,7 @@ func (a *Agent) connectionWatcher(ctx context.Context) {a.events.Append(events.KindWSConnected, events.SeverityInfo,"Connected to panel",map[string]interface{}{"url": a.cfg.Server.URL})+ a.sendCapabilities()} else if prev {// Only log disconnect after we'd previously been up — avoids// a spurious "lost connection" on cold-start before the@@ -410,6 +429,28 @@ func (a *Agent) connectionWatcher(ctx context.Context) {}}+// sendCapabilities ships the cached capability probe to the panel.+// Failures are logged and ignored — capabilities are best-effort+// metadata; missing ones just mean an agent doesn't show up in feature+// pickers until the next reconnect.+func (a *Agent) sendCapabilities() {+ msg := protocol.CapabilitiesMessage{+ Message: protocol.NewMessage(protocol.TypeCapabilities, auth.GenerateNonce()),+ Capabilities: a.capabilities.Capabilities,+ Platform: a.capabilities.Platform,+ Distro: a.capabilities.Distro,+ DistroVersion: a.capabilities.DistroVersion,+ }+ if err := a.ws.Send(msg); err != nil {+ a.log.Warn("Failed to send capabilities", "error", err)+ return+ }+ a.log.Debug("Sent capabilities to panel",+ "platform", a.capabilities.Platform,+ "distro", a.capabilities.Distro,+ )+}+// heartbeatLoop sends periodic heartbeatsfunc (a *Agent) heartbeatLoop(ctx context.Context) {ticker := time.NewTicker(a.cfg.Server.PingInterval)diff --git a/agent/internal/capabilities/capabilities.go b/agent/internal/capabilities/capabilities.gonew file mode 100644index 00000000..6bac973f--- /dev/null+++ b/agent/internal/capabilities/capabilities.go@@ -0,0 +1,175 @@+// Package capabilities probes the host for which feature surfaces the+// agent can manage (cron, docker, systemd, nginx, …). The result is a+// flat map[string]bool the agent ships to the panel on connect; the+// panel uses it to gate per-feature target pickers.+//+// Probes are cheap (PATH lookups + a couple of file/socket checks) and+// run once per agent process at startup. Results are cached for the+// process lifetime — re-probing is a future concern (e.g. SIGHUP, an+// explicit panel-issued "recapability" command).+package capabilities++import (+ "context"+ "os"+ "os/exec"+ "path/filepath"+ "runtime"+ "sync"++ "github.com/serverkit/agent/internal/logger"+ "github.com/serverkit/agent/pkg/protocol"+ gopsutilhost "github.com/shirou/gopsutil/v3/host"+)++// Probe runs all known capability probes and returns the result. log is+// optional — used to record what the probe found, mostly for ops+// debugging when an agent unexpectedly fails to expose a feature.+//+// dockerAvailable is passed in by the agent because it has already+// dialled the docker socket during startup; re-probing here would just+// duplicate that work.+func Probe(ctx context.Context, log *logger.Logger, dockerAvailable bool) protocol.CapabilitiesMessage {+ caps := protocol.Capabilities{}++ // Docker — the agent's own client is the source of truth. If the+ // agent couldn't dial dockerd, nothing this layer probes will fix+ // it.+ caps["docker"] = dockerAvailable++ // Linux service surfaces. On non-Linux these stay false; the+ // panel's UI is already conditional on them.+ caps["cron"] = probeCron()+ caps["systemd"] = probeSystemd()+ caps["nginx"] = probeNginx()+ caps["php_fpm"] = probePHPFPM()+ caps["packages"] = probePackageManager()++ // Platform / distro for any code that needs more than the booleans+ // (e.g. "use apt vs dnf" — Phase 4 territory, but we capture it+ // now so we don't have to add another roundtrip later).+ platform := runtime.GOOS+ distro := ""+ distroVer := ""+ if info, err := gopsutilhost.InfoWithContext(ctx); err == nil {+ // gopsutil reports "ubuntu", "debian", "centos", etc. on Linux;+ // "windows", "darwin" on those platforms — we don't need it+ // there.+ distro = info.Platform+ distroVer = info.PlatformVersion+ }++ if log != nil {+ log.Info("Capability probe complete",+ "platform", platform,+ "distro", distro,+ "docker", caps["docker"],+ "cron", caps["cron"],+ "systemd", caps["systemd"],+ "nginx", caps["nginx"],+ "php_fpm", caps["php_fpm"],+ "packages", caps["packages"],+ )+ }++ return protocol.CapabilitiesMessage{+ Capabilities: caps,+ Platform: platform,+ Distro: distro,+ DistroVersion: distroVer,+ }+}++// probeCron — present if `crontab` is on PATH OR a cron daemon is+// installed (we don't require it to be running; the panel can start it).+func probeCron() bool {+ if runtime.GOOS != "linux" {+ return false+ }+ if hasOnPath("crontab") {+ return true+ }+ // On systemd hosts that only expose the timer subsystem, crontab+ // may be missing but cron.d is still useful. Treat presence of+ // /etc/cron.d as the fallback signal.+ if _, err := os.Stat("/etc/cron.d"); err == nil {+ return true+ }+ return false+}++// probeSystemd — systemctl on PATH and the system bus is reachable.+// On a container without systemd, systemctl is sometimes installed as a+// shim that fails with "Failed to connect to bus", so we additionally+// check for /run/systemd/system which is the canonical "systemd is PID 1+// here" marker.+func probeSystemd() bool {+ if runtime.GOOS != "linux" {+ return false+ }+ if !hasOnPath("systemctl") {+ return false+ }+ if _, err := os.Stat("/run/systemd/system"); err == nil {+ return true+ }+ return false+}++func probeNginx() bool {+ if runtime.GOOS != "linux" {+ return false+ }+ return hasOnPath("nginx")+}++func probePHPFPM() bool {+ if runtime.GOOS != "linux" {+ return false+ }+ // PHP-FPM is shipped per-version on Debian/Ubuntu (php-fpm,+ // php8.1-fpm, php8.2-fpm, …). hasOnPath only catches the bare+ // name, so glob the common install dirs as a fallback.+ if hasOnPath("php-fpm") {+ return true+ }+ for _, pat := range []string{+ "/usr/sbin/php*-fpm*",+ "/usr/local/sbin/php*-fpm*",+ } {+ if matches, _ := filepath.Glob(pat); len(matches) > 0 {+ return true+ }+ }+ return false+}++// probePackageManager — true if any of the recognized managers (apt,+// dnf, yum, apk, pacman, zypper) is on PATH. Phase 0 only needs+// "package management is possible from here"; identifying which manager+// goes in the system_info / capabilities Distro field above.+func probePackageManager() bool {+ if runtime.GOOS != "linux" {+ return false+ }+ for _, mgr := range []string{"apt-get", "apt", "dnf", "yum", "apk", "pacman", "zypper"} {+ if hasOnPath(mgr) {+ return true+ }+ }+ return false+}++// hasOnPath checks whether a binary is reachable via $PATH. Cached to+// avoid hammering the filesystem on agents that re-probe via SIGHUP.+func hasOnPath(name string) bool {+ if v, ok := pathCache.Load(name); ok {+ return v.(bool)+ }+ _, err := exec.LookPath(name)+ ok := err == nil+ pathCache.Store(name, ok)+ return ok+}++var pathCache sync.Mapdiff --git a/agent/internal/transport/poll/client.go b/agent/internal/transport/poll/client.goindex 16619413..cc5f37a2 100644--- a/agent/internal/transport/poll/client.go+++ b/agent/internal/transport/poll/client.go@@ -53,6 +53,10 @@ type Client struct {hbMetrics *protocol.HeartbeatMetrics// One-shot system info, sent on the first /poll after it's queued.sysInfo map[string]interface{}+ // One-shot capabilities, sent on the first /poll after it's queued.+ // Re-queued on every reconnect by agent.connectionWatcher so the+ // panel's record stays current after a panel restart.+ caps map[string]interface{}baseURL string}@@ -233,6 +237,10 @@ func (c *Client) pollOnce(ctx context.Context) error {body["system_info"] = c.sysInfoc.sysInfo = nil}+ if c.caps != nil {+ body["capabilities"] = c.caps+ c.caps = nil+ }c.hbMu.Unlock()var resp struct {@@ -320,6 +328,30 @@ func (c *Client) Send(msg interface{}) error {return nil}}+ // Capabilities arrive as a typed struct (CapabilitiesMessage), not+ // a map — round-trip through JSON to lift the inner fields out+ // without growing this layer a Go-typed dependency on the+ // protocol message shape.+ if cm, ok := msg.(protocol.CapabilitiesMessage); ok {+ buf, err := json.Marshal(cm)+ if err != nil {+ return err+ }+ var raw map[string]interface{}+ if err := json.Unmarshal(buf, &raw); err != nil {+ return err+ }+ // Strip the envelope (type/id/timestamp/signature) — the panel+ // poll endpoint cares about the inner payload.+ delete(raw, "type")+ delete(raw, "id")+ delete(raw, "timestamp")+ delete(raw, "signature")+ c.hbMu.Lock()+ c.caps = raw+ c.hbMu.Unlock()+ return nil+ }c.log.Debug("Dropping unsupported Send in poll mode")return nil}diff --git a/agent/pkg/protocol/messages.go b/agent/pkg/protocol/messages.goindex db07f43f..5941f1e8 100644--- a/agent/pkg/protocol/messages.go+++ b/agent/pkg/protocol/messages.go@@ -33,6 +33,11 @@ const (// SystemTypeSystemInfo MessageType = "system_info"+ // Capabilities — agent reports which feature surfaces it can drive+ // (cron, docker, systemd, …) so the panel can gate target pickers+ // without round-tripping each click.+ TypeCapabilities MessageType = "capabilities"+// DiscoveryTypeDiscovery MessageType = "discovery"TypeDiscoveryRequest MessageType = "discovery_request"@@ -145,6 +150,26 @@ type SystemInfoMessage struct {Info SystemInfo `json:"info"`}+// Capabilities is a flat dict of feature → bool reported by the agent on+// connect. The panel uses this to gate target pickers: an agent shows up+// in the Cron page's picker only if Capabilities["cron"] is true.+//+// Format is intentionally a map[string]bool rather than a struct so new+// keys can be added on the agent side and ignored by older panels (and+// vice versa) without protocol breakage.+type Capabilities map[string]bool++// CapabilitiesMessage is sent by the agent to advertise which feature+// surfaces it can drive. Panel echo-saves this on the in-memory+// ConnectedAgent record.+type CapabilitiesMessage struct {+ Message+ Capabilities Capabilities `json:"capabilities"`+ Platform string `json:"platform"` // "linux", "windows", "darwin"+ Distro string `json:"distro,omitempty"` // "ubuntu", "debian", "rhel", ...+ DistroVersion string `json:"distro_version,omitempty"` // "22.04"+}+// SystemInfo contains detailed system informationtype SystemInfo struct {Hostname string `json:"hostname"`diff --git a/backend/app/__init__.py b/backend/app/__init__.pyindex 92bb6330..e13cc84e 100644--- a/backend/app/__init__.py+++ b/backend/app/__init__.py@@ -239,6 +239,10 @@ def create_app(config_name=None):from app.api.fleet_monitor import fleet_monitor_bpapp.register_blueprint(fleet_monitor_bp, url_prefix='/api/v1/fleet-monitor')+ # Register blueprints - Fleet (target picker, capability discovery)+ from app.api.fleet import fleet_bp+ app.register_blueprint(fleet_bp, url_prefix='/api/v1/fleet')+# Register blueprints - Agent Pluginsfrom app.api.agent_plugins import agent_plugins_bpapp.register_blueprint(agent_plugins_bp, url_prefix='/api/v1/agent-plugins')diff --git a/backend/app/agent_gateway.py b/backend/app/agent_gateway.pyindex 6d513197..57d677d2 100644--- a/backend/app/agent_gateway.py+++ b/backend/app/agent_gateway.py@@ -228,6 +228,37 @@ class AgentNamespace(Namespace):info = data.get('info', {})agent_registry.update_system_info(agent.server_id, info)+ def on_capabilities(self, data):+ """+ Handle agent capability advertisement.++ Sent by the agent right after auth succeeds (and on every+ reconnect). The payload tells the panel which feature surfaces+ this agent can drive — cron, docker, systemd, etc. — and is+ used to filter target pickers in the UI.++ Expected data:+ {+ "type": "capabilities",+ "capabilities": {"docker": true, "cron": true, ...},+ "platform": "linux",+ "distro": "ubuntu",+ "distro_version": "22.04"+ }+ """+ sid = request.sid+ agent = agent_registry.get_agent_by_socket(sid)++ if not agent:+ emit('error', {+ 'type': 'error',+ 'code': 'NOT_AUTHENTICATED',+ 'message': 'Not authenticated'+ })+ return++ agent_registry.update_capabilities(agent.server_id, data or {})+def on_stream(self, data):"""Handle streaming data from agent (logs, metrics).diff --git a/backend/app/api/agent_poll.py b/backend/app/api/agent_poll.pyindex a7bb61bb..de0829f2 100644--- a/backend/app/api/agent_poll.py+++ b/backend/app/api/agent_poll.py@@ -104,10 +104,13 @@ def poll():body = request.get_json(silent=True) or {}metrics = body.get('metrics') or {}sysinfo = body.get('system_info')+ caps = body.get('capabilities')agent_registry.update_heartbeat(agent.server_id, metrics)if sysinfo:agent_registry.update_system_info(agent.server_id, sysinfo)+ if caps:+ agent_registry.update_capabilities(agent.server_id, caps)# Long-poll up to 25s for any queued command. Below the typical# tunnel idle-timeout (Cloudflare ~100s, ngrok ~60s) so we neverdiff --git a/backend/app/api/fleet.py b/backend/app/api/fleet.pynew file mode 100644index 00000000..f2aa3096--- /dev/null+++ b/backend/app/api/fleet.py@@ -0,0 +1,79 @@+"""+Fleet API++Cross-server endpoints that don't belong to any single server's resource+tree — primarily the target-picker support that every agent-aware+feature page consumes.++The "target" abstraction:++ target = {"kind": "local"}+ | {"kind": "agent", "server_id": "...", "server_name": "..."}++Pages render a picker; clicks send `target` in the request body of+feature CRUD calls; the backend dispatches against `target.kind`. See+`backend/app/services/fleet_targeting.py` (Phase 1) for the dispatch+helper.++This module is read-only; it does not write any state.+"""++from flask import Blueprint, jsonify, request+from flask_jwt_extended import jwt_required++from app.models.server import Server+from app.services.agent_registry import agent_registry+++fleet_bp = Blueprint('fleet', __name__)+++@fleet_bp.route('/targets', methods=['GET'])+@jwt_required()+def list_targets():+ """List runnable targets, optionally filtered by feature.++ Query params:+ feature — capability name (cron, docker, systemd, …). When+ present, only agents whose advertised capability+ map has feature=true are returned. When absent,+ every connected agent is returned regardless of+ capabilities.++ The local panel host is always included as the first entry. Even+ if no agent has the requested feature the caller still gets the+ local target back, which matches the behaviour the UI expects:+ "the local target is always available, agents are additive."+ """+ feature = (request.args.get('feature') or '').strip() or None++ targets = [{'kind': 'local'}]++ # Walk the in-memory registry of connected agents. We intentionally+ # do NOT pull from the Server table — capabilities are per-session+ # state, and a server with status=offline can't take a command no+ # matter what it last reported.+ for server_id in agent_registry.get_connected_servers():+ if feature and not agent_registry.has_capability(server_id, feature):+ continue++ # Look up the display name. We could cache this on+ # ConnectedAgent, but the table is small and the lookup is+ # cheap; not worth the staleness risk.+ server = Server.query.get(server_id)+ if not server:+ # Connected agent without a Server row would be a bug+ # elsewhere; skip rather than 500.+ continue++ caps = agent_registry.get_capabilities(server_id) or {}++ targets.append({+ 'kind': 'agent',+ 'server_id': server.id,+ 'server_name': server.name,+ 'hostname': server.hostname,+ 'capabilities': caps,+ })++ return jsonify({'targets': targets})diff --git a/backend/app/api/servers.py b/backend/app/api/servers.pyindex 35341446..c3acd270 100644--- a/backend/app/api/servers.py+++ b/backend/app/api/servers.py@@ -286,6 +286,14 @@ def get_server(server_id):agent = agent_registry.get_agent(server.id)result['is_connected'] = agent is not Noneresult['transport'] = agent.transport if agent else None+ # Capability map the agent advertised on connect; empty for older+ # agents that don't speak the protocol yet. Consumers (UI target+ # pickers, etc.) should treat missing keys as false.+ result['capabilities'] = dict(agent.capabilities) if agent else {}+ if agent:+ result['platform'] = agent.platform+ result['distro'] = agent.distro+ result['distro_version'] = agent.distro_versionreturn jsonify(result)diff --git a/backend/app/services/agent_registry.py b/backend/app/services/agent_registry.pyindex 4248a3a2..487fb6a4 100644--- a/backend/app/services/agent_registry.py+++ b/backend/app/services/agent_registry.py@@ -44,6 +44,15 @@ class ConnectedAgent:outbound_queue: Queue = field(default_factory=Queue)# Pending commands waiting for responsepending_commands: Dict[str, 'PendingCommand'] = field(default_factory=dict)+ # Feature surfaces the agent reported it can drive (cron, docker,+ # systemd, …). Empty until the agent sends a `capabilities` event;+ # older agents that don't speak the protocol leave this empty so+ # they only show up as default-local in target pickers. The dict is+ # forward-compatible: unknown keys are passed through verbatim.+ capabilities: Dict[str, bool] = field(default_factory=dict)+ platform: Optional[str] = None+ distro: Optional[str] = None+ distro_version: Optional[str] = None@dataclass@@ -711,6 +720,67 @@ class AgentRegistry:return server+ # ==================== Capabilities ====================++ def update_capabilities(self, server_id: str, payload: dict):+ """Stash the capability map an agent reported on connect.++ payload shape mirrors protocol.CapabilitiesMessage minus the+ envelope:++ {+ "capabilities": {"docker": true, "cron": true, ...},+ "platform": "linux",+ "distro": "ubuntu",+ "distro_version": "22.04"+ }++ Stored only on the in-memory ConnectedAgent — capabilities are+ re-shipped on every reconnect, so persisting across panel+ restarts isn't necessary. An older agent that never sends this+ message simply has an empty capabilities dict and never shows+ up in feature-gated target pickers.+ """+ if not isinstance(payload, dict):+ return+ caps = payload.get('capabilities') or {}+ # Coerce values to bool — agents are trusted but defensive+ # casting protects the API consumer (UI) from malformed types.+ clean_caps = {str(k): bool(v) for k, v in caps.items() if isinstance(k, str)}++ with self._lock:+ agent = self._agents.get(server_id)+ if not agent:+ return+ agent.capabilities = clean_caps+ agent.platform = payload.get('platform') or None+ agent.distro = payload.get('distro') or None+ agent.distro_version = payload.get('distro_version') or None++ logger.info(+ "Capabilities updated for server %s: %s",+ server_id,+ sorted(k for k, v in clean_caps.items() if v),+ )++ def get_capabilities(self, server_id: str) -> Optional[Dict[str, bool]]:+ """Return the capability map for a connected agent, or None if+ the agent is not connected. Returns an empty dict if the agent+ is connected but hasn't (yet) reported capabilities — that's a+ valid state for older agents."""+ with self._lock:+ agent = self._agents.get(server_id)+ if not agent:+ return None+ return dict(agent.capabilities)++ def has_capability(self, server_id: str, feature: str) -> bool:+ """Convenience: is the given feature reported as available?"""+ caps = self.get_capabilities(server_id)+ if not caps:+ return False+ return bool(caps.get(feature))+# ==================== System Info ====================def update_system_info(self, server_id: str, info: dict):