Admin API

Admin API (gRPC Services)

Runtime management services for admin tools. Core exposes three gRPC services for querying and controlling modules, spools, and audit logs. These are intended for the admin-ui module, the muxcorectl CLI, and other management tooling.

All three services are registered on the same gRPC port (default :9090) alongside the existing module-facing services.

---

SpoolService

Proto: muxcore/spool/v1/spool.proto Go package: proto/gen/muxcore/spool/v1

Runtime management of spool configurations and tag-based module deployment. Use this to inspect available spools, list tags, and trigger deployments without restarting core.

RPC	Request	Response	Purpose
ListSpools	ListSpoolsRequest	ListSpoolsResponse	Returns all configured spool URLs (active spool + any configured via API)
ListTags	ListTagsRequest	ListTagsResponse	Lists all tag names available on the given spool
FetchTag	FetchTagRequest	FetchTagResponse	Fetches a tag definition without deploying its modules
DeployTag	DeployTagRequest	DeployTagResponse	Fetches a tag, resolves modules, verifies checksums, spawns new ones. Idempotent — already-running modules are skipped

DeployTag Response

{
  "tag_name": "media-stack",
  "spool_url": "https://github.com/Muxcore-Media/spool",
  "results": [
    {"module_id": "downloader-qbittorrent", "spawned": true, "already_running": false, "error": ""},
    {"module_id": "media-movies", "spawned": false, "already_running": true, "error": ""}
  ],
  "total": 2,
  "spawned": 1,
  "skipped": 1,
  "failed": 0
}

---

ModuleLifecycleService

Proto: muxcore/lifecycle/v1/lifecycle.proto Go package: proto/gen/muxcore/lifecycle/v1

Runtime control over individual module lifecycle — inspect, spawn, stop, and restart modules.

RPC	Request	Response	Purpose
ListModules	ListModulesRequest	ListModulesResponse	All modules known to this node, including state, health, capabilities, uptime
SpawnModule	SpawnModuleRequest	SpawnModuleResponse	Resolve and spawn a module from a previously deployed tag
StopModule	StopModuleRequest	StopModuleResponse	Send SIGTERM to a running module and wait for stop
RestartModule	RestartModuleRequest	RestartModuleResponse	Kill and re-spawn a module from its existing binary

ListModules Response

{
  "modules": [
    {
      "module_id": "downloader-qbittorrent",
      "name": "qBittorrent Downloader",
      "version": "1.0.2",
      "state": "running",
      "health_error": "",
      "capabilities": ["downloader.torrent", "downloader.qbittorrent"],
      "repo": "https://github.com/Muxcore-Media/downloader-qbittorrent",
      "node_id": "muxcore-127.0.0.1:9090",
      "restart_policy": "on-failure",
      "uptime_seconds": 86400
    }
  ]
}

---

AuditService

Proto: muxcore/audit/v1/audit.proto Go package: proto/gen/muxcore/audit/v1

Query, export, and verify the core audit log. Provides programmatic access to the tamper-evident JSONL audit trail.

RPC	Request	Response	Purpose
Query	AuditQueryRequest	AuditQueryResponse	Search audit entries by actor, action, resource, trace ID, and time range
Export	AuditExportRequest	stream AuditExportChunk	Stream all matching entries in JSON or CSV format (supports terabytes-scale logs)
VerifyChain	AuditVerifyChainRequest	AuditVerifyChainResponse	Standalone SHA-256 hash-chain integrity check over a time range — verifies without exposing entry content
Log	LogRequest	LogResponse	Write an entry to the audit log (used by admin tools and modules)

AuditQueryRequest

Field	Type	Description
actor	string	Filter by actor ID (user, system, module). Empty matches all
action	string	Filter by action string
resource	string	Filter by resource string
trace_id	string	Filter by trace ID
from_time	string	Start of time range (RFC3339)
to_time	string	End of time range (RFC3339)
verify_chain	bool	When true, validates hash chain of returned entries
max_results	int32	Cap on returned entries (0 = no limit)

---

DiscoveryService Extensions

The existing DiscoveryService was extended with a ListAll RPC that returns health and state information for every registered module across the cluster:

RPC	Purpose
ListAll	All registered modules on this node and all known peer nodes, including state, health status, and node ID

ModuleEntryProto

Field	Type	Description
info	ModuleInfoProto	Module identity and capabilities
state	string	Lifecycle state: registered, starting, running, degraded, stopping, stopped
health_error	string	Empty when healthy, last health check error otherwise
node_id	string	Cluster node running this module

The ModuleInfoProto also now carries state (field 11), health_error (field 12), and repository (field 13) for consolidated reporting.

---

Next Steps

• Architecture — full gRPC service overview and bootstrap sequence
• Security — audit logging and authentication
• Spool and Marketplace — spool system details