Rokha SDK

Rokha is the phone book — and the kitchen — of the agentic world. Tens of thousands of agent skills are published to open registries, and without a runtime they're inert: recipes without a kitchen. Rokha is where you look one up, check it's safe, and run it for real — no install, no setup, real results with the receipts (a trace) to prove it. The runtime is the product.

Two kinds of users, one platform: look-up users find and try tools fast (free, no account); builders chain skills into workflows (also free), then sign in to keep, publish, and compose them. Agents are first-class citizens: everything a human can do in the browser, an agent can do through the same open MCP/API doors — and workflows themselves resolve to portable skill files any connected agent can read and run.

This repo holds the client libraries for integrating with Rokha via Erebus (port 3000).

Connecting an AGENT? One line: claude mcp add --transport http rokha https://rokha.ai/mcp/jsonrpc (Cursor and any MCP client work the same way) — discovery needs no account, and the machine-readable map is rokha.ai/llms.txt. Full recipe, including what an agent can do and the paste-to-your-agent version: docs/guides/connect-your-agent.md.

Found a bug, or have an idea? See docs/guides/feedback.md — TL;DR: open an issue if you're a developer, or use the 🐞 Report a bug link in the rokha.ai footer if you'd rather not have a GitHub account (we file it for you).

Advertising inside the agent? docs/guides/advertise.md — the AdSpace board and Rokha Ads, set up in four lines.

Building a tool of your own? docs/guides/scripted-skills.md — and give it a dashboard: docs/guides/build-a-stage.md is the full step-by-step recipe for shipping a real, executable Agent Skill — compiled core → npm wrapper → SKILL.md → Rokha registry → Rig — the same pattern behind Solwatch.

Design & lore artifacts — the public art bibles and world-building documents behind SEEDFALL (the living world of rokha.ai), published for the community: aetherbytes.github.io/rokha-sdk/artifacts.

Packages

Package	Language	Path	What it is
@rokha_ai/sdk	TypeScript	sdk/typescript/	Typed HTTP client
rokha-sdk	Python	sdk/python/	Typed HTTP client
ro	Rust (CLI)	svc/rokha-cli/	The local terminal agent

Distribution status (live since 2026-08-06): everything below is published and installable today — npm i @rokha_ai/sdk, npx -y @rokha_ai/cli, cargo install rokha-cli, brew install aetherBytes/tap/rokha, or the one-line scripts/install.sh binary installer. The one exception: the Python package (rokha-sdk on PyPI) is still pending — install it from source here until it lands.

The local terminal agent (ro)

ro is a lightweight local interface to Rokha: a thin client on your machine that does no heavy lifting itself — discovery, execution, and the agent all run on the platform. Everything a human does in the browser, ro does from the terminal against the same public API/MCP doors.

ro status                 # remote reachability + schema match + login state
ro login                  # browser device-flow sign-in (RFC 8628)
ro tools list <query>     # search the live Rokha Registry (205k+ listings)
ro chat "<message>"       # one-shot chat with the Rokha agent
ro run <slug>             # run a registry skill FOR REAL in the platform sandbox
ro tui                    # live heads-up monitor (status / registry / agent)
ro mcp serve              # expose the FULL platform tool suite to any MCP host
ro mcp install            # hook the bridge into Claude Code / Claude Desktop

ro run is the product thesis from the terminal: the skill executes on a throwaway, isolated cloud sandbox (nothing installs locally, no secrets travel), progress streams live, and the trace is the receipt. Anonymous runs ride the free daily taste; logged in, runs draw from your plan's quota — the runner pays, always.

ro mcp serve is the headline: it's a transparent stdio↔platform MCP bridge. Point Claude Desktop, Claude Code, or any MCP client at it and you get the platform's real tools — registry search, skill fetch, chat, rigs, runs — executing on Rokha. Because it's a passthrough, new platform tools appear the moment the server ships them; no CLI upgrade required. Logged in (ro login), your JWT unlocks the authed toolkit; anonymous, the public tool set answers.

API Surface

All requests route through Erebus — one front door. Point the SDK at https://api.rokha.ai for the live platform, or http://localhost:3000 for a local dev stack. No direct service connections.

Path	Service	Description
/api/agents/*	Agents	Chat, tasks, models
/api/harnesses/*	Harnesses	Memory/context CRUD
/api/marketplace/registry	Rokha Registry	Listings, search, discovery
/api/runtime/*	Runtime	Run a skill for real (free taste + tier-quota run)
/api/wallets/*	Erebus	Auth, sessions
/api/v1/chat/completions · /api/v1/models	LLM Proxy	OpenAI-compatible
/api/v1/llm/proxy	LLM Proxy	Anthropic /v1/messages-shaped
/mcp/jsonrpc	MCP	MCP 2025-11-25 JSON-RPC (public + authed tools)
/api/discovery/*	Erebus	Service/tool discovery
/api/skills/*	Erebus	First-party agentskills.io skills (public, CORS-open)

Quick Start (TypeScript)

import { RokhaClient } from '@rokha_ai/sdk';

const nb = new RokhaClient({ baseUrl: 'https://api.rokha.ai' });

const status = await nb.agents.status('rokha-agent');
const tools = await nb.mcp.listTools();
const results = await nb.marketplace.search({ query: 'UI design' });

// Run a skill for real (free public taste — one per anon session/day):
const ack = await nb.runtime.taste({
  anon_session_id: crypto.randomUUID(),
  skill_provider: 'rokha',
  skill_slug: 'some-skill',
  harness_id: crypto.randomUUID(),
});

Quick Start (Python)

from rokha import RokhaClient

nb = RokhaClient(base_url="https://api.rokha.ai")

status = nb.agent_status("rokha-agent")
tools = nb.mcp_list_tools()
results = nb.search_listings(query="UI design")

Skills (cross-agent portability)

Rokha publishes agentskills.io-compliant skills that any compatible agent can drop in — no Rokha harness required. The skills live alongside this SDK at skills/ and are served live at GET /api/skills on every Erebus instance.

Browse available skills

# Live registry (CORS-open, no auth)
curl https://api.rokha.ai/api/skills | jq

# Or the public GitHub mirror
curl https://api.github.com/repos/rokha-ai/rokha-sdk/contents/skills | jq '.[].name'

Install a skill

For Claude Code (~/.claude/skills/):

mkdir -p ~/.claude/skills/rokha-audit
curl -fsSL https://raw.githubusercontent.com/rokha-ai/rokha-sdk/main/skills/rokha-audit/SKILL.md \
  -o ~/.claude/skills/rokha-audit/SKILL.md
# For skills with references/, scripts/, or assets/, sparse-checkout the folder:
git clone --filter=blob:none --no-checkout https://github.com/rokha-ai/rokha-sdk.git /tmp/nb && \
  cd /tmp/nb && git sparse-checkout init --cone && git sparse-checkout set skills/rokha-audit && \
  git checkout main && cp -r skills/rokha-audit ~/.claude/skills/

For OpenClaw (~/.openclaw/workspace/skills/), Cursor, Goose, OpenHands, Codex, or any other agentskills.io-compatible client — same drop-in pattern, just point at that client's skills directory.

Available skills

Skill	What it does
rokha-audit	Security & compliance audit for MCP tools. Three-stage flow: heuristic scan → optional sandboxed probe → harness persistence.

The layering, briefly

Layer	What	How to consume
Distribution	SKILL.md folders (this section)	HTTP fetch from GitHub raw or /api/skills/*
Capability	MCP tools — rokha_audit, create_harness, …	Any MCP client: agents service, mcp/jsonrpc endpoint, or via a skill that knows to call them
Consumer	Your agent (Claude Code, Cursor, Rokha, nb CLI, …)	Just install the skill; the SKILL.md tells your agent what to do

You don't need OpenClaw. You don't need Rokha's frontend. You don't need npm. Skill ≠ package. Drop a folder, your agent runs the workflow.