Ruriko

module

v0.0.0-...-0226060 Latest Latest Go to latest Published: Jul 15, 2026 License: Apache-2.0

Details

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

Repository

github.com/bdobrica/Ruriko

Links

Open Source Insights

README ¶

Ruriko

A conversational control plane for secure, capability-scoped AI agents over Matrix.

Ruriko is a self-hosted system where a human talks to Ruriko over Matrix, and Ruriko plans and configures specialized LLM-powered agents (Gitai) that collaborate peer-to-peer — messaging each other directly over Matrix, with secrets handled securely and control operations kept off the conversation layer.

📖 Full product story, UX contract, and canonical glossary: docs/preamble.md

For the MVP installation path, start with the single-host quickstart and read the supported security boundary.

Instead of treating agents like chatbots, Ruriko treats them like operated system components — with lifecycle control, secret management, deterministic policies, and auditable tool access.

✨ Why Ruriko?

Most agent frameworks are:

Python-first
Developer-centric
Monolithic
Loosely guarded
Hard to operate safely in production

Ruriko takes a different approach:

🔐 Policy-first – deterministic capability enforcement
🧱 Immutable runtime – agents cannot self-modify
🗝️ Centralized secret management
🔄 Lifecycle control – spawn, stop, respawn, update
🛰️ Matrix-native communication – humans and agents coexist naturally
🧩 MCP-based tool ecosystem
🐳 Single binary agents – easy to deploy anywhere

Ruriko is inspired by Kubernetes, MLOps control planes, and capability-based security models.

🏗 Architecture

Ruriko consists of two main components:

1️⃣ Ruriko (Control Plane)

Plans workflows and drafts agent configurations
Manages agent lifecycle
Provisions Matrix accounts
Stores and rotates secrets
Applies and versions agent configuration (Gosuto)
Defines the agent mesh topology (which agents can message which) Operator guide: see docs/ops/agent-mesh-topology.md for /ruriko agents create peer override flags (--peer-alias, --peer-mxid, --peer-room, --peer-protocol-id, --peer-protocol-prefix) and alternate topology examples.
Enforces administrative approvals
Maintains audit logs
Provides templates and versioned Gosuto configuration; autonomous template and agent generation is planned

Ruriko is the planner and policy authority. It does not sit in the hot path of agent-to-agent collaboration — it plans the topology and agents execute peer-to-peer.

Both binaries reuse shared low-level SQLite bootstrap/migration helpers from common/sqliteutil, while keeping domain-specific repositories separate in internal/ruriko/store and internal/gitai/store.

2️⃣ Gitai (Agent Runtime)

Each agent runs as a separate single binary:

Connects to Matrix via mautrix-go
Sends messages to other agents and users via built-in Matrix messaging tool (policy-gated)
Persists DB-backed cron schedules via built-in schedule.* tools
Communicates via structured message envelopes
Calls LLM providers
Manages and supervises MCP tool processes
Manages and supervises event gateway processes (built-in cron/webhook, external binaries)
Executes DB-backed cron schedules for built-in cron gateways configured with config.source: db
Accepts inbound event triggers via ACP POST /events/{source} and routes them through the same policy → LLM → tool pipeline as Matrix messages
Enforces policy locally
Handles approvals
Executes tool calls within strict constraints

Runtime is immutable. Behavior is controlled by structured configuration. Agents collaborate peer-to-peer over Matrix — Ruriko is not in the message path.

Shared transport/security primitives used by both binaries live under common/ (for example ACP specs, webhook signature validation, and rate-limiting utilities) to keep behavior consistent and reduce duplication.

OpenAI-compatible chat transport is shared under common/llm/openai, while Gitai (internal/gitai/llm) and Ruriko NLP (internal/ruriko/nlp) keep their domain-specific request/response mapping logic.

Matrix low-level lifecycle/transport primitives are shared under common/matrixcore, while app-specific routing/policy checks remain in internal/gitai/matrix and internal/ruriko/matrix.

Memory contracts and context-assembly primitives are shared under common/memory; Ruriko's memory subsystem consumes these shared definitions and Gitai can opt into prompt memory-context injection with GITAI_MEMORY_CONTEXT_ENABLE=1.

👻 Gosuto (Agent Configuration — Policy, Instructions, Persona)

Each agent is configured using a versioned YAML file called Gosuto.

Gosuto defines:

Allowed rooms and senders
Capability rules
MCP server wiring
Event gateway wiring (built-in cron/webhook, and external gateway binaries baked into the image)
Tool allowlists and constraints
Approval requirements
Limits (rate, cost, concurrency, events-per-minute)
Secret bindings
Messaging targets — rooms the agent is allowed to send messages to (policy-gated, rate-limited)
Instructions — operational workflow: role, workflow steps, peer and user awareness (auditable, versioned)
Persona — cosmetic tone and style (non-authoritative)

The Gosuto authority model is three-tier: Policy (code-enforced) > Instructions (operational workflow) > Persona (cosmetic). Instructions cannot grant capabilities outside policy.

🔐 Security Model

Ruriko uses capability-based enforcement:

All actions are evaluated against structured policy rules.
First-match-wins rule evaluation.
Default deny.
Sensitive tool calls require explicit human approval.
Secrets are never stored in Gosuto or sent through Matrix.
Secrets are entered by humans via Kuze one-time secure links.
Secrets are encrypted at rest (AES-GCM, master key from environment).
Agents fetch secrets via one-time redemption tokens (never raw credentials).
All actions are auditable and traceable.

Agents cannot:

Modify their runtime
Access secrets outside their scope
Call tools not explicitly allowed
Execute privileged operations without approval

🛡️ CI Security Automation

Security and supply-chain checks run automatically in GitHub Actions via .github/workflows/security-supply-chain.yml.

It runs on pull requests, pushes to main, and weekly on schedule, and includes:

govulncheck ./... for Go dependency/runtime vulnerability detection
CycloneDX SBOM generation (ruriko-go-mod.cdx.json)
Trivy image scanning for ruriko and gitai (fails on HIGH/CRITICAL)

Current security baseline tracks Go 1.25.8 and golang.org/x/net v0.51.0.

To retrieve SBOM output, open a workflow run in Actions and download the artifact named sbom-cyclonedx.

The full four-tier verification contract—fast checks, credential-free Compose, restricted live-provider tests, and release-candidate recovery/security checks—is documented in docs/testing.md.

📡 Communication Model

Ruriko uses three distinct channels:

Channel	Used for
Matrix (conversation)	Human ↔ Ruriko dialogue, agent ↔ agent peer-to-peer collaboration, audit breadcrumbs
ACP (Agent Control Protocol)	Lifecycle control, config apply, health checks, restarts, inbound event delivery (`POST /events/{source}`) — private to the Docker network
Kuze (secret plane)	One-time secret entry (human) and one-time secret redemption (agents) — never through Matrix
Event Gateways (inbound triggers)	Cron ticks, email arrivals, webhook deliveries — translated to event envelopes, posted to ACP

This separation keeps the transcript meaningful and safe.

🧠 Tooling via MCP

Agents integrate with tools via the Model Context Protocol (MCP).

Examples:

Browser automation (Playwright MCP)
Weather APIs
Scheduling
File systems
Custom enterprise connectors

MCP processes are supervised and reconciled by Gitai.

🔔 Inbound Event Gateways

Agents can be woken by external events rather than waiting for Matrix messages.

Gateway types:

Built-in Cron — fires cron.tick events on any 5-field cron schedule (no external process needed)
Built-in Webhook — receives HTTP POSTs proxied through Ruriko's rate-limited, HMAC-authenticated /webhooks/{agent}/{source} endpoint
External binaries — compiled gateway processes baked into the Gitai Docker image (e.g. ruriko-gw-imap for email-reactive agents)

Gateways are wired in Gosuto under gateways: and are supervised identically to MCP processes — same credential management, same restart semantics, same audit trail. Events enter the same policy → LLM → tool pipeline as Matrix messages; prompt injection from external sources is mitigated by code-enforced policy.

🛠 Agent Templates

Canonical agents

Saito Agent – deterministic cron/trigger agent; fires periodic triggers and sends Matrix messages to other agents to initiate workflows (e.g., tells Kairo to check the portfolio). Singleton identity.
Kairo Agent – finance and portfolio analysis via the Finnhub MCP; retrieves market data, analyses tickers, delegates news lookups to Kumo via Matrix, and delivers final reports to the user. Singleton identity.
Kumo Agent – news and web search via the Brave Search MCP; receives requests from Kairo via Matrix and summarises news for tickers and topics. Singleton identity.

Canonical agents are named singleton identities with distinct personalities and roles — not interchangeable worker instances.

Generic templates

Cron Agent – scheduled checks and recurring tasks, woken by a built-in cron gateway
Email Agent – example configuration for an email-reactive agent; the bundled ruriko-gw-imap binary is currently a lifecycle/configuration stub and does not connect to IMAP
Browser Agent – headless browsing with approval-gated navigation
Research Agent – structured envelope-based task delegation

🚀 Deployment Philosophy

Single command: docker compose up -d
Bundled Tuwunel Matrix homeserver (federation OFF, registration OFF)
Container-friendly
Intended for a trusted single Docker host during the MVP phase
Kubernetes and systemd runtime adapters are planned, not implemented
SQLite for state (WAL mode)
No heavy external dependencies required

🧪 Canonical Live Verification

Before opening a pull request, run the same required fast gate as CI:

make check

This runs all Go tests, go vet, module verification, a read-only gofmt check, and builds Ruriko, Gitai, and the IMAP gateway. It does not require Matrix, Docker, or external credentials.

Run canonical live checks (compose + security):

make test-ruriko-saito-operator-live
make test-canonical-workflow-live-compose
make test-canonical-workflow-live-compose-3cycles
make test-canonical-workflow-live-security
make test-canonical-workflow-live

Run standalone Kumo workflow checks (no Ruriko; Kumo + Tuwunel only):

make test-kumo-live-compose
make test-kumo-live-compose-summary

Run standalone Saito scheduling checks (no Ruriko; Saito + Tuwunel only):

make test-saito-live-compose
make test-saito-live-compose-2cycles

Useful overrides:

RURIKO_SAITO_TIMEOUT_SECONDS (default 300)
RURIKO_SAITO_CRON_EXPR (default */2 * * * *)
RURIKO_SAITO_CRON_MESSAGE (default Saito scheduled heartbeat to operator)
CANONICAL_REQUIRED_CYCLES (default 1; 3 when using test-canonical-workflow-live-compose-3cycles)
CANONICAL_LIVE_TIMEOUT_SECONDS (default 600)
CANONICAL_LIVE_POLL_SECONDS (default 5)
CANONICAL_SAITO_CRON_EXPR (default @every 30s)
CANONICAL_OPENAI_MODE (stub or passthrough, default stub)
CANONICAL_OPENAI_API_KEY (default dummy-live-key; must be real in passthrough mode)
CANONICAL_BRAVE_API_KEY (required; set through Kuze in canonical flow)
CANONICAL_SECURITY_LOOKBACK (default 30m)
KUMO_LIVE_OPENAI_MODE (stub or passthrough, default stub)
KUMO_LIVE_OPENAI_API_KEY (default dummy-live-key)
KUMO_LIVE_BRAVE_API_KEY (set for live Brave API execution)
KUMO_LIVE_REQUIRE_SUMMARY (0/1, default 0)
SAITO_LIVE_CRON_EXPRESSION (default @every 15s)
SAITO_LIVE_CRON_MESSAGE_PREFIX (default SAITO_LIVE_TICK)
SAITO_LIVE_REQUEST_TIMEOUT_SECONDS (default 180)
SAITO_LIVE_REQUIRED_DELIVERIES (default 1)

🧭 Project Goals

Make agentic AI safe for non-programmers
Provide operational guardrails by default
Separate policy from prompt
Enable distributed, small-footprint agents
Avoid probabilistic control logic

🧪 Current Status

The authoritative public status is the capability matrix. Ruriko has a broad implemented foundation, but it is not yet MVP-complete: fail-closed policy hardening, single-host recovery, autonomous agent reuse/creation/evolution, and a complete release proof remain open.

The matrix records the boundary of each implemented or planned capability, including workflow steps, memory, runtime adapters, gateways, autonomy, and release verification. TODO.md and dated files under docs/audits/ are historical planning and review records.

💡 Inspiration

Ruriko is influenced by:

Kubernetes control plane patterns
MLOps lifecycle management
Capability-based security systems
Service meshes
Matrix federation architecture

📜 License

Apache 2.0

Directories ¶

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

Path	Synopsis
cmd
gateway/ruriko-gw-imap command ruriko-gw-imap is a placeholder IMAP event gateway for Gitai agents.	ruriko-gw-imap is a placeholder IMAP event gateway for Gitai agents.
gitai command Gitai is the AI agent runtime binary.	Gitai is the AI agent runtime binary.
ruriko command
ruriko-docker-broker command
ruriko-maint command
ruriko-preflight command
common
crypto Package crypto provides AES-GCM encryption helpers for secrets at rest.	Package crypto provides AES-GCM encryption helpers for secrets at rest.
environment Package environment provides helpers for loading configuration from environment variables.	Package environment provides helpers for loading configuration from environment variables.
httpauth Package httpauth provides strict, constant-time HTTP authentication helpers.	Package httpauth provides strict, constant-time HTTP authentication helpers.
httpbody Package httpbody provides fail-closed bounded request-body helpers.	Package httpbody provides fail-closed bounded request-body helpers.
llm/openai Package openai provides a shared OpenAI-compatible chat completions transport used by both Ruriko and Gitai.	Package openai provides a shared OpenAI-compatible chat completions transport used by both Ruriko and Gitai.
matrixcore Package matrixcore provides shared low-level Matrix client transport primitives reused by both Ruriko and Gitai.	Package matrixcore provides shared low-level Matrix client transport primitives reused by both Ruriko and Gitai.
memory Package memory contains reusable conversation memory primitives shared by both Ruriko and Gitai.	Package memory contains reusable conversation memory primitives shared by both Ruriko and Gitai.
ratelimit Package ratelimit provides shared in-memory rate limiting primitives.	Package ratelimit provides shared in-memory rate limiting primitives.
redact Package redact provides centralized safe serialization for logs, audit payloads, Matrix notices, and HTTP errors.	Package redact provides centralized safe serialization for logs, audit payloads, Matrix notices, and HTTP errors.
retry Package retry provides exponential-backoff retry logic for transient errors.	Package retry provides exponential-backoff retry logic for transient errors.
spec/acp Package acp defines the shared Agent Control Protocol (ACP) wire schema.	Package acp defines the shared Agent Control Protocol (ACP) wire schema.
spec/envelope Package envelope defines the event envelope types used for inbound gateway event ingress.	Package envelope defines the event envelope types used for inbound gateway event ingress.
spec/gosuto Package gosuto defines types for the Gosuto agent configuration schema (v1).	Package gosuto defines types for the Gosuto agent configuration schema (v1).
sqliteutil Package sqliteutil provides shared SQLite bootstrap helpers used by both Ruriko and Gitai stores.	Package sqliteutil provides shared SQLite bootstrap helpers used by both Ruriko and Gitai stores.
trace Package trace provides trace ID generation and context propagation for request correlation across handler → sub-operation boundaries.	Package trace provides trace ID generation and context propagation for request correlation across handler → sub-operation boundaries.
version Package version provides build-time version information	Package version provides build-time version information
webhookauth Package webhookauth provides shared webhook authentication helpers.	Package webhookauth provides shared webhook authentication helpers.
internal
gitai/app Package app wires all Gitai subsystems and implements the turn processing loop: Matrix message received → policy check → LLM → tool calls → reply.	Package app wires all Gitai subsystems and implements the turn processing loop: Matrix message received → policy check → LLM → tool calls → reply.
gitai/approvals Package approvals manages the agent-side approval workflow.	Package approvals manages the agent-side approval workflow.
gitai/builtin Package builtin provides the built-in tool registry for Gitai agents.	Package builtin provides the built-in tool registry for Gitai agents.
gitai/control Package control implements the Agent Control Protocol (ACP) HTTP server.	Package control implements the Agent Control Protocol (ACP) HTTP server.
gitai/gateway Package gateway implements built-in inbound event gateways for Gitai agents.	Package gateway implements built-in inbound event gateways for Gitai agents.
gitai/gosuto Package gosuto handles loading, validation, and hot-reloading of the agent's Gosuto configuration.	Package gosuto handles loading, validation, and hot-reloading of the agent's Gosuto configuration.
gitai/llm Package llm defines the LLM provider interface and common message types used by the Gitai turn loop.	Package llm defines the LLM provider interface and common message types used by the Gitai turn loop.
gitai/matrix Package matrix wraps mautrix-go for the Gitai agent runtime.	Package matrix wraps mautrix-go for the Gitai agent runtime.
gitai/mcp Package mcp provides types for the Model Context Protocol (MCP) JSON-RPC 2.0 transport, and a client that communicates with a running MCP server process over stdin/stdout.	Package mcp provides types for the Model Context Protocol (MCP) JSON-RPC 2.0 transport, and a client that communicates with a running MCP server process over stdin/stdout.
gitai/observability Package observability provides structured logging helpers for Gitai.	Package observability provides structured logging helpers for Gitai.
gitai/policy Package policy provides the Gitai policy engine.	Package policy provides the Gitai policy engine.
gitai/secrets Package secrets — Manager provides a TTL-bounded cache on top of a *Store.	Package secrets — Manager provides a TTL-bounded cache on top of a *Store.
gitai/store Package store provides database access for the Gitai agent runtime.	Package store provides database access for the Gitai agent runtime.
gitai/supervisor gateway.go — external gateway subprocess lifecycle management.	gateway.go — external gateway subprocess lifecycle management.
gitai/workflow Package workflow provides deterministic workflow-trigger parsing, trust gating, schema checks, and execution context primitives.	Package workflow provides deterministic workflow-trigger parsing, trust gating, schema checks, and execution context primitives.
ruriko/allocation
ruriko/app Package app provides the main Ruriko application	Package app provides the main Ruriko application
ruriko/approvals Package approvals implements the approval workflow for gated Ruriko operations.	Package approvals implements the approval workflow for gated Ruriko operations.
ruriko/audit Package audit provides the audit room notification subsystem.	Package audit provides the audit room notification subsystem.
ruriko/bootstrap Package bootstrap validates the single-host deployment before Compose starts.	Package bootstrap validates the single-host deployment before Compose starts.
ruriko/changes
ruriko/commands Package commands provides command parsing and routing for Ruriko	Package commands provides command parsing and routing for Ruriko
ruriko/config Package config provides a lightweight key/value configuration store backed by a SQLite table.	Package config provides a lightweight key/value configuration store backed by a SQLite table.
ruriko/dockerbroker Package dockerbroker exposes only the Docker API subset required by Ruriko.	Package dockerbroker exposes only the Docker API subset required by Ruriko.
ruriko/kuze
ruriko/learning
ruriko/matrix Package matrix provides Matrix client functionality for Ruriko	Package matrix provides Matrix client functionality for Ruriko
ruriko/memory Package memory implements short-term and long-term conversation memory for Ruriko's natural language interface.	Package memory implements short-term and long-term conversation memory for Ruriko's natural language interface.
ruriko/nlp Package nlp provides the natural-language classification layer for Ruriko.	Package nlp provides the natural-language classification layer for Ruriko.
ruriko/ops Package ops implements offline-verifiable Ruriko recovery operations.	Package ops implements offline-verifiable Ruriko recovery operations.
ruriko/plans
ruriko/provisioning Package provisioning handles Matrix account lifecycle for agents.	Package provisioning handles Matrix account lifecycle for agents.
ruriko/runtime Package runtime defines the Runtime interface for agent container lifecycle management.	Package runtime defines the Runtime interface for agent container lifecycle management.
ruriko/runtime/acp Package acp provides an HTTP client for the Agent Control Protocol.	Package acp provides an HTTP client for the Agent Control Protocol.
ruriko/runtime/docker Package docker provides a Docker Engine runtime adapter for spawning agent containers.	Package docker provides a Docker Engine runtime adapter for spawning agent containers.
ruriko/secrets Package secrets — distributor sends bound secrets to agent ACP endpoints.	Package secrets — distributor sends bound secrets to agent ACP endpoints.
ruriko/store Package store provides database access for Ruriko	Package store provides database access for Ruriko
ruriko/templates Package templates provides loading and interpolation of Gosuto agent configuration templates.	Package templates provides loading and interpolation of Gosuto agent configuration templates.
ruriko/webhook Package webhook implements the Ruriko-side webhook reverse proxy (R13.1).	Package webhook implements the Ruriko-side webhook reverse proxy (R13.1).