Extensibility & Intelligence

Built to be extended

Write plugins with a typed SDK, distribute them through a signed marketplace, and bring AI into your operations (beta) with multi-provider LLM support and a governance model that keeps credentials and PII from leaving your environment.

Get started in 30 seconds

Install the SDK

$ pip install freesdn-sdk

Scaffold a plugin

$ freesdn-sdk init my-plugin
Extensibility

Plugin System & SDK

Native modules run with full trust and ship under AGPL-3.0, which means adding one takes a pull request to the core. SDK plugins do not: they install at runtime as signed ZIPs, run under permissions they declare, and the SDK is MIT, so a plugin is how you extend FreeSDN without opening your own code, and without asking anyone. Install the kit with pip install freesdn-sdk.

Trusted-Author Model

The plugin loader applies load-time import hygiene and permission checks. It is not a security sandbox in the OS/container sense. Plugins are cooperative: they are expected to be authored by trusted parties (super_admin installs only). SDK interfaces, SSRF-locked HTTP, and permission gates provide the safety guardrails.

Full SDK Interfaces

Typed interfaces for devices, sites, alerts, metrics, events, settings, and HTTP. Your plugin gets a PluginContext with DeviceSDK, SiteSDK, AlertSDK, MetricsSDK, EventSDK, PluginSettingsSDK, and an SSRF-protected HTTP client (blocks internal IPs, private ranges, cloud metadata endpoints). Each entry point gets its own database session, so a scheduled run and a route call cannot collide.

Manifest Validation

Every plugin declares a plugin.yaml manifest with ID, version, permissions, dependencies, event subscriptions, and settings schema. Validated at install time and at development time via the SDK CLI.

Event-Driven Architecture

Subscribe to any event pattern (device.status.changed, alert.fired, device.adopted) with priority routing. Plugins can emit their own events. Full correlation and causation ID tracing across the event chain.

Runs On A Timer

Declare schedules in plugin.yaml and the platform runs them per organization, unattended. At-most-once across every worker via Redis slot claims, spread so twelve tenants do not all sweep at the same instant, and no catch-up storm after downtime. Supervised like everything else, and an operator can see the last run and switch any schedule off.

Ed25519-Signed Marketplace

Package plugins as versioned ZIPs. Catalog entries are Ed25519-signed by the publisher; unsigned packages are refused by default and SHA-256 is verified at install. A plugin the registry withdraws stops being installable everywhere, without touching the copies already running. Per-organization enablement, super_admin install only. The public catalog is live at registry.freesdn.org.

Updates Without A Restart

Install or update a plugin from the UI and it is live on the next request. Method bodies reload in place, so the rest of the appliance keeps running: no dropped websockets, no in-flight requests lost, no other plugin restarted. The one case that genuinely needs a restart is a version that changed its own HTTP endpoints, and the install response says so instead of leaving you to find out.

Broken And Blocked Are Different

Supervision quarantines a plugin that keeps failing. A plugin whose remote is simply down says so instead, and is retried with a gentler backoff rather than punished for somebody else's outage. Settings are checked when you save them, not six hours later by a schedule failing quietly into a log, and one shared fetch serves every route, schedule and event handler that needs the same data.

Developer CLI

freesdn-sdk init, validate, package, and check commands. Scaffold a plugin in seconds, validate your manifest, build a distributable ZIP, and check for import hygiene issues before deploying.

Write a plugin in minutes

Subclass FreeSDNPlugin, implement lifecycle hooks, and use the typed SDK context to interact with devices, alerts, events, and settings. Permissions you declare in the manifest are the ceiling for what the platform will allow.

SDK Interfaces
DeviceSDK

Read the inventory, page through it, and propose device changes

list, get, iter_all, get_ports, register_device, stage_change

SiteSDK

Read sites, subject to the caller's own site grants

list, get, iter_all

AlertSDK

Raise and resolve alerts, delivered through the operator's own channels

list, create, resolve

MetricsSDK

Read time-series: status history, availability trends

query, series, latest, metric_names, available

EventSDK

Publish and subscribe to domain events

emit, subscribe

PluginSettingsSDK

Per-plugin configuration and encrypted secrets

get, set, get_secret, set_secret

PluginHTTPClient

SSRF-protected HTTP client with timeout limits

get, post, put, delete

PluginCoordinator

One shared fetch for every caller, with backoff and last-known-good data

async_get, async_refresh, snapshot

plugin.py
from freesdn import FreeSDNPlugin, PluginContext
class OfflineMonitor(FreeSDNPlugin):
"""Alert when devices go offline."""
async def on_start(self, org_id, db=None):
await super().on_start(org_id, db)
self.ctx.events.subscribe(
"device.status.changed"
)
async def on_event(self, event):
if event.payload.get("status") == "offline":
await self.ctx.alerts.create(
title=f"{event.payload['name']} went offline",
severity="critical",
)
terminal
$ pip install freesdn-sdk
$ freesdn-sdk init offline-monitor
$ freesdn-sdk validate .
# Manifest valid. 0 warnings.
$ freesdn-sdk check .
# Import hygiene OK. 0 warnings.
$ freesdn-sdk package .
# Created offline-monitor-1.0.0.zip (2.1 KB)

Runtime Limits

Hard limits enforced by the FreeSDN runtime to prevent resource abuse.

10

Schedules per plugin

60s - 24h

Schedule interval

50

Triggers per plugin

50

Actions per plugin

20

AI tools per plugin

50

Python dependencies

50 MB

Max ZIP size

60s

HTTP timeout

Fabric: universal app-interconnect

The Fabric layer (GET /api/v1/fabric/catalog) publishes a single tier-tagged catalog of operations, events, and AI-tool projections from both native modules and SDK plugins. Operators author Connections (event → step chain) that wire any app to any other without custom code. Three built-in sinks (notify / log / webhook), inbound org-key ingestion, outbound webhook, and a community n8n node (n8n-nodes-freesdn). Writes always ride the staged dual-gate.

The Catalog

Twelve plugins, already written

Install any of these from inside FreeSDN in one click. The catalog is signed, every download is checksum-verified, and when a newer version is published your plugins page tells you so and updates them in place.

NetBox Sync

Integration

Pushes the device inventory into NetBox as devices and sites, so the switch you adopted this morning is in your source of truth by lunchtime. Runs dry by default, so you can see exactly what would change first.

Zabbix Sync

Integration

Creates Zabbix hosts for the devices FreeSDN finds, so a new switch is monitored without being typed into a second system. Dry by default and never deletes.

LibreNMS Sync

Integration

The same idea for LibreNMS. Adds what FreeSDN already knows about, so a new device does not have to be entered twice.

Snipe-IT Sync

Integration

Creates asset records for hardware found on the network, so warranty, cost and ownership are tracked from the day a device appears rather than whenever somebody remembers.

Home Assistant Bridge

Integration

Publishes network state into Home Assistant as sensors, so the automations you already have can react to the network. Estate totals, availability and per-site health.

Jira Tickets

Ticketing

Opens a Jira issue when an alert fires and closes it when the alert clears. One issue per alert, not one per firing, so a flapping rule does not fill your queue overnight.

ServiceNow Incidents

Ticketing

The same for ServiceNow, with an explicit severity-to-urgency mapping rather than a guess: ServiceNow derives priority from a matrix every instance tunes.

PagerDuty Incidents

On-call

Pages on-call when an alert fires and resolves the incident when it clears. Deduplicated by PagerDuty itself, and it defaults to critical-only, because this one wakes people up.

Config Drift Guard

Compliance

Compares your sites against a declared baseline and reports what has drifted: sites missing a kind of device, settings that no longer match, configuration that moved without a ticket.

New Device Watch

Security

Raises an alert when a device appears that is not on your allowlist. Matches by MAC, by OUI vendor prefix, or by device type.

Port Hygiene

Monitoring

Finds the switch-port problems nothing else looks for: ports enabled with no link for weeks, links that negotiated half duplex, error counters climbing quietly.

Hello World

Utility

The worked example. Lists offline devices, raises an alert, emits an event, stores settings and exposes a REST route, in one readable file. Start here when writing your own.

Browse the registry

Or run your own: point an instance at any catalog URL and pin its publisher key.

AI-Powered Operations

LLM Integration & Governance BETA

Bring AI into your network operations with built-in governance. Three cloud and self-hosted providers, 11 platform tools, an agentic loop, and a 3-layer governance model that keeps credentials and PII from reaching the cloud. AI is off by default and must be explicitly enabled.

Supported Providers

ProviderModelsStatus
OpenAIGPT-4o, GPT-4o-mini, and othersReady
AnthropicClaude Sonnet, Haiku, and othersReady
OllamaLlama 3, Mistral, Qwen (self-hosted)Ready

Global Kill-Switch (default OFF)

AI is disabled by default at the platform level. Administrators must explicitly enable it. No AI calls leave the platform until a super_admin opts in, preventing accidental cloud exposure.

Per-Org Policy

Each organization has its own AI policy: DISABLED, LOCAL_ONLY (Ollama only, no cloud), or CLOUD_APPROVED. Orgs cannot exceed the platform-level policy ceiling.

PII Redaction Before Cloud

Sensitive values are stripped from context before any prompt reaches a cloud provider. Device credentials, secrets, and personal data are redacted so they never leave your environment in plain text.

11 Built-in Tools & Agentic Loop

The assistant ships 11 platform tools (device queries, alert management, config review, diagnostics, and more). An agentic loop (up to 5 iterations) lets the model chain tool calls to complete multi-step tasks. Plugins can register up to 20 additional AI tools each.

Built-in Use Cases

Network Diagnostics

Ask AI to analyze device health, explain port errors, and suggest fixes based on real-time telemetry data.

Alert Triage

AI summarizes alert clusters, identifies root causes, and recommends remediation steps across device types.

Configuration Review

Submit config changes for AI review before deployment. Catch VLAN mismatches, routing loops, and security gaps.

Natural Language Queries

Ask questions in plain English: 'Which switches have high CPU?' or 'Show me all offline cameras at Site 3'.

Plugin Security

Cooperative trusted-author model

The plugin loader applies load-time import hygiene and permission checks. It isnot an OS-level or container-level security sandbox. Plugins are expected to be authored by trusted parties; super_admin installation is required. Guardrails include: SDK-only interfaces, SSRF-locked HTTP, a confused-deputy permission check (plugin runs with plugin∩caller permissions), hash-pinned dependencies, and an Ed25519-signed marketplace catalog that refuses unsigned packages by default.

SDK

Typed Interfaces Only

Plugins access devices, alerts, events, and settings exclusively through typed SDK interfaces

SSRF

Protected HTTP

HTTP client blocks internal IPs, private ranges, and cloud metadata endpoints

Ed25519

Signed Catalog

Marketplace catalog is publisher-signed; unsigned packages refused by default

∩

Confused-Deputy Guard

Plugin executes with the intersection of plugin permissions and calling-user permissions

Open Source

Free as in freedom

FreeSDN is fully open-source under the AGPLv3 (AGPL-3.0-only) license. No artificial limitations, no "community edition" crippling, no surprise licensing changes.

AGPL-3.0 Licensed

No vendor lock-in, no per-device fees, no phone-home telemetry. Fork it, extend it, build services on top of it. The source is yours.

No Per-Device Fees

Monitor a small lab or a large fleet. FreeSDN charges nothing per device. Compare that to commercial per-device licensing.

Self-Hosted

By default, your credentials and data stay on your own infrastructure. No cloud dependency, no SaaS outage risk, fully air-gappable.

Community-Driven

Built by network engineers for network engineers. Feature requests, bug reports, and pull requests are all welcome.

Ready to take control of your network?

Join the community managing their multi-vendor infrastructure with a single, open-source platform.

See it running in your browser

Explore the full FreeSDN dashboard with realistic sample data, no signup, no backend. Then install it in minutes.