Creating packages

A package is a directory with a service.yaml and the scripts it references. That's the entire contract, the same layout the official packages use.

my-service/
  service.yaml          # name, version, params, nodes/actions, ui…
  scripts/
    install.js
    configure.js
    verify.js
  lib/                  # optional package-local helpers (require("./lib/x"))

service.yaml essentials

name: my-service          # the package name (how it's referenced in managed.yaml)
version: "1.0.0"          # semver; published versions are immutable
description: "What it does"

# Optional dashboard metadata (see "Writing a Service" for the full list)
display_name: My Service
category: Databases
icon: my-service          # simple-icons slug or lucide name

params:
  admin_password:
    type: string
    required: true
    description: "..."

nodes:
  primary:
    count: 1
    actions:
      install:   { script: scripts/install.js }
      configure: { script: scripts/configure.js }
      verify:    { script: scripts/verify.js }

The version matters: a registry stores each version immutably under packages/<name>/<version>/, and latest is the highest semver. To release a change, bump version:, re-pushing an existing version is refused (unless you pass --force).

See Writing a Service and the JavaScript API for how scripts work. Adding a package never requires changing the managed binary.

Developing against a local copy

While iterating, point a repo at your working directory so changes are picked up immediately, no push/pull:

repos:
  - path: ./my-services

managed catalog            # confirm your package shows up
managed apply              # deploy it

When it's ready to share, publish it.