Guides
Trellis Guides
Introduction
What is Trellis?
A minimally technical overview of why Trellis exists, how it compares with REST and pub/sub, and what it gives teams building connected data systems.
Trellis Concepts
Deeper concepts behind Trellis, including platform boundaries, contract-driven authority, transport surfaces, resources, and generated APIs.
Trellis Concepts
Architecture
Service categories, platform boundaries, runtime ownership, and public cross-service surfaces.
Contracts
Service and app contracts, contract identity, and generated artifacts.
Deployment authority
Deployment authority, identity authority, authority updates, reconciliation, availability, liveness, grant overrides, and contract evidence.
Communication
RPCs, operations, events, feeds, cross-contract dependencies, and surface availability.
Authentication and authorization
Principals, session keys, browser login, portals, approvals, and capabilities.
Resources
KV buckets, store resources, public app state, and runtime stream semantics.
Files and transfers
Public file APIs, service-owned stores, and operation-native byte transfer.
Type system and errors
Schemas, validation, declared errors, Result values, pagination, and stable storage identity.
Devices and activation
Preregistered devices, activation portals, device deployments, review policy, and online credentials.
Jobs
Service-private background execution and when to use operations instead.
Libraries
Libraries
How Trellis programs use runtime libraries, generated SDKs, and API reference docs.
TypeScript libraries
Use Trellis from TypeScript apps, services, devices, portals, and CLIs with generated SDKs and surface-first APIs.
Rust libraries
Use Trellis from Rust services, CLIs, devices, and generated Cargo participant facades.
Installing Trellis
Getting started
Tutorial: Write a service
Build the same orders-service tutorial in TypeScript or Rust.
Set up the project
Create the standalone orders-service project and install Trellis dependencies.
Your first contract
Define the smallest valid Trellis service contract for the selected language.
The service entry point
Connect the service runtime, provision an instance, and run the service locally.
Adding a database
Declare a service-owned KV bucket and open a typed KV client from the runtime binding.
Writing our first RPC
Add the Orders.Create schemas, contract declaration, capability gate, and handler.
Retrieving an order with service errors
Add Orders.Get schemas, a domain error, the contract declaration, and a typed read handler.
Listening to the outside world
Declare an auth event dependency and subscribe to Auth.Connections.Opened.
Publishing your own events
Declare and publish an Orders.Shipped event for downstream services.
Use a feed for filtered live views
Expose caller-filtered live views instead of forwarding broad service events to browsers.
Handle graceful shutdown
Stop the service cleanly on SIGTERM so local restarts and deployments drain work safely.
Prepare SDKs and contract artifacts
Generate publishable client packages and service contract artifacts from the contract.
Declare optional dependencies
Use optional uses for additive integrations that should not block service activation.
Development loop
Know when to regenerate artifacts, review deployment authority, and restart the service.
Write a SvelteKit app
A working browser app that authenticates with Trellis and calls RPCs.
Features
Jobs: TypeScript
Add background job processing to a TypeScript service with retry, progress tracking, and dead-letter handling.
Jobs: Rust
Add background job processing to a Rust service with retry, progress tracking, and dead-letter handling.
Operations: TypeScript
Expose caller-visible async workflows from a TypeScript service with typed progress and cancellation.
Operations: Rust
Expose caller-visible async workflows from a Rust service with typed progress and cancellation.
Store resources: TypeScript
Declare and use service-owned `resources.store` from a TypeScript service for large unstructured blobs.
State: TypeScript
Use Trellis-managed `State.*` RPCs from TypeScript apps and devices for semi-durable cloud-backed app memory with contract-lineage storage and state-version migrations.
Advanced
Create a custom portal
Build and register a custom SvelteKit portal app for provider selection and contract approval.
Devices
Build a Trellis device that displays a QR activation URL and completes the device activation flow.
Develop Trellis services with AI agents
Use llms.txt, llms-full.txt, language-specific LLM guides, and a service AGENTS.md template to guide AI agents working in Trellis service repos.
Administration
Install a service from an image
Deploy a published service from an OCI image into a running Trellis environment.
Install a service from source
Install and run a service from its source tree during development.
Administer Jobs
Query, cancel, replay, and monitor jobs across all services using the built-in Jobs API.