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"]
  preview["App Builder preview"]
  deployBuilder["Deployment builder"]
  deployEdge["Deployment dispatcher"]
  claw["KiloClaw"]
  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
  web --> preview
  web --> deployBuilder --> deployEdge
  web --> claw
  chat --> claw
  agent --> repos
  agent --> providers
  claw --> providers
  town --> repos
  town --> providers
  town --> wasteland
  gateway --> stores
  agent --> stores
  preview --> stores
  deployBuilder --> stores
  claw --> stores
  chat --> stores
  wasteland --> stores

Not every hosted flow launches Cloud Agent. Shared services also route model requests, deliver chat events, dispatch notifications, serve generated applications, and coordinate owner-scoped runtimes.

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.

App generation boundaries

App Builder is product orchestration, not normal automation ingress.

flowchart TB
  prompt["User prompt"] --> web["Web App Builder orchestration"] --> coding["Cloud Agent<br/>coding and iteration"]

  subgraph previewBoundary ["Preview boundary: services/app-builder/"]
    direction LR
    worker["app-builder Worker"] --> repo["GitRepositoryDO"] --> preview["PreviewDO"] --> previewSandbox["Preview Sandbox container"]
  end

  subgraph deployBoundary ["Deployment build boundary: services/deploy-infra/builder/"]
    direction LR
    builder["Deployment builder"] --> orchestrator["DeploymentOrchestrator"] --> buildSandbox["Deployment build Sandbox container"]
  end

  subgraph ingressBoundary ["Public ingress boundary: services/deploy-infra/dispatcher/"]
    direction LR
    dispatcher["Public wildcard ingress"] --> app["Dispatched generated application"]
  end

  coding --> worker
  coding --> builder
  buildSandbox --> dispatcher

Webhook Agent Ingest

services/webhook-agent-ingest/ is configured-trigger boundary. It accepts HTTP webhooks and scheduled alarms, then dispatches selected Cloud Agent or Kilo Chat destination. 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.

KiloClaw

KiloClaw is owner-scoped hosted OpenClaw runtime coordination. Durable Objects track instance lifecycle, routing, configuration, and reconciliation. Runtime provider support includes Fly, docker-local development, and Northflank paths; source support does not prove active provider rollout. See Cloud Security for ingress controls.

KiloClaw resolves owner or instance scope before runtime delivery. Table compares ingress boundaries; it does not describe global shared destinations.

Fly-provider topology example

flowchart TB
  subgraph worker ["Cloudflare Worker"]
    direction LR
    auth["JWT auth<br/>tied to Kilo user"]
    instanceDO["Per-instance Durable Object"]
    dbConnection["Kilo database connection"]
  end

  db["Kilo database<br/>Instances<br/>Short-lived access codes<br/>Image catalog<br/>Billing and user preferences"]
  proxy["Fly proxy<br/>Per-user Fly app<br/>Per-user encryption<br/>Routes to pinned instance"]

  subgraph flyInstance ["Fly instance: owner-scoped runtime"]
    direction TB
    subgraph container ["KiloClaw container"]
      direction TB
      controller["KiloClaw controller<br/>Supervises OpenClaw gateway<br/>Exposes control endpoints<br/>Proxies HTTP and WebSocket traffic"]
      openclaw["OpenClaw<br/>Gateway and Control UI"]
      tools["Pre-installed tools and skills"]
      controller --> openclaw
      tools --> openclaw
    end
    volume["Persistent Fly volume<br/>/root/.openclaw config<br/>/root/clawd workspace"]
    volume --> openclaw
  end

  dbConnection <--> db
  worker <--> proxy
  proxy <--> controller

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