README

Unofficial client libraries (SDKs) for the Beszel server monitoring system API.

Note: These are community-maintained wrappers, not officially affiliated with Beszel.

Projects

🐍 Python SDK (beszel-py)

Location: python/

A Python client library with both synchronous and asynchronous support for the Beszel API.

Features:

• Sync and async clients (BeszelClient / AsyncBeszelClient)
• Type-safe models with Pydantic v2
• Context manager support
• Comprehensive exception handling
• Full coverage of Systems, Metrics, Users, Alerts, System Details, Containers, Quiet Hours, and Realtime APIs

Installation:

pip install beszel-py

Quick Start:

from beszel import BeszelClient

client = BeszelClient(base_url="https://beszel.example.com")
client.auth("admin@example.com", "password")

systems = client.systems.list()
for system in systems:
    print(f"{system.name}: {system.status}")

🔷 .NET SDK (Beszel.Net)

Location: dotnet/

A modern .NET 8+ client library with typed HTTP client and dependency injection support.

Features:

• Typed HTTP client with IHttpClientFactory integration
• Native dependency injection extensions
• Async/await with CancellationToken support
• Strongly-typed models with record types
• Full OpenAPI coverage

Installation:

dotnet add package Beszel.Net

Quick Start:

services.AddBeszelClient(options =>
{
    options.BaseUrl = "https://beszel.example.com";
    options.Email = "admin@example.com";
    options.Password = "password";
});

// Inject and use
public class MonitoringService
{
    private readonly IBeszelClient _beszel;

    public MonitoringService(IBeszelClient beszel)
    {
        _beszel = beszel;
    }

    public async Task<IEnumerable<SystemRecord>> GetSystemsAsync()
    {
        return await _beszel.Systems.GetSystemsAsync();
    }
}

API Reference

Both SDKs implement the Beszel REST API, which is built on PocketBase.

Key Endpoints:

• Authentication: POST /api/collections/users/auth-with-password
• Systems (Agents): GET/POST/PATCH/DELETE /api/collections/systems/records
• System Stats: GET /api/collections/system_stats/records
• Container Stats: GET /api/collections/container_stats/records
• Users: GET /api/collections/users/records
• Alerts: GET /api/collections/alerts/records
• System Details: GET /api/collections/system_details/records
• Containers: GET /api/collections/containers/records
• Quiet Hours: GET /api/collections/quiet_hours/records
• Realtime: Server-Sent Events via /api/realtime

Development

Python

cd python
pip install -e ".[dev]"
pytest

.NET

cd dotnet
dotnet restore
dotnet build
dotnet test

CI/CD

This monorepo uses isolated GitHub Actions workflows:

• Python CI: Triggered on python/** changes and python-v* tags
• .NET CI: Triggered on dotnet/** changes and dotnet-v* tags

Contributing

Contributions are welcome! Please ensure:

• All tests pass
• Code follows project style guidelines
• New features include tests and documentation

License

MIT License - see LICENSE for details

Resources

• Beszel Official Site
• Beszel Official GitHub
• Beszel REST API Documentation
• This Wrapper Repository