Koshi | Terminal-Native Decentralized SNS

Features

Why Koshi?

💻

Terminal-Native

No browser bloat. Everything from posting to DMing is handled natively within your command line. Perfect with tmux or Zellij.

🔐

Cryptographic Identity

Your identity is your ed25519 public key. Secure authentication without passwords — every action is cryptographically signed.

⚡

Real-Time Feed

WebSocket-powered live updates. Connect to the stream and see posts, DMs, and presence changes as they happen.

📝

Signed Posts

Every post carries an ed25519 signature, ensuring authenticity. Verify authorship without trusting a central authority.

✉️

Direct Messages

Signed, authenticated DMs with real-time delivery via WebSocket. Every message is verifiable and tamper-proof.

💬

Real-Time Chat

Interactive DM chat mode with live WebSocket messaging. Connect to any user and chat in real-time with cryptographic signatures.

✏️

Profile Editing

Update your display name, bio, and avatar URL directly from the CLI with the kb edit-profile command.

🛠️

Admin Controls

Built-in admin system with user management, account deletion with cascade, and admin privilege grants via dedicated API endpoints.

🔑

Nostr Protocol

Full Nostr integration: generate/manage nsec/npub keys, push koshi posts to Nostr relays, pull events from the Nostr network. Cross-post seamlessly between koshi and Nostr.

🖧

P2P Sync

Hypercore-powered peer-to-peer synchronization. Your posts and DMs are replicated across connected peers via hyperswarm DHT. No central server needed for data distribution.

👥

Multi-Account

Manage multiple identities from a single CLI. Switch between accounts with kb switch, register or import Nostr keys per account. All credentials stored securely in ~/.config/koshi/config.json.

👥

Group Chats (E2EE)

End-to-end encrypted group messaging with Sender Keys. Create groups, invite members, share images/files. All groups are always E2EE — server never sees plaintext.

🔐

X3DH Key Management

Full X3DH protocol support for E2E encryption. Register devices, fetch key bundles, manage one-time prekeys. Ready for Signal-style double ratchet.

📱

TypeScript SDK

First-class TypeScript types for client developers. import { Group, DM, Device, WSEventMap } from '@ryopc/koshi/types' — build your own client with full type safety.

⌨️

Typing Indicators

Real-time typing start/stop events for both DMs and group chats. See when others are typing via WebSocket.

✅

Read Receipts

Unified read receipts for DMs and group messages. Delivered via WebSocket for instant cross-device sync.

Quick Start

Get started in seconds

# Install Koshi globally
$ npm install -g @ryopc/koshi

# Register a new account (generates ed25519 keypair)
$ kb register alice
✔ Registration successful!

# Post to the koshi board
$ kb post "Hello, koshi! 🌊"
✔ Post created!

# View your feed
$ kb feed --limit=10
📋 Koshi Board Feed (3 posts)

# Connect to real-time stream
$ kb realtime
📡 Connecting to realtime feed...
✓ Connected! Waiting for new posts...

# Start local server (Web UI + P2P mesh + WebSocket)
$ kb serve
🖥️  koshi server — serverless P2P node
Web UI:  http://127.0.0.1:3000

Full installation guide →

Architecture

How Koshi works

🔧

Stack

Runtime Node.js 20+

Framework Express.js

Database SQLite (default) / PostgreSQL

Auth ed25519 + JWT

Real-time WebSocket (ws)

CLI Chalk + Ora

📁

Project Structure

koshi/

├── bin/

├── cli.js # CLI entry point (kb command)

└── server.js # Express + WS server (PostgreSQL mode)

├── src/

├── local/ db.js, api.js, server.js, p2p-bridge.js # Serverless SQLite+P2P

├── api/ auth.js, users.js, posts.js, dms.js

├── auth/ ed25519.js, jwt.js, utils.js

├── db/ schema.sql, migrate.js, pool.js

├── ws/ index.js, handlers.js

├── p2p/ hypercore + hyperswarm mesh

├── nostr/ nsec/npub, relay push/pull

└── middleware/ auth.js, rateLimit.js

├── client/ # React Web UI (Vite)

├── web/ # Built static files for serving

├── Dockerfile

├── render.yaml # Render Blueprint

└── package.json

CLI

All Commands

Command	Description	Auth
`kb register`	Create a new account with ed25519 keypair	No
`kb login`	Authenticate using existing keypair	No
`kb whoami`	Show your profile information	Yes
`kb post`	Create a new post on the board	Yes
`kb feed [--limit=N]`	Display your post feed	Opt
`kb follow`	Follow a user	Yes
`kb unfollow`	Unfollow a user	Yes
`kb dm`	Send a direct message	Yes
`kb dms [--unread]`	View your direct messages	Yes
`kb chat`	Interactive real-time DM chat	Yes
`kb edit-profile`	Update your display name, bio, avatar	Yes
`kb profile [username]`	View a user's profile	Opt
`kb search`	Search users by username	Opt
`kb groups [list\|create\|delete\|info]`	Manage groups (E2EE group chats)	Yes
`kb group members [add\|remove\|list]`	Manage group members	Yes
`kb devices [list\|remove]`	Device management for E2E (X3DH)	Yes
`kb keys [rotate\|bundle]`	Key management (X3DH bundles)	Yes
`kb config set`	Configuration management	Yes
`kb admin promote`	Promote user to admin	Admin
`kb realtime`	Connect to the live event stream	Yes
`kb serve [--port=N] [--daemon]`	Start local serverless node (SQLite+P2P+Web UI)	No
`kb connect`	Connect to a remote server / --reset for local mode	No
`kb admin`	Admin: users, delete-user, grant, revoke	Admin
`kb p2p`	P2P node: status, sync, peers	No
`kb nostr`	Nostr: key, relay, push, pull	Yes

Full CLI reference with examples →

CLI Reference

Nostr Integration

kb nostr key generate

Generate a new Nostr secp256k1 keypair (nsec/npub) and save to the active account config.

$ kb nostr key generate
✔ Nostr keypair generated and saved!

  npub: npub1...
  nsec: nsec1...

kb nostr key import

Import an existing Nostr secret key (nsec1... or 64-char hex).

$ kb nostr key import nsec1...

kb nostr key show

Display current Nostr keys, relay list, and sync timestamps.

$ kb nostr key show
  🔑 Nostr Keys
  npub: npub1...
  nsec: nsec1abc... (truncated)
  Relays: 4 件設定
  Last Push: 7/14/2026, 2:30:00 PM
  Last Pull: 7/14/2026, 2:35:00 PM

kb nostr npub

Output only the public key (npub) for sharing.

kb nostr relay list

List configured Nostr relays.

$ kb nostr relay list
  🌐 Nostr Relays (4件)
    1. wss://relay.damus.io
    2. wss://relay.nostr.band

kb nostr relay add

Add a relay URL to the active account.

$ kb nostr relay add wss://relay.example.com
✓ リレーを追加しました: wss://relay.example.com

kb nostr relay remove

Remove a relay from the active account.

kb nostr relay test [url]

Test relay connectivity and measure latency. Without URL, picks from configured relays interactively.

$ kb nostr relay test wss://relay.damus.io
✓ wss://relay.damus.io  Latency: 120ms

kb nostr push [--limit=20]

Publish recent koshi posts to Nostr relays as kind 1 events with k: koshi tag.

$ kb nostr push --limit=20
✔ 5/20 posts published to Nostr!

  📡 Relay Results:
    • wss://relay.damus.io ✓ 5 published
    • wss://relay.nostr.band ✓ 5 published

kb nostr pull [--limit=50]

Fetch Nostr events from relays (filtered by your pubkey) and display in koshi format.

$ kb nostr pull --limit=50
✔ Found 12 Nostr events!

  📡 Nostr Events (12件)
  ────────────────────────────────────────────
  nostr:a1b2c3d4 ...
  Hello from Nostr!

kb nostr status

Show Nostr configuration status (keys, relays, last sync times).

CLI Reference

P2P Sync

kb p2p start [--foreground] [--stop] [--status]

Start the P2P node. Runs as background daemon by default.

# Background daemon (default)
$ kb p2p start
✔ P2P node started in background!
  PID: 12345
  Log: ~/.config/koshi/p2p.log

# Foreground (debug)
$ kb p2p start --foreground
✔ P2P node started!
  Status: Running  Posts: 42  DMs: 12  Peers: 3

# Check background status
$ kb p2p start --status
✓ P2P node running (PID: 12345)

# Stop background node
$ kb p2p start --stop
✔ P2P node stopped (PID: 12345)

kb p2p status

Show P2P node status (running/stopped, posts, DMs, peers, discovery key, storage path).

$ kb p2p status
  Status:     Running
  Posts:      42
  DMs:        12
  Peers:      3
  Username:   alice
  Discovery:  0123456789abcdef...
  Storage:    ~/.config/koshi/corestore

kb p2p sync [--limit=20]

Display posts synced from the P2P mesh (aggregated from all peer cores).

$ kb p2p sync --limit=20
  📡 P2P Synced Posts (15 件)
  ────────────────────────────────────────────
  alice  2:30:00 PM
  Hello, koshi! 🌊

kb p2p dms [--limit=20]

Display DMs synced from the P2P mesh (decrypted where possible).

$ kb p2p dms --limit=20
  ✉️ P2P Synced DMs (3 件)
  ────────────────────────────────────────────
  alice → bob  2:35:00 PM
  Hey Bob!

kb p2p stop

Stop an in-process P2P node (foreground mode). For background daemon, use kb p2p start --stop.

The social network for your terminal.

Why Koshi?

Terminal-Native

Cryptographic Identity

Real-Time Feed

Signed Posts

Direct Messages

Real-Time Chat

Profile Editing

Admin Controls

Nostr Protocol

P2P Sync

Multi-Account

Group Chats (E2EE)

X3DH Key Management

TypeScript SDK

Typing Indicators

Read Receipts

Get started in seconds

How Koshi works

Stack

Project Structure

All Commands

Nostr Integration

kb nostr key generate

kb nostr key import

kb nostr key show

kb nostr npub

kb nostr relay list

kb nostr relay add

kb nostr relay remove

kb nostr relay test [url]

kb nostr push [--limit=20]

kb nostr pull [--limit=50]

kb nostr status

P2P Sync

kb p2p start [--foreground] [--stop] [--status]

kb p2p status

kb p2p sync [--limit=20]

kb p2p dms [--limit=20]

kb p2p stop

The social network
for your terminal.