Synapse Node Agent for Linux Hosts, Homelabs and Infrastructure Integrations #44

New issue

Open

opened 2026-05-24 02:30:18 +02:00 by FTMahringer · 0 comments

FTMahringer commented

2026-05-24 02:30:18 +02:00

(Migrated from github.com)

Problem / Motivation

Synapse is evolving into a backend-first orchestration platform and not only a chat/LLM application.

Many future use-cases involve interacting with:

Linux hosts
Homelab infrastructure
Proxmox nodes
Docker hosts
Kubernetes clusters
monitoring systems
storage systems
automation environments

Direct SSH/API integrations work for some tasks, but larger deployments would benefit from a lightweight local node agent similar to:

Portainer agents
Kubernetes agents
monitoring collectors
remote execution daemons

This would allow Synapse to securely communicate with remote systems through a controlled runtime instead of requiring unrestricted SSH access.

Related issues:

#43 External Worker Runtime for Non-Java Plugins
#41 Local-First & Homelab-Oriented Deployment Philosophy
#37 Integration Plugin System with Calendar/Mail/Service Providers
#35 Workflow & Automation Ideas
#38 Plugin API & Ecosystem Architecture Refactor for Long-Term Extensibility

Proposed Solution

Create a lightweight Synapse Node Agent.

The agent would run on Linux machines and register itself with a Synapse instance.

Possible installation targets:

bare-metal Linux
Docker container
LXC container
Proxmox VE nodes
Raspberry Pi systems
NAS systems
Kubernetes worker/master nodes
remote VPS systems

Possible architecture:

Synapse Core
 ├── Node Registry
 ├── Capability System
 ├── Task Scheduler
 ├── Workflow Engine
 └── Agent Gateway
      ├── Linux Node Agent
      ├── Proxmox Reader Agent
      ├── Docker Runtime Agent
      └── Future infrastructure agents

Potential Capabilities

Example capabilities:

capabilities:
  - host.metrics.read
  - filesystem.read.scoped
  - docker.read
  - proxmox.readonly
  - process.execute.limited
  - logs.read
  - network.info.read

Synapse should centrally approve and manage these capabilities.

Agents should not automatically receive unrestricted system access.

Example Use Cases

Linux Host Monitoring

CPU/RAM/Disk metrics
running services
temperatures
process information
network interfaces
storage usage

Proxmox Integration

VM/LXC status
node health
storage information
cluster information
backup status
optional read-only mode

Workflow Automation

Example:

Workflow detects low disk space
 → Node Agent confirms usage
 → Synapse creates alert
 → optional cleanup workflow starts

AI Agent Integration

Future AI agents/tools could request:

log analysis
health summaries
diagnostics
infrastructure reports
controlled maintenance tasks

Security Requirements

Agent registration approval flow
Scoped authentication tokens or certificates
Capability-based permissions
Read-only vs execution modes
Optional local-only/LAN-only mode
Audit logs for all actions
Revocable tokens
Optional mTLS
Rate limiting and task timeout controls
Optional command allowlists

Future Ideas

Web-based terminal bridge
Cluster-aware infrastructure view
Auto-discovery inside homelab VLANs
Proxmox-specific optimized integration
Docker Compose management
Kubernetes node integration
Remote file browser
Energy/power monitoring
GPU metrics and AI runtime integration
Wake-on-LAN integration
Local AI worker execution routing

Alternatives

Only use SSH directly
- simple, but difficult to govern and scale
Only use vendor APIs
- not every system exposes good APIs
Install full Synapse on every machine
- too heavy for many use-cases

Priority

High / Strategic

This could become one of the strongest differentiators for Synapse in homelab, local-first and infrastructure orchestration environments.

## Problem / Motivation Synapse is evolving into a backend-first orchestration platform and not only a chat/LLM application. Many future use-cases involve interacting with: - Linux hosts - Homelab infrastructure - Proxmox nodes - Docker hosts - Kubernetes clusters - monitoring systems - storage systems - automation environments Direct SSH/API integrations work for some tasks, but larger deployments would benefit from a lightweight local node agent similar to: - Portainer agents - Kubernetes agents - monitoring collectors - remote execution daemons This would allow Synapse to securely communicate with remote systems through a controlled runtime instead of requiring unrestricted SSH access. Related issues: - #43 External Worker Runtime for Non-Java Plugins - #41 Local-First & Homelab-Oriented Deployment Philosophy - #37 Integration Plugin System with Calendar/Mail/Service Providers - #35 Workflow & Automation Ideas - #38 Plugin API & Ecosystem Architecture Refactor for Long-Term Extensibility --- ## Proposed Solution Create a lightweight Synapse Node Agent. The agent would run on Linux machines and register itself with a Synapse instance. Possible installation targets: - bare-metal Linux - Docker container - LXC container - Proxmox VE nodes - Raspberry Pi systems - NAS systems - Kubernetes worker/master nodes - remote VPS systems Possible architecture: ```text Synapse Core ├── Node Registry ├── Capability System ├── Task Scheduler ├── Workflow Engine └── Agent Gateway ├── Linux Node Agent ├── Proxmox Reader Agent ├── Docker Runtime Agent └── Future infrastructure agents ``` --- ## Potential Capabilities Example capabilities: ```yaml capabilities: - host.metrics.read - filesystem.read.scoped - docker.read - proxmox.readonly - process.execute.limited - logs.read - network.info.read ``` Synapse should centrally approve and manage these capabilities. Agents should not automatically receive unrestricted system access. --- ## Example Use Cases ### Linux Host Monitoring - CPU/RAM/Disk metrics - running services - temperatures - process information - network interfaces - storage usage ### Proxmox Integration - VM/LXC status - node health - storage information - cluster information - backup status - optional read-only mode ### Workflow Automation Example: ```text Workflow detects low disk space → Node Agent confirms usage → Synapse creates alert → optional cleanup workflow starts ``` ### AI Agent Integration Future AI agents/tools could request: - log analysis - health summaries - diagnostics - infrastructure reports - controlled maintenance tasks --- ## Security Requirements - Agent registration approval flow - Scoped authentication tokens or certificates - Capability-based permissions - Read-only vs execution modes - Optional local-only/LAN-only mode - Audit logs for all actions - Revocable tokens - Optional mTLS - Rate limiting and task timeout controls - Optional command allowlists --- ## Future Ideas - Web-based terminal bridge - Cluster-aware infrastructure view - Auto-discovery inside homelab VLANs - Proxmox-specific optimized integration - Docker Compose management - Kubernetes node integration - Remote file browser - Energy/power monitoring - GPU metrics and AI runtime integration - Wake-on-LAN integration - Local AI worker execution routing --- ## Alternatives - Only use SSH directly - simple, but difficult to govern and scale - Only use vendor APIs - not every system exposes good APIs - Install full Synapse on every machine - too heavy for many use-cases --- ## Priority High / Strategic This could become one of the strongest differentiators for Synapse in homelab, local-first and infrastructure orchestration environments.