Packaging Format

Town OS packages are YAML definitions that describe how to run a containerized service, including its image, networking, storage, and user-facing configuration prompts. Packages can also run virtual machines or Windows applications via Proton.

Repository Structure

A package repository is any git repository containing a packages/ directory. Anyone can create one — host your own packages for family, friends, or custom deployments. The structure is simple:

packages/
  <package-name>/
    <version>.yaml
featured.json          # optional

# Example:
packages/
  nginx/
    1.0.yaml
    2.0.yaml
  postgres/
    1.0.yaml
featured.json

Each package directory under packages/ contains one or more versioned YAML files. Versions are compared using dot-separated segments — numeric segments are compared numerically, otherwise lexicographically. The storage system supports upgrading between versions and temporary uninstallation with later restoration. Town OS ships with a default repository of packages, but you can add as many additional repositories as you need.

Top-Level Fields

Exactly one runtime must be specified: image (container), vm (virtual machine), or proton (Windows app). These are mutually exclusive.

Supplies Tags

The supplies field declares what capabilities a package provides, enabling categorization and filtering. Tags are free-form strings — the following are conventional:

Volumes

Volume names must start with an alphanumeric character and contain only alphanumerics, dots, hyphens, and underscores (pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$). Omit volumes entirely if the package has none.

Git Sources

The git_sources field clones git repositories into volumes:

git_sources:
  - url: "https://github.com/example/config.git"
    branch: main
    volume: config

Templates

The templates field defines files that are rendered using Go text/template and written to volumes during installation. Templates are only written if the target file does not already exist, preserving user modifications across upgrades.

templates:
  config:
    volume: data
    path: config.yaml
    content: |
      host: {{ .Responses.hostname }}
      port: {{ .Responses.port }}
      name: {{ .Package.Name }}
      system: {{ .System.Hostname }}

Template Data Context

The following data is available inside {{ }} expressions:

Template names follow the same rules as volume names. Files are written with mode 0600 and parent directories are created with mode 0750.

Template System

Town OS has two template systems that operate at different stages of compilation.

@variable@ Substitution

The @variable@ syntax is substituted during package compilation across all configurable fields: environment values, network port mappings, network domains, volume mountpoints, volume quotas, volume git URLs, git source URLs and branches, template volume and path fields, VM image and memory, Proton configuration, and note values.

Each question name becomes a variable. To include a literal @ character (e.g. for a git SSH URL like git@@domain@), use @@ — two consecutive @ characters produce one literal @.

Unresolved variables (referencing a name with no matching question response) are left as-is in the output.

Built-in Variables

Built-in variables are substituted before user question responses, so they take precedence.

Go Templates (in templates field)

The templates field uses Go text/template syntax ({{ .Responses.name }}) for rendering files written to volumes. See the Templates section for available data context.

Proton Runtime

Packages can run Windows applications via Proton by specifying a proton field:

image:
  type: oci
proton:
  app_image: "mycompany/windows-app:1.0"
  app_directory: /app
  volume: app
  exe: /app/myapp.exe
  args: ["-fullscreen", "-config", "/app/config.ini"]
volumes:
  app:
    mountpoint: /app

When proton is set, the container command is automatically generated as ["proton", "run", <exe>, ...<args>]. The proton field is mutually exclusive with vm and command.

Importing Repositories

Once you've created a package repository, add it to your Town OS instance using either the web UI or direct filesystem configuration.

Via the UI

Log in to the Town OS dashboard, navigate to Packages, select the Repositories tab, and click Add Repository. Provide a name, the git URL, and optional credentials. Click Refresh to pull package metadata immediately.

Via the Filesystem

Edit repositories.json in the btrfs package data directory. The file is a JSON array of objects:

[
  {"name": "default", "url": "https://gitea.com/town-os/default-packages"},
  {"name": "my-packages", "url": "https://github.com/myuser/my-packages"}
]

Order matters — later entries override earlier ones when package names collide. For private repositories, embed credentials in the URL. Restart the service or hit Refresh in the UI for changes to take effect.

Style Guidelines

• Omit empty maps (environment: , internal: , volumes: ) — leave them out entirely.
• Omit type on questions that accept free-form text — do not write type: with no value.
• Include description with a short summary of what the package is.
• Include supplies with relevant capability tags when the package provides a well-known service.
• Include notes with connection URLs and any important post-install information.
• Use @variable@ templates to let users customize ports, hostnames, and credentials at install time.
• Use templates for config files that need Go template logic — they are only written once and preserve user edits.