Workspaces and ArtifactsUpdated 2026-03-11

Workspace Templates, Pools, and Reset Behavior

How choosing a default template differs from resetting the current workspace project, and how pool changes affect the reset flow.

Workspace Templates, Pools, and Reset Behavior

Where you see this in the app

This page explains the workspace template controls inside the post workspace panel.

Authors use them when they want to choose a prepared starter project for future workspace sessions, or when they explicitly want to reset the current persistent workspace project files.

Choose default template

Browse templates is the non-destructive template chooser.

Its job is to save the post's default workspace template and runtime pool for future fresh workspace starts. Selecting a template here does not, by itself, overwrite the current mounted workspace files.

From an end-user standpoint, the main rule is:

Browse templates changes the default starter project for future sessions.
It also resets the post back to that template or pool's default container tier. If you want a different tier afterward, change Default container tier in workspace settings.

Reset workspace to template

Reset workspace to template is the destructive action.

It is available only to the post author while an edit-mode workspace session is active. When used, it resets the persistent workspace project files in /project to the selected template.

Important details:

it preserves .git
it preserves .gpx_workspace_marker.json
it leaves /data intact
it does not close other users' sessions automatically

How to read template cards

Template cards are there to help users choose the right starting point.

Common fields:

Field	What it means
Name	The starter project identity
Version	Which packaged revision of the template you are using
Estimated size	Rough project size to expect
Entry file	The main file the template expects as its starting point
Publish	The publish directory, entry path, and routing mode when the template includes a publishable site
Build	The build command, when the template expects one
Stack tags	The main technologies or environment hints

These fields are selection hints. They help users choose a good starter project before they save the default or perform a reset.

Future sessions vs current session

There are two separate outcomes:

Action	What happens
Choose default template	Updates the post default template/pool/runtime config for future fresh workspace sessions
Reset workspace to template	Rewrites the current persistent `/project` workspace files to that template

This distinction matters because workspace storage persists across sessions. A non-empty workspace does not get silently overwritten just because the post default template changed.

Pool mismatch and reopen guidance

Some templates require a different workspace pool than the one currently running.

When that happens during a reset attempt, the app should save the template as the new default and then instruct the user to:

close the current workspace session
reopen the workspace on the new runtime pool
run Reset workspace to template again

The app should not try to destructively reset the current workspace in-place on the wrong runtime pool.

The mental model:

templates can carry runtime expectations
those expectations can change the required workspace pool
template selection also restores the pool-default tier for future sessions
changing the default template and resetting the current workspace are separate actions