Blueprints

A blueprint is a declarative YAML recipe for installing and operating a service over SSH. Blueprints power the service layer: a station registers services from blueprints and runs them on your VMs.

Where blueprints live

Each blueprint is one folder under blueprints/, with a blueprint.yaml entrypoint:

blueprints/
└── docker/
    ├── blueprint.yaml        # required
    └── scripts/              # optional shell sidecars
        └── install.sh

The catalog is discovered automatically — drop a folder in and it shows up when you register a service. No code, no registration.

Two shapes

• Standalone — declares its own roles[], each running on its own VMs (e.g. docker, k3s).
• Hosted — declares host: { blueprint, role } and runs on another service (e.g. argocd on k3s.server).

Example

A minimal standalone blueprint:

name: docker
description: Container runtime (Docker CE)
version: 1.0.0
compatibility:
  os: [ubuntu-22-04, ubuntu-24-04, debian-12, debian-13]

roles:
  - name: main
    install:
      - name: install
        description: Install Docker CE
        script: scripts/install.sh
        verify:
          run: command -v docker >/dev/null 2>&1
    uninstall:
      - name: remove
        description: Remove Docker CE
        run: sudo apt-get remove -y docker-ce

Steps run over SSH; each verify keeps them idempotent. Steps can publish values (secrets or facts) for later roles or hosted services, and an uninstall block tears the service down in reverse order. Templating resolves ${inputs.X}, ${secrets.X}, peer values and inlined files (${file:...}) per host at run time.

Authoring

The full DSL reference — every field, all templating, and verify / publish / rollback / uninstall — is maintained in the repository: docs/blueprint-dsl.md.

The repository also ships a blueprint-dsl agent skill (.agents/skills/blueprint-dsl/), so an AI assistant can author blueprints with full command of the DSL.