Cloud Platform Architecture

Kilo Cloud is hosted platform layer for authentication, model routing, billing, product configuration, automation, and scoped execution services. Cloud implementation lives in open-source Kilo-Org/cloud repository.

How to use this page

Use this page to understand hosted service topology: which product boundaries exist, where long-running work executes, and how hosted runtimes relate. For trigger-to-execution workflows, continue to Automation Services. For trust boundaries and controls, continue to Cloud Security.

Hosted layers

Where these pages say owner, they mean personal user or organization that authorizes scoped product state and credentials.

Cloudflare terms

Product topology

flowchart LR
  clients["Browser, editor, and mobile clients"]
  web["Web control plane"]
  gateway["Kilo Gateway"]
  automation["Automation Workers"]
  agent["Cloud Agent"]
  chat["Kilo Chat / Event Service / Notifications"]
  town["Gas Town"]
  wasteland["Wasteland"]
  repos["GitHub and GitLab repositories"]
  providers["Model providers and gateways"]
  stores["PostgreSQL, Durable Objects, queues, R2, KV, and analytics stores"]

  clients --> web
  clients --> gateway
  web -. "short-lived connection ticket" .-> clients
  clients -->|"ticketed WebSocket"| chat
  web --> automation --> agent
  web --> agent
  agent --> repos
  agent --> providers
  town --> repos
  town --> providers
  town --> wasteland
  gateway --> stores
  agent --> stores
  chat --> stores
  wasteland --> stores

Not every hosted flow launches Cloud Agent. Shared services also route model requests, deliver chat events, and dispatch notifications.

Service families

Kilo Gateway

Gateway consists of cloud API routes plus packages/kilo-gateway/ client integration in Kilo-Org/kilocode. It handles account-aware and anonymous-free model access. See Cloud Security for request branches and endpoint families.

Auto Model clients send stable kilo-auto/* tier IDs. Gateway resolves tiers server-side before provider routing so mappings can change without client releases. See Models and Providers for current tier behavior.

Eligible gateway requests can include normalized project label for usage attribution and grouping. Label identifies project without sending full repository URL.

Cloud Agent

services/cloud-agent-next/ is current Cloud Agent session runtime. Each launched unit is a Cloud Agent execution session. Runtime uses queue-first orchestration and session messages.

Every Cloud Agent execution session receives separate workspace and home paths. Policy-selected sandbox allocation is not universally one container per session.

flowchart TB
  callers["Web control plane and automation Workers"]
  session["CloudAgentSession Durable Object"]
  sandbox["Sandbox"]
  small["SandboxSmall"]
  dind["SandboxDIND"]
  ingest["Session Ingest binding"]
  tokens["Git Token Service binding"]
  notify["Notifications binding"]
  r2["R2 session bucket"]
  db["Hyperdrive -> PostgreSQL"]
  callback["Callback queue"]
  report["Report queue"]
  dlq["Report dead-letter queue"]

  callers --> session
  session --> sandbox
  session --> small
  session --> dind
  session --> ingest
  session --> tokens
  session --> notify
  session --> r2
  session --> db
  session --> callback
  session --> report --> dlq

services/cloud-agent-next/wrangler.jsonc defines these bindings. Presence in Wrangler config proves deployable topology, not active production allocation counts or rollout policy.

Automation boundaries

Automation Services owns trigger, owner-scope, queue, callback, output, and recovery details. This table only shows how automation relates to hosted platform.

Webhook Agent Ingest

services/webhook-agent-ingest/ is configured-trigger boundary. It accepts HTTP webhooks and scheduled alarms, then dispatches a Cloud Agent session. Automation Services owns activation, authentication, queue, and alarm details.

Security Agent

Security Agent keeps finding sync, analysis dispatch, and sandbox execution separate.

flowchart TB
  github["GitHub Dependabot API"]
  postgres["PostgreSQL<br/>Security Agent state"]

  subgraph sync ["Finding sync"]
    direction LR
    interactive["Interactive web sync"] --> web["Web Security Agent handler"] --> github
    cron["security-sync<br/>six-hour cron"] --> queue["Owner-level sync queue"] --> tokens["Git Token Service binding"] --> github
    github --> postgres
  end

  subgraph analysis ["Analysis"]
    direction LR
    postgres -->|"Queued analysis row"| worker["security-auto-analysis"] --> triage["Model gateway triage"] --> deep{"Deep analysis needed?"}
    deep -->|"Yes"| agent["Cloud Agent<br/>deep analysis"] --> callback["Finding-scoped callback"] --> postgres
    deep -->|"No"| postgres
  end

  subgraph cleanup ["Stale-analysis cleanup"]
    direction LR
    cleanupCron["Web cleanup cron"] --> reconcile["Reconcile stale running findings<br/>without active queue work"] --> postgres
  end

PostgreSQL holds owner-scoped findings, analysis queue rows, owner pause or block state, Security Agent configuration, and audit records. See Automation Services for queue lifecycle and its static-source limitation, and Cloud Security for trust boundaries.

Chat events and notifications

sequenceDiagram
  participant Client as Browser or mobile client
  participant Ticket as Event Service ticket API
  participant Events as Event Service
  participant Session as UserSessionDO
  participant Chat as Kilo Chat conversation-state DOs
  participant Notify as NotificationChannelDO
  participant Expo
  participant Queue as Receipt queue

  Client->>Ticket: Request short-lived connection ticket
  Ticket-->>Client: Return short-lived ticket
  Client->>Events: Open WebSocket with ticket
  Events->>Session: Register presence
  Chat->>Events: Fan out conversation event
  Events-->>Client: Deliver WebSocket event
  Chat->>Notify: Request selected conversation push
  Notify->>Events: Check presence context
  Events-->>Notify: Return presence context
  alt User already present
    Notify-->>Chat: Suppress push
  else Push needed
    Notify->>Expo: Send push
    Expo-->>Notify: Return receipt
    Notify->>Queue: Enqueue receipt
    Queue->>Notify: Process receipt and stale-token cleanup
  end

Kilo Chat stores conversation state in Durable Objects and fans events out through Event Service. Notifications checks Event Service presence context before selected pushes and processes Expo receipts asynchronously. See Cloud Security for ticket and push-delivery trust boundaries.

Gas Town and Wasteland

Gas Town is multi-agent orchestration for coding work on repositories. TownDO owns town state and TownContainerDO owns town container execution. Active town work uses 5-second alarm cadence. Idle towns use 5-minute cadence.

Gas Town binds separate wasteland Worker through WASTELAND_SERVICE. Wasteland uses WastelandDO and WastelandRegistryDO Durable Objects and DoltHub-backed collaborative commons paths.

flowchart LR
  town["Gas Town TownDO"]
  container["TownContainerDO"]
  binding["WASTELAND_SERVICE binding"]
  wasteland["Wasteland Worker"]
  dos["WastelandDO and WastelandRegistryDO"]
  dolt["DoltHub-backed collaborative commons"]

  town --> container
  town --> binding --> wasteland --> dos --> dolt

Observability

services/o11y/ is current metrics and alert infrastructure. Higher-order agent outcome analysis remains roadmap work unless backed by separate implementation.

Source map

Paths below are relative to Kilo-Org/cloud.

Related pages

• Architecture Overview - local and hosted execution map
• Automation Services - trigger-to-execution workflows, queue ownership, callbacks, and recovery
• Cloud Security - trust boundaries, persistence, controls, privacy, and shared responsibility
• Development Patterns - choose code-ownership seam before changing architecture-facing contracts