Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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. See Environment Setup for instructions.

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 alerts and 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.

Recipes

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

Getting Started

  1. Environment Setup - Install the required development tools
  2. Quick Start - Create, build, and install your first package

Reference

  1. Project Structure - Understand the file layout of a StartOS package
  2. Manifest - Define your service metadata, release notes, and alerts
  3. Versions - Handle install, update, and downgrade logic
  4. Main - Configure daemons, health checks, and the service lifecycle
  5. Initialization - Run code when your service initializes
  6. Interfaces - Expose network interfaces to users
  7. Actions - Define user-facing buttons and scripts
  8. Tasks - Prompt users to run actions at the right time
  9. File Models - Represent and validate configuration files
  10. Dependencies - Declare and configure service dependencies
  11. Makefile - Automate build and install workflows
  12. Writing READMEs - Write effective service documentation