This directory contains examples demonstrating different ways to use the Trellis engine.
New to Trellis? Begin with:
- Tour — Run
trellis run ./examples/tourfor a guided walkthrough - Hello World — Minimal example using in-memory graphs
Then explore by category below based on your needs.
- 🚀 Start Here
- 1. Getting Started
- 2. Core Features
- 3. Infrastructure & Patterns
- 4. Advanced Control
- 5. Production & Observability
- 6. Internals & API
Concepts: Loam Adapter, Markdown Files, CLI
A content-heavy example that demonstrates the features of the Trellis file format (.md files). This is what you run with trellis run ./examples/tour.
Concepts: MemoryLoader, TUI, trellis.Runner
The standard entry point for developers building internal tools. It shows how to define a graph in Go code (in-memory) and run it using the standard Runner.
Concepts: default_context, Mocking, Local Dev
Demonstrates how to define fallback values in start.md. These defaults act as mocks for local development, allowing you to run flows without needing lengthy CLI context flags.
Concepts: required_context, Fail Fast
Shows how to enforce data contracts using required_context. If a required key is missing, the engine stops immediately, preventing "silent failures" later in the flow.
Concepts: context_schema, Typed Context, Fail Fast
Demonstrates type validation for context values before nodes render. Useful for catching data mismatches early.
Concepts: on_error, metadata.confirm_msg, Implicit IDs
Demonstrates robust tool usage, including Safety Middleware (confirmation prompts) and Error Handling (on_error transitions).
Concepts: Middleware, Encryption, PII Masking
Showcases how to securely wrap the state store with encryption and PII sanitization middleware. This is a manual infrastructure setup (wrapping the runner) rather than a built-in feature.
Concepts: Saga Pattern, on_error, Rollback
Demonstrates how to implement distributed transactions with compensating actions (Rollback) using standard Trellis primitives (Manual Wiring).
Concepts: Native SAGA, do/undo, on_error: rollback
Demonstrates the new Native SAGA orchestration in Trellis v0.7. The engine automatically handles the stack unwinding and compensation execution when a failure occurs.
Concepts: Durable Execution, Persistence, Signals
Demonstrates a Long Running SAGA. The flow pauses for an external signal (Manager Approval), is interrupted (process exit), resumed from disk, and then rolled back upon Rejection.
Concepts: input_type: confirm, input_default, Unix Conventions
Demonstrates the native confirmation UX. It shows how the engine follows standard CLI conventions (Enter = Yes) and how to formally override those defaults for secure flows.
Concepts: x-exec, Tools, YAML Metadata
Demonstrates the power of Universal Action Semantics. This example shows how to define and execute dynamic OS processes (scripts) directly from node metadata without pre-compiling Go tools.
Concepts: tools.yaml, Python/Node/PowerShell, JSON IO
A reference implementation for the Unix-Style Contract. Shows how to write scriptable tools in multiple languages that receive arguments via Environment Variables and return structured JSON output, all registered via a safe tools.yaml manifest.
Concepts: Standalone Nodes, Dynamic x-exec
Demonstrates how to execute tools without any tools.yaml file. Everything is self-contained in the Markdown metadata, allowing for portable and easy-to-distribute flows.
Concepts: on_signal, Graceful Shutdown, Ctrl+C
Demonstrates how to handle global interruptions (like SIGINT) gracefully. Instead of crashing, the flow transitions to a confirmation node ("Are you sure?"), preventing data loss.
Concepts: Modular Graphs, Portability, Logical Segregation
Demonstrates how to split a complex state machine into multiple smaller, manageable files. This is the cornerstone of building complex, enterprise-ready automation.
Concepts: --watch, Hot Reload, DX
Shows how Trellis supports a high-velocity developer experience. Modify your Markdown files and see the engine reload the logic in real-time without restarting the process.
Concepts: --context, Seed State, Templates
Demonstrates how to inject initial data into the flow via the CLI flag --context. Critical for automated testing or integration with legacy systems.
Concepts: on_signal, step_timeout
Demonstrates global signals (interrupts) and step timeouts.
Concepts: slog (JSON Logs), Prometheus (Metrics)
Demonstrates industry-standard observability by integrating Trellis with Go's log/slog and prometheus/client_golang. Shows how to output machine-readable logs and metrics.
Concepts: LifecycleHooks, --debug, Events
Demonstrates how to use the --debug flag to visualize state transitions and events in the console.
Concepts: Manual Loop, engine.Render, engine.Navigate
Demonstrates how to manually drive the engine without using the trellis.Runner. Useful if you need to integrate Trellis into a custom UI framework, a game engine, or a non-standard event loop.
Concepts: pkg/dsl, Fluent API, Type Safety
Demonstrates how to build graphs using the Go DSL (Fluent Builders) instead of YAML/Markdown files. Ideal for scenarios requiring compile-time type safety and programmatic graph construction.
Concepts: introspection.TypedWatcher, lifecycle Integration
Advanced example showing integration with the lifecycle package for unified observability across the Engine, Workers, and Signals.
Concepts: SSE, State Delta, Chat Interface, Frontend Integration
Demonstrates the integrated web chat UI (/ui) with Server-Sent Events for real-time state updates. Shows how frontends can consume deltas efficiently and inject tool results via HTTP.