Kilo Cloud Security Architecture

This page gives contributors and customer security reviewers a high-level view of Kilo Cloud security architecture. It covers logical topology, trust boundaries, data flows, persistence, execution isolation, external integrations, and shared responsibility.

Executive overview

Kilo Cloud combines web control plane with Cloudflare-hosted services and scoped execution environments.

• Browser, editor, and mobile clients connect to public application, gateway, and event surfaces.
• Vercel-hosted Next.js application provides account management, organization authorization, billing, product configuration, and API orchestration.
• Cloudflare Workers provide feature-specific ingress, service bindings, queue-backed workflows, durable coordination, real-time streams, and selected sandbox orchestration.
• Managed PostgreSQL stores relational control-plane records. Durable Objects, queues, KV, R2, and feature-specific analytical stores hold scoped state.
• Cloud Agent coding sessions run in Cloudflare sandbox containers with session-specific workspaces and policy-selected sandbox allocation.
• Generated-app preview and deployment builds run in boundaries separate from Cloud Agent coding sessions.
• KiloClaw assistant instances run in owner-scoped provider-backed runtimes with instance-scoped storage and encrypted configuration delivery.
• Gas Town binds to Wasteland as separate multi-agent orchestration boundary.

Logical topology

flowchart LR
  subgraph customer["Customer and Internet-controlled inputs"]
    clients["Browser, editor, and mobile clients"]
    repos["Customer repositories"]
    integrations["Webhooks, email, push, and source-control events"]
  end

  subgraph public["Public ingress"]
    webEdge["Web application edge"]
    gateway["Model gateway routes"]
    cloudEdge["Feature-specific Worker ingress"]
    deployEdge["Deployment dispatcher"]
  end

  subgraph control["Control and service layer"]
    web["Web and API application"]
    workers["Cloud service Workers"]
    chat["Kilo Chat / Event Service / Notifications"]
    async["Queues and Durable Objects"]
  end

  subgraph execution["Scoped execution"]
    agent["Cloud Agent policy-selected sandbox"]
    preview["App Builder preview sandbox"]
    build["Deployment builder sandbox"]
    claw["Owner-scoped KiloClaw runtime"]
    town["Gas Town Town container"]
    wasteland["Wasteland commons boundary"]
  end

  subgraph stores["Managed persistence"]
    postgres["Managed PostgreSQL"]
    durable["Durable Object state"]
    objects["R2 object storage"]
    analytics["Analytics and operational stores"]
  end

  subgraph providers["External providers"]
    model["Model gateways and providers"]
    source["Source-control providers"]
    messaging["Expo, Gmail, and messaging providers"]
    telemetry["Monitoring and telemetry providers"]
  end

  clients --> webEdge --> web
  clients --> gateway --> model
  clients --> cloudEdge
  integrations --> cloudEdge
  clients --> deployEdge
  web --> workers
  workers --> async --> durable
  workers --> chat
  workers --> agent
  workers --> preview
  workers --> build
  workers --> claw
  workers --> town --> wasteland
  agent --> repos
  agent --> source
  agent --> model
  claw --> model
  chat --> messaging
  web --> postgres
  workers --> postgres
  workers --> objects
  workers --> analytics
  web --> telemetry
  workers --> telemetry

Trust boundaries

Identity and access

Web control plane uses JWT-backed application sessions and supports multiple sign-in methods. Repository-supported providers include Google, Apple, GitHub, GitLab, Discord, LinkedIn OpenID Connect, WorkOS enterprise SSO, and email magic links.

Kilo Cloud uses several authorization contexts:

• Browser sessions for web product use.
• Signed bearer tokens for non-browser clients and selected cloud services.
• Organization membership and role checks for tenant-scoped operations.
• Administrative authorization for restricted operations.
• Internal service credentials, callback tokens, and Cloudflare service bindings.
• Short-lived one-time Event Service connection tickets.
• Provider-specific signature or token checks on supported external ingress.

Application records commonly scope to user or organization. Cloud Agent durable state scopes to session while sandbox allocation remains policy-selected. KiloClaw runtime scopes to owner or instance rather than global assistant process.

Data and persistence

Core data flows

Model request gateway

Gateway exposes endpoint families for chat API kinds, autocomplete, transcription, embeddings, catalogs, anonymous free access, custom LLM endpoints, and BYOK routing.

Authenticated and anonymous requests diverge after model eligibility and free-model limit checks.

flowchart TB
  client["Client model request"]
  route["Gateway route and API-kind validation"]
  free["Eligible free model?"]
  auth["Valid account auth?"]
  signed["Authenticated account / organization context"]
  ip["IP-derived anonymous context anon:{ip}"]
  reject["Reject paid unauthenticated request"]
  limits["Free-model rate limit and usage log"]
  provider["Managed, BYOK, custom, or configured provider routing"]
  usage["Usage and billing metadata"]

  client --> route --> free
  free -->|yes| limits --> auth
  free -->|no| auth
  auth -->|yes| signed --> provider
  auth -->|no, eligible free| ip --> provider
  auth -->|no, paid| reject
  provider --> usage

Static source details:

• Paid model requests require authentication.
• Anonymous access applies only to eligible free models.
• Anonymous context derives from request IP and uses synthetic ID format anon:{ip_address}.
• Free-model requests use rate limits. General path checks IP-based usage; server-side feature traffic from Cloudflare IPs can use user-based limits.
• Anonymous free requests also use promotion limit by IP.
• free_model_usage records support limits. apps/web/vercel.json defines hourly cleanup cron and cleanup route code removes rows older than seven days in batches.

Seven-day cleanup is code-defined retention path, not proof of live retention execution. Validate deployed cron and database policy before external retention claim.

Cloud Agent session

sequenceDiagram
  participant Client
  participant Web as Web control plane
  participant Service as Cloud Agent
  participant State as CloudAgentSession DO
  participant Sandbox as Policy-selected sandbox
  participant Source as Source-control provider
  participant Model as Model gateway or provider

  Client->>Web: Start authorized coding task
  Web->>Service: Create scoped session
  Service->>State: Persist admitted work and metadata
  Service->>Sandbox: Prepare workspace and execution environment
  Sandbox->>Source: Fetch authorized repository content
  Sandbox->>Model: Send configured model request
  Sandbox-->>State: Stream session events
  State-->>Client: Replay and stream authorized output

Every Cloud Agent execution session receives separate workspace and home paths. Policy-selected sandbox allocation is not universally one container per session. Default allocation may share owner-scoped sandbox across sessions; selected organization flows may use per-session sandbox; devcontainer flows use per-session DIND sandbox. See Cloud Agent for canonical topology, isolation matrix, and binding inventory.

Generated application preview and deployment

flowchart LR
  prompt["App Builder prompt"]
  coding["Cloud Agent coding and iteration"]
  preview["app-builder PreviewDO"]
  previewSandbox["Preview Sandbox container"]
  builder["deploy-infra/builder DeploymentOrchestrator"]
  buildSandbox["Deployment build Sandbox container"]
  dispatcher["deploy-infra/dispatcher public wildcard ingress"]
  app["Dispatched generated app"]

  prompt --> coding --> preview --> previewSandbox
  coding --> builder --> buildSandbox --> dispatcher --> app

App Builder orchestrates prompt-driven product flow. Cloud Agent owns coding and iteration only. services/app-builder/ owns preview routing and preview sandbox; services/deploy-infra/builder/ owns deployment build sandbox; services/deploy-infra/dispatcher/ owns public deployed-app ingress. See App generation boundaries for canonical phase topology. Deployment builder config enables Sentry instrumentation; static source currently includes sendDefaultPii: true. Treat deployment telemetry payload shape, masking, access, and retention as review item, not assumed privacy property.

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 bearer-authenticated connection ticket
  Ticket-->>Client: Return short-lived ticket
  Client->>Events: Open WebSocket with ticket
  Events->>Session: Register per-user 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 delayed receipt
    Queue->>Notify: Process receipt and stale-token cleanup
  end

Kilo Chat binds to Event Service and Notifications. Event Service consumes one-time tickets before WebSocket upgrade and places connections in per-user Durable Objects. Notifications service uses per-user Durable Objects, checks presence context for conversation pushes, sends Expo push, and processes delayed receipts. See Chat, events, and notifications for canonical service topology.

KiloClaw ingress

flowchart TB
  subgraph ingress ["Public and external ingress"]
    direction LR
    browser["Browser request"] --> jwt["JWT validation"]
    code["One-time code"] --> access["Access gateway form"]
    machine["Runtime machine"] --> machineAuth["API key + gateway token"]
    chat["Kilo Chat RPC binding"]
    email["Cloudflare Email Routing"] --> parse["Alias lookup + bounded parse"]
    gmail["Gmail Pub/Sub push"] --> oidc["Google OIDC validation"]
  end

  subgraph coordination ["KiloClaw coordination"]
    direction LR
    proxy["KiloClaw proxy"]
    scope["Resolve owner or instance scope"]
    instance["Owner- or instance-scoped<br/>Durable Object"]
    redeem["Hyperdrive-backed redemption<br/>Auth cookie + derived gateway token"]
    controller["/api/controller/checkin"]
    emailQueue["Inbound email queue"]
    gmailQueue["Gmail delivery queue"]
    platform["KiloClaw platform delivery"]
    controllerDelivery["KiloClaw controller delivery"]
  end

  runtime["Provider-backed runtime"]
  ui["OpenClaw UI"]

  jwt --> proxy --> scope
  access --> redeem --> scope
  machineAuth --> controller --> scope
  chat --> scope
  parse --> emailQueue --> platform --> scope
  oidc --> gmailQueue --> controllerDelivery --> scope
  scope --> instance --> runtime
  scope --> ui

KiloClaw separates lifecycle coordination from runtime process. Fly is provider path and legacy fallback, docker-local supports development, and Northflank support exists in provider model. Active rollout must be checked in live environment. See KiloClaw for canonical runtime topology.

Gas Town and Wasteland

Gas Town and Wasteland are separate trust boundaries. Gas Town owns town state and container execution. It calls Wasteland through WASTELAND_SERVICE binding; Wasteland owns separate Durable Objects and DoltHub-backed collaborative commons paths. See Gas Town and Wasteland for canonical topology and orchestration concepts.

Security Agent sync and cleanup

Security Agent interactive web sync and scheduled Worker sync are separate paths. services/security-sync config defines six-hour cron, owner-level queue, Hyperdrive access, and Git Token Service binding. apps/web/vercel.json defines stale cleanup every 15 minutes. Cleanup marks stale running findings failed only when no matching queue row remains pending or running. Static source does not prove scheduled sync enqueues newly synced findings for auto-analysis.

See Cloud Platform for topology and Automation Services for queue ownership.

Observability

Observability is a security-review boundary because operational metrics and exports can contain customer-linked identifiers and diagnostic content. services/o11y/ defines Worker-backed metrics, alerts, Analytics Engine datasets, Pipeline streams, R2 Parquet export infrastructure, KV cooldown state, and AlertConfigDO. See Observability for canonical topology. Active providers, access, filtering, and retention require live validation.

Higher-order agent outcome analysis is roadmap work unless separate source proves implementation.

Security controls summary

Third-party integration categories

Privacy logging and retention

Kilo Cloud includes user soft-delete flows that anonymize direct user PII, invalidate auth material, delete many user-owned records and integrations, remove selected object-storage content, and request deletion from selected downstream services. Financial, audit, anti-abuse, and product-specific records can have retention exceptions.

Operational telemetry can contain customer-linked identifiers and diagnostic content. Telemetry-enabled product surfaces can also submit assistant-response feedback with limited correlation metadata. Production access, filtering, retention, and vendor config remain required review areas. Pay special attention to deployment-builder Sentry payloads, mobile diagnostics, replay masking, screenshots, object storage, Durable Object state, vector stores, analytical stores, runtime volumes, and backups.

Data paths vary by product and enabled integration. State residency and retention commitments require validation against live production inventory.

Shared responsibility

Kilo Cloud provides platform controls for auth, scoped authorization, internal-service separation, durable coordination, execution isolation, and protected handling of supported secrets.

Customers remain responsible for decisions that expand enabled trust boundaries:

• Repositories, organizations, users, and source-control installations they authorize.
• Models, BYOK credentials, custom endpoints, and optional integrations they enable.
• Setup commands, repository code, MCP servers, and third-party tools they permit inside isolated session or owner-scoped runtime.
• Customer-configured endpoints and credentials meeting customer security, privacy, and compliance needs.
• Generated changes reviewed before merge or deployment.

Related pages

• Architecture Overview - local and hosted execution map
• Cloud Platform - hosted layers, Cloudflare terms, Cloud Agent topology, and adjacent hosted runtimes
• Automation Services - trigger-to-execution workflows, queue ownership, callbacks, and recovery
• Development Patterns - choose code-ownership seam before changing architecture-facing contracts