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
Run a Nested OCI Runtime	Rootless Podman or Docker inside the service for CI runners, build daemons, sandboxed jobs

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

User Communication

Recipe	Description
Post a Notification to the User	Send a plain or markdown-detailed notification to the StartOS panel when a long-running action finishes or a sync completes

Keyboard shortcuts

Service Packaging