Templates

Templates let you create game servers without needing to configure all the technical details by yourself. Instead of manually configuring the Docker image, ports, environment variables, and commands, you select a template and COSY fills in everything for you.

How Templates Work

COSY fetches templates from the cosy-templates repository via an external Template Service. Templates are defined as YAML files, validated against a JSON schema, and synced periodically.

Each template specifies:

• Docker image name and tag
• Port mappings (TCP/UDP)
• Environment variables (with support for user-configurable variables)
• File mounts for persistent storage
• Resource limits (CPU and memory)
• Execution command (optional)
• Tags for filtering templates in the creation wizard (e.g. fabric, modpack)
• Host mounts and annotations (optional, advanced — see below)

Games

Games are defined in the games/ directory of the same repository — one YAML file per game with its display name and artwork (the file name is the game's slug, e.g. minecraft.yaml). Templates reference their game via the game_id field. In the server creation wizard, games appear in a sidebar and group the available templates.

Available Templates

Templates are organized by game in the templates/ directory. The list below is fetched live from the template service:

Loading templates...

The collection is community-maintained — new games and variations are added through pull requests.

Using a Template

Templates are selected during the server creation process. For a detailed walkthrough, see Your First Game Server.

In short: create a new server, pick a game from the sidebar, optionally narrow the template list with tag filters, select a template, fill in any template variables (e.g., memory allocation, player limits), and create the server. You can modify any template-provided setting after creation through the server's configuration page.

Template Variables

Templates can define variables — user-configurable inputs that get substituted into the template using {{placeholder}} syntax.

For example, the Minecraft Fabric template defines a version variable. When you fill in 1.21.2, the environment variable VERSION is set to 1.21.2 inside the container.

Placeholders are not limited to environment variables. They can appear in port mappings, resource limits (e.g. memory: "{{memory}}GiB"), the execution command, host mount paths, and annotation values — the value you enter is substituted wherever the placeholder is used.

Variable types:

Each variable can also specify:

• regex — A regular expression to validate user input (string type only). For example, \d\.\d+\.\d+ ensures a valid version number like 1.1.6.
• default — A default value that is pre-filled when creating the server.
• example — An example value shown as a hint in the input field.
• options — A list of allowed values (required for the select type).
• description — A human-readable explanation of what the variable controls, shown below the input in the creation wizard.
• required — Whether the user must provide a value (no default accepted).

Contributing Templates

If you'd like to request a template for a game that isn't supported yet, you can open a template request issue. If you want to contribute one yourself, submit a pull request to the cosy-templates repository.

Templates must be placed at templates/{game-name}/{template-description}.yaml using lowercase letters and dashes.

Template Format

# yaml-language-server: $schema=../../schema/template.schema.json
name: Minecraft Fabric
description: Minecraft Fabric Server with default fabric installation
game_id: minecraft
docker_image_name: itzg/minecraft-server
docker_image_tag: latest

tags:
  - fabric

variables:
  - name: Minecraft Version
    type: string
    regex: \d+\.\d+(\.\d+)?
    placeholder: version
    example: "1.21.2"
    description: The Minecraft version to run
  - name: Memory Allocation (in Gigabyte)
    type: string
    placeholder: memory
    example: "4"
    default: "6"
    description: Amount of RAM in gigabytes allocated to the server JVM

environment_variables:
  VERSION: "{{version}}"
  EULA: "true"
  TYPE: "FABRIC"
  MODRINTH_PROJECTS: "fabric-api"
  MEMORY: "{{memory}}G"

port_mapping:
  "25565/tcp": 25565

file_mounts:
  - /data

resource_limit:
  memory: "{{memory}}GiB"
  cpu: 3

Required Fields

Optional Fields

All templates are validated against a JSON schema in CI before they can be merged.