Packaging Guide

StartOS is a Server OS – a Linux distribution optimized for administering servers. While operating systems like Mac, Windows, and Ubuntu are designed for client devices such as phones and laptops, StartOS provides a graphical interface for server administration that eliminates the need to “pop the hood” and use the command line.

Through the StartOS web interface, users can discover, download, install, configure, monitor, back up, and generally manage any variety of self-hosted, open-source software.

Designed for AI-Assisted Development

StartOS service packaging is designed to be done with an AI coding agent. This guide, the SDK, and every existing package are structured so that an AI assistant can read the docs, study real packages, and write or modify package code with minimal human intervention. You do not need to be an expert TypeScript developer – you need to understand what your service requires and let the AI handle how to implement it.

The recommended setup is Claude Code with this guide and your package in the same workspace, scaffolded by start-cli s9pk init-workspace. See Environment Setup and the Quick Start to get going.

What is a StartOS Package?

What makes this experience possible is a unique package format (.s9pk) that permits services to take advantage of StartOS APIs. In its most basic form, a package is a thin metadata wrapper around a service that allows it to be discovered, installed, and run on StartOS. Beyond that, the StartOS APIs grant developers an incredible degree of creative capacity to define the end-user experience for their service. Developers can:

• Display instructions and tooltips
• Present warnings under certain conditions
• Run arbitrary code on install, update, and uninstall
• Represent configuration files as validated forms with all varieties of form inputs
• Define scripts and commands that present as buttons with optional inputs
• Write health checks that run on an interval and are optionally displayed
• Automatically install and configure dependencies
• Maintain state and optionally expose particular values to users or dependent services
• Grant users flexible networking options such as LAN, Tor, and clearnet
• Offer one-click, encrypted backups of targeted data

Where to Start

1. Set up your environment — Follow Environment Setup, including the Claude Code section.
2. Build your first package — Follow Quick Start to create, build, and install the Hello World template.
3. Use recipes to build your service — Browse Recipes to find the patterns you need. Each recipe describes what to do, links to reference pages for API details, and points to real packages for working code. Your AI agent reads these docs and writes the code.

Getting Started

• Environment Setup - Install the required development tools
• Quick Start - Create, build, and install your first package
• New Package Checklist - Turn the scaffolded template into your service
• Development Workflow - How to behave while working on a package
• Maintaining a Package - Branches, upstream updates, and sibling dependencies over a package’s life
• Agent Context - The AGENTS.md linked into every packaging workspace

Recipes

Intent-driven guides for common packaging objectives. These are the primary entry point for both you and your AI coding agent.

• Browse All Recipes - Browse all recipes by intent

Configuration

• Set Up a Basic Service
• Package a Prebuilt Docker Image
• Create Configuration Actions
• Generate Config Files
• Pass Config via Environment Variables
• Hardcode Config Values
• Set a Primary URL
• Set Up SMTP / Email

Credentials & Access Control

• Auto-Generate Internal Secrets
• Prompt User to Create Admin Credentials
• Reset a Password
• Gate User Registration

Setup & Lifecycle

• Require Setup Before Starting
• Run One-Time Setup on Install
• Bootstrap via Temporary Daemon Chain
• Handle Version Upgrades
• Handle Restore from Backup

Daemons & Containers

• Run Multiple Containers
• Run a PostgreSQL Sidecar
• Run a MySQL/MariaDB Sidecar
• Run a Redis/Valkey Cache
• Create Dynamic Daemons
• Run a One-Shot Command
• Run a Nested OCI Runtime

Networking

• Expose a Web UI
• Expose Multiple Interfaces
• Expose an API-Only Interface

Dependencies

• Depend on Another Service
• Enforce Settings on a Dependency
• Mount Volumes from Another Service
• Let Dependents Through a Proxy Auth Gate
• Support Alternative Dependencies

Data & Health

• Back Up and Restore Data
• Add Standalone Health Checks

User Communication

• Post a Notification to the User

Hosting a Registry

• Overview - What a registry is and why you might run your own
• Setup - Install and configure the registry service
• Administration - Day-to-day registry administration with start-cli

Reference

• Project Structure - Understand the file layout of a StartOS package
• Manifest - Define your service metadata and release notes
• Versions - Handle install, update, and downgrade logic
• Main - Configure daemons, health checks, and the service lifecycle
• Initialization - Run code when your service initializes
• Interfaces - Expose network interfaces to users
• Service-to-Service Networking - Reach another service at runtime
• Outbound Network Access - Reach the internet from your service
• Actions - Define user-facing buttons and scripts
• Tasks - Prompt users to run actions at the right time
• Notifications - Post messages to the StartOS notifications panel
• File Models - Represent and validate configuration files
• Dependencies - Declare and configure service dependencies
• Makefile - Automate build and install workflows
• Writing READMEs - Write effective service documentation
• Writing Instructions - Write the Instructions tab users see in StartOS
• Publishing - Distribute your package through a registry
• CLI Reference - The start-cli commands most relevant to service developers