How tr3kkr/yuzu works
1. This repo is a full endpoint-management control plane, not a single app.
The main runtime pieces are agents/core (endpoint daemon), server/core (central management server), gateway/ (optional Erlang/OTP relay), and sdk/ (stable plugin ABI). The repo also carries the protocol definitions, packaged instruction content, deploy artifacts, docs/site, and tests.
2. The agent is the on-device execution and telemetry boundary.
agents/core is a C++23 daemon that discovers identity/certificates, loads plugins, runs triggers/schedulers, and maintains local KV/state. It is the only component that directly touches the managed endpoint’s OS surfaces and hardware/network APIs.
3. Plugins are the main extensibility mechanism on the agent.
agents/plugins/* contains many small shared-library plugins for inventory, security, network, software, and response actions. The SDK in sdk/ defines the ABI, so plugins can be built independently while still being loaded by the agent at runtime.
4. The server is the orchestration and control-plane hub.
server/core owns authentication, RBAC, session/API token handling, instruction execution, policy/compliance evaluation, device inventory, notifications, workflows, and dashboards. Its code is organized around “stores”, “routes”, “engines”, and “UI” renderers rather than a single monolith.
5. Device communication is gRPC/protobuf over mTLS.
The wire contract lives under proto/yuzu/... and is mirrored by generated code in gateway/ and used by both agent and server. The core data flows are registration, heartbeats, streaming command execution, result submission, and event watching.
6. The optional gateway is a separate Erlang/OTP tier.
gateway/ sits between agents and server in larger or distributed deployments. It handles upstream routing, buffering/aggregation of heartbeats and registrations, health/circuit behavior, and gRPC proxying using grpcbox.
7. Instruction content is a first-class data model, embedded at build time.
content/definitions/*.yaml describes instruction definitions, sets, and packs. These are validated and embedded into the server build, then imported/executed as governed, versioned operations with typed params, typed result columns, and approval semantics.
8. Persistence is split by concern, with explicit storage layers.
The server has many domain stores and a PostgreSQL substrate/migration layer (server/core/src/pg/*), plus embedded-store helpers where appropriate. The agent uses local persistent state for identity and coordination, while the server persists operational records such as audits, approvals, executions, inventory, policies, and response/result sets.
9. The web UI is server-rendered and tightly coupled to backend routes.
server/core serves HTMX-style HTML fragments, static JS/CSS bundles, and route handlers for dashboards like inventory, devices, network, DEX, TAR, workflow, and settings. This is a server-driven UI rather than a separate frontend SPA.
10. Observability and integrations are built into the architecture.
Both agent and server expose Prometheus metrics; the repo includes Grafana provisioning/dashboards and ClickHouse-oriented deployment assets. External integrations also include OIDC for auth, webhooks/event sinks, and MCP tooling for agentic access.
11. Deployment is multi-target and operationally opinionated.
The repo includes Meson/vcpkg build files, Docker images and compose stacks, systemd units, Debian/RPM/MSI/macOS packaging, and CI workflows. That means architecture diagrams should show both the runtime topology and the packaging/deployment boundary, since the same codebase produces server, agent, gateway, and demo stacks.
12. Docs and tests are part of the architecture contract.
docs/ contains the authoritative design docs and ADRs, while tests/ covers unit, integration, end-to-end, and UI/puppeteer flows. The repo is heavily test- and policy-driven, so behavior is expected to be validated at multiple layers, not just by manual use.
Main entry points: server/core Server core · agents/core Agent core · deploy Deploy · gateway Gateway
Components 19
Runtime plane
Core online services and on-device execution boundary.
- Agent core · On-device C++ runtime that owns identity, local state, plugin loading, triggers, scheduling, and endpoint telemetry.
agents/core - Plugins · Shared-library capability modules for inventory, security, network, software, response, and collection tasks.
agents/plugins - SDK · Stable headers and utilities that define the plugin interface and allow independent plugin builds.
sdk - Server core · Central C++ service for auth, orchestration, policies, inventory, workflows, UI rendering, and data persistence.
server/core - Ingest · Heartbeats, registrations, inventory, execution results, analytics, and event ingestion paths.
server/core/src - Execution · Instruction loading, approvals, scheduling, bundle orchestration, result sets, and response execution.
server/core/src - Policy & auth · Authentication, OIDC/MFA, RBAC, compliance, preflight, and approval decisions.
server/core/src - Server UI · HTMX-style routes and renderers for dashboards, settings, devices, inventory, network, DEX, TAR, and workflows.
server/core/src - Storage · PostgreSQL-backed stores, migrations, and domain-specific state for audits, inventory, executions, policies, and tokens.
server/core/src/pg - Gateway · Optional distributed tier that proxies gRPC, buffers registrations and heartbeats, and manages health and upstream routing.
gateway - Protobuf API · Shared gRPC/protobuf definitions for agent, common, gateway, and server management APIs over mTLS.
proto/yuzu
Content plane
Versioned instruction definitions and embedded governed operations.
- Instructions · YAML instruction definitions, sets, and packs validated at build time and embedded into the server.
content/definitions
Delivery plane
Build, packaging, deployment, observability, and docs.
- Deploy · Docker, systemd, packaging, compose, and environment assets for server, agent, gateway, and demo stacks.
deploy - Observability · Prometheus, Grafana provisioning, dashboards, alerts, and telemetry-oriented deployment assets.
deploy/grafana - Docs · Authoritative design docs, ADRs, runbooks, and user manuals that define behavior and operating constraints.
docs - Tests · Unit, integration, shell, and puppeteer flows covering server, agent, gateway, and UI behavior.
tests - Site · Astro-based docs and manual site used to publish architecture and user-facing documentation.
site - Scripts · Build, CI, release, UAT, and maintenance scripts that bridge development and deployment workflows.
scripts - CI · GitHub workflows and code scanning that validate builds, security, docs, and release pipelines.
.github/workflows
Connections 28
- Agent core → Plugins: loads · The daemon discovers and loads capability plugins at runtime.
- Plugins → SDK: implements · Plugins are compiled against the stable ABI and helper headers.
- Agent core → Protobuf API: speaks · Agent uses the protobuf contract for registration, heartbeats, and execution streams.
- Gateway → Protobuf API: mirrors · Gateway vendors and proxies the same management and agent API contract.
- Server core → Protobuf API: serves · Server implements management-side gRPC and shared wire semantics.
- Server core → Ingest: ingests · Ingestion paths receive device telemetry, results, and events.
- Server core → Execution: orchestrates · Instruction execution and workflow engines coordinate governed operations.
- Server core → Policy & auth: governs · Auth, RBAC, compliance, and approvals gate actions.
- Server core → Server UI: renders · Route handlers and page renderers build the server-driven UI.
- Server core → Storage: persists · Domain stores and migrations back operational records.
- Gateway → Server core: forwards · Optional relay tier routes upstream traffic to the server.
- Agent core → Server core: registers · Agents enroll, heartbeat, and submit results to the control plane.
- Instructions → Execution: feeds · Embedded instruction packs are imported by the execution layer.
- Instructions → Policy & auth: checks · Definitions carry approval, typing, and governance semantics.
- Deploy → Agent core: packages · Build and packaging assets produce agent binaries and installers.
- Deploy → Server core: packages · Deployment assets produce server images and service packages.
- Deploy → Gateway: packages · Deployment assets build and ship the gateway tier.
- Observability → Server core: observes · Dashboards and metrics expose server health and operations.
- Observability → Gateway: observes · Gateway metrics and dashboards cover relay health and buffering.
- Docs → Server core: documents · Design docs capture architecture, auth, storage, and operations.
- Docs → Agent core: documents · Agent docs cover privilege, plugins, enrollment, and runtime behavior.
- Tests → Agent core: verifies · Unit and integration tests exercise endpoint runtime behavior.
- Tests → Server core: verifies · Tests cover routes, stores, engines, and UI rendering.
- Tests → Gateway: verifies · Gateway suites cover routing, buffering, mTLS, and proxy behavior.
- Site → Docs: publishes · The documentation site renders the repo's architectural and user docs.
- Scripts → Deploy: drives · Scripts orchestrate builds, releases, UAT, and stack bring-up.
- CI → Tests: runs · Workflows execute test suites, checks, and release gates.
- CI → Deploy: builds · CI produces artifacts and validates packaging paths.