SkyKoi Runtime

The Koi runtime that powers SkyKoi. This is the npm package (skykoi) that runs on each user's dedicated EC2 instance, handling the Koi gateway, LLM inference, tool execution, and channel integrations.

npm: skykoi (latest: v2026.3.83) Platform: www.skykoi.com

What This Is

SkyKoi Runtime is a personal Koi runtime forked from SKYKOI (MIT License). It runs as a gateway process on an EC2 instance and provides:

• Real-time chat via WebSocket
• LLM inference through AWS Bedrock (Claude Opus 4.6) or any supported provider
• Tool execution (bash, browser, file operations, cron, etc.)
• Channel integrations (Discord, Telegram, WhatsApp, Slack, Signal, iMessage, and more)
• Koi workspace with persistent memory
• Self-update capability for fleet-wide rolling updates

Architecture

User (browser/app)
    |
    v  WebSocket (wss://<id>.gw.skykoi.com)
+---------------------------+
|     SkyKoi Gateway        |
|     (Node.js process)     |
|                           |
|  - WebSocket server       |
|  - Session management     |
|  - Koi runtime (Pi)       |
|  - Tool execution         |
|  - Channel routing        |
|  - Heartbeat system       |
|  - Cron scheduler         |
+---------------------------+
    |
    v  Bedrock API / Provider APIs
  LLM Inference

Key Modules

src/
  kois/           - Koi runtime, tool definitions (exec, process, browser)
  auto-reply/       - Message handling, Koi turn execution, command registry
  channels/         - Channel plugin system (Discord, Telegram, WhatsApp, etc.)
  config/           - Configuration loading, validation, schema
  cron/             - Scheduled jobs, isolated Koi turns
  gateway/          - WebSocket server, RPC handlers, session management
  infra/            - Retry logic, backoff, error handling, updates
  memory/           - Embedding-based memory with SQLite + vector search
  node-host/        - Node device management (camera, screen, location)
  providers/        - LLM provider adapters (Bedrock, Anthropic, OpenAI, Google, etc.)
  browser/          - Chrome/Chromium automation via CDP
  tui/              - Terminal UI for local development

Install

Typically installed automatically by the platform's cloud-init during EC2 provisioning:

npm install -g skykoi@latest

Running

The gateway runs as a long-lived process:

skykoi gateway --port 18789 --verbose

Or with the daemon (auto-restart on crash):

skykoi onboard --install-daemon

Configuration

Configuration lives at ~/.skykoi/skykoi.json:

{
  "koi": {
    "model": "amazon-bedrock/us.anthropic.claude-opus-4-6-v1"
  },
  "gateway": {
    "port": 18789
  }
}

On cloud instances, configuration is pushed via SSM after the instance is claimed from the warm pool. The runtime reads it on startup and connects to the platform.

Development

git clone https://github.com/ricardoamartinez/skykoi-runtime.git
cd skykoi-runtime

pnpm install
pnpm build

# Dev loop (auto-reload)
pnpm gateway:watch

Testing

pnpm test          # Full suite: 6790/7001 passing
pnpm test:config   # Config tests: 304/305 passing

Known test gaps: Worker crash cascades on Windows, browser E2E flakes.

Build

pnpm build         # Produces dist/ (26MB optimized)

The build uses SWC for compilation. tsconfig targets es2020. TypeScript has 0 errors.

How It Connects to the Platform

1. The platform provisions an EC2 instance and pushes config via SSM
2. The runtime starts and reads the config (gateway token, model settings, etc.)
3. The gateway opens a WebSocket server on the configured port
4. A wildcard TLS cert from S3 enables wss://<instanceId>.gw.skykoi.com
5. The platform's frontend connects and sends/receives messages via WebSocket RPC
6. The Koi processes messages through the LLM provider and streams responses back
7. The runtime heartbeats to the platform every 30 seconds to report health

Self-Update

The runtime can update itself in place:

skykoi gateway update

This pulls the latest npm version and restarts the gateway without losing the Koi workspace or memory. Used for fleet-wide rolling updates.

Koi Workspace

Each Koi has a workspace at ~/.skykoi/workspace/ containing:

• KOI.md - Koi behavior instructions
• SOUL.md - Personality and tone
• USER.md - User profile (built over time)
• MEMORY.md - Long-term memory
• memory/ - Daily logs and state
• BACKLOG.md - Task tracking

The Koi can modify all of these files. Updates must preserve this workspace.

Security

• Tools run on the host for the main session (full access)
• Non-main sessions (groups/channels) can be sandboxed via Docker
• DM pairing by default: unknown senders must authenticate
• Exec approval system for sensitive commands

Origins

Forked from SKYKOI (MIT License). See THIRD_PARTY_LICENSES.txt.

License

MIT