Architecture Overview

This page maps Kilo Code's repository-defined architecture. It introduces the local runtime, editor clients, cloud service boundaries, and hosted execution products before the subsystem pages add implementation detail.

{% callout type="info" title="Scope" %} Use these pages for stable system boundaries and contributor-wide contracts. Source code remains the reference for feature-level implementation details. Static source shows code paths and deployable surfaces, not production enablement, traffic, retention, or vendor configuration. {% /callout %}

How to read these pages

Choose the path closest to the change you are making:

Repository boundaries

Architecture pages cross two repositories:

Three architecture layers

Local execution and hosted execution are separate boundaries. Editor clients use a local kilo serve server. Hosted automation can launch Cloud Agent execution sessions when cloud coding work is required.

Terms used throughout

Core execution spine

The three layers appear in two primary execution shapes: local client requests and hosted cloud work.

flowchart LR
  subgraph clients ["Local clients"]
    tui["Kilo CLI TUI"]
    run["kilo run"]
    console["Kilo Console"]
    editors["VS Code and JetBrains"]
  end

  subgraph local ["Local Kilo CLI boundary"]
    daemon["Local daemon manager"]
    server["kilo serve server"]
    runtime["Kilo CLI runtime"]
    router["Provider router"]
  end

  subgraph cloud ["Kilo Cloud shared services"]
    web["Web control plane"]
    workers["Automation Workers, queues, and Durable Objects"]
    gateway["Kilo Gateway"]
    agent["Cloud Agent"]
  end

  trigger["Hosted product or automation trigger"]
  repos["Repositories"]
  models["Model providers and external gateways"]

  tui -->|"daemon attach when available"| server
  tui -->|"worker-backed fallback"| runtime
  run -->|"attach when available"| server
  run -->|"embedded fallback"| runtime
  console -->|"starts or reuses"| daemon
  daemon -->|"owns detached child"| server
  editors -->|"start editor-owned child over HTTP + SSE"| server
  server --> runtime --> router
  router -->|"direct provider"| models
  router --> gateway --> models

  trigger --> web
  trigger --> workers
  web --> workers --> agent
  web --> agent
  agent --> repos
  agent --> models

Two execution paths

This distinction is central: using editor does not move coding session into Cloud Agent. Cloud services also route model requests, deliver chat events, dispatch notifications, serve generated applications, and coordinate adjacent hosted boundaries without launching Cloud Agent.

Adjacent hosted boundaries

The core execution spine is not the full cloud product catalog. These service families and hosted runtimes attach to it for specific product flows:

flowchart LR
  web["Web control plane"]
  workers["Automation Services"]
  agent["Cloud Agent"]
  builder["App Builder"]
  preview["Generated-application preview"]
  deploy["Generated-application deployment"]
  security["Security Agent"]
  chat["Kilo Chat, events, and notifications"]
  claw["KiloClaw"]
  town["Gas Town"]
  wasteland["Wasteland"]

  web --> workers --> agent
  web --> builder --> agent
  builder --> preview
  builder --> deploy
  web --> security
  security -->|"optional deep analysis"| agent
  web --> claw
  chat --> claw
  web --> town --> wasteland

Local entry points and clients

These local surfaces live in Kilo-Org/kilocode. Package paths below are relative to that repository root.

Cloud service families

Hosted service families live in Kilo-Org/cloud. Paths below are relative to that repository root unless another repository is named.

Supporting packages

These supporting packages also live in Kilo-Org/kilocode. Package paths below are relative to that repository root.

Architecture pages

Development pages

After system-boundary pages, continue with Development Patterns for implementation rules. Use CLI Config Schema when changing config keys or editor-facing schema publication.

Related pages

• CLI Runtime - local runtime, server, routing, persistence, and SDK contracts
• Cloud Platform - hosted layers, Cloud Agent topology, and adjacent hosted boundaries
• Cloud Security - cross-cutting trust boundaries, controls, and shared responsibility
• Development Patterns - code-ownership decisions and contributor workflow
• Development Environment - setup guide
• Ecosystem - related projects and integrations
• KiloClaw Overview - customer-facing KiloClaw docs