README
¶
kyyard-server
Supported cryptographic configuration and migration: Key strength and TLS.
Start here: Standalone installation. Local accounts and MFA work without KyIdentity. The default Docker installation connects the local Docker host and grants KyYard host-level authority through the mounted Docker socket. Remote hosts and Kubernetes clusters need separate enrollment; suite management needs a KyQuickStart runner handoff.
The simple control plane for your container fleet.
KyYard provides a Go backend, embedded React PWA, SQLite/PostgreSQL, local authentication with self-service TOTP MFA and recovery codes, configurable OAuth 2/OIDC (including KyIdentity) and KyRecovery. The standard installation automatically shows the local Docker host, with container inventory, lifecycle controls, image operations and logs. Connect additional hosts when needed. Remaining milestones are tracked in KyYard-Implementation-Plan.md. SAML metadata is inherited; SAML login is not yet implemented.
Fresh installations only: KyYard uses its own recovery service identity and token-sealing
label. Existing base-project databases, pairing tokens and capsules are not a supported
in-place migration. The SQLite filename ky_server.db remains the inherited storage format.
Container data lives under /data, including local capsules under /data/backups in Compose.
KyYard generates persistent secrets without manual configuration. Compose runs one
container with SQLite and a named kyyard-data volume; SSO is optional and configured in Settings.
The default local URL is http://localhost:9273; follow the installation guide before exposing the service.
What it can do
- Inspect and control containers, images, logs and resource use.
- Manage local Docker and enroll additional Docker hosts or Kubernetes endpoints.
- Use organizations, roles, local MFA or optional KyIdentity sign-in.
- Back up KyYard state separately from the applications it manages.
- Let an AI agent inspect the homelab, and optionally restart containers and apply updates, over MCP.
Connect an AI agent
AI agents such as OpenClaw and Hermes Agent reach an organization over MCP at
https://<your host>/mcp. On the organization's Access page, under AI agents (MCP),
an organization administrator names the agent and picks an access level:
- Read only (the default): the agent lists hosts, clusters, applications and containers, their state, health and resource use, recent logs (500 lines at most) and pending updates.
- Operator: it can also restart a container or Kubernetes workload and apply an image-update plan someone made in KyYard.
No agent can stop, delete, run commands in or reconfigure anything, touch volumes or read
secrets. The page shows the token once, with config for both agents that reads it from
KYYARD_TOKEN, and the command to install the KyYard skill (served at
/agent/skills/kyyard/SKILL.md), which teaches the agent the tools and when to ask you first.
You can change an agent's access there later. An agent token unused for 90 days is revoked; an
agent token never works as a kyPulse service token, nor the reverse. Every operation, log read and
refusal is in the audit history. Details: Integrations.
Container logs are written by the software you run, and an agent may treat them as instructions. Give an agent operator access only if you trust everyone who can message it and every workload whose logs it reads.
License
kyyard-server is released under the MIT License.
Documentation
-
Running — Start KyYard, First sign-in, Account security, Transport and advanced deployment, and related procedures.
-
Tenants — Initial organization, Organizations and accounts, Tenant API.
-
Integrations — Pair kyPulse, Connect an AI agent, Suite management.
-
Containers — Show containers after installation, Container user, Static internal IPs for proxy backends, Compose projects, and related procedures.
-
Agents and Kubernetes — Agent, Kubernetes endpoints, Migrating a Docker application to a cluster.
-
Recovery — Persistent keys, Disaster recovery, Two ways to get a key, Why TLS matters here, and related procedures.
-
Updates — Upgrading.
-
Verifying releases — Check a release image's signature and source commit, and rebuild its binaries to the same bytes.
-
Assurance case — Threat model summary, trust boundaries, and why the security requirements are met.
-
Contributing and verification — Local checks and desktop/phone browser regressions.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
agent
command
kyyard-agent enrolls a Docker host or a Kubernetes cluster with a KyYard control plane and keeps it connected.
|
kyyard-agent enrolls a Docker host or a Kubernetes cluster with a KyYard control plane and keeps it connected. |
|
server
command
|
|
|
soak
command
Command soak drives the storage path at the capacity targets in docs/retention-policy.md and checks that the bounds it promises actually hold: rows stay under the per-endpoint ceiling, retention keeps up with the writers, the disk budget engages and can be left again, refused mutations are recorded, and the list screens stay fast while all of that runs.
|
Command soak drives the storage path at the capacity targets in docs/retention-policy.md and checks that the bounds it promises actually hold: rows stay under the per-endpoint ceiling, retention keeps up with the writers, the disk budget engages and can be left again, refused mutations are recorded, and the list screens stay fast while all of that runs. |
|
internal
|
|
|
agent/client
Package client is the KyYard agent: durable identity, enrollment and the connection loop from docs/agent-protocol.md sections 2, 3, 6 and 9.
|
Package client is the KyYard agent: durable identity, enrollment and the connection loop from docs/agent-protocol.md sections 2, 3, 6 and 9. |
|
agent/protocol
Package protocol holds the wire-level helpers shared by the control plane and the agent: signed-message preimages (docs/agent-protocol.md section 2) and key fingerprints.
|
Package protocol holds the wire-level helpers shared by the control plane and the agent: signed-message preimages (docs/agent-protocol.md section 2) and key fingerprints. |
|
agentskill
Package agentskill holds the SKILL.md that teaches AI agents (OpenClaw, Hermes Agent) to use KyYard's MCP tools.
|
Package agentskill holds the SKILL.md that teaches AI agents (OpenClaw, Hermes Agent) to use KyYard's MCP tools. |
|
applications
Package applications validates desired configuration without reading host files, process environment, URLs or runtime inventory (docs/application-schema.md).
|
Package applications validates desired configuration without reading host files, process environment, URLs or runtime inventory (docs/application-schema.md). |
|
appversion
Package appversion is the one answer to "which version is this?".
|
Package appversion is the one answer to "which version is this?". |
|
migration
Package migration analyzes how an application adopted on a Docker host would run on a Kubernetes cluster: every service on every axis, as supported, operator_choice_required or blocked, with a code from a closed vocabulary and a parameter.
|
Package migration analyzes how an application adopted on a Docker host would run on a Kubernetes cluster: every service on every axis, as supported, operator_choice_required or blocked, with a code from a closed vocabulary and a parameter. |
|
registry
Package registry resolves image references against container registries.
|
Package registry resolves image references against container registries. |
|
runtime/docker
internal/runtime/docker/deploy.go
|
internal/runtime/docker/deploy.go |
|
runtime/kubernetes
Package kubernetes is the Kubernetes adapter: it reads the cluster the agent runs in through the typed clientset, with the agent's ServiceAccount, and returns product types only.
|
Package kubernetes is the Kubernetes adapter: it reads the cluster the agent runs in through the typed clientset, with the agent's ServiceAccount, and returns product types only. |
|
runtime/kubernetes/manifest
Package manifest renders the file an administrator applies to enroll a Kubernetes cluster.
|
Package manifest renders the file an administrator applies to enroll a Kubernetes cluster. |
|
runtime/kubernetes/render
Package render turns one deployment request into the Kubernetes objects a cluster agent applies: per service a Deployment, a Service, a ConfigMap and a Secret, labelled as KyYard's.
|
Package render turns one deployment request into the Kubernetes objects a cluster agent applies: per service a Deployment, a Service, a ConfigMap and a Secret, labelled as KyYard's. |
|
suite
Package suite is the client for suite runner protocol v1 (KyQuickStart docs/superpowers/specs/2026-10-16-suite-runner-design.md, "Runner protocol v1"): HTTP/1.1 over the runner's Unix socket, JSON both ways, unknown fields refused.
|
Package suite is the client for suite runner protocol v1 (KyQuickStart docs/superpowers/specs/2026-10-16-suite-runner-design.md, "Runner protocol v1"): HTTP/1.1 over the runner's Unix socket, JSON both ways, unknown fields refused. |
|
testdb
Package testdb hands tests an isolated database configuration.
|
Package testdb hands tests an isolated database configuration. |