# Runku Self-Hosted Free Runtime

## Purpose

The free self-hosted edition is a complete local governed MCP gateway running
as the `runku` agent binary. It does not require or share Runku Cloud Control
Plane, Edge, tenant billing or hosted identity infrastructure.

Only the agent is distributed. Hosted Control Plane and Edge binaries remain
part of the SaaS product.

## Deployment Shape

```mermaid
flowchart LR
    C[MCP client] -->|HTTPS or local transport| A[Runku agent]
    A --> AUTH[Local OIDC or API-key verification]
    A --> POLICY[Local policy and identity bindings]
    A --> DB1[(PostgreSQL)]
    A --> DB2[(MySQL)]
    A --> DB3[(SQL Server)]
    A --> AUDIT[(Local audit SQLite)]
    ADMIN[Local administrator] --> PORTAL[Local operator portal]
    PORTAL --> A
```

There is no cloud tunnel and no SaaS routing hop. The MCP client connects
directly to the customer-operated agent or to a reverse proxy in front of it.

Example endpoints:

```text
https://runku.internal.example/mcp/postgres-primary
https://runku.internal.example/mcp/mysql-erp
```

## Authentication Options

The free agent owns its local authentication boundary. This is existing agent
functionality, not a future Cloud dependency or a separate authentication app.

### Existing behaviour

1. **API keys:** created and revoked in the local admin store. Appropriate for
   automation and clients that cannot perform OAuth.
2. **OIDC bearer verification:** configured against the operator's existing
   IdP. The agent validates issuer, audience and token claims locally.

Roles, identities, API-key hashes and connector policy live in the agent's
local admin store. They are not managed by Runku Cloud.

## Local Administration

The local portal and CLI manage:

- configured database connectors;
- discovered schemas, tables, views and procedures;
- exposed MCP tools and their descriptions;
- row limits, column restrictions, masks and mutation permissions;
- local roles, OIDC identity bindings and API keys;
- local playground requests;
- audit activity and agent runtime information;
- optional audit/telemetry export webhooks.

The portal does not show:

- SaaS tenants or tenant switching;
- cloud workspaces/environments;
- cloud enrollment or tunnel state;
- centralized agents from other installations;
- Stripe plans, quotas, invoices or hosted billing;
- hosted member invitations or company SSO administration.

## Audit Model

Every MCP operation records locally:

- request and timestamp identifiers;
- connector, tool and affected resource;
- verified human identity or API-key identity;
- allowed, blocked or error verdict;
- policy reason, duration and row count;
- MCP client name and version when available.

Raw query results and credentials are never written to the audit event. Local
operators own retention, backup and export. Optional exports must be explicitly
configured and remain disabled by default.

## Configuration and Storage

The agent keeps first-class local configuration for:

- server/TLS and reverse-proxy settings;
- connector DSNs and credentials;
- local admin-store location;
- OIDC verification settings when used;
- audit SQLite, retention and export settings.

Binary and container installations operate without a Cloud dependency.
Databases used by connectors may be containerized or externally managed at the
operator's choice.

## Failure Behaviour

- Loss of internet does not affect local MCP calls unless the configured IdP
  itself is remote and token validation requires unavailable metadata.
- Loss of an optional export destination does not block MCP execution; events
  remain in the bounded local outbox and retry.
- Database or connector failure affects only that connector.
- Invalid or expired credentials fail closed.
- Policy reload failure preserves the last valid policy and reports the error.

## Edition Boundary

| Capability | Self-hosted free | Runku Cloud SaaS |
|---|---:|---:|
| Agent and SQL connectors | Yes | Yes |
| Local portal and playground | Yes | Optional local diagnostics |
| Agent OIDC/API keys | Yes, primary ingress | Yes for direct ingress; trusted Edge caller for tunneled ingress |
| Centralized multi-agent inventory | No | Yes |
| Hosted Edge and remote tunnel routing | No | Yes |
| Tenant membership and company SSO management | No | Yes |
| Centralized audit metadata and retention | No | Yes |
| Usage plans, quotas and invoices | No | Yes |