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.

Add agent capability probing and reporting

Juan Denisa93697c7f6b9
diff --git a/agent/internal/agent/agent.go b/agent/internal/agent/agent.go
index 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 handlers
handlers 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 tracking
startTime time.Time
restartCh 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 handlers
agent.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 heartbeats
func (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.go
new file mode 100644
index 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.Map
diff --git a/agent/internal/transport/poll/client.go b/agent/internal/transport/poll/client.go
index 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.sysInfo
c.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.go
index db07f43f..5941f1e8 100644
--- a/agent/pkg/protocol/messages.go
+++ b/agent/pkg/protocol/messages.go
@@ -33,6 +33,11 @@ const (
// System
TypeSystemInfo 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"
+
// Discovery
TypeDiscovery 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 information
type SystemInfo struct {
Hostname string `json:"hostname"`
diff --git a/backend/app/__init__.py b/backend/app/__init__.py
index 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_bp
app.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 Plugins
from app.api.agent_plugins import agent_plugins_bp
app.register_blueprint(agent_plugins_bp, url_prefix='/api/v1/agent-plugins')
diff --git a/backend/app/agent_gateway.py b/backend/app/agent_gateway.py
index 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.py
index 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 never
diff --git a/backend/app/api/fleet.py b/backend/app/api/fleet.py
new file mode 100644
index 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.py
index 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 None
result['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_version
return jsonify(result)
diff --git a/backend/app/services/agent_registry.py b/backend/app/services/agent_registry.py
index 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 response
pending_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):