Regulus

module

v0.2.0-alpha.1 Latest Latest Go to latest Published: Nov 13, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/CodexCircle/Regulus

Links

Open Source Insights

README ¶

Regulus

CodexCircle Server Manager, also known as Regulus, is a platform to manage one or more Linux servers from a single web dashboard.

Project status: early development. Hub, built-in and remote agents, dashboard, authentication and updates are implemented; plugins are not yet. No release has been published, and the release, the packages and the update path have not yet been tested on a real system (#81). See the roadmap and the design decisions.

How it works

Regulus is built around plugins. The base installation provides a simple dashboard, and every plugin adds features and tools.

Dashboard: fully web-based and customizable. Users choose which widgets to show and how to arrange them.
Agent: installed on every server to be managed. It connects the server to the user's server network.
Hub: installed on one server per group. It manages the agents connected to it and serves the dashboard. The hub installer asks whether to include the agent as well, so the hub's own server can be managed like the others.
Plugins: extend the platform with new server-side features and new dashboard widgets.

  Browser (React dashboard)
            │
            ▼
      ┌───────────┐
      │    Hub    │  one hub per server group
      └───────────┘
        ▲   ▲   ▲
        │   │   │    outbound connections from the agents (gRPC, mTLS)
   ┌────┘   │   └────┐
 Agent    Agent    Agent    one agent per managed server

Agents open the connection to the hub, so no inbound ports are needed on managed servers and everything works behind NAT or firewalls. For how the parts work together (trust, data, updates), see docs/architecture.md.

The words used here (hub, agent, built-in agent, role, channel…) are defined in the glossary.

Tech stack

Component	Technology
Agent and hub	Go: a single `regulus` executable used as agent or hub depending on the role
Dashboard	React with TypeScript and Vite, embedded in the binary
Communication	gRPC with Protobuf as the contract, mTLS between agent and hub
Plugins	Separate processes talking gRPC with the host, plus JavaScript modules for dashboard widgets
Data	SQLite (default, nothing to set up) or PostgreSQL, chosen by configuration (Database); the installer choice (#123) and moving data between them (#124) are not done yet

Supported platforms

Ubuntu Server LTS (22.04, 24.04 and 26.04, amd64 and arm64) is the reference platform; so far a release has been tested on 26.04 amd64. Debian and RHEL-like distributions follow.

Roadmap

Phase 1: hub with built-in agent and dashboard.
Phase 2: remote agents on other servers.
Phase 3: separate agent and hub, protocol versioning, updates (manual, download-only or automatic).
Phase 4: plugins.

Third-party plugins come after the plugin system is stable. Work is tracked in the issues, grouped in milestones M1 to M6; docs/decisions.md maps them to the phases.

Quick install (Ubuntu Server)

curl -fsSLO https://github.com/CodexCircle/Regulus/releases/latest/download/install.sh
sh install.sh

It downloads the latest release, verifies its checksum and signature, installs it, starts the service and prints where to open the dashboard and the one-time setup token. Until the first stable release is out, latest has nothing to serve: use the command at the top of the notes of a pre-release. Options, what the package sets up and how to add other servers are in Installation. The dashboard speaks plain HTTP on port 8080: put a reverse proxy with TLS in front of it before exposing it beyond a trusted network.

Documentation

The documentation index says where to go for each task. The main pages:

Installation, configuration, releases and updates
Console and command line, authentication, remote agents, HTTP API and dashboard
Architecture (with the code map), glossary, design decisions and the plugin design draft

Contributing

See CONTRIBUTING.md, development setup and the design decisions. Security problems: SECURITY.md.

License

Apache License 2.0. See LICENSE.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
regulus command Command regulus is the single Regulus executable.	Command regulus is the single Regulus executable.
internal
agent Package agent is the client side of the agent-hub contract defined in proto/regulus/agent/v1.	Package agent is the client side of the agent-hub contract defined in proto/regulus/agent/v1.
auth Package auth implements the hub's local accounts and everything that protects the HTTP API: first-run setup of the admin, password hashing, login sessions, users, roles and permissions, two-factor authentication (TOTP and recovery codes), credential reset and the HTTP middleware.	Package auth implements the hub's local accounts and everything that protects the HTTP API: first-run setup of the admin, password hashing, login sessions, users, roles and permissions, two-factor authentication (TOTP and recovery codes), credential reset and the HTTP middleware.
capability Package capability is the draft data model for what an agent machine does (its capabilities) and what it may reach or use (its permissions), with the defaults of each preset (compute, backup, gateway, development) and the rules for overriding them per machine.	Package capability is the draft data model for what an agent machine does (its capabilities) and what it may reach or use (its permissions), with the defaults of each preset (compute, backup, gateway, development) and the rules for overriding them per machine.
config Package config loads the hub configuration.	Package config loads the hub configuration.
console Package console is the interactive terminal console of Regulus and the plain-text and JSON output that takes its place when no terminal UI is wanted: what the hub is doing, its settings, its logs and health checks.	Package console is the interactive terminal console of Regulus and the plain-text and JSON output that takes its place when no terminal UI is wanted: what the hub is doing, its settings, its logs and health checks.
fleet Package fleet manages the remote agents of the hub: the single-use tokens that let a new agent enroll, the registry of the agents that did, and the revocation of an agent.	Package fleet manages the remote agents of the hub: the single-use tokens that let a new agent enroll, the registry of the agents that did, and the revocation of an agent.
gen/regulus/agent/v1
hub Package hub implements the Regulus hub, the process that everything else talks to: it serves the dashboard and the HTTP API, accepts the connections of the agents, keeps the live state of the fleet and drives the updates.	Package hub implements the Regulus hub, the process that everything else talks to: it serves the dashboard and the HTTP API, accepts the connections of the agents, keeps the live state of the fleet and drives the updates.
inproc Package inproc is an in-memory gRPC transport.	Package inproc is an in-memory gRPC transport.
localstatus Package localstatus is the small channel between a running hub and the tools on the same machine (the console and `regulus status`): a Unix socket in the data directory, readable only by the user that runs the hub.	Package localstatus is the small channel between a running hub and the tools on the same machine (the console and `regulus status`): a Unix socket in the data directory, readable only by the user that runs the hub.
logging Package logging builds the structured logger (log/slog) used across Regulus from the log section of the configuration.	Package logging builds the structured logger (log/slog) used across Regulus from the log section of the configuration.
pki Package pki is the small certificate authority of the hub.	Package pki is the small certificate authority of the hub.
protocol Package protocol holds the version of the agent-hub contract defined in proto/regulus/agent/v1 and the rules to compare versions.	Package protocol holds the version of the agent-hub contract defined in proto/regulus/agent/v1 and the rules to compare versions.
storage Package storage opens the hub database and applies its migrations (embedded, applied in order and recorded).	Package storage opens the hub database and applies its migrations (embedded, applied in order and recorded).
storage/storagetest Package storagetest opens a hub database for tests.	Package storagetest opens a hub database for tests.
update Package update finds, downloads, verifies and installs new releases of Regulus.	Package update finds, downloads, verifies and installs new releases of Regulus.
webui Package webui embeds the compiled dashboard (the dashboard/ directory, built by `make build`) so the hub can serve it.	Package webui embeds the compiled dashboard (the dashboard/ directory, built by `make build`) so the hub can serve it.