# Lloyal docs

> Lloyal is a TypeScript platform for AI apps with the model inside them — no API key, no Docker, no vector database. Create one with a single command, run it on a laptop, an office appliance or a GPU box, and ship it as an app people download.

Every page is also published as Markdown: append `.md` to its URL (for example https://docs.lloyal.ai/ship.md; the overview is https://docs.lloyal.ai/index.md).

## Start

- [Lloyal docs](https://docs.lloyal.ai/): Lloyal is a TypeScript platform for AI apps with the model inside them — no API key, no Docker, no vector database. Create one with a single command, run it on a laptop, an office appliance or a GPU box, and ship it as an app people download.
- [Quickstart](https://docs.lloyal.ai/quickstart): Create a Lloyal app, run it on your own machine, and ask it something — three commands, no API key.
- [System requirements](https://docs.lloyal.ai/system-requirements): What a machine needs to run a Lloyal harness, what the installer checks before it downloads anything, and how to install Node.js if you have never used a terminal.
- [Build your first harness](https://docs.lloyal.ai/build-your-first-harness): Create a Lloyal app from the basic template, find the program inside it, and change how it thinks: its angles, its topology, what it remembers, and what it is called.

## Build

- [Agents and orchestration](https://docs.lloyal.ai/agents): Run one agent or many over the one resident model: withSpine for a shared line of attention, agentPool with parallel, chain, fanout or dag — or your own orchestrator — and how to read what each agent found.
- [Tools](https://docs.lloyal.ai/tools): A tool is a class with a name, a description, a JSON schema and an execute generator. What the model sees of it, what it can read about the agent calling it, what it may return, and the one flag that decides whether it runs beside other agents.
- [Tool hooks and guards](https://docs.lloyal.ai/tool-hooks): Every tool call passes through five moments — may it run, was it an attempt, does the result fit, it is in, may the turn end. A hook is a plain object with an opinion at any of them; a guard refuses a call before it runs.
- [Typed Decisions from LLMs](https://docs.lloyal.ai/typed-decisions): Get a typed value back from the resident model — a number, an enum, an object — constrained by grammar so there is nothing to parse, and classify many items against one option list at the cost of one.
- [Agent policy](https://docs.lloyal.ai/agent-policy): Set the numbers every agent obeys — turns, context, time, recovery — as one budget row, and decide what happens at each boundary with hooks or a policy of your own.
- [Human approval](https://docs.lloyal.ai/human-approval): Mark a consequential tool protected, and the framework refuses it unless the session holds a grant. The model can ask; it cannot authorise. How grants are held, given and revoked, and when a new one applies.
- [Prompts](https://docs.lloyal.ai/prompts): Every word your app says to the model is an Eta file in src/harness/prompts/, read again on every render — edit it and the next question hears it. The frame, the app's two instructions, loops and branches, and what happens to a missing input.
- [Settings](https://docs.lloyal.ai/settings): Declare a setting once as data in src/config.ts and it exists everywhere: harness.yml can commit it, the dev pane lists and saves it with its provenance, and code reads it live under a running agent.
- [Models](https://docs.lloyal.ai/models): Choose the model that lives inside your app, swap it, bring your own .gguf, and know how it is fetched and verified: the catalog, the four models:* commands, the machine each model needs, and the GPU.
- [Services](https://docs.lloyal.ai/services): The models beside the reasoning model — a reranker, a vision projector, an embedder — named once in harness.yml and read with one call. What a service is, how a block enables it, what a bound one exposes, and what the boot does.
- [Retrieval](https://docs.lloyal.ai/retrieval): Admit only the passages that answer the question: chunk what a tool fetched, score every chunk with the resident reranker in one batched pass, and hand the agent the source's own words within a token budget.
- [Attachments and documents](https://docs.lloyal.ai/attachments): Let readers attach images and PDFs: bytes go to a content-addressed store, never to the model or the wire; an image is projected once for every agent; a document is searched and read, and a page is shown to the model only when an agent asks to see it.
- [The interface](https://docs.lloyal.ai/interface): How a view attaches to a harness: one fold of the harness's events into state, one provider over whichever bridge the surface has, and a handful of hooks — so the same React view runs on the desktop and in a browser, and the terminal folds the same events.
- [Testing](https://docs.lloyal.ai/testing): Test the real harness — its command loop, its agents, what it keeps on disk — over a scripted model with no weights, in milliseconds, and know what that proves and what only a real run can.

## Abilities

- [Abilities](https://docs.lloyal.ai/abilities): A packaged capability — manifest, source, tools, instructions — that any harness can install and enable, signed and reviewed. What the model learns about it, how it sits in the model's memory, and what one is made of.
- [Build an ability](https://docs.lloyal.ai/build-an-ability): Scaffold an Ability, write its manifest and useWhen, construct its source and tools in the setup, read its settings live, and declare the services it cannot work without.
- [Publish and install](https://docs.lloyal.ai/publish-and-install): Publish an Ability through the signed channel at apps.lloyal.ai, and install one: what the install verifies before it writes anything, why it takes a name and never a URL, and the attention surface a reviewer reads.
- [Security model](https://docs.lloyal.ai/ability-security): Abilities run in-process with the model, so the trust boundary is the prompt itself: the three attacks that follow — catalogue escape, cross-ability injection, unauthorised writes — and the defences built into the contract.
- [First-party abilities](https://docs.lloyal.ai/first-party-abilities): The four Abilities Lloyal ships — wikipedia, web, corpus and documents: what each lets agents do, its tools, the services it needs, its settings, and how to install one.

## Run & ship

- [Where a harness runs](https://docs.lloyal.ai/where-a-harness-runs): How one harness contract spans application surfaces, local and shared-residency execution, process boundaries, transports, hardware, and operators.
- [Ship your app](https://docs.lloyal.ai/ship): How a scaffolded harness becomes a distributable macOS application — what the packager is told, what your users meet on first launch, and what signing and notarizing actually require.
- [Serve to many users](https://docs.lloyal.ai/serve): Serve one harness to many people from your own machine or GPU box: one resident model, a session per browser, admitted in order — the command, the box's four settings, what a session holds, and when to isolate by process instead.
- [Choose where the work lives](https://docs.lloyal.ai/project-root): Run a harness whose code lives in one place and whose work — the manifest, the settings overlay, the models, the content store, what it keeps — lives in another, with LLOYAL_PROJECT_ROOT. What moves, what stays, and how the desktop app uses the same rule.
- [Debug with traces](https://docs.lloyal.ai/traces): Turn on the trace and the dev pane, read what every agent saw and did — the exact prompt, each tool call, every refusal and recovery — and go from a symptom to the event that explains it.
- [Troubleshooting](https://docs.lloyal.ai/troubleshooting): The messages a Lloyal harness can show you, in the words it uses — what each means and what to do — from installing, through the first launch, to a run that cannot continue.

## Understand

- [Structured concurrency](https://docs.lloyal.ai/structured-concurrency): Lloyal's harnesses are built on Effection, Frontside's structured concurrency library for JavaScript. What Effection guarantees, its translation from async/await, what Lloyal adds for live inference, the mistakes that compile and leak, and the rules to hand your coding agent.
- [Thinking in Lloyal](https://docs.lloyal.ai/thinking-in-lloyal): How owned lifetimes, live inference state, Agents, Tools, orchestration, finality, and continuity fit together.
- [Advanced patterns](https://docs.lloyal.ai/advanced-patterns): What the same primitives express when topology, observation, evidence flow, inference shaping, lifecycle policy, authority and continuity are composed deliberately — adaptive harnesses, direct inference programming, acceptance and continuation.
- [Continuous Context](https://docs.lloyal.ai/continuous-context): Why live inference state changes the application boundary
- [Adaptive compute through semantic pruning](https://docs.lloyal.ai/agent-policy-and-context-pressure): Adaptive compute in a running AgentPool: how policy, context pressure, effort, recovery and wind-down decide what continues. Semantic pruning removes whole branches on judgement rather than compacting the context window on arithmetic.
- [A focal lens for context admission](https://docs.lloyal.ai/focal-lens): Every candidate admitted through a reranked path got there by answering a question. The question is a sentence bound by the harness, the answer is two logits, and each available leaf group settles in one batched dispatch — the same code on a laptop and on two B200s.

## Reference

- [CLI reference](https://docs.lloyal.ai/cli): Every lloyal-ai command: scaffold a harness or an ability, manage models, surfaces and GPU backends, ship a macOS app, and install or publish signed abilities — with each command's options.
- [harness.yml](https://docs.lloyal.ai/harness-yml): Every key a harness is configured with — the model blocks, your own keys, the abilities family, where each rung reads it, what it takes, and when a change applies. Derived from the tables the keys are declared in.
- [Lookup](https://docs.lloyal.ai/lookup): Signatures, enumerations, and floors — the facts you look up mid-task. Each entry derived from current source, with the file it came from.
- [Adding a service kind](https://docs.lloyal.ai/service-kinds): For framework contributors: how a new kind of model beside the trunk is added to rig — a key in ServiceMap, its settings, one provider row, a catalog entry — and what the contract does and does not buy.