start-os/sdk

Start SDK

The Start SDK (@start9labs/start-sdk) is a TypeScript framework for packaging services to run on StartOS. It provides a strongly-typed, builder-pattern API for defining every aspect of a service package: manifests, daemons, health checks, networking interfaces, actions, backups, dependencies, configuration, and more.

Features

• Type-safe manifest definitions - Declare your service's identity, metadata, images, volumes, and dependencies with full TypeScript inference.
• Daemon management - Define multi-process topologies with startup ordering, ready probes, and graceful shutdown via Daemons.of().addDaemon().
• Health checks - Built-in checks for TCP port listening, HTTP(S) endpoints, and custom scripts, with configurable polling strategies (fixed interval, cooldown, adaptive).
• Network interfaces - Bind ports, export UI/API/P2P interfaces, and manage hostnames with MultiHost and ServiceInterfaceBuilder.
• User actions - Create interactive operations with validated form inputs (text, select, toggle, list, union/variants, and more) that users can trigger from the StartOS UI.
• Backup and restore - Rsync-based volume backups with exclude patterns and custom sync paths.
• Dependency management - Declare inter-service dependencies with version ranges, health check requirements, and volume mounts.
• Configuration file helpers - Read, write, and merge JSON, YAML, TOML, INI, and ENV files with type-safe FileHelper.
• Reactive subscriptions - Watch for changes to container IPs, SSL certificates, SMTP config, service status, and more with const(), once(), watch(), onChange(), and waitFor() patterns.
• Extended versioning (ExVer) - Flavor-aware semantic versioning with range matching, supporting independent upstream and downstream version tracking.
• Internationalization - Built-in i18n support with locale fallback and parameter substitution.
• Container execution - Run commands in subcontainers with volume mounts, environment variables, and entrypoint overrides.
• Plugin system - Extensible plugin architecture (e.g. url-v0 for URL management).

Quick Start

import { setupManifest, buildManifest } from '@start9labs/start-sdk'

const manifest = setupManifest({
  id: 'my-service',
  title: 'My Service',
  license: 'MIT',
  // ...
})

export default buildManifest(manifest)

The primary entry point is the StartSdk facade:

import { StartSdk } from '@start9labs/start-sdk'
import { manifest } from './manifest'

export const sdk = StartSdk.of().withManifest(manifest).build(true)

From there, sdk exposes the full toolkit:

// Define daemons
export const main = sdk.setupMain(async ({ effects }) =>
  sdk.Daemons.of(effects)
    .addDaemon('primary', { /* ... */ })
)

// Define actions
export const setName = sdk.Action.withInput('set-name', /* ... */)

// Define interfaces
export const setInterfaces = sdk.setupInterfaces(async ({ effects }) => {
  const multi = sdk.MultiHost.of(effects, 'web')
  const origin = await multi.bindPort(80, { protocol: 'http' })
  const ui = sdk.createInterface(effects, { name: 'Web UI', id: 'ui', /* ... */ })
  return [await origin.export([ui])]
})

// Define backups
export const { createBackup, restoreBackup } = sdk.setupBackups(
  async () => sdk.Backups.ofVolumes('main')
)

Packages

Package	npm	Description
package/	@start9labs/start-sdk	Full SDK for service developers
base/	@start9labs/start-sdk-base	Core types, ABI definitions, and effects interface

Documentation

For comprehensive packaging guides, tutorials, and API reference:

docs.start9.com/packaging

The packaging docs cover:

• Environment setup and prerequisites
• Project structure and conventions
• Manifest, main, interfaces, actions, and all other service modules
• File models and configuration management
• Versioning, migrations, and initialization
• Dependencies and cross-service communication
• Building and installing .s9pk packages

Contributing

See CONTRIBUTING.md for environment setup, building from source, testing, and development workflow.

Architecture

See ARCHITECTURE.md for a detailed overview of the SDK's internal structure, module responsibilities, and data flow.

License

MIT