Cerberus

Cerberus is a self-hosted infrastructure control plane for managing one local host and many remote hosts from one dashboard.

It is designed for homelabs, small teams, and indie operators who want fast day-1 setup, strong multi-node operations, and a clean operational UI without heavy enterprise complexity.

What Cerberus Does Today

• Runs as a single Go backend + static frontend.
• Supports two runtime modes:
  • dashboard mode: full control plane and UI.
  • node mode: managed target that can be controlled by a dashboard.
• Manages:
  • local machine operations
  • remote Cerberus nodes
  • fleet-wide automation workflows

Current Feature Inventory

1) Setup, Bootstrap, and Runtime Control

• First-run setup flow (/api/setup-required, /api/setup) with guided initialization.
• Mode selection (dashboard or node) during bootstrap.
• Instance settings management:
  • bind address
  • instance name
  • dev mode
  • cluster/session secrets
• Runtime settings update endpoint with restart-needed awareness.
• Bootstrap summary and node template generation for quick node onboarding.
• Self-service install/uninstall/restart controls for Cerberus service lifecycle.

2) Authentication, Authorization, and Security

• Session-based authentication with login/logout and current user endpoint.
• Role model:
  • viewer
  • operator
  • admin
• Admin user lifecycle:
  • create users
  • update role/status
  • password reset/update
  • delete users
• Cluster token support for node/dashboard interactions.
• Terminal policy controls (allowlist/denylist) in runtime settings.
• Audit log endpoints and UI for action history.

3) Overview and Operational Dashboard

• Overview summary cards for target host/system state.
• Operations snapshot for service health visibility.
• Resource consumer visibility for quick triage.
• Live metric sampling and trend mini-cards:
  • CPU
  • Memory
  • Disk
  • Network
• Launchpad shortcuts into core workflows.

4) Services and Process Management

• Service inventory listing and filtering.
• Service actions:
  • start
  • restart
  • stop
• Process listing and filtering.
• Process stop/terminate action from UI.

5) Logs and Terminal

• Logs source discovery and log viewer with line count controls.
• Log auto-refresh mode.
• Log copy/export helpers.
• Terminal command execution:
  • streaming run
  • standard run
  • command history
• Output copy/export helpers.

6) Files and Content Operations

• Directory listing/navigation.
• File read/write editing.
• Create folder/file.
• Delete path.
• Upload file to current target/path.
• Download file from current target/path.
• Works against local and selected remote target via target routing.

7) Apps Management

• Managed app model with supported kinds:
  • systemd
  • command
  • binary
• App CRUD:
  • create
  • update
  • delete
• App lifecycle actions.
• Startup-enabled app support + apply startup operation.
• App health fields (health_port, health_path).
• Inline modal editor for app updates.

8) Tasks Automation

• Task CRUD for reusable command tasks.
• Run tasks with stdin/timeout support.
• Task cloning.
• Task output panel with diagnostics for sudo/stdin behavior.
• Task output copy/export helpers.

9) Caddy Management

• Caddyfile get/save.
• Format/validate/reload actions.
• Caddy binary status visibility.
• Caddy status copy helper.

10) Multi-Node Fleet Operations

• Node registry with rich metadata:
  • name
  • base URL
  • token
  • tags
  • group
  • environment
  • notes
  • favorite/pin
  • enabled status
• Node health and reachability operations.
• Node selection/filtering for bulk workflows.
• Bulk terminal execution across selected nodes.
• Bulk service action across selected nodes.

11) Fleet Scripts, Scheduling, Deployments, and Sync

• Fleet scripts:
  • create/list/update/delete
  • run on selected nodes
• Scheduled actions:
  • create/list/update/delete
  • run-now execution
• Deployment plans:
  • create/list/update/delete
  • run plans
  • deployment run history
• Sync profiles:
  • create/list/delete
  • run profile to push source content to selected nodes

12) Alerting and Notifications

• Alert config management with cooldown support.
• Offline node alerting channels:
  • generic webhook
  • Discord webhook
  • Telegram bot/chat
  • SMTP email
• Persistent alert channel settings stored in database.

13) UX, Navigation, and Productivity

• Sidebar section/subsection navigation model.
• Sidebar collapse behavior and mobile drawer behavior.
• Dark/light theme toggle with persistence.
• Density toggle (compact/comfortable) with persistence.
• Profile button in top command bar.
• Inline modal forms replacing prompt-based edits for key entities.
• Hover hints on major settings/actions.

Tech Stack and Architecture

Backend

• Language: Go
• Storage: SQLite (backend/cerberus.db)
• HTTP server: stdlib net/http + route wiring in backend/httpserver/server.go
• Core modules:
  • auth, audit, bootstrap, nodes, services, processes, tasks, terminal, files, apps, caddy, logs, serviceinstall

Frontend

• Static SPA (no bundler required):
  • frontend/index.html
  • frontend/styles.css
  • frontend/js/core.js
  • frontend/js/render.js
  • frontend/js/actions.js
  • frontend/js/actions-files.js
  • frontend/js/actions-nodes.js
• UI state is kept client-side and refreshed by API pulls.

API Surface (High-Level)

Primary route groups currently available:

• Auth/setup/meta:
  • /api/setup-required
  • /api/setup
  • /api/login, /api/logout, /api/me, /api/meta
  • /api/bootstrap/*, /api/runtime/*
• Target operations:
  • /api/system, /api/services, /api/processes
  • /api/apps/*, /api/tasks/*
  • /api/terminal/*, /api/logs/*
  • /api/files/*
  • /api/caddy/*
• Admin/fleet/security:
  • /api/admin/users/*
  • /api/admin/nodes/*
  • /api/admin/fleet-scripts/*
  • /api/admin/scheduled-actions/*
  • /api/admin/deployments/*
  • /api/admin/sync-profiles/*
  • /api/admin/alerts/*
  • /api/admin/audit
• Node proxy:
  • /api/nodes/proxy

For exact handler wiring and permissions, see:

• backend/httpserver/server.go

Running Cerberus

Prerequisites

• Go toolchain installed
• Caddy installed (optional, only needed for Caddy management features)

Start in Development

go run ./backend

Default address:

• http://0.0.0.0:8080

Build

./scripts/build_release.sh

Build outputs are written to dist/.

Instance Deploy Script

./scripts/deploy_instance.sh

Optional:

./scripts/deploy_instance.sh <repo_url> <branch>

Data and Configuration

• Main config/settings: backend/settings.json
• Database: backend/cerberus.db
• Frontend assets: frontend/

Operational Notes

• Some runtime setting changes require a service restart.
• Alerting and fleet operations are most useful in dashboard mode with connected nodes.
• Secure deployment is recommended:
  • trusted network and/or VPN
  • HTTPS reverse proxy
  • strong admin credentials and secret rotation practices

Roadmap and Change Tracking

• Feature roadmap and execution history: cerberus_feature_roadmap.md