App templates

An app template is a staff-curated, reusable app definition: a Docker image plus default environment variables, volume mounts, and ports. Any workspace can browse and deploy from templates. Creating, updating, and deleting templates is restricted to staff.

Deploying from a template is asynchronous: the deploy endpoint returns a workflow you poll until the app is running.

All path parameters are required strings containing numeric IDs.

List app templates

GET/v1/app-templatesList app templates

Lists all globally available app templates with pagination. Authentication is required but any valid token may call this endpoint.

Query parameters

Name	Type	Description
q	string	Quick search by name, image, or ID
name	string	Filter by template name (partial match)
image	string	Filter by Docker image (partial match)
category	string	Filter by category (DEFAULT, GAMES, SOFTWARE, INFRASTRUCTURE, AI, MEDIA, TOOLS, DATABASES, MONITORING, PRODUCTIVITY, DEVOPS, AUTOMATION, NETWORK)

All query parameters are optional, including the shared pagination parameters.

Returns 200 OK with a KeysetResultAppTemplateView object. Its items contain id, name, description, image, and nullable category. Pagination fields are total, page, limit, has_next, has_previous, after, and before.

curl -A 'curl/8.5' \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN" \
  "https://api.galaxygate.net/v1/app-templates"

Create an app template

POST/v1/app-templatesCreate an app template

Creates a new globally available app template. Staff only.

Request body

Field	Type	Required	Description
name	string	yes	Template name, globally unique
description	string	yes	Short description of what this template deploys
image	string	yes	Docker image including tag, for example plexinc/pms-docker:latest
environment	TemplateEnv[] or null	no	Environment variable specifications (see below)
mounts	AppVolumeMount[] or null	no	Default volume mounts (see Apps for AppVolumeMount field details)
ports	TemplatePort[] or null	no	Container ports the app exposes (see below)

TemplateEnv fields

Only key is required. value and description may be omitted or null.

Field	Type	Description
key	string	Environment variable name passed to the container
value	string or null	Default value. A null default omits the variable unless supplied at deploy time. May contain {{...}} placeholders (see Deploy from template)
description	string or null	Short hint shown in the deploy UI

TemplatePort fields

All fields are required.

Field	Type	Description
name	string	Slug identifier for this port, unique within the template. Referenced by placeholders such as {{host_port.web}}
description	string	Short hint shown in the deploy UI
container_port	integer	Container port the app listens on, from 1 to 65535
protocol	string	TCP or UDP
http	boolean	Whether this port serves HTTP and can back a custom domain. At most one port per template may be marked true, and it must use TCP.

Returns 201 Created with an AppTemplateDetailView object, as described under Fetch.

Fetch an app template

GET/v1/app-templates/{atid}Fetch an app template

Returns the full configuration of an app template, including default environment variables, mounts, and ports.

Path parameters

Name	Type	Description
atid	string	Template ID

Returns 200 OK with an AppTemplateDetailView object containing id, name, description, image, nullable category, environment, mounts, and ports.

Update an app template

PATCH/v1/app-templates/{atid}Update an app template

Partially updates an app template. Omitted fields are left unchanged. Setting a non-nullable field to null is rejected. Setting category to null clears it. Staff only.

Path parameters

Name	Type	Description
atid	string	Template ID

Request body

All fields are optional.

Field	Type	Description
name	string	New template name (globally unique)
description	string	New short description
image	string	New Docker image including tag
category	string or null	Category to group this template under. Accepts DEFAULT, GAMES, SOFTWARE, INFRASTRUCTURE, AI, MEDIA, TOOLS, DATABASES, MONITORING, PRODUCTIVITY, DEVOPS, AUTOMATION, NETWORK. null clears it
environment	TemplateEnv[]	Replacement environment variable specifications (see Create for field details)
mounts	AppVolumeMount[]	Replacement default volume mounts
ports	TemplatePort[]	Replacement port specifications

Returns 200 OK with the updated AppTemplateDetailView object.

Delete an app template

DELETE/v1/app-templates/{atid}Delete an app template

Deletes an app template. Staff only.

Path parameters

Name	Type	Description
atid	string	Template ID

Returns 204 No Content.

Deploy an app from a template

POST/v1/instances/{iid}/apps/from-templateDeploy an app from a template

Creates a Docker app on the given instance using the specified template. Requires the Editor role or higher on the workspace.

At deploy time:

• Host ports default to the template's container_port if that port is free on the target instance. Otherwise a random port in the 20000-60000 range is allocated.
• Environment variable values (from the template defaults and any user-supplied overrides) may contain {{...}} placeholders that are resolved once and persisted as the final values.

Supported placeholders

Placeholder	Resolves to
{{host_port.<name>}}	Host port allocated for the template port with the given name slug
{{container_port.<name>}}	Container port declared for the template port with the given name slug
{{instance.ip4}}	First IPv4 address assigned to the target instance
{{instance.ip6}}	First IPv6 address assigned to the target instance
{{random:<length>}}	Cryptographically secure random alphanumeric string of the given length (1-128). Useful for bootstrapping admin tokens or encryption keys

Unknown placeholders or unresolvable references fail the request.

Path parameters

Name	Type	Description
iid	string	Instance ID

Request body

Field	Type	Required	Description
template_id	string	yes	App template ID (sent as a string to preserve 64-bit precision)
name	string	yes	App name, unique within the workspace
environment	object or null	no	Key/value overrides merged over the template's defaults. A string value overrides the template default. A null value removes the template's default entirely.
mounts	AppVolumeMount[] or null	no	When supplied, fully replaces the template's default mounts. Omit to use the template defaults unchanged.
domain	string or null	no	Custom domain name for the app, for example grafana.galaxygate.app. Only valid when the template has a port marked http: true.

curl -X POST -A 'curl/8.5' \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "1501040853023444992",
    "name": "jellyfin",
    "environment": { "TZ": "America/New_York" },
    "domain": "jellyfin.galaxygate.app"
  }' \
  "https://api.galaxygate.net/v1/instances/101/apps/from-template"

Returns 201 Created with a WorkflowWithResource object containing workflow and resource. Poll GET /v1/apps/{aid} until state is AVAILABLE.