Recipes
This is the primary entry point for StartOS service packaging — for both you and your AI coding agent. Each recipe describes a common packaging pattern, names the SDK constructs involved, links to reference pages for API details, and points to real packages for working code. Your agent reads these to understand what to build; you read them to understand what to ask for.
If you’re using Claude Code (recommended), point your agent at the recipe for your task and let it follow the reference and package links from there.
Configuration
| Recipe | Description |
|---|---|
| Set Up a Basic Service | Minimal single-container service with a web UI, health check, and backup |
| Create Configuration Actions | Let users configure your service through actions with input forms |
| Generate Config Files | Produce YAML, TOML, INI, JSON, or ENV files from user settings using FileModel |
| Pass Config via Environment Variables | Configure your service through environment variables in the daemon definition |
| Hardcode Config Values | Lock down ports, paths, or auth modes so users cannot change them |
| Set a Primary URL | Let users choose which hostname the service uses for links, invites, and federation |
| Set Up SMTP / Email | Let users configure email sending with disabled/system/custom modes |
Credentials & Access Control
| Recipe | Description |
|---|---|
| Auto-Generate Internal Secrets | Generate passwords or tokens in init for internal use (database auth, secret keys) |
| Prompt User to Create Admin Credentials | Critical task on install that triggers an action to generate and display a password |
| Reset a Password | Action that regenerates credentials and updates the running application |
| Gate User Registration | Toggle action that enables/disables public signups with a dynamic label |
Setup & Lifecycle
| Recipe | Description |
|---|---|
| Require Setup Before Starting | Block service startup with a critical task until the user completes configuration |
| Run One-Time Setup on Install | Generate passwords, seed databases, or bootstrap config on first install only |
| Bootstrap via Temporary Daemon Chain | Start the service during init, call its API to bootstrap, then tear it down |
| Handle Version Upgrades | Migrate data between package versions using the version graph |
| Handle Restore from Backup | Re-register services or fix state after restoring from backup |
Daemons & Containers
| Recipe | Description |
|---|---|
| Run Multiple Containers | App + database, app + cache, app + worker — multi-daemon setups |
| Run a PostgreSQL Sidecar | Password generation, pg_isready health check, pg_dump backup |
| Run a MySQL/MariaDB Sidecar | MySQL daemon, health check, mysqldump backup and restore |
| Run a Redis/Valkey Cache | Ephemeral cache daemon with valkey-cli ping health check |
| Create Dynamic Daemons | Variable number of daemons based on user configuration |
| Run a One-Shot Command | Migrations, file ownership fixes, or setup scripts before the main daemon starts |
Networking
| Recipe | Description |
|---|---|
| Expose a Web UI | Single HTTP interface for browser access |
| Expose Multiple Interfaces | RPC, API, peer, WebSocket, or SSH on different ports |
| Expose an API-Only Interface | Programmatic access with no browser UI |
Dependencies
| Recipe | Description |
|---|---|
| Depend on Another Service | Declare a dependency, read its connection info, and auto-configure |
| Enforce Settings on a Dependency | Create a cross-service task that requires specific dependency configuration |
| Mount Volumes from Another Service | Read-only access to a dependency’s data volume |
| Support Alternative Dependencies | Let users choose between backends (e.g., LND vs CLN) |
Data & Health
| Recipe | Description |
|---|---|
| Back Up and Restore Data | Volume snapshots, pg_dump, mysqldump, and incremental rsync strategies |
| Add Standalone Health Checks | Sync progress, reachability, and other ongoing checks beyond daemon readiness |