README
¶
Flowbot
Homelab Data Hub & Capability Orchestration Center
Flowbot discovers self-hosted apps, abstracts their capabilities, exposes unified interfaces, and orchestrates cross-service automation via declarative Pipelines and Workflows.
What Flowbot Solves
In a typical homelab, dozens of self-hosted apps run under /home/<user>/homelab/apps/. Each has its own API, auth model, pagination convention, and data format. Flowbot answers a single question:
How do I make all these apps work together?
| Problem | Flowbot Solution |
|---|---|
| App discovery & lifecycle | Homelab Scanner scans docker-compose.yaml, registers apps |
| Capability abstraction | Ability Layer maps apps to unified capabilities (bookmark, archive, reader, ...) |
| Unified interfaces | REST, CLI, Chat, Form, Webhook, Cron, Workflow |
| Cross-service data flow | Declarative Pipeline — event-driven, idempotent, auditable |
| Composable automation | Workflow Capability Step — DAG of capability invocations |
| Auth boundary | AuthContext spans REST / CLI / Chat / Webhook / Cron / Pipeline / Workflow |
| Audit trail | Durable events, execution history, audit logs — traceable, recoverable, replayable |
| Provider differences | Standard errors (ErrNotFound, ErrForbidden, ErrProvider) + unified pagination (limit + opaque cursor) |
Flowbot is not a chatbot. It uses chat as one of many interaction surfaces. At its core, it is a data hub and orchestration engine for your homelab.
Architecture
/home/<user>/homelab/apps
| Module (16 interaction surfaces)
| scan apps/*/docker-compose.yaml |
v v
+-------------------+ +---------------------+
| Homelab Registry | bind app → | Capability Registry |
| archivebox,atuin, | capability | bookmark, archive, |
| beszel,karakeep...| ---------------> | reader, kanban, |
+-------------------+ | infra, shellhistory |
| +---------+-----------+
| register apps |
v ability.Invoke()
+-------------------+ |
| Hub | v
| /hub/apps | +--------------------+
| /hub/capabilities | | Ability Layer |
| /hub/health | | bookmark.Service |
+-------------------+ | archive.Service |
| reader.Service |
| kanban.Service |
| infra.Service |
+---------+----------+
| adapter
v
+-----------------------+
| Provider Layer |
| karakeep, archivebox,|
| miniflux, kanboard, |
| fireflyiii, beszel, |
| atuin, ... |
+-----------------------+
See architecture diagrams for full PlantUML component, layer, dataflow, and deployment diagrams.
Capabilities
| Capability | Apps Mapped | Interfaces |
|---|---|---|
| bookmark | karakeep, linkwarden | REST, CLI, Chat, Workflow |
| archive | archivebox | REST, CLI, Chat, Workflow |
| reader | miniflux | REST, CLI, Chat, Webhook, Cron |
| kanban | kanboard | REST, CLI, Chat, Webhook |
| finance | fireflyiii | REST, CLI, Chat, Webhook |
| infra | beszel, uptime-kuma, adguard | REST, CLI |
| shell_history | atuin | REST, CLI |
All capabilities share the same invocation pattern:
result, err := ability.Invoke(ctx, "bookmark", ability.OpList, ability.Params{Limit: 20})
Standard errors, unified pagination, provider-agnostic.
Pipeline & Workflow
Declarative Pipeline
Cross-service data flows defined in YAML, triggered by durable events:
# When a new bookmark is saved, archive it and notify
trigger:
event: "bookmark.created"
steps:
- action: archive.submit
input: $.event.url
- action: notify.send
input:
channel: slack
message: "Archived: $.event.url"
Every pipeline run is persisted, idempotent, and audited.
Workflow Capability Step
Composable automation DAG where each step invokes a capability:
[cron trigger] → [reader.fetch] → [llm.summarize] → [notify.send]
Built-in step types: Capability, Message, Fetch, Feed, LLM, Docker, Grep, Unique, Torrent.
Quick Start
Requirements
- Go 1.26+
- PostgreSQL + Redis
- Task runner
- Docker
Install
git clone https://github.com/flowline-io/flowbot.git
cd flowbot
cp docs/reference/config.yaml flowbot.yaml
# Edit flowbot.yaml
task build
./bin/flowbot
Docker
docker build -f deployments/Dockerfile -t flowbot .
docker run -p 6060:6060 -v $(pwd)/flowbot.yaml:/opt/app/flowbot.yaml flowbot
CLI
Install the flowbot CLI from GitHub releases:
curl -fsSL https://raw.githubusercontent.com/flowline-io/flowbot/master/scripts/install.sh | bash
Or install a specific version:
curl -fsSL https://raw.githubusercontent.com/flowline-io/flowbot/master/scripts/install.sh | bash -s -- --version v0.40
The CLI is installed to /usr/local/bin/flowbot. Run flowbot --help to see available commands.
Module Surface
16 modules serve as interaction entry points. Each can expose commands, forms, webhooks, cron jobs, web services, or workflow triggers.
| Module | Surface |
|---|---|
| workflow | DAG execution, job scheduling |
| hub | App lifecycle management |
| notify | Multi-channel dispatch (Slack, Pushover, ntfy, Message Pusher) |
| server | System operations |
| webhook | Inbound/outbound hooks |
Development
task default # tidy → swagger → format → lint → test
task build # Main server
task test # Unit tests
task lint # revive + actionlint
task air # Live reload
Code Generation
task swagger # Generate Swagger/OpenAPI docs
task doc # Generate database schema docs
task ent # Generate ent code from database
API
| Endpoint | Description |
|---|---|
/service/{capability}/* |
Capability plane |
/hub/* |
Management plane |
/swagger/ |
OpenAPI docs |
/livez /readyz /startupz |
Health probes |
/metrics |
Prometheus |
Auth: X-AccessToken header or OAuth 2.0.
Configuration
listen: ":6060"
store_config:
use_adapter: mysql
adapters:
mysql:
dsn: "root:password@tcp(localhost)/flowbot?parseTime=True"
redis:
addr: "localhost:6379"
platform:
slack:
enabled: true
bot_token: "xoxb-..."
discord:
enabled: true
bot_token: "..."
Documentation
License
Documentation
¶
Overview ¶
Package webassets embeds the public/ static assets directory so that the web module can serve CSS, JS, and other frontend files from the compiled binary without depending on the process working directory.
Index ¶
Constants ¶
This section is empty.
Variables ¶
View Source
var FS embed.FS
FS is the embedded filesystem rooted at the public/ directory. Use it with fiber's static middleware Config.FS field.
View Source
var SubFS fs.FS
SubFS is the embedded filesystem with the "public" prefix stripped, suitable for use with fiber's static middleware Config.FS field.
Functions ¶
This section is empty.
Types ¶
This section is empty.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package main is the entry point for the Flowbot server binary.
|
Package main is the entry point for the Flowbot server binary. |
|
cli
command
Package main is the entry point for the Flowbot CLI binary.
|
Package main is the entry point for the Flowbot CLI binary. |
|
cli/command
Package command implements CLI command definitions.
|
Package command implements CLI command definitions. |
|
cli/store
Package store provides local file storage for CLI data
|
Package store provides local file storage for CLI data |
|
cli/utils
Package utils provides shared CLI utility functions.
|
Package utils provides shared CLI utility functions. |
|
composer
command
Package main is the entry point for the Flowbot composer CLI binary.
|
Package main is the entry point for the Flowbot composer CLI binary. |
|
composer/action/admin
Package admin provides management commands for Flowbot administration.
|
Package admin provides management commands for Flowbot administration. |
|
composer/action/doc
Package doc provides action documentation schema generation.
|
Package doc provides action documentation schema generation. |
|
composer/action/skills
Package skills generates SKILL.md files for CLI-invokable capabilities.
|
Package skills generates SKILL.md files for CLI-invokable capabilities. |
|
composer/action/webdoc
Package webdoc generates the Flowbot documentation website from markdown sources.
|
Package webdoc generates the Flowbot documentation website from markdown sources. |
|
docs
|
|
|
api
Package api Code generated by swaggo/swag.
|
Package api Code generated by swaggo/swag. |
|
internal
|
|
|
modules
Package modules provides fx dependency injection registration for all modules.
|
Package modules provides fx dependency injection registration for all modules. |
|
modules/example
Package example implements the example module demonstrating all module entry points.
|
Package example implements the example module demonstrating all module entry points. |
|
modules/hub
Package hub implements the hub management module providing chat commands for health checks, app management, and resource tag query endpoints.
|
Package hub implements the hub management module providing chat commands for health checks, app management, and resource tag query endpoints. |
|
modules/web
Package web provides a web UI module with server-rendered HTML pages.
|
Package web provides a web UI module with server-rendered HTML pages. |
|
platforms
Package platforms provides multi-platform integration for chat and messaging.
|
Package platforms provides multi-platform integration for chat and messaging. |
|
platforms/discord
Package discord implements the Discord platform integration.
|
Package discord implements the Discord platform integration. |
|
platforms/slack
Package slack implements the Slack platform integration.
|
Package slack implements the Slack platform integration. |
|
platforms/tailchat
Package tailchat implements the Tailchat platform integration.
|
Package tailchat implements the Tailchat platform integration. |
|
server
Package server provides the HTTP API server (Fiber v3) and route handlers.
|
Package server provides the HTTP API server (Fiber v3) and route handlers. |
|
store
Package store provides database storage implementations.
|
Package store provides database storage implementations. |
|
store/ent
Package ent provides the Ent ORM client initialization and database connectivity.
|
Package ent provides the Ent ORM client initialization and database connectivity. |
|
store/ent/schema
Package schema provides Ent ORM schema definitions.
|
Package schema provides Ent ORM schema definitions. |
|
store/postgres
Package postgres implements the PostgreSQL storage adapter.
|
Package postgres implements the PostgreSQL storage adapter. |
|
pkg
|
|
|
ability
Package ability provides the capability invocation framework.
|
Package ability provides the capability invocation framework. |
|
ability/bookmark
Package bookmark implements the bookmark management capability.
|
Package bookmark implements the bookmark management capability. |
|
ability/bookmark/karakeep
Package karakeep implements the Karakeep adapter for the bookmark capability.
|
Package karakeep implements the Karakeep adapter for the bookmark capability. |
|
ability/conformance
Package conformance provides a standard test suite for ability adapters.
|
Package conformance provides a standard test suite for ability adapters. |
|
ability/example
Package example implements the example capability for demonstration.
|
Package example implements the example capability for demonstration. |
|
ability/example/example
Package example implements the example provider adapter for the example capability.
|
Package example implements the example provider adapter for the example capability. |
|
ability/forge
Package forge implements the software forge capability.
|
Package forge implements the software forge capability. |
|
ability/forge/gitea
Package gitea implements the Gitea adapter for the forge capability.
|
Package gitea implements the Gitea adapter for the forge capability. |
|
ability/github
Package github implements the GitHub capability.
|
Package github implements the GitHub capability. |
|
ability/github/github
Package github implements the GitHub adapter for the github capability.
|
Package github implements the GitHub adapter for the github capability. |
|
ability/kanban
Package kanban implements the Kanban board capability.
|
Package kanban implements the Kanban board capability. |
|
ability/kanban/kanboard
Package kanboard implements the Kanboard adapter for the kanban capability.
|
Package kanboard implements the Kanboard adapter for the kanban capability. |
|
ability/memo
Package memo implements the memo capability for short-form note-taking systems.
|
Package memo implements the memo capability for short-form note-taking systems. |
|
ability/memo/memos
Package memos implements the Memos adapter for the memo capability.
|
Package memos implements the Memos adapter for the memo capability. |
|
ability/note
Package note implements the note capability for note-taking systems.
|
Package note implements the note capability for note-taking systems. |
|
ability/note/trilium
Package trilium implements the Trilium adapter for the note capability.
|
Package trilium implements the Trilium adapter for the note capability. |
|
ability/notify
Package notify provides the notification capability for the ability framework.
|
Package notify provides the notification capability for the ability framework. |
|
ability/reader
Package reader implements the RSS/feed reading capability.
|
Package reader implements the RSS/feed reading capability. |
|
ability/reader/miniflux
Package miniflux implements the Miniflux adapter for the reader capability.
|
Package miniflux implements the Miniflux adapter for the reader capability. |
|
backoff
Package backoff provides a unified retry strategy with configurable backoff, jitter, adaptive behavior, and error filtering.
|
Package backoff provides a unified retry strategy with configurable backoff, jitter, adaptive behavior, and error filtering. |
|
bulkhead
Package bulkhead provides per-capability semaphore isolation for ability invocations.
|
Package bulkhead provides per-capability semaphore isolation for ability invocations. |
|
cache
Package cache provides caching abstractions and implementations.
|
Package cache provides caching abstractions and implementations. |
|
client
Package client provides a Go client SDK for the Flowbot server's web service API.
|
Package client provides a Go client SDK for the Flowbot server's web service API. |
|
config
Package config provides runtime configuration loading and management.
|
Package config provides runtime configuration loading and management. |
|
event
Package event provides event system definition and data event types.
|
Package event provides event system definition and data event types. |
|
executor
Package executor provides the pipeline execution engine.
|
Package executor provides the pipeline execution engine. |
|
executor/runtime
Package runtime implements pipeline task execution runtimes.
|
Package runtime implements pipeline task execution runtimes. |
|
executor/runtime/capability
Package capability implements capability-based execution runtime.
|
Package capability implements capability-based execution runtime. |
|
executor/runtime/docker
Package docker implements the Docker execution runtime.
|
Package docker implements the Docker execution runtime. |
|
executor/runtime/machine
Package machine implements the machine execution runtime.
|
Package machine implements the machine execution runtime. |
|
executor/runtime/shell
Package shell implements the shell command execution runtime.
|
Package shell implements the shell command execution runtime. |
|
flog
Package flog provides structured logging for Flowbot.
|
Package flog provides structured logging for Flowbot. |
|
homelab
Package homelab provides homelab application scanning and registry.
|
Package homelab provides homelab application scanning and registry. |
|
homelab/probe
Package probe provides homelab service discovery and authentication detection.
|
Package probe provides homelab service discovery and authentication detection. |
|
hub
Package hub provides hub lifecycle management and automatic binding.
|
Package hub provides hub lifecycle management and automatic binding. |
|
llm
Package llm provides LLM agent integration and invocation.
|
Package llm provides LLM agent integration and invocation. |
|
media
Package media defines an interface which must be implemented by media upload/download handlers.
|
Package media defines an interface which must be implemented by media upload/download handlers. |
|
media/fs
Package fs implements github.com/flowline-io/flowbot/media interface by storing media objects in a single directory in the file system.
|
Package fs implements github.com/flowline-io/flowbot/media interface by storing media objects in a single directory in the file system. |
|
media/minio
Package minio implements media interface by storing media objects in Minio bucket.
|
Package minio implements media interface by storing media objects in Minio bucket. |
|
metrics
Package metrics provides Prometheus metrics collection for abilities.
|
Package metrics provides Prometheus metrics collection for abilities. |
|
module
Package module provides the module handler interface and base types.
|
Package module provides the module handler interface and base types. |
|
notify
Package notify provides the notification dispatcher interface and registry.
|
Package notify provides the notification dispatcher interface and registry. |
|
notify/messagepusher
Package messagepusher implements the Message Pusher notification provider.
|
Package messagepusher implements the Message Pusher notification provider. |
|
notify/ntfy
Package ntfy implements the ntfy notification provider.
|
Package ntfy implements the ntfy notification provider. |
|
notify/pushover
Package pushover implements Pushover notification provider.
|
Package pushover implements Pushover notification provider. |
|
notify/rules
Package rules provides the notification rule engine for throttling, aggregation, and mute/DND.
|
Package rules provides the notification rule engine for throttling, aggregation, and mute/DND. |
|
notify/slack
Package slack implements the Slack notification provider.
|
Package slack implements the Slack notification provider. |
|
notify/template
Package template provides notification template rendering using Go text/template with Sprig function library support.
|
Package template provides notification template rendering using Go text/template with Sprig function library support. |
|
parser
Package parser provides command and expression parsing.
|
Package parser provides command and expression parsing. |
|
pipeline
Package pipeline provides the event-driven pipeline execution engine.
|
Package pipeline provides the event-driven pipeline execution engine. |
|
pipeline/template
Package template provides pipeline template rendering engine.
|
Package template provides pipeline template rendering engine. |
|
plugin
Package plugin provides the plugin runner framework for extending flowbot via external binaries communicating over gRPC.
|
Package plugin provides the plugin runner framework for extending flowbot via external binaries communicating over gRPC. |
|
plugin/adapter
Package adapter provides bridge types that adapt plugin.Runner calls to flowbot's module, ability, and provider registries.
|
Package adapter provides bridge types that adapt plugin.Runner calls to flowbot's module, ability, and provider registries. |
|
plugin/grpc
Package grpc provides the gRPC-based plugin runtime implementation.
|
Package grpc provides the gRPC-based plugin runtime implementation. |
|
plugin/manager
Package manager provides the PluginManager that orchestrates plugin discovery, loading, lifecycle, and hot-reload.
|
Package manager provides the PluginManager that orchestrates plugin discovery, loading, lifecycle, and hot-reload. |
|
plugin/sdk
Package sdk provides the plugin SDK for building flowbot module plugins.
|
Package sdk provides the plugin SDK for building flowbot module plugins. |
|
plugin/source
Package source provides plugin discovery from local filesystem directories.
|
Package source provides plugin discovery from local filesystem directories. |
|
plugin/types
Package types provides shared plugin types with zero internal dependencies to avoid import cycles.
|
Package types provides shared plugin types with zero internal dependencies to avoid import cycles. |
|
plugin/wasm
Package wasm provides the WebAssembly-based plugin runner.
|
Package wasm provides the WebAssembly-based plugin runner. |
|
profiling
Package profiling provides runtime profiling and performance monitoring.
|
Package profiling provides runtime profiling and performance monitoring. |
|
providers
Package providers provides provider registry and common provider interfaces.
|
Package providers provides provider registry and common provider interfaces. |
|
providers/adguard
Package adguard implements the AdGuard Home provider.
|
Package adguard implements the AdGuard Home provider. |
|
providers/archivebox
Package archivebox implements the ArchiveBox provider.
|
Package archivebox implements the ArchiveBox provider. |
|
providers/drone
Package drone implements the Drone CI provider.
|
Package drone implements the Drone CI provider. |
|
providers/dropbox
Package dropbox implements the Dropbox provider.
|
Package dropbox implements the Dropbox provider. |
|
providers/email
Package email implements the email provider.
|
Package email implements the email provider. |
|
providers/example
Package example implements the example provider using jsonplaceholder.typicode.com for demonstration.
|
Package example implements the example provider using jsonplaceholder.typicode.com for demonstration. |
|
providers/fireflyiii
Package fireflyiii implements the Firefly III finance provider.
|
Package fireflyiii implements the Firefly III finance provider. |
|
providers/gitea
Package gitea implements the Gitea provider.
|
Package gitea implements the Gitea provider. |
|
providers/github
Package github implements the GitHub API provider.
|
Package github implements the GitHub API provider. |
|
providers/kanboard
Package kanboard implements the Kanboard project management provider.
|
Package kanboard implements the Kanboard project management provider. |
|
providers/karakeep
Package karakeep implements the Karakeep bookmark provider.
|
Package karakeep implements the Karakeep bookmark provider. |
|
providers/memos
Package memos implements the Memos provider for note-taking and knowledge management.
|
Package memos implements the Memos provider for note-taking and knowledge management. |
|
providers/miniflux
Package miniflux implements the Miniflux RSS reader provider.
|
Package miniflux implements the Miniflux RSS reader provider. |
|
providers/n8n
Package n8n implements the n8n workflow automation provider.
|
Package n8n implements the n8n workflow automation provider. |
|
providers/slack
Package slack implements the Slack API provider.
|
Package slack implements the Slack API provider. |
|
providers/slash
Package slash implements the Slash provider.
|
Package slash implements the Slash provider. |
|
providers/transmission
Package transmission implements the Transmission BitTorrent provider.
|
Package transmission implements the Transmission BitTorrent provider. |
|
providers/trilium
Package trilium implements the Trilium Notes ETAPI provider.
|
Package trilium implements the Trilium Notes ETAPI provider. |
|
providers/uptimekuma
Package uptimekuma implements the Uptime Kuma monitoring provider.
|
Package uptimekuma implements the Uptime Kuma monitoring provider. |
|
rdb
Package rdb provides a singleton Redis client with connection pool configuration.
|
Package rdb provides a singleton Redis client with connection pool configuration. |
|
route
Package route provides HTTP route registration and discovery.
|
Package route provides HTTP route registration and discovery. |
|
stats
Package stats provides runtime statistics and metrics collection.
|
Package stats provides runtime statistics and metrics collection. |
|
trace
Package trace provides OpenTelemetry tracing integration for Fiber.
|
Package trace provides OpenTelemetry tracing integration for Fiber. |
|
types
Package types provides core type definitions, interfaces, and value objects.
|
Package types provides core type definitions, interfaces, and value objects. |
|
types/audit
Package audit provides the Auditor interface and supporting types for audit logging.
|
Package audit provides the Auditor interface and supporting types for audit logging. |
|
types/model
Package model provides shared data types for UI views and transport.
|
Package model provides shared data types for UI views and transport. |
|
types/protocol
Package protocol provides platform-agnostic protocol types for request/response handling.
|
Package protocol provides platform-agnostic protocol types for request/response handling. |
|
types/ruleset/command
Package command implements the command ruleset type.
|
Package command implements the command ruleset type. |
|
types/ruleset/form
Package form implements the form ruleset type.
|
Package form implements the form ruleset type. |
|
types/ruleset/webservice
Package webservice implements the web service ruleset type.
|
Package webservice implements the web service ruleset type. |
|
utils
Package utils provides shared utility functions.
|
Package utils provides shared utility functions. |
|
utils/reexec
Package reexec facilitates the busybox style reexec of the docker binary that we require because of the forking limitations of using Go.
|
Package reexec facilitates the busybox style reexec of the docker binary that we require because of the forking limitations of using Go. |
|
utils/sets
Package sets provides generic set data structures.
|
Package sets provides generic set data structures. |
|
utils/syncx
Package syncx provides synchronized concurrent-safe data structures.
|
Package syncx provides synchronized concurrent-safe data structures. |
|
validate
Package validate provides shared validation rules and helpers for the application.
|
Package validate provides shared validation rules and helpers for the application. |
|
views/pages
templ: version: v0.3.1020
|
templ: version: v0.3.1020 |
|
views/partials
templ: version: v0.3.1020
|
templ: version: v0.3.1020 |
|
workflow
Package workflow provides the workflow definition loader and runtime.
|
Package workflow provides the workflow definition loader and runtime. |
|
Package version provides build-time version and buildstamp information.
|
Package version provides build-time version and buildstamp information. |
Click to show internal directories.
Click to hide internal directories.