You already know this architecture

The closest familiar analogy is MVC with a live language model as the Model:

product surfaces are the Views;
the harness—ordinary TypeScript—is the Controller;
a resident model holds the live generative state.

The analogy continues into the serving layer. Rails separated the application from the server that happened to run it. Lloyal separates the harness from the surface, process boundary, and host that happen to carry it.

Rails	Lloyal	Architectural role
Views	CLI, desktop, web, and future mobile surfaces	Presentation does not own the intelligent procedure.
Controller	The harness	Ordinary code governs topology, evidence, policy, authority, completion, and continuity.
Model	Resident model and live inference state	The model is inside the application boundary rather than behind an endpoint.
Rack	`@lloyal-labs/binding`	One interface between every harness and every surface or transport.
`config.ru`	Generated placement driver	The harness and host do not need to import or understand one another.
Puma	`@lloyal-labs/host`	Multiple Sessions share one resident weight set while retaining isolated context and lifecycle.
Unicorn	Process-isolated serving shape	Stronger OS-process isolation in exchange for duplicated residency.
Gems	Signed AgentApps	Installable capabilities composed into the harness.
`rails new`	`npx harness.dev new`	Scaffold the application and its conventional wiring.

The load-bearing Rails lesson is not the nouns. It is the separation:

Where the harness runs is a deployment decision, not an application decision.

Read the full Rails analogy

One application contract

Every harness exposes the same headless shape:

TypeScript

export function* harness<E, C>(
  ctx: SessionContext,
  events: EventBus<E>,
  commands: Signal<C, void>,
): Operation<void>

The harness owns the intelligent procedure. It accepts typed commands, emits typed events, and runs over an injected model context. The surface and placement bind to that contract rather than redefining it.

Flow

surface
   ↓ commands
harness(ctx, events, commands)
   ↓ events
surface

Unlike Rack's request/response cycle, this contract is a stream. A live harness may emit tokens, Agent lifecycle events, Tool progress, pressure changes, and results while a Session remains active.

Convention below, code at the centre

harness.dev generates the repetitive wiring: targets, bindings, runners, and build configuration. Harness authors work at the centre—the procedure and domain rules that are genuinely theirs.

That is convention over configuration with an intentional boundary:

Infrastructure is conventional. Intelligent behaviour remains code.

Surface is not placement

Several independent choices are often collapsed into one word such as “deployment.” Keep them separate.

SurfaceWhere does the user interact?

CLI, desktop, web; mobile is planned.

Execution familyHow is the harness instantiated?

Local edge runner or shared-residency host.

TransportHow do events and commands cross the cut?

Native render, NDJSON, IPC, WSS.

LocationWhere is compute physically placed?

User laptop, private workstation, on-prem box, cloud GPU host.

OperatorWho controls the compute?

Self-hosted today; paved BYOC and managed workflows are planned.

Compute classHow much model can it carry?

Laptop, appliance, single GPU, multi-GPU frontier host.

A browser does not imply a public cloud. It may connect over WSS to a host on the same laptop, a private network, an on-prem appliance, or a GPU box. Likewise, “local” does not force an in-process surface: the scaffolded web target runs a browser against a local resident-model host.

Two execution families

01 · Local edge

Model on user-controlled compute

CLI or desktop surface
        ↕
local runner
        ↓
SessionContext + resident model

Use local edge for offline or zero-egress operation, user-owned data and compute, a single-user application, or the lowest operational surface area.

02 · Shared residency

One model, isolated Sessions

clients ─ WSS ─ host
               ├ Session A
               ├ Session B
               └ Session C

The host loads a model once and gives each admitted Session its own context, KV/recurrent state, configuration, Agent population, and structured lifetime.

The host is the Puma side of the analogy: density through multiplexing. A process-isolated shape is the Unicorn side: stronger kernel isolation, but each process pays its own residency. The harness contract remains unchanged either way.

Shifting the harness left

Endpoint architecture

application → network → model endpoint

Lloyal

surface → harness + AgentApps + live inference → placement

That changes the unit a developer builds and deploys. It is no longer merely an inference endpoint that another application must orchestrate. It is the intelligent application itself—its topology, Tools, evidence rules, policy, authority, completion, and continuity intact.

The runtime owns KV tenancy, branch sharing, Continuous Tree Batching, scheduling, and accelerator execution beneath the harness. Application code owns what those mechanics mean.

Read “Shifting the harness left”

Where the Rails analogy bends

The Model runs

An Active Record model is silent until called. A resident language model may continuously produce and react inside a Session. The binding is therefore a bidirectional event/command stream rather than a request cycle.

The Model forks

Agents inherit shared decoded state and diverge into application-owned lineages. Topology is part of the program, not a server-side implementation detail.

The Model persists differently

Physical attention state is tied to its model and runtime configuration. Portable Session continuity is based on accepted logical state that can be reconstructed, with physical snapshots treated as optional accelerators.

Placement portability and durability are distinct:

Placement portability means the same harness contract can run elsewhere.
Output reattach reconnects a surface to a Session that is still live.
Session rehydration reconstructs accepted state after the original runtime has gone.
Mid-execution recovery reconstructs an active multi-branch graph.

The first is part of the platform shape today. The durability planes remain staged work and should not be inferred merely from placement independence.

Choose a placement

Need	Start with
Fastest path from scaffold to working application	Local CLI or desktop
Offline, private, or user-owned inference	Local edge
A browser over compute on the same machine	Local host + web target
A browser over private or on-prem compute	Shared-residency host over WSS
Several Sessions sharing a large model	Shared-residency host
Maximum OS-process isolation	Process-isolated serving shape
Frontier open-weight models	Multi-GPU host
On-device mobile inference	Planned React Native / JSI placement
One-command managed or BYOC deployment	Planned `harness.dev deploy`

Current and planned

Current Available now

harness.dev new with CLI, desktop, and web targets;
one headless harness contract across those surfaces;
native render, IPC, NDJSON, and WSS binding shapes;
local resident-model execution;
shared-residency hosting with per-Session state isolation;
signed AgentApps composed into the harness.

Planned Not yet paved

on-device mobile through @lloyal-labs/lloyal-react-native;
a first-class harness.dev deploy workflow;
managed and BYOC provisioning as developer-facing modes;
complete served output reattachment and Session rehydration;
full mid-execution graph recovery;
process-isolated serving as an equally paved front door.

The harness is the application. Placement wraps it; placement does not redefine it.

Where a harness runs