# SkyKoi Runtime

The Koi runtime that powers [SkyKoi](https://www.skykoi.com). 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](https://www.skykoi.com)

## What This Is

SkyKoi Runtime is a personal Koi runtime forked from [SKYKOI](https://github.com/nicepkg/SKYKOI-runtime) (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:

```bash
npm install -g skykoi@latest
```

## Running

The gateway runs as a long-lived process:

```bash
skykoi gateway --port 18789 --verbose
```

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

```bash
skykoi onboard --install-daemon
```

## Configuration

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

```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

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

pnpm install
pnpm build

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

### Testing

```bash
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

```bash
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:

```bash
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](https://github.com/nicepkg/SKYKOI-runtime) (MIT License). See [THIRD_PARTY_LICENSES.txt](./docs/THIRD_PARTY_LICENSES.txt).

## License

MIT
