How d-buckner/bloud works
Bloud is a self-hosted home-server manager: a user installs apps through its dashboard, while a reconciliation engine resolves dependencies, starts containers, configures integrations and proxy routes, and verifies apps through their APIs. Its major product branches include catalog-driven app setup, unified login, media-stack wiring, dashboard settings and widgets, and sharing. The README documents the control-loop workflow; sampled Go excerpts show server construction and API-client behavior. Several subsystem paths are directory-level because their implementation files were not sampled.
Main entry points: orchestrator Reconciliation engine · api HTTP API · apps App configurators · appclient App API clients
Components 22
Dashboard
- Dashboard UI
services/host-agent/web/src - Web API clients
services/host-agent/web/src/lib/clients
Control plane
- HTTP API
services/host-agent/internal/api - App catalog
services/host-agent/internal/catalog - Reconciliation engine
services/host-agent/internal/engine/orchestrator - Dependency graph
services/host-agent/internal/engine/graph - Host-agent startup
services/host-agent/cmd/host-agent/main.go
App runtime
- App configurators
apps - Container runtime
services/host-agent/internal/container - Podman client
services/host-agent/internal/podman - App API clients
services/host-agent/pkg/appclient - AFFiNE setup
apps/affine/api.go - Configurator checks
apps/configtest/configtest.go
Integrations
- Authentik integration
services/host-agent/pkg/authentik/client.go - Proxy configuration
services/host-agent/internal/traefikgen - Sharing and tailnet
services/host-agent/internal/sharing - Media-stack wiring
apps/seerr/jellyfin.go - Authentik setup
apps/authentik/server_configurator.go - Download-client support
services/host-agent/pkg/servarr/downloadclient.go
State and operations
- Persistent state
services/host-agent/internal/store - Event streams
services/host-agent/internal/eventbus
Other components
- Home-server user
Connections 24
- Home-server user → Dashboard UI: manages apps
- Dashboard UI → Web API clients: uses clients
- Web API clients → HTTP API: sends requests
- HTTP API → Reconciliation engine: submits intents
services/host-agent/internal/api/server.go - Reconciliation engine → App catalog: resolves apps
services/host-agent/internal/engine/orchestrator/pipeline.go - Reconciliation engine → Dependency graph: orders dependencies
services/host-agent/internal/engine/orchestrator/pipeline.go - Reconciliation engine → Container runtime: reconciles containers
- Container runtime → Podman client: controls containers
- Reconciliation engine → App configurators: runs configurators
- App configurators → App API clients: verifies apps
apps/affine/api.go - Reconciliation engine → Proxy configuration: writes routes
- Reconciliation engine → Authentik integration: configures identity
- App configurators → Authentik integration: sets up identity
- Reconciliation engine → Sharing and tailnet: converges sharing
services/host-agent/internal/engine/orchestrator/pipeline.go - Reconciliation engine → Media-stack wiring: wires app stack
- Media-stack wiring → Download-client support: configures download clients
- HTTP API → Persistent state: reads and writes
services/host-agent/internal/api/server.go - Reconciliation engine → Persistent state: records state
services/host-agent/internal/engine/orchestrator/pipeline.go - HTTP API → Event streams: serves events
services/host-agent/cmd/host-agent/main.go - Host-agent startup → HTTP API: starts server
services/host-agent/cmd/host-agent/main.go - Host-agent startup → Reconciliation engine: starts loop
services/host-agent/cmd/host-agent/main.go - Authentik setup → Authentik integration: configures provider
apps/authentik/server_configurator.go - AFFiNE setup → App API clients: calls app APIs
apps/affine/api.go - Configurator checks → App API clients: uses shared client