Architecture overview

0. Host split

The host split separates the product package, app-facing SDK, Desktop Host bridge, and App Server runtime substrate. Lime Desktop remains a full multi-app workspace, but it is no longer the mandatory way to launch every Agent App. Standalone and runtime-backed apps still use the same Capability SDK boundary and App Server bridge profile.

flowchart TD
  App["Agent App Package<br/>UI / Worker / Workflow / App Backend"] --> SDK["@lime/app-sdk"]
  App --> AppStorage["App-local storage<br/>namespace / schema / migrations"]
  SDK --> Host["Host Bridge / Desktop Host IPC"]
  Host --> SharedState["Shared host user state<br/>user / tenant / workspace / theme"]
  Host --> SharedCaps["Shared host capabilities<br/>files / model settings / secrets / billing"]
  Host --> Server["App Server JSON-RPC"]
  Server --> Runtime["RuntimeCore / services<br/>Agent / Storage / Secrets / Policy / Evidence / Tools"]
  Runtime --> StorageBoundary["Storage boundary<br/>host DB separate; app DB/schema isolated"]
  Runtime --> Desktop["Lime Desktop<br/>multi-app workspace"]
  Runtime --> Shell["Lime App Shell<br/>standalone branded app"]
  Runtime --> Backed["Runtime-backed shell<br/>uses system lime-runtime"]
  Runtime --> Web["Compatible Web Host"]
  Desktop --> User["User"]
  Shell --> User
  Backed --> User
  Web --> User

This page collects the key structural, install-mode, requirement-boundary, and runtime diagrams for Agent App in one place. The specification defines rules; this page renders them. Desktop host implementations such as lime-desktop-platform must also satisfy Desktop host conformance.

Agent Apps depend only on Capability SDK / Host Bridge semantics. Desktop Host IPC, App Server JSON-RPC, RuntimeCore, services, and ExecutionBackend are host-side fact sources; app packages must not access those internals directly. User state and host capabilities are shared as host projections; app storage and app backend services remain isolated by app, workspace, and tenant.

1. Standard layers

The standard layers split delivery across App, Host, Cloud, connector, external-system, and human-decision planes, with an explicit App Server bridge profile across Lime Desktop, Lime App Shell, runtime-backed shells, and compatible web hosts. The layered manifest and Capability SDK are the stable app-facing boundaries; hosts and the Cloud control plane stay on contracts and never on business implementation.

flowchart TD
  subgraph Cloud[Cloud / Registry control plane]
    Catalog[App Catalog]
    Release[Release metadata]
    Tenant[Tenant enablement]
    Reg[Registration / License]
  end

  subgraph Standard[Agent App standard]
    APPMD[APP.md frontmatter + sections]
    LAYERED[app.*.yaml layered config]
    BOUNDARY[requirements / boundary / integrations / operations]
    INSTALL[app.install.yaml / install modes]
    SKILLS[skills/ bundled Skills]
    EVALS[evals/ readiness + health]
    SIG[app.signature.yaml]
    I18N[app.i18n.yaml + locales]
  end

  subgraph Host[Host runtime - Lime Desktop / lime-desktop-platform]
    Discover[Discovery & trigger routing]
    Verify[Signature & hash verify]
    Project[Projection]
    Readiness[Readiness self-check]
    SDK[Capability SDK bridge]
    Bridge[Host Bridge v1]
    IPC[Desktop Host IPC]
    Server[App Server client / JSON-RPC]
    Core[RuntimeCore / services]
    TaskSvc[Agent / Workflow service]
    StorageSvc[Storage service]
    ArtifactSvc[Artifact / Evidence service]
    ToolSvc[Tool / Knowledge service]
    Policy[Policy / permission]
    Health[Health monitoring]
  end

  subgraph Package[App runtime package]
    UI[dist/ui]
    Worker[dist/worker]
    Workflow[workflows/]
    Storage[(storage namespace)]
    Artifacts[artifacts/ + evidence]
  end

  Catalog --> Discover
  Release --> Verify
  Tenant --> Policy
  Reg --> Policy

  APPMD --> Discover
  LAYERED --> Project
  BOUNDARY --> Project
  BOUNDARY --> Readiness
  INSTALL --> Project
  INSTALL --> Readiness
  SKILLS --> SDK
  EVALS --> Readiness
  EVALS --> Health
  SIG --> Verify
  I18N --> SDK

  Verify --> Project
  Project --> Readiness
  Readiness --> SDK
  SDK --> Bridge
  SDK --> Policy
  Bridge --> IPC
  IPC --> Server
  Server --> Core
  Core --> TaskSvc
  Core --> StorageSvc
  Core --> ArtifactSvc
  Core --> ToolSvc
  Core --> Policy
  Bridge --> UI
  SDK --> Worker
  SDK --> Workflow
  SDK --> Storage
  SDK --> Artifacts
  Health --> Readiness

2. Responsibility matrix

Layer	Owns	Does not own
Cloud / Registry	catalog, release metadata, tenant enablement, registration, license, ToolHub metadata	app execution, UI rendering, local storage
Host runtime	discovery, signature verify, projection, readiness, SDK injection, Host Bridge, policy, cleanup	business logic, customer data, vertical rules
App runtime	UI, workers, workflows, storage business code, artifact, evidence write-back	model / tool / credential / permission scheduling (must go through the SDK)
Standard (agentapp)	manifest schema, reference CLI, SDK contract, best practices	concrete host or app implementations

3. Requirement-boundary architecture

This view answers the product and delivery question: what can the App do, and what requires Lime Host, Lime Cloud, connectors, external systems, or human confirmation.

flowchart LR
  User[End user] --> App[Agent App\nUX / Workflow / Artifact / Review]
  App --> Host[Lime Host\nLocal Agent / MCP / CLI / Tools / Files / Policy]
  App --> Cloud[Lime Cloud\nRegistry / Tenant Policy / OAuth / Webhook / Sync]
  Host --> Connector[Connector / Tool Adapter\nMCP / CLI / API / Browser]
  Cloud --> Connector
  Connector --> External[External System\nDocs / Tables / Drives / Publishing / CRM]
  App --> Human[Human Decision\nReview / Publish / High-risk approval]
  External --> App
  Human --> App

sequenceDiagram
  autonumber
  participant User as End user
  participant App as Agent App
  participant Host as Lime Host
  participant Cloud as Lime Cloud
  participant Conn as Connector
  participant Ext as External System

  User->>App: Choose business flow
  App->>Host: Request capability profile and readiness
  Host->>Cloud: Query connector registry, tenant policy, OAuth state
  Cloud-->>Host: Return allowed capabilities and missing setup
  Host-->>App: Return ready / needs-setup / blocked
  App-->>User: Show required connection or authorization items
  User->>Host: Authorize connector or confirm risky action
  App->>Host: Start workflow / agent task
  Host->>Conn: Controlled MCP / CLI / API / tool invocation
  Conn->>Ext: Read or write external source of truth
  Ext-->>Conn: Structured result
  Conn-->>Host: Result + logs + side-effect status
  Host-->>App: Result + evidence refs
  App-->>User: Show artifact and next step

flowchart TD
  Start([Sanitized business requirement]) --> Split[Split into requirement items]
  Split --> Classify[Classify as App / Host / Cloud / Connector / External / Human]
  Classify --> Fit{Good Agent App fit?}
  Fit -- No --> Explain[Explain need for external system, cloud service, or manual flow]
  Fit -- Yes --> Scope[Define MVP / non-goals / later phases]
  Scope --> Files[Write requirements / boundary / integrations / operations]
  Files --> Ready{Dependent capabilities ready?}
  Ready -- No --> Setup[Connect, authorize, install tool, or enable cloud capability]
  Setup --> Ready
  Ready -- Yes --> Run[Run app workflow]
  Run --> Risk{High-risk side effect?}
  Risk -- Yes --> Review[Human confirmation + evidence]
  Risk -- No --> Save[Save artifact + evidence]
  Review --> Save
  Save --> Done([Accepted delivery])

4. Install and launch sequence

End-to-end flow from Cloud bootstrap → local download → verify → projection → readiness → launch.

sequenceDiagram
  autonumber
  participant User
  participant Cloud as Cloud catalog
  participant Host as Lime Desktop
  participant Pkg as App package
  participant SDK as Capability SDK
  participant App as App UI

  User->>Cloud: Browse or request app (with keywords)
  Cloud-->>Host: bootstrap payload + triggers
  User->>Host: Choose to install
  Host->>Pkg: Download package
  Host->>Host: Verify packageHash + sigstore + revocation
  Host->>Pkg: Parse APP.md + app.*.yaml + evals/*.yaml
  Host->>Host: Build projection (with provenance)
  Host->>Host: Run evals/readiness.yaml three-tier check
  alt Required checks fail
    Host-->>User: Show needs-setup + setupActions
    User->>Host: Complete setup (bind knowledge / grant permission / set secret)
    Host->>Host: Re-run readiness
  end
  User->>Host: Launch quickstart.entry
  Host->>SDK: Inject capability handles
  Host->>App: Initialize UI (iframe / native)
  App->>Host: app:ready
  Host-->>App: host:snapshot (theme / locale / entry context)
  App->>SDK: capability:invoke (business call)
  SDK-->>App: host:response or host:error

5. Readiness flow

evals/readiness.yaml runs three tiers (required / recommended / performance) and produces five states.

flowchart TD
  Start([App launch request]) --> Required{required all pass?}
  Required -- No --> Blocker{any blocker?}
  Blocker -- Yes --> Blocked[blocked<br/>list blockers + setupActions]
  Blocker -- No --> NeedsSetup[needs-setup<br/>list setupActions]
  Required -- Yes --> Recommended{recommended all pass?}
  Recommended -- No --> Degraded[ready-degraded<br/>list warnings]
  Recommended -- Yes --> Performance{performance ok?}
  Performance -- No --> Degraded
  Performance -- Yes --> Ready[ready<br/>allow launch]
  Blocked --> SetupFlow{user completes setup?}
  NeedsSetup --> SetupFlow
  SetupFlow -- Yes --> Required
  SetupFlow -- No --> Stop([abort launch])
  Degraded --> Launch[launch with warnings]
  Ready --> Launch

6. Host Bridge v1 sequence

App UI and Host exchange events through lime.agentApp.bridge; all capability calls go through capability:invoke and the host decides allow or deny.

sequenceDiagram
  autonumber
  participant App as App iframe
  participant Bridge as Host Bridge v1
  participant Policy as Policy / readiness
  participant Cap as Capability handler

  App->>Bridge: app:ready
  Bridge-->>App: host:snapshot (theme / locale / entry context / capability summary)
  Note over App,Bridge: Theme or locale change
  Bridge-->>App: theme:update
  Note over App,Bridge: Business call
  App->>Bridge: capability:invoke (capability, method, args, requestId)
  Bridge->>Policy: Check allowlist / readiness / policy
  alt Allowed
    Policy-->>Bridge: Pass
    Bridge->>Cap: Route to capability handler
    Cap-->>Bridge: Result + traceId + evidenceId
    Bridge-->>App: host:response (requestId, value)
  else Denied
    Policy-->>Bridge: Deny (error code)
    Bridge-->>App: host:error (requestId, code, message)
  end
  Note over App,Bridge: Surface hidden
  Bridge-->>App: host:visibility { visible: false }

7. Capability invocation topology

capability:invoke requests are routed to capability handlers; each capability has its own permission, policy, and evidence boundary.

flowchart LR
  AppUI[App UI / Worker] -->|capability:invoke| Bridge[Host Bridge v1]
  Bridge --> Allow{Allowlist + Readiness + Policy}
  Allow -- Deny --> Err[host:error stable code]
  Allow -- Allow --> Router[Capability router]
  Router --> UI[lime.ui]
  Router --> Storage[(lime.storage)]
  Router --> Files[lime.files]
  Router --> Agent[lime.agent]
  Router --> Knowledge[(lime.knowledge)]
  Router --> Tools[lime.tools]
  Router --> Artifacts[(lime.artifacts)]
  Router --> Workflow[lime.workflow]
  Router --> Evidence[(lime.evidence)]
  Router --> Secrets[(lime.secrets)]
  Storage --> Evidence
  Agent --> Evidence
  Tools --> Evidence
  Artifacts --> Evidence

8. Workflow state machine example

Workflow descriptors keep a state machine and add a mermaid diagram and unified recovery policy. The example below is the Content Factory content_scenario_planning workflow.

stateDiagram-v2
  [*] --> input_topic
  input_topic: user-input
  input_topic --> analyze_topic
  analyze_topic: agent-task<br/>entry=content_ideation<br/>timeout=60s
  analyze_topic --> generate_scenarios
  analyze_topic --> show_error_and_retry: onError
  generate_scenarios: agent-task
  generate_scenarios --> human_review
  human_review: human-review
  human_review --> save_calendar: approve
  human_review --> generate_scenarios: modify
  human_review --> input_topic: reject
  save_calendar: storage-write
  save_calendar --> create_artifact
  create_artifact: artifact-create
  create_artifact --> [*]
  show_error_and_retry --> analyze_topic

9. Package file dependency

APP.md is the discovery entry; layered files are loaded by file-name convention and form the projection input together.

flowchart LR
  APPMD[APP.md frontmatter] --> Discover
  APPMD --> Sections[Body sections<br/>When to Use / Red Flags / Verification]
  Sections --> Onboarding[First-launch onboarding]

  APPMD --> Capabilities[app.capabilities.yaml]
  APPMD --> Entries[app.entries.yaml]
  APPMD --> Permissions[app.permissions.yaml]
  APPMD --> Errors[app.errors.yaml]
  APPMD --> I18N[app.i18n.yaml]
  APPMD --> Sig[app.signature.yaml]
  APPMD --> Runtime[app.runtime.yaml]
  APPMD --> Req[app.requirements.yaml]
  APPMD --> Boundary[app.boundary.yaml]
  APPMD --> Integrations[app.integrations.yaml]
  APPMD --> Operations[app.operations.yaml]

  Capabilities --> Project[Projection]
  Entries --> Project
  Permissions --> Project
  Errors --> Project
  I18N --> Project
  Sig --> Verify[Signature & revocation]
  Runtime --> Project
  Runtime --> AgentRT[lime.agent task control plane]
  Req --> Project
  Boundary --> Project
  Integrations --> Readiness
  Operations --> Readiness

  APPMD --> Readiness[evals/readiness.yaml]
  APPMD --> Health[evals/health.yaml]
  Readiness --> ReadyCheck[Readiness self-check]
  Health --> HealthCheck[Health monitoring]

  APPMD --> Skills[skills/<name>/SKILL.md]
  Skills --> AgentRT

  APPMD --> Locales[locales/*.json]
  Locales --> I18N

10. Upgrade and rollback

Older manifests continue to work in compatible hosts; the reference CLI provides migrate-check / migrate-generate.

flowchart LR
  oldManifest[older manifest] -->|host reads directly| currentHost[compatible host]
  oldManifest -->|migrate-check / migrate-generate| currentManifest[current manifest]
  currentManifest --> currentHost
  currentHost -. failure .-> Rollback[Rollback to previous version]
  Rollback --> oldManifest

11. Further reading

Specification: rules, fields, and constraints.
Quickstart: build a package from scratch.
Runtime model: host implementation detail.
Capability SDK: stable capability call contract.
Latest update: concise version notes.

Architecture overview ​

0. Host split ​

1. Standard layers ​

2. Responsibility matrix ​

3. Requirement-boundary architecture ​

4. Install and launch sequence ​

5. Readiness flow ​

6. Host Bridge v1 sequence ​

7. Capability invocation topology ​

8. Workflow state machine example ​

9. Package file dependency ​

10. Upgrade and rollback ​

11. Further reading ​