SkyKoiSKYKOIDocs
Docs/Architecture/Platform Overview

Platform Overview

SkyKoi as the orchestration layer for kois on dedicated EC2 instances.

SkyKoi sits between your business and the cloud infrastructure. It's the orchestration layer that turns "I want a koi" into a fully provisioned, dedicated server running your personal assistant.

Architecture Diagram

text
┌───────────────────────────────────────────────────┐
│                 SKYKOI PLATFORM                   │
│                                                   │
│  Dashboard ──▶ API ──▶ EC2 Provisioner            │
│      │              │                              │
│      │         Clerk Auth · Stripe Billing         │
│      │              │                              │
│      ▼              ▼                              │
│  ┌──────────────────────────────────────┐          │
│  │      AWS Infrastructure              │          │
│  │  EC2 Instances (t3.small)            │          │
│  │  IAM Instance Profiles               │          │
│  │  Security Groups                     │          │
│  │  User-Data Provisioning              │          │
│  └──────────┬───────────────────────────┘          │
│             │                                      │
│    ┌────────┼────────┐                             │
│    ▼        ▼        ▼                             │
│  ┌────┐  ┌────┐  ┌────┐  Dedicated Instances      │
│  │EC2 │  │EC2 │  │EC2 │  (1 per user)             │
│  │ #1 │  │ #2 │  │ #3 │                           │
│  └────┘  └────┘  └────┘                           │
│    │        │        │                             │
│  Koi   Koi    Koi  (Claude Opus 4.6          │
│                           via AWS Bedrock)         │
└───────────────────────────────────────────────────┘

What SkyKoi Manages

  • •EC2 Provisioning — Launches dedicated t3.small instances with Ubuntu 22.04 and a user-data script that installs everything automatically
  • •Config Generation — config-generator.ts creates valid koi config with Bedrock model config, token auth, and Gateway settings
  • •Workspace Provisioning — Seeds koi workspaces with KOIS.md, SOUL.md, USER.md, TOOLS.md, and IDENTITY.md
  • •TLS & Networking — nginx reverse proxy with self-signed TLS (port 443 → localhost:18789)
  • •IAM & Security — Instance profile skykoi-tenant-koi-profile for Bedrock access, security groups for network control
  • •Billing — Maps Stripe subscriptions to resource allocation and usage tracking
  • •Monitoring — Tracks Gateway health, koi status, and token usage

What the Koi Runtime Handles

  • •Gateway Daemon — Long-lived systemd service managing the WebSocket API, message routing, and session state
  • •Koi Runtime — Claude Opus 4.6 via AWS Bedrock with workspace files, JSONL sessions, tools (exec/read/write/browser/etc.), and skills
  • •Message Processing — Queuing, debouncing, streaming, block chunking, and delivery
  • •Automation — Heartbeats, cron jobs, and proactive koi actions
  • •Tool Execution — Full shell access (exec.security: "full"), web browsing, file operations, and more

💡SkyKoi adds the business layer (auth, billing, provisioning, monitoring) on top of the koi engine. The koi runtime provides full-featured capabilities out of the box.

NextKoi Runtime →