Kybernis Documentation

A tamper-proof log (ledger) of what happened and when.

Checks budgets, retries, and safe destinations.

The proxy + gates that stop risky actions unless approved.

• Per‑app retries and idempotency keys
• Ad‑hoc logging and manual incident review
• Budget checks sprinkled in code

• Centralized policy enforcement
• Deterministic run ledger + receipts
• Durable idempotency + safe retries

Policies, budgets, retries, ledger, and /infra/decide.

Proxy + gates enforce policy at the side‑effect boundary.

SDK emits spans for non‑HTTP work to keep the ledger complete.

A single unit of work (one user request, workflow, or job).

A metered step inside a run (HTTP call, tool, LLM, DB, side‑effect).

Append‑only record of spans and events for audit + replay.

Human‑in‑the‑loop boundary for irreversible actions.

A deterministic key that prevents duplicate side‑effects.

Ordered spans + verdicts + hashes for replay‑safe audit.

• allow
• deny
• delay
• downgrade
• require_approval

• ok
• error
• canceled
• deduped
• blocked

• API_BASE — control plane base URL.
• API_TOKEN — bearer token for server calls.
• DASH_TENANT_ID — default tenant for UI actions.

• KYB_SDK_ON — enable SDK (1/0).
• KYB_API_BASE — control plane base URL.
• KYB_API_TOKEN — bearer token.
• KYB_TENANT_ID — tenant scope (from API keys).
• KYB_RUN_ID — run scope (unique per request/workflow).
• KYB_TOOL_REGISTER — auto‑register tools.
• KYB_GATE_AUTO_APPROVE — auto‑approve gates for dev.
• KYB_TOOL_CALL_LIMIT — per‑tool call limit.
• KYB_ENFORCE_EGRESS — fail‑closed if proxy missing.
• HTTP_PROXY/HTTPS_PROXY — route HTTP through proxy.

• X-Kyb-On — turn rules on
• X-Kyb-Idempotency-Key — stop duplicates
• X-Kyb-Retry — allow safe retries
• X-Kyb-Budget — cap spend
• X-Kyb-Run-Id — tie to a run

• X-Kyb-Verdict — allowed or blocked
• X-Kyb-Reason — plain reason
• X-Kyb-Policy-Id — which rule
• X-Kyb-Dedupe-Of — link to original
• X-Kyb-Attempt — retry count

• tool_register(name, kind, endpoint, labels) → tool_id
• tool_heartbeat(tool_id) → keeps tool alive
• tool_report(tool_id, status, circuit_state, failure_inc)
• emit_event(run_id, event_type, payload) → ledger event
• record_cost(run_id, cost_micros, currency)
• gate_request(...) → {gate_id, status, verdict}
• gate_request_span(...) → gate + span linkage
• gate_status(gate_id) → {status}
• gate_wait(gate_id, timeout_s) → final decision

• span_start(client, run_id, span_type, name) → span_id
• span_end(client, run_id, span_id, status, latency_ms)
• span(client, run_id, span_type, name) → context manager

Wrap a tool call with gate checks. If denied, it raises (or returns a blocked object).

• webhook(url, payload, idempotency_key)
• email(url, payload, idempotency_key)
• charge(url, payload, idempotency_key)

• Data Analyst: market + SEC research via Google Search
• Trading Analyst: proposes strategies by risk profile
• Execution Agent: plans entry/exit execution
• Risk Evaluation: analyzes risks and mitigations

• Guardrails on side‑effects (orders, webhooks, notifications)
• Idempotency across retries
• Run ledger + receipts for auditability
• Policy‑gated HITL for risky actions

Fast to test, but no centralized registry, tenant scoping, or gateway-level policy and rate limits. Each agent must know the GitLab MCP URL and handle auth on its own.

export GITLAB_MCP_URL=https://gitlab-mcp.example.com

curl -X POST $GITLAB_MCP_URL/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "gitlab.search",
    "input": {"query": "rate limit"}
  }'

Kybernis becomes the MCP gateway. Tools are registered once, tenant-scoped, and invoked through a single endpoint with consistent auth and rate limits.

export KYB_PROTOCOL_GATEWAY=http://localhost:8080
export GITLAB_MCP_URL=https://gitlab-mcp.example.com

curl -X POST http://localhost:8080/infra/mcp/tools/register \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KYB_API_KEY" \
  -d '{
    "tenant_id": "'$KYB_TENANT_ID'",
    "name": "gitlab.search",
    "description": "Search GitLab issues and repos",
    "endpoint": "'$GITLAB_MCP_URL'/mcp/invoke",
    "input_schema": {"type":"object","properties":{"query":{"type":"string"}},"required":["query"]},
    "output_schema": {"type":"object"}
  }'

curl -X POST http://localhost:8080/mcp/invoke \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KYB_API_KEY" \
  -H "X-Kyb-Tenant-Id: $KYB_TENANT_ID" \
  -d '{
    "tool": "gitlab.search",
    "input": {"query": "rate limit"}
  }'

• POST /infra/decide
• GET /infra/runs
• GET /infra/runs/receipt

• POST /infra/graph/event
• POST /infra/graph/events/batch
• GET /infra/graph/events

• POST /infra/tasks/enqueue
• POST /infra/tasks/claim
• POST /infra/tasks/ack
• POST /infra/tasks/fail
• POST /infra/tasks/extend
• POST /infra/tasks/requeue
• GET /infra/tasks/stats

• POST /infra/fleet/register
• POST /infra/fleet/heartbeat
• GET /infra/fleet/workers
• GET /infra/fleet/utilization
• POST /infra/policies/budget
• POST /infra/policies/retry
• POST /infra/policies/allowlist
• POST /infra/policies/tool_downtime

Required fields: ksp_version, event_type, ts, tenant_id, run_id, span_id, span_type, name.

Required fields: ksp_version, event_type, ts, tenant_id, run_id, span_id, status, latency_ms.

policy.verdict, policy.reason, policy_id, retry settings, and budget limits.

prompt_tokens, completion_tokens, bytes_in/out, cpu_ms, mem_bytes_peak, cost_micros.

Shows run status, cost, and stop state. Click a run to inspect its spans and receipts.

Live view of pending/claimed tasks. Useful for dispatchers and retry tuning.

Worker heartbeats and utilization (how busy dispatchers are).

Create tokens and copy your tenant ID in Settings → API keys.