How It Works

SkyKoi is an orchestration layer on top of a powerful Gateway architecture. Understanding the stack helps you get the most out of your agent.

The Stack

┌─────────────────────────────────────────┐
│  SkyKoi Dashboard (Next.js 14)         │ ← You interact here
│  Clerk Auth · Stripe Billing · RBAC     │
│  Hosted on Vercel                       │
└────────────────┬────────────────────────┘
                 │ SkyKoi API
                 ▼
┌─────────────────────────────────────────┐
│  EC2 Provisioner                        │
│  Launches t3.small · User-data script   │
│  IAM Instance Profile · Security Group  │
└────────────────┬────────────────────────┘
                 │ Dedicated EC2 Instance
                 ▼
┌─────────────────────────────────────────┐
│  Ubuntu 22.04 (t3.small, us-east-1)     │
│  nginx (self-signed TLS, port 443)      │
│  → reverse proxy to localhost:18789     │
├─────────────────────────────────────────┤
│  Koi Gateway (systemd)        │
│  skykoi-gateway.service                │
│  WebSocket API on port 18789            │
│  Token-based auth                       │
├─────────────────────────────────────────┤
│  Agent Runtime                          │
│  Claude Opus 4.6 via AWS Bedrock        │
│  Model: amazon-bedrock/us.anthropic.    │
│         claude-opus-4-6-v1              │
│  Tools: exec/read/write/browser/etc.    │
│  Workspace: /home/ubuntu/koi/         │
│  Config: Koi agent configuration (Koi config)      │
│  Sessions: JSONL transcripts            │
└─────────────────────────────────────────┘

The Gateway

The Gateway is a single long-lived process that runs as a systemd service. It listens on port 18789 (localhost) and is reverse-proxied through nginx on port 443 with self-signed TLS. The Gateway exposes a typed WebSocket API, handles session routing, message queuing, and delivery.

The Gateway validates inbound frames against JSON Schema, emits events (agent, chat, presence, health, heartbeat, cron), and handles authentication via token-based auth.

The Agent Runtime

The Koi runs a single embedded agent runtime. The agent uses Claude Opus 4.6 via AWS Bedrock (amazon-bedrock/us.anthropic.claude-opus-4-6-v1) — not the Anthropic API directly. The instance's IAM profile (skykoi-tenant-agent-profile) provides Bedrock access without API keys.

The agent has a workspace directory at /home/ubuntu/koi/ containing persona files (AGENTS.md, SOUL.md, USER.md, TOOLS.md, IDENTITY.md) and memory files. Sessions are stored as JSONL transcripts.

On each session start, the agent receives injected workspace files as context, then processes messages using Claude Opus 4.6 with full tool access. The agent can read/write files, execute shell commands, browse the web, search the internet, analyze images, generate speech, manage cron jobs, and spawn sub-agents.

Sessions

The agent runtime treats one direct-chat session per agent as primary. Direct chats collapse to agent:<agentId>:main, while group/channel chats get isolated keys. Sessions support daily reset (default 4:00 AM), idle reset, per-type overrides, and manual reset via /new or /reset.

Configuration

The Gateway reads JSON5 config from /home/ubuntu/.skykoi/skykoi.json with strict schema validation. Key config includes gateway.mode: "local", token-based auth, and the Bedrock model configuration. SkyKoi's config-generator.ts creates this config automatically during provisioning.