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

Select 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 (the private tunnel). 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

Select Create template. You land in the template editor.

Fork a lab

Select 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.

A template someone has shared with you as Deployer or above can be forked too. The fork copies the source's current files — including edits its author has not built yet — and starts its own version history.

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.

What every new template starts as

However you create it — from scratch, a fork or an import — a new template starts the same way:

Setting	Starts as
Status	draft — nothing is built yet
Stability	alpha — private work in progress
Visibility	Private, even if you picked Team or Public, or the imported file said otherwise. You open it up later from the Sharing tab, once it is built and past alpha.
Owner	You
Slug	Made from the name. If the slug is taken, a short suffix is added.

You can own up to 25 templates

Each template you own counts, whether it is built or not. At 25, you see Template limit reached: you already own 25 templates (limit 25). Delete a template you no longer need to make room. Platform administrators have no limit.

The template editor

Shown on labs.selfmade.ninja, the Selfmade Ninja Academy platform. On your own platform you will see your own domain and data.

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, select Open in editor. You get a full VS Code in a new browser tab, opened on this template's folder.

Shown on labsdev.selfmade.ninja, a Selfmade Ninja Labs platform. On your own platform you will see your own domain and data.

1. Select Open in editor. The Editor ready dialog shows a One-time password.
2. Copy it. The dialog says it is shown only once, but if you lose it, select Open in editor again. While the editor is running, the password is shown again.
3. Select 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.
• Idle means the template's page in the dashboard has not been open in a visible browser tab. While that page is open and visible, it keeps the editor alive. Working only in the editor tab does not count, so keep the template page open in another tab.
• 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.

How the editor session works

Question	Answer
Who can open it?	Only the template's owner. It opens on all of your templates at once, so someone you shared a template with as Editor gets The workspace editor is available to the template owner only… — they edit through the Files tab instead.
What if it is already running?	Open in editor reuses it. The dialog says Your workspace editor is already running and shows the password again.
Can I see its state?	A badge next to the buttons shows editor: spawning, running, closed or error.
What does closing it do?	It stops the editor. Files you saved stay in the template; unsaved changes in the editor are lost.
Does deleting a template close it?	No. The editor serves all your templates, so it keeps running.

After the editor has closed, the same Open in editor button starts it again.

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