# Telo

> Define how your app works. Telo builds and runs it.

- [Examples](https://telo.run/examples.md)

## Learn

- [Getting Started](https://telo.run/learn/getting-started.md): Install Telo, write a minimal YAML manifest, run it, and understand what the kernel did — loading, resolving references, initializing resources, and dispatching targets.
- [Your first HTTP API](https://telo.run/learn/first-http-api.md): Build a working HTTP API in Telo: a server, a router, a validated request, a typed response, and configuration bound to the environment. About fifteen minutes.
- [How Telo works](https://telo.run/learn/how-telo-works.md): The mental model behind Telo: manifests, resources and kinds, capabilities, the multi-pass init loop, where side effects live, and why a manifest stays statically analyzable.
- [!ref and !cel](https://telo.run/learn/refs-and-cel.md): The two YAML tags that carry everything dynamic in a Telo manifest: !ref to point at a resource, !cel to compute a value, what is in scope where, and the errors you meet first.
- [Embedding files](https://telo.run/learn/embedding-files.md): !include-text and !include-bytes embed a file that ships beside your manifest — fonts, artwork, SQL, prompts — with the path checked statically and the file added to your published artifact automatically.
- [Catching errors early](https://telo.run/learn/static-analysis.md): What telo check finds before your application runs — unknown kinds, broken references, CEL type errors — what it cannot see, and how to debug the rest.
- [Composing behaviour](https://telo.run/learn/composing-behaviour.md): Orchestrate work declaratively with Run.Sequence, Run.Choice and Run.Value: steps, branching, loops, error handling, and when a script is genuinely the right answer.
- [Durable execution](https://telo.run/learn/durable-execution.md): Make a body of steps survive process death: record progress as it runs so a crash and a restart continue where the work stopped, wait for days without holding a process, and know exactly which regions may re-run.
- [Talking to a database](https://telo.run/learn/talking-to-a-database.md): Connect a Telo application to SQL: a connection, migrations, injection-safe statements with !sql, repository handlers without hand-written SQL, and all-or-nothing transactions.
- [Configuring an application](https://telo.run/learn/configuration.md): Bind an application to its environment and command line with variables, secrets and ports, pass values into imported libraries, and keep one place that reads the host.
- [Logging basics](https://telo.run/learn/logging-basics.md): Every Telo application logs with no configuration. Set the level, drive it from an environment variable, and understand why secrets never reach the log.
- [Libraries](https://telo.run/learn/libraries.md): Share and reuse manifests: writing a Telo.Library, importing it by relative path or as a published module, choosing what it exports, and splitting a file with include.
- [Declaring a need](https://telo.run/learn/declaring-a-need.md): Ask whoever runs a module for what it depends on — a database, a signing key — as a typed need, supplied at the import, whole or field by field, or read from the environment at the root.
- [Providing needs](https://telo.run/learn/providing-needs.md): Provision what an application needs before starting it: read the needs report, set one environment variable per field, and know how each variable is named, read and checked.
- [Workspaces](https://telo.run/learn/workspaces.md): Declare a repo as a Telo workspace with telo-workspace.yaml: one module cache, where modules live and publish, which paths are not release-relevant, and how far a run may look for .env files.
- [Editing against a telo version](https://telo.run/learn/editor-telo-version.md): Which telo version an editor checks your manifests against: Auto picks one per module from requires: telo:, a telo.version pin fixes it, and the chosen version's own engine produces every diagnostic, completion and quick fix.
- [Installation & CLI](https://telo.run/learn/installation-and-cli.md)
- [Packaging an application](https://telo.run/learn/packaging-an-app.md): Ship a Telo application as one executable with telo package: what the payload carries, which controllers can travel, how arguments and .env reach it, and how to read a packaged binary.
- [Distributing an application](https://telo.run/learn/distributing-an-application.md): Publish a Telo application to an OCI registry, attach your own annotations, understand why a published version's pin never moves, and run the application by its pinned ref.
- [Coming from somewhere else](https://telo.run/learn/coming-from.md): Telo mapped onto the models you already have — a web framework, Kubernetes, or Terraform — and honest answers to the questions each one raises.
- [Compared to low-code platforms](https://telo.run/learn/vs-low-code.md): How Telo compares to n8n, Dify, Windmill, Node-RED, Zapier, Retool and OutSystems — what each one builds, who owns the artifact, and when another platform is the better choice.
- [What you get for free](https://telo.run/learn/what-you-get.md): The features a Telo application gets without writing them — request cancellation, graceful shutdown, configuration you can see, checks a compiler cannot make — and what the standard library adds on top.
- [Style Guide](https://telo.run/learn/style-guide.md): Naming conventions for Telo identifiers, kinds, imports, and variables to ensure CEL expression correctness
- [Glossary](https://telo.run/learn/glossary.md): Short definitions for the vocabulary the Telo documentation assumes: manifest, resource, kind, capability, controller, module, reference, and the rest.

## Build

- [Overview](https://telo.run/build.md): How to author a Telo manifest — the editor, AI-assisted authoring, and the test loop that keeps changes safe.
- [Telo Studio](https://telo.run/build/studio.md): A web and desktop editor for authoring Telo manifests visually — topology canvas, resource inventory, raw YAML, and an integrated runner.
- [VS Code extension](https://telo.run/ide/vscode.md)
- [Working with coding agents](https://telo.run/build/coding-agents.md): Connect Claude Code, Cursor, or any MCP-aware editor to the Telo hub so the LLM can discover modules and author manifests against the real surface.
- [Testing your manifests](https://telo.run/build/testing.md): Test Telo manifests with Telo manifests — Run.Sequence drives the test, Assert.* checks the result, and the telo CLI runs it.
- [Logging](https://telo.run/build/logging.md): Structured logging in Telo: levels, choosing sinks and their durability, per-dependency verbosity, redaction, sampling, emitting from a controller, and shipping records to OTLP.
- [Tracing](https://telo.run/build/tracing.md): Tracing in Telo: turning span export on with trace sinks, reading spans as log records or shipping them to an OpenTelemetry collector, putting contract values on a span, and opening spans from a controller.

## Deploy

- [Overview](https://telo.run/deploy.md): How to deploy a Telo manifest — Docker image (recommended), AWS Lambda for serverless, or the bare telo CLI under a process supervisor.
- [Docker image](https://telo.run/deploy/docker.md): Package a Telo manifest as an OCI container using the telorun/node base image, with a build stage that warms the controller cache so production boots offline.
- [AWS Lambda](https://telo.run/deploy/lambda.md): Package a Telo manifest as an AWS Lambda function — the managed and custom runtime bootstraps, handler kinds per event source, and the packaging flow.
- [Running in production](https://telo.run/deploy/production.md): Process lifecycle, signal handling and shutdown, exit codes, health checks, a Kubernetes deployment, and every environment variable the runtime reads.
- [Upgrades & version skew](https://telo.run/deploy/upgrades.md): Two things move independently in a deployed Telo app — the module pins in imports: and the kernel image that runs them. How requires: ties them together, what telo upgrade holds back, and the order that never strands one behind the other.
- [Security & supply chain](https://telo.run/deploy/security.md): What a Telo module can reach on your host, how import pins and layer digests are verified end to end, how secrets are handled, and how to lock down egress.

## Extend

- [Overview](https://telo.run/extend/sdk.md)
- [Authoring a Module](https://telo.run/extend/authoring-a-module.md): Add new resource kinds to Telo — declare a Telo.Definition, implement a controller, and wire them together so the kernel can run your kind.
- [Templated Definitions](https://telo.run/extend/templated-definitions.md): Define a new resource kind without writing a controller — compose existing kinds declaratively with a dispatch body (resources, invoke/provide/run/mount, targets, inputs, result).
- [Kind Inheritance](https://telo.run/extend/kind-inheritance.md): Specialize any existing kind — abstract or concrete — with single inheritance. A child inherits the parent's controller, capability, and schema, and maps the parent's config through a base: construction mapping.
- [Step Bodies](https://telo.run/extend/step-bodies.md): Give a kind of your own a body of steps — a transaction, a batch, a durable run — by pointing an array at the shared step grammar, so it gets invoke / if / while / switch / try and steps.<name>.result for free.
- [Sharing Across Libraries](https://telo.run/extend/library-resource-inputs.md): Hand one instance down to several libraries with a resources: block, or let several libraries reach one shared library with lifecycle: shared — so two libraries over one database connection see one connection, not two.
- [Need Types](https://telo.run/extend/need-types.md): Declare what a module can ask its host or importer for — the fields a fulfilment hands over, which are required and sensitive, the parameters a need may state, and whether fulfilments are versioned or carry features — with a Telo.NeedType.
- [Consuming Needs](https://telo.run/extend/consuming-needs.md): Write a kind that takes a need's whole fulfilment at a reference slot, opens it with ctx.resolveNeed, and reports the version and features it found with ctx.verifyNeed so the kernel can enforce the need's constraints.
- [Execution Zones](https://telo.run/extend/execution-zones.md): Declare that a resource must be reached through another resource's body — a transaction, a durable run, a batch — and have telo check say so before the path ever executes.
- [Sensitive Contract Fields](https://telo.run/extend/sensitive-contract-fields.md): Mark an inputType / outputType field with x-telo-sensitive so a token or credential is carried as [redacted] on the debug wire instead of verbatim — and why the annotation is reported when written anywhere it would not be read.
- [Resource Rules](https://telo.run/extend/resource-rules.md): Let a kind declare, as a CEL condition, how the fields of one resource must relate to each other — an index naming a real column, a foreign key whose sides agree — so telo check reports it before boot.
- [Referrer Rules](https://telo.run/extend/referrer-rules.md): Let a kind state, as data, what must be true of whoever references one of its resources — checked by telo check on the referrer's own line instead of failing at boot.
- [Schema Projections](https://telo.run/extend/schema-projections.md): Type what a resource's entries mean — a table's rows, an extraction's fields — as a JSON Schema its consumers are checked against, statically and at dispatch.
- [Telo Formats](https://telo.run/extend/telo-formats.md): Declare a string field whose grammar Telo checks — a CSS selector, a language tag, a message pattern, a portable regular expression — with format:, refused by telo check on its own line and by the kernel at creation with the same reason.
- [CEL Functions](https://telo.run/extend/cel-functions.md): Declare functions a module's CEL expressions call — written in CEL as Telo.Function, or natively in TypeScript or Rust as a callable kind — with typed signatures, derived determinism, and export control.
- [Reading a Text](https://telo.run/extend/text-records.md): Declare a field or a function parameter that holds text shown to a person, and read the record the runtime hands your controller: the message as written, its context, the language it is written in, and whether it was computed.
- [Manifest Migrations](https://telo.run/extend/manifest-migrations.md): How a renamed keyword or annotation keeps loading: migrations rewrite a legacy spelling to the current one at load, report it in your own files, and telo migrate writes the repair back to disk.
- [Native Files](https://telo.run/extend/native-files.md): Declare a module's platform-specific files — prebuilt addons, shared libraries, per-platform data — once in a native: block, so publish ships each platform's file in its own layer and the platform-neutral bundle ships once.
- [Accessor Fields](https://telo.run/extend/accessor-fields.md): Let a kind take a field that names a value instead of computing one — a plain, statically typed CEL chain the controller receives as a binding and resolves wherever its data lives.
- [Browser Entries](https://telo.run/extend/browser-entries.md): Ship code for a browser with a module — ES modules declared under exports.browser, built by the kernel, packaged in their own artifact layer, and named from a resource with a checked export.
- [Controller Protocol](https://telo.run/extend/controller-protocol.md): What crosses between a Telo kernel and a controller: the closed set of operations, the two carriers that deliver them, and what a controller may and may not count on when the kernel running it is written in another language.
- [Runtime Requirements](https://telo.run/extend/declaring-runtime-requirements.md): Declare the Telo versions a module is verified against with a requires: block, so an older runtime reports one clear MODULE_REQUIRES_NEWER_RUNTIME instead of blaming the module's syntax, and telo upgrade never selects a version your runtime cannot read.
- [Releasing Modules](https://telo.run/extend/releasing-modules.md): Version and publish the modules of a workspace with telo release: the workspace marker, change fragments, the ledger, and why a dependent's version moves when a sibling's bytes do.
- [Overview](https://telo.run/extend/sdk/nodejs.md)
- [Templating Engines](https://telo.run/extend/sdk/nodejs/templating-engines.md)
- [Overview](https://telo.run/extend/sdk/rust.md)

## Reference

- [Standard library](https://telo.run/reference/standard-library.md): The Telo standard library: what each module is for, the kinds it exports, and how to import and pin one.
- [CEL Functions](https://telo.run/cel.md): Every CEL function available in a Telo manifest expression — strings, math, formatting, collections, JSON, encoding, hashing, time and UUIDs — generated from the runtime registry.
- [Diagnostics reference](https://telo.run/reference/diagnostics.md): Every diagnostic code the Telo analyzer and runtime can emit, what triggers it, and how to fix it.
- [Overview](https://telo.run/reference/kernel.md)
- [Resource Definition](https://telo.run/reference/kernel/resource-definition.md): v1.0 spec for Telo.Definition: schema, capability, topology, invocation contract, and controller declarations
- [Resource Lifecycle](https://telo.run/reference/kernel/resource-lifecycle.md): v1.0 spec: resource lifecycle stages (Validated, Initialized, Draining, Teardown) and topological ordering across dependency graphs
- [Resource References](https://telo.run/reference/kernel/resource-references.md): v1.0 spec for resource references: x-telo-ref keyword, module identity lookup, kind constraints, and resolution phases
- [Inheritance](https://telo.run/reference/kernel/inheritance.md): Inheritance via extends: abstract interface declaration (Telo.Abstract) and implementation pattern for pluggable subsystems
- [Evaluation Context](https://telo.run/reference/kernel/evaluation-context.md): v1.0 spec: two-layer CEL context (Module Context with variables/secrets/resources, Execution Context with request/inputs)
- [Data Types](https://telo.run/reference/kernel/data-types.md): Type system: Type.JsonSchema and Type.Cue resources for structured validation with CEL business rules and fail-fast enforcement
- [Observed State](https://telo.run/reference/kernel/observed-state.md): Declared observed state: the status: block on a kind, the resources.<name>.status CEL segment, providers reporting from init(), and where reported values may be read
- [Invoke Cancellation](https://telo.run/reference/kernel/invoke-cancellation.md): Cooperative invocation cancellation via the out-of-band InvokeContext — token/source split, the pre-dispatch gate, deadlines, and how leaves honor it.
- [Overview](https://telo.run/reference/kernel/capabilities.md): Five lifecycle capabilities (Runnable, Service, Invocable, Mount, Provider) assigned per resource definition, mutually exclusive
- [Invocable](https://telo.run/reference/kernel/capabilities/invocable.md): Invocable capability contract: inputs/outputs, controller interface, and kernel invocation with CEL expansion
- [Overview](https://telo.run/reference/kernel/topology.md): Topology design: composition patterns (Sequence, Router, Workflow) that drive kernel execution and editor rendering
- [Sequence](https://telo.run/reference/kernel/topologies/sequence.md): Sequence topology: ordered step execution with invoke, if/elseif/else, while, switch, and try/catch control flow
- [Router](https://telo.run/reference/kernel/topologies/router.md): Router topology: matcher-to-handler dispatch where CEL matchers are evaluated in order and first match invokes handler
- [Module System](https://telo.run/reference/kernel/modules.md): v1.0 spec for modules: Telo.Application and Telo.Library contracts with inputs, exports, and external manifest inclusion
- [Application Environment Variables](https://telo.run/reference/kernel/application-env-variables.md): How Telo.Application declares variables and secrets sourced from host environment variables, with per-field env mapping, type coercion, and schema validation.
- [Application Ports](https://telo.run/reference/kernel/application-ports.md): How Telo.Application declares the inbound ports it listens on: name-keyed, env-bound entries that resolve into the ports.<name> CEL scope, with transport brands for static wiring checks.
- [Controllers](https://telo.run/reference/kernel/controllers.md): v1.0 spec: controller loader resolves Package URLs (PURLs) to implementations with type, namespace, version, qualifiers
- [Controller Protocol](https://telo.run/kernel/specs/controller-protocol.md): v1.0 spec: the Telo controller protocol — every operation that crosses between a kernel and a controller, its direction and payloads, the length-prefixed framed carrier pinned byte-exactly, and the generation counter both carriers report
- [Invocation Contract](https://telo.run/kernel/specs/invocation-contract.md): v1.0 spec: the invocation contract — how a resource's declared inputType/outputType is resolved, typed by the declaration it is bound to, bound, default-filled and enforced at dispatch, and how contract violations are reported
- [Revertible Effects](https://telo.run/kernel/specs/revertible-effects.md): v1.0 spec: revertible effects — the per-resource inverse accumulator, its frames, LIFO recovery, the iterator form, early disposal, and the failure rules for a failed init and for teardown
- [Execution Zones](https://telo.run/kernel/specs/execution-zones.md): v1.0 spec: execution zones — the ambient zone stack on the invocation context, the provides/requires annotations, correlation, instance identity, clearing guarantees, and the provider-private payload rule
- [Durable Execution](https://telo.run/kernel/specs/durable-execution.md): v1.1 spec: the kernel's half of durable execution — the replay contract every step engine must satisfy, the determinism rules, the key scheme, suspension as a signal, and what a backend must guarantee about its journal
- [Logging](https://telo.run/kernel/specs/logging.md): v1.0 spec: the language-neutral structured logging contract every Telo runtime implements — OTel-aligned record model, severity scale, sinks, redaction, and encodings
- [Tracing](https://telo.run/kernel/specs/tracing.md): v1.0 spec: trace export — how a root Application turns tracing on with trace sinks, what a finished span carries, how spans parent, how a contract puts values on a span, and the built-in and OTLP trace sinks
- [Module Artifact](https://telo.run/kernel/specs/module-artifact.md): v1.0 spec: the layered module artifact — how a published Telo module is partitioned into layers, how the pinned layer index addresses and verifies them, and how a runtime selects the layers it needs
- [Application Arguments](https://telo.run/kernel/specs/application-arguments.md): Normative: how a root Telo.Application binds command-line flags and positional arguments to its variables and ports — the binding forms, the token grammar, value coercion, precedence, asking the host for a missing input and --help.
- [Built-in Vocabulary](https://telo.run/kernel/specs/builtin-vocabulary.md): Normative: the Telo.Builtins archive — the built-in vocabulary of one telo release as a YAML stream: its root and documents, the byte layout every reader slices, what refuses it, telo builtins, and its publication as oci://ghcr.io/telorun/telo.