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.

Cache agent capabilities to DB and surface them in System Status card

Juan Denis32bf2b80819e
diff --git a/backend/app/api/servers.py b/backend/app/api/servers.py
index 9880850c..7e85c930 100644
--- a/backend/app/api/servers.py
+++ b/backend/app/api/servers.py
@@ -286,15 +286,33 @@ 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 {}
- result['runtimes'] = dict(agent.runtimes) if agent else {}
+ # Capability map the agent advertised on connect. When the agent is
+ # connected, prefer the live in-memory copy; when offline, fall back
+ # to the snapshot persisted by update_capabilities so the Overview
+ # tab can still render the last-known state instead of an empty
+ # screen. capabilities_stale + capabilities_at let the UI badge the
+ # data as cached.
if agent:
+ result['capabilities'] = dict(agent.capabilities)
+ result['runtimes'] = dict(agent.runtimes)
+ result['runtime_managers'] = dict(getattr(agent, 'runtime_managers', {}) or {})
+ result['allowed_paths'] = list(getattr(agent, 'allowed_paths', []) or [])
+ result['sudo'] = getattr(agent, 'sudo', '') or (server.cached_sudo or '')
+ result['systemd_json'] = bool(getattr(agent, 'systemd_json', server.cached_systemd_json or False))
result['platform'] = agent.platform
result['distro'] = agent.distro
result['distro_version'] = agent.distro_version
+ result['capabilities_stale'] = False
+ result['capabilities_at'] = server.capabilities_at.isoformat() + 'Z' if server.capabilities_at else None
+ else:
+ result['capabilities'] = dict(server.cached_capabilities or {})
+ result['runtimes'] = dict(server.cached_runtimes or {})
+ result['runtime_managers'] = dict(server.cached_runtime_managers or {})
+ result['allowed_paths'] = list(server.cached_allowed_paths or [])
+ result['sudo'] = server.cached_sudo or ''
+ result['systemd_json'] = bool(server.cached_systemd_json)
+ result['capabilities_stale'] = bool(server.capabilities_at)
+ result['capabilities_at'] = server.capabilities_at.isoformat() + 'Z' if server.capabilities_at else None
return jsonify(result)
diff --git a/backend/app/models/server.py b/backend/app/models/server.py
index 38945b2f..cd107fe5 100644
--- a/backend/app/models/server.py
+++ b/backend/app/models/server.py
@@ -119,6 +119,18 @@ class Server(db.Model):
registered_at = db.Column(db.DateTime)
registered_by = db.Column(db.Integer, db.ForeignKey('users.id'))
+ # Cached capability snapshot — written every time the agent reports
+ # a Capabilities message, so the panel can render the full Overview
+ # tab even when the agent is offline. Old agents that pre-date these
+ # fields just have NULL here; the UI falls back gracefully.
+ cached_capabilities = db.Column(db.JSON) # {docker:bool, files:bool, ...}
+ cached_runtimes = db.Column(db.JSON) # {python:"3.11.4", node:"20.10.0", ...}
+ cached_runtime_managers = db.Column(db.JSON) # {python:"pyenv-win"|"pyenv"|""}
+ cached_allowed_paths = db.Column(db.JSON) # ["/var/www", ...]
+ cached_sudo = db.Column(db.String(20)) # "root"|"passwordless"|"unavailable"
+ cached_systemd_json = db.Column(db.Boolean) # systemctl --output=json supported?
+ capabilities_at = db.Column(db.DateTime) # when the snapshot was last refreshed
+
# Timestamps
created_at = db.Column(db.DateTime, default=datetime.utcnow)
updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
diff --git a/backend/app/services/agent_registry.py b/backend/app/services/agent_registry.py
index 2e99fdda..de0b5895 100644
--- a/backend/app/services/agent_registry.py
+++ b/backend/app/services/agent_registry.py
@@ -771,6 +771,19 @@ class AgentRegistry:
clean_paths = [str(p) for p in raw_paths if isinstance(p, str) and p.strip()] \
if isinstance(raw_paths, list) else []
+ # Newer payloads carry sudo mode + runtime managers + systemd_json.
+ # Coerce defensively — older agents won't include these keys.
+ sudo_mode = payload.get('sudo')
+ if not isinstance(sudo_mode, str):
+ sudo_mode = ''
+ raw_managers = payload.get('runtime_managers') or {}
+ clean_managers: Dict[str, str] = {}
+ if isinstance(raw_managers, dict):
+ for k, v in raw_managers.items():
+ if isinstance(k, str) and isinstance(v, (str, type(None))):
+ clean_managers[k] = v or ''
+ systemd_json = bool(payload.get('systemd_json'))
+
with self._lock:
agent = self._agents.get(server_id)
if not agent:
@@ -782,6 +795,32 @@ class AgentRegistry:
agent.runtimes = clean_runtimes
agent.allowed_paths = clean_paths
+ # Persist a snapshot to the Server row so the Overview tab can
+ # render even when the agent is offline. Wrapped in a try/except
+ # so a transient DB hiccup doesn't drop the in-memory update —
+ # the cache is best-effort, the live value above is the source
+ # of truth while the agent is connected.
+ try:
+ from app import db
+ from app.models.server import Server
+ server = Server.query.get(server_id)
+ if server is not None:
+ server.cached_capabilities = clean_caps
+ server.cached_runtimes = clean_runtimes
+ server.cached_runtime_managers = clean_managers
+ server.cached_allowed_paths = clean_paths
+ server.cached_sudo = sudo_mode
+ server.cached_systemd_json = systemd_json
+ server.capabilities_at = datetime.utcnow()
+ if payload.get('platform'):
+ server.platform = payload.get('platform')
+ if payload.get('distro'):
+ server.os_version = payload.get('distro_version') or server.os_version
+ db.session.commit()
+ except Exception as exc:
+ # Don't let cache persistence failures break live updates.
+ logger.warning("Failed to persist capability snapshot for %s: %s", server_id, exc)
+
logger.info(
"Capabilities updated for server %s: %s",
server_id,
diff --git a/backend/migrations/versions/005_server_capabilities_cache.py b/backend/migrations/versions/005_server_capabilities_cache.py
new file mode 100644
index 00000000..d6f91b3c
--- /dev/null
+++ b/backend/migrations/versions/005_server_capabilities_cache.py
@@ -0,0 +1,53 @@
+"""Cache capability snapshot per server.
+
+Adds JSON columns to ``servers`` so the panel can render the Overview
+tab when the agent is offline. Written by agent_registry.update_
+capabilities every time an agent reports state.
+
+Revision ID: 005_server_capabilities_cache
+Revises: 004_deployment_jobs
+Create Date: 2026-05-01
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+revision = '005_server_capabilities_cache'
+down_revision = '004_deployment_jobs'
+branch_labels = None
+depends_on = None
+
+
+_NEW_COLUMNS = [
+ ('cached_capabilities', sa.JSON()),
+ ('cached_runtimes', sa.JSON()),
+ ('cached_runtime_managers', sa.JSON()),
+ ('cached_allowed_paths', sa.JSON()),
+ ('cached_sudo', sa.String(20)),
+ ('cached_systemd_json', sa.Boolean()),
+ ('capabilities_at', sa.DateTime()),
+]
+
+
+def upgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ if 'servers' not in inspector.get_table_names():
+ return
+ existing = {c['name'] for c in inspector.get_columns('servers')}
+ with op.batch_alter_table('servers') as batch_op:
+ for name, type_ in _NEW_COLUMNS:
+ if name not in existing:
+ batch_op.add_column(sa.Column(name, type_, nullable=True))
+
+
+def downgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ if 'servers' not in inspector.get_table_names():
+ return
+ existing = {c['name'] for c in inspector.get_columns('servers')}
+ with op.batch_alter_table('servers') as batch_op:
+ for name, _ in _NEW_COLUMNS:
+ if name in existing:
+ batch_op.drop_column(name)
diff --git a/frontend/src/components/serverdetail/SystemStatusCard.jsx b/frontend/src/components/serverdetail/SystemStatusCard.jsx
new file mode 100644
index 00000000..2cab44d4
--- /dev/null
+++ b/frontend/src/components/serverdetail/SystemStatusCard.jsx
@@ -0,0 +1,204 @@
+import { useState } from 'react';
+import api from '../../services/api';
+import { useToast } from '../../contexts/ToastContext';
+import { Button } from '@/components/ui/button';
+import { Badge } from '@/components/ui/badge';
+
+// Surfaces everything the agent's capability probe reports: detected
+// runtimes (python/node/php/go/ruby/java versions), runtime version
+// managers (pyenv/pyenv-win), package manager + sudo mode + systemd
+// JSON support, allowed file roots, and the boolean capability map.
+//
+// Reads from the server payload — when the agent is offline, the
+// fields fall back to the most recent snapshot persisted to the DB by
+// agent_registry.update_capabilities. capabilities_stale flips true in
+// that case and we badge the card accordingly.
+export default function SystemStatusCard({ server, onRefresh }) {
+ const toast = useToast();
+ const [refreshing, setRefreshing] = useState(false);
+
+ const stale = !!server.capabilities_stale;
+ const probedAt = server.capabilities_at;
+ const platform = server.platform || server.os_type;
+ const distro = server.distro || server.os_version;
+ const sudo = server.sudo;
+ const caps = server.capabilities || {};
+ const runtimes = server.runtimes || {};
+ const managers = server.runtime_managers || {};
+ const allowedPaths = server.allowed_paths || [];
+
+ async function handleRefresh() {
+ setRefreshing(true);
+ try {
+ await api.refreshRemoteCapabilities(server.id);
+ toast.success('Capabilities re-probed');
+ if (onRefresh) await onRefresh();
+ } catch (err) {
+ toast.error(err.message || 'Refresh failed');
+ } finally {
+ setRefreshing(false);
+ }
+ }
+
+ const capabilityKeys = Object.keys(caps).sort();
+ const runtimeKeys = Object.keys(runtimes).filter((k) => runtimes[k]).sort();
+
+ return (
+ <div className="info-card system-status-card">
+ <div className="system-status-card__header">
+ <h3>System Status</h3>
+ <div className="system-status-card__header-meta">
+ {stale && (
+ <Badge variant="outline" title="Agent offline — showing last cached snapshot">
+ Stale
+ </Badge>
+ )}
+ {probedAt && (
+ <span className="system-status-card__probed-at">
+ probed {formatRelative(probedAt)}
+ </span>
+ )}
+ <Button
+ size="sm"
+ variant="outline"
+ onClick={handleRefresh}
+ disabled={refreshing || !server.is_connected}
+ title={server.is_connected ? 'Re-run capability probe on the agent' : 'Agent must be online to refresh'}
+ >
+ {refreshing ? 'Refreshing…' : 'Refresh'}
+ </Button>
+ </div>
+ </div>
+
+ <div className="system-status-card__rows">
+ <Row label="Platform" value={[platform, distro].filter(Boolean).join(' · ') || 'Unknown'} />
+ <Row label="Sudo" value={<SudoBadge mode={sudo} />} />
+ <Row
+ label="Package manager"
+ value={detectedPackageManager(caps, server) || <Muted>not detected</Muted>}
+ />
+ <Row
+ label="Runtime managers"
+ value={
+ Object.keys(managers).length === 0 ? (
+ <Muted>none</Muted>
+ ) : (
+ <span className="system-status-card__chips">
+ {Object.entries(managers).map(([rt, mgr]) =>
+ mgr ? (
+ <Badge key={rt} variant="secondary">
+ {rt}: {mgr}
+ </Badge>
+ ) : (
+ <Badge key={rt} variant="outline" title={`No ${rt} manager installed`}>
+ {rt}: none
+ </Badge>
+ )
+ )}
+ </span>
+ )
+ }
+ />
+ <Row
+ label="Detected runtimes"
+ value={
+ runtimeKeys.length === 0 ? (
+ <Muted>none reported</Muted>
+ ) : (
+ <span className="system-status-card__chips">
+ {runtimeKeys.map((rt) => (
+ <Badge key={rt} variant="outline">
+ {rt} {runtimes[rt] || '?'}
+ </Badge>
+ ))}
+ </span>
+ )
+ }
+ />
+ <Row
+ label="Capabilities"
+ value={
+ capabilityKeys.length === 0 ? (
+ <Muted>none reported (older agent?)</Muted>
+ ) : (
+ <span className="system-status-card__chips">
+ {capabilityKeys.map((k) => (
+ <Badge
+ key={k}
+ variant={caps[k] ? 'default' : 'outline'}
+ title={caps[k] ? 'available' : 'not available on this host'}
+ >
+ {k}
+ </Badge>
+ ))}
+ </span>
+ )
+ }
+ />
+ {allowedPaths.length > 0 && (
+ <Row
+ label="File access roots"
+ value={
+ <ul className="system-status-card__paths">
+ {allowedPaths.map((p) => (
+ <li key={p} className="mono">{p}</li>
+ ))}
+ </ul>
+ }
+ />
+ )}
+ </div>
+ </div>
+ );
+}
+
+function Row({ label, value }) {
+ return (
+ <div className="system-status-card__row">
+ <span className="system-status-card__row-label">{label}</span>
+ <span className="system-status-card__row-value">{value}</span>
+ </div>
+ );
+}
+
+function Muted({ children }) {
+ return <span className="text-muted-foreground">{children}</span>;
+}
+
+function SudoBadge({ mode }) {
+ if (mode === 'root') return <Badge variant="default" title="Agent is running as root">root</Badge>;
+ if (mode === 'passwordless') return <Badge variant="default" title="sudo -n succeeded">passwordless sudo</Badge>;
+ if (mode === 'unavailable') {
+ return (
+ <Badge variant="destructive" title="Privileged actions (apt, systemd) will fail">
+ unavailable
+ </Badge>
+ );
+ }
+ return <Muted>not reported</Muted>;
+}
+
+// We don't have a dedicated package manager field, but the capability
+// probe sets caps.packages true when *some* manager is on PATH. Surface
+// the distro hint so users know what'll be invoked.
+function detectedPackageManager(caps, server) {
+ if (!caps.packages) return null;
+ const distro = (server.distro || server.os_type || '').toLowerCase();
+ if (distro.includes('ubuntu') || distro.includes('debian')) return 'apt';
+ if (distro.includes('rhel') || distro.includes('fedora') || distro.includes('centos') || distro.includes('rocky')) return 'dnf';
+ if (distro.includes('alpine')) return 'apk';
+ if (distro.includes('arch')) return 'pacman';
+ if (distro.includes('suse') || distro.includes('opensuse')) return 'zypper';
+ return 'available';
+}
+
+function formatRelative(iso) {
+ if (!iso) return '';
+ const ts = new Date(iso).getTime();
+ if (!Number.isFinite(ts)) return iso;
+ const diff = Date.now() - ts;
+ if (diff < 60_000) return 'just now';
+ if (diff < 3600_000) return `${Math.round(diff / 60_000)}m ago`;
+ if (diff < 86400_000) return `${Math.round(diff / 3600_000)}h ago`;
+ return new Date(iso).toLocaleString();
+}
diff --git a/frontend/src/pages/ServerDetail.jsx b/frontend/src/pages/ServerDetail.jsx
index 086193ac..19051378 100644
--- a/frontend/src/pages/ServerDetail.jsx
+++ b/frontend/src/pages/ServerDetail.jsx
@@ -14,6 +14,7 @@ import { Badge } from '@/components/ui/badge';
import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/components/ui/tabs';
import PackagesTab from '../components/serverdetail/PackagesTab';
import ServicesTab from '../components/serverdetail/ServicesTab';
+import SystemStatusCard from '../components/serverdetail/SystemStatusCard';
const ServerDetail = () => {
const { id, tab } = useParams();
@@ -251,10 +252,11 @@ const ServerDetail = () => {
server={server}
metrics={metrics}
systemInfo={systemInfo}
+ onRefreshServer={loadServer}
/>
</TabsContent>
<TabsContent value="docker">
- <DockerTab serverId={id} serverStatus={server.status} />
+ <DockerTab serverId={id} serverStatus={server.status} server={server} />
</TabsContent>
{server.capabilities?.cron && (
<TabsContent value="cron">
@@ -310,7 +312,7 @@ const ServerDetail = () => {
);
};
-const OverviewTab = ({ server, metrics, systemInfo }) => {
+const OverviewTab = ({ server, metrics, systemInfo, onRefreshServer }) => {
const formatBytes = (bytes) => {
if (!bytes) return 'N/A';
const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
@@ -397,6 +399,8 @@ const OverviewTab = ({ server, metrics, systemInfo }) => {
</div>
</div>
)}
+
+ <SystemStatusCard server={server} onRefresh={onRefreshServer} />
</div>
</div>
);
@@ -433,10 +437,11 @@ const unwrapList = (response) => {
return [];
};
-const DockerTab = ({ serverId, serverStatus }) => {
+const DockerTab = ({ serverId, serverStatus, server }) => {
const [containers, setContainers] = useState([]);
const [images, setImages] = useState([]);
const [loading, setLoading] = useState(true);
+ const [loadError, setLoadError] = useState(null);
const [subTab, setSubTab] = useState('containers');
const toast = useToast();
const { confirm: confirmDocker, confirmState: confirmDockerState, handleConfirm: handleDockerConfirm, handleCancel: handleDockerCancel } = useConfirm();
@@ -451,6 +456,7 @@ const DockerTab = ({ serverId, serverStatus }) => {
async function loadDockerData() {
setLoading(true);
+ setLoadError(null);
try {
const [containersRes, imagesRes] = await Promise.all([
api.getRemoteContainers(serverId, true),
@@ -461,11 +467,40 @@ const DockerTab = ({ serverId, serverStatus }) => {
setImages(unwrapList(imagesRes));
} catch (err) {
console.error('Failed to load Docker data:', err);
+ setLoadError(err.message || 'Failed to load Docker data');
} finally {
setLoading(false);
}
}
+ // If the agent reports docker capability false (Docker daemon not
+ // reachable from the agent process — common on Windows when the
+ // service hasn't been started, or on hosts where the agent user
+ // isn't in the docker group), explain that instead of pretending
+ // there are no containers.
+ const dockerCapability = server?.capabilities?.docker;
+ if (serverStatus === 'online' && server && dockerCapability === false) {
+ return (
+ <div className="empty-state docker-empty-state">
+ <h4>Docker not reachable from this agent</h4>
+ <p>
+ The agent connected successfully but couldn&apos;t talk to a Docker daemon.
+ Common causes:
+ </p>
+ <ul>
+ <li>Docker Desktop / dockerd is not running on the host</li>
+ <li>The agent user isn&apos;t in the <code>docker</code> group (Linux)</li>
+ <li>The npipe socket <code>//./pipe/docker_engine</code> isn&apos;t accessible (Windows)</li>
+ </ul>
+ <p>
+ Start Docker on the host, then click <strong>Refresh</strong> on the Overview tab to
+ re-probe capabilities. The Docker tab will appear normally once the agent
+ can reach the daemon.
+ </p>
+ </div>
+ );
+ }
+
async function handleContainerAction(containerId, action) {
try {
let result;
@@ -506,6 +541,12 @@ const DockerTab = ({ serverId, serverStatus }) => {
return (
<div className="docker-tab">
+ {loadError && (
+ <div className="docker-tab__error">
+ <strong>Couldn&apos;t load Docker data:</strong> {loadError}
+ <Button size="sm" variant="outline" onClick={loadDockerData}>Retry</Button>
+ </div>
+ )}
<div className="docker-sub-tabs">
<button
className={`sub-tab ${subTab === 'containers' ? 'active' : ''}`}
diff --git a/frontend/src/styles/pages/_server-packages.scss b/frontend/src/styles/pages/_server-packages.scss
index a9ddc2c1..328028d0 100644
--- a/frontend/src/styles/pages/_server-packages.scss
+++ b/frontend/src/styles/pages/_server-packages.scss
@@ -120,6 +120,114 @@
}
}
+// System Status card on Overview — surfaces what the agent has detected
+// (capabilities, runtimes, sudo mode, allowed paths). Designed to feel
+// like the existing info-card but with chip rows for the multi-value
+// fields.
+.system-status-card {
+ grid-column: span 2;
+
+ &__header {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: 0.75rem;
+ margin-bottom: 0.75rem;
+
+ h3 {
+ margin: 0;
+ }
+ }
+
+ &__header-meta {
+ display: flex;
+ align-items: center;
+ gap: 0.5rem;
+ font-size: 0.85rem;
+ color: var(--muted-foreground);
+ }
+
+ &__probed-at {
+ font-size: 0.8rem;
+ }
+
+ &__rows {
+ display: flex;
+ flex-direction: column;
+ gap: 0.65rem;
+ }
+
+ &__row {
+ display: grid;
+ grid-template-columns: 160px 1fr;
+ gap: 0.75rem;
+ align-items: flex-start;
+ }
+
+ &__row-label {
+ font-size: 0.85rem;
+ color: var(--muted-foreground);
+ text-transform: uppercase;
+ letter-spacing: 0.04em;
+ }
+
+ &__row-value {
+ font-size: 0.9rem;
+ }
+
+ &__chips {
+ display: flex;
+ gap: 0.35rem;
+ flex-wrap: wrap;
+ }
+
+ &__paths {
+ list-style: none;
+ margin: 0;
+ padding: 0;
+ display: flex;
+ flex-direction: column;
+ gap: 0.2rem;
+ }
+}
+
+// Docker tab error banner + capability-empty state
+.docker-tab__error {
+ display: flex;
+ align-items: center;
+ gap: 0.75rem;
+ padding: 0.65rem 0.85rem;
+ margin-bottom: 0.75rem;
+ border: 1px solid var(--destructive, #ef4444);
+ border-radius: 0.5rem;
+ background: color-mix(in srgb, var(--destructive, #ef4444) 8%, transparent);
+ font-size: 0.9rem;
+}
+
+.docker-empty-state {
+ padding: 1.5rem;
+ border: 1px dashed var(--border);
+ border-radius: 0.5rem;
+ background: var(--muted);
+
+ h4 {
+ margin: 0 0 0.5rem;
+ }
+
+ ul {
+ margin: 0.5rem 0;
+ padding-left: 1.25rem;
+ }
+
+ code {
+ font-family: var(--font-mono, monospace);
+ font-size: 0.85rem;
+ padding: 0.05rem 0.3rem;
+ border-radius: 0.25rem;
+ background: var(--card);
+ }
+}
+
// Shared by JobProgressModal — kept here because Packages is its primary
// consumer. Services tab logs use a different component path.
.job-progress-modal {