Create a template

By the end of this page you will have a template of your own open in the template editor, and know where everything in it lives.

Templates live under Instances → My Templates. The banner there has three ways to start:

Button	Use it when
Create template	You want to start from a clean base system
Fork a lab	An existing lab is close to what you want
Import ▾	You have a template exported as JSON, or stored in a Git repository

Don't see these buttons?

They appear only when template authoring is enabled for your account. See Who can author templates.

Create from scratch

1. Open the form

Click Create template.

2. Fill it in

Field	Notes
Name	1–80 characters. A preview underneath shows the short name (the slug) it will deploy as.
Description	Up to 500 characters
Type	Machine — a persistent working lab with SSH, a home directory and your tools
Base image	The system to build on — see below
Visibility	Private to start. You can change it later.
Kind	Machine lab, or App if it has something to launch (a web interface, a desktop, a code editor). Apps also appear on the launcher.
Categories	At least one. The first you pick is the primary category.

Base image. Pick one of the curated systems — Ubuntu 24.04, 22.04 or 20.04, Debian Bookworm, Alpine 3.20, Fedora 40 or Rocky Linux 9 — or choose Custom… and type any public Docker Hub image.

A custom base image may not support the private tunnel

Curated images are known to work with the VPN. For a custom image, a check at build time decides. If it fails, the template cannot be deployed with the VPN until you fix the image and rebuild — or switch the template to internal-only.

Visibility. Team and Public only take effect after the template's first successful build and once its stability is beyond alpha. Every new template starts as your private work in progress.

3. Create it

Click Create template. You land in the template editor.

Fork a lab

Click Fork a lab (or Import ▾ → Fork an existing lab…). Choose what to start from — a machine lab, a challenge lab, or one of your templates — pick it from the list, and optionally give the fork a name and visibility.

You become the owner of a new, independent template. It shows a from source chip so you remember where it came from.

You can fork your own templates and public ones. Anything else is refused with You can only fork your own or public templates.

Import

Import ▾ → From JSON… — choose a file you exported earlier with Export as JSON (up to 2 MB). A new template is created from it, owned by you.

Import ▾ → From Git… — paste the web address of a repository on the platform's GitLab. Repositories hosted anywhere else are refused as an invalid URL.

Either way, review the configuration, then Build & validate.

You can own a limited number of templates

If you reach the limit you'll see Template limit reached. Delete a template you no longer need to make room.

The template editor

The banner tells you where the template stands:

Badge	Meaning
Status — draft, building, built, published, failed	Whether the current files have been built
VPN — verified, probe failed, or not probed yet	Whether the built image works with the private tunnel
code-server ✓ or missing	Whether the browser code editor is available in the image
Version, e.g. v0.3.2	Goes up on every save and every build

Buttons: Build & validate, Deploy, Open in editor, and a ⋯ menu with Export as JSON and Delete template.

The tabs:

Tab	What is there
Deployments	Copies running from this template, and Deploy
Files	Every file in the template, with an editor
Configuration	All settings — see Configure a template
Build & validate	Checks, build progress and results — see Build and deploy
Sharing	Visibility and who has access — see Share and publish
Versions	History, diffs, restore and Git sync

Your templates also appear as cards on My Templates, each with Config, Files and Deploy shortcuts.

The Files tab

A file tree on the left and an editor on the right.

• New file, New folder, Delete, and Save (or Ctrl+S).
• A dot marks unsaved changes.
• Up to 256 KB per file and 500 files per template in the browser. Binary files cannot be opened here — use the full editor.
• config.json is checked when you save it. The Configuration tab is the guided way to change it, and the safer one.
• config.json and the Dockerfile cannot be deleted.
• PROMPT.md holds instructions for AI assistants — see Auto-login and connection info.

If a file changed somewhere else since you opened it — in the full editor, for example — saving warns you File changed on disk since you opened it, and you can reload the newer version.

Every save is recorded in Versions.

Editing a file means rebuilding

Any change to a template file resets the status to draft. Copies keep running the last built version until you build again and redeploy them.

The full editor

For multi-file changes, a terminal, extensions or binary files, click Open in editor. You get a full VS Code in a new browser tab, opened on this template's folder.

1. Click Open in editor. The Editor ready dialog shows a One-time password.
2. Copy it — it is shown only once.
3. Click Open editor and sign in with that password.

Things to know:

• You have one editor per account. It serves all your templates, and the Your editor card on My Templates shows when it is running.
• It closes by itself after 30 minutes idle, and after four hours at most. Save your files before stepping away.
• Close editor shuts it down straight away when you are done.
• Changes you save there are template edits like any other: the template needs a rebuild.

Do it with an AI assistant

You can also do this by asking an AI assistant connected to your account — see Connect an AI assistant to set one up.

Ask	What the assistant does
“Create a template called Flask Dev based on Ubuntu 24.04”	Reads the categories with list_categories, then create_template
“Start a template from the essentials lab instead”	list_forkable, then fork_template
“Add a line to the Dockerfile that installs nginx”	read_template_file, then edit_template_file
“Give it 2 CPUs and 4 GB of memory”	configure_template

Get it right before the first deploy

Template authoring needs a paid account. Any edit returns the template to draft, so rebuild after your last change — and settle the files and settings before its first deploy.

Next

• Configure a template — resources, users, networking and exposure
• Build and deploy — turn it into running copies