Build and deploy
By the end of this page you will have built your template, deployed a running copy of it, and know how to roll a change out — or back.
1. Build & validate
Open the template and go to the Build & validate tab.
| Control | What it does |
|---|---|
| Build & validate | Checks the template, then builds it into an image |
| Validate only | Runs the checks without building — quick feedback while you edit |
| No cache | Builds every step from scratch instead of reusing earlier results. Use it when a build seems to be using stale downloads. |
What validation checks
Before anything is built, the template is checked in phases:
- The configuration is well-formed.
- The
Dockerfile— a usable base image and package manager. - code-server is installed and has a user to run as.
- The VPN plumbing is in place.
- Bind mounts point only at safe locations.
Findings are listed with a severity. Errors block the build — you'll see Validation failed — fix the errors before building. Warnings are advice; the build goes ahead.
Build progress
While it builds, a progress bar shows how far through it is and which step is running. The full output streams to the Server Logs terminal at the bottom of the page. When it finishes, you get Build complete — or Build failed with the reason, and the log shows the detail.
Only one build runs per template at a time (A build is already running for this template), and you can run a limited number of builds at once across all your templates.
Following a build
- Opening the tab checks the template. When you open Build & validate, the checks run straight away and any findings are listed, before you select anything.
- The step label names the build step that is running, for example build 19/62 followed by the command. The percentage counts finished steps. Steps that are reused from an earlier build finish instantly, so the bar can jump.
- Leaving the page does not stop the build. Come back, or reload, and the bar picks up where the build is, and the log reattaches.
- Builds started elsewhere show up. If you start a build from another tab or through an AI assistant, an open Build & validate tab notices it within about 15 seconds and follows it.
- Validate only shows the five checks as a list of named steps, checked off as they pass. It does not show a percentage.
- The header shows last built with how long ago that was, and the current status.
Build limits
| Limit | What you see |
|---|---|
| One build per template at a time | A build for this template is already running. |
| Three builds at once across all your templates | You already have 3 builds running (limit 3). Wait for one to finish. |
Platform administrators are not limited to three.
There is no button to cancel a build once it has started. Let it finish or fail.
When a build fails
- The bar turns red and the reason appears under it. This is the error line the build reported. The Build failed message shows the same reason.
- The status goes back to draft, and the VPN and code-server badges are cleared. Deploy still runs the last successful build, if there was one.
- The reason stays on the Build & validate tab, marked last build failed, even after a reload, until your next build starts.
- The full output is in the Server Logs terminal. Read it from the bottom up: the reason is usually in the last lines before the failure.
A build that never finishes. If a build stops reporting — for example because the platform restarted during it — the template does not stay stuck on building forever. After about 30 minutes, it is marked failed with a message that says the build was lost, and you can build again.
The post-build checks
After a successful build, the platform checks two things. The results appear as badges in the editor banner.
| Check | If it fails |
|---|---|
| VPN | Copies cannot be deployed with the VPN. Deploys are refused with a message telling you to fix the image and rebuild, or switch the template to internal-only. |
| code-server | The browser code editor is marked missing |
2. Deploy a copy
Go to the Deployments tab and select Deploy. The Deploy a copy dialog is the same one used for extra labs: a name, the login user, shared or isolated storage, and SSH keys.
The dialog tells you how many of your lab slots you are using. Copies count against your plan's limits like any other lab.
The deploy log streams in the Server Logs terminal. When it finishes, you get Deployment ready — open the copy's dashboard from the list — or Deployment failed with a pointer to the deploy log.
Deploying copies of templates requires a paid plan.
Common messages:
| Message | Meaning |
|---|---|
| Build this template first — only built templates can be deployed. | Run Build & validate first |
| Edits are pending a rebuild — Deploy runs the last built version | You changed something since the last build. The copy gets the older build. |
| This template is not published for deployment yet (still in alpha/draft). | Someone else's template that is still in alpha |
The Deployments tab lists every copy, in list or card view, each linking to its own dashboard.
- The heading counts this template's copies — for example 3 deployments · 2 running.
- The line under Deploy counts your whole account: Using X of Y lab slots on your plan. It turns amber when you are at the limit. Copies of your templates share the same pool as every other lab you run.
- Each copy keeps its own record of deploy attempts, with status, duration and errors — see Deploy history and failures.
Who can deploy what. You can always deploy your own template once it has been built, even while it is still alpha. Anyone else can deploy it only when it is built, its stability is beta or stable, and they can see it (because it is public or shared with them as Deployer or above). They also need a paid plan.
A deploy is also refused if the template needs the VPN and its VPN check failed on the last build.
3. Roll out a change
- Edit the template and save.
- If the change needs a rebuild (see When a change takes effect), run Build & validate.
- Redeploy each copy. Copies built from an older version show an update available badge — its tooltip names the new version.
A copy never updates by itself. Redeploying keeps its home directory, like any redeploy.
Versions
The Versions tab records every save, build, restore and publish. The version number in the banner goes up with each one.
How the number moves. Versions look like v0.4.2:
| Event | Change | Example |
|---|---|---|
| A build | The middle number goes up and the last resets | v0.4.2 → v0.5.0 |
| A save, a restore or an import | The last number goes up | v0.5.0 → v0.5.1 |
So the middle number counts builds, and the last counts changes since the last build. Each row in the list shows its kind (save, build, restore, import), when it happened and who made it — the owner, a platform administrator, or someone you shared the template with as Editor.
Diff compares a version with the one before it, side by side or as a single Unified view. A version that changed no files says so. Very large diffs are cut short with Output truncated (large diff).
| Action | What it does |
|---|---|
| Diff | Shows exactly what changed in that version |
| Restore | Puts the template's files back as they were at that point. The status goes to draft, and the restore is itself recorded — so you can always roll forward again. |
Restoring changes the template, not your copies. Rebuild and redeploy to put a restored version into service.
Git sync
Sync to my GitLab pushes the template's history to a repository in your own account on the platform's GitLab. It creates the repository the first time.
- Repo name is optional; it defaults to the template name.
- Visibility: Private (recommended), Internal or Public.
- It is one-way: the platform pushes, and never reads changes back. To bring a repository in, use Import ▾ → From Git….
- Save or build at least once first, so there is something to push.
Export
⋯ → Export as JSON downloads the template as one file, which you can bring back later with Import ▾ → From JSON….
Text files are included up to about 8 MB in total. Larger files and binary files are listed by name only. Use Git sync to keep a fuller history.
Deleting a template
⋯ → Delete template. It is refused while copies are still running — you'll see Terminate them before deleting the template. Terminate the copies from their dashboards first.
The check counts everyone's copies, not just yours. If your template is public or shared, a copy another person is running, or one that is still deploying, also blocks the delete. The message tells you how many live copies there are.
The owner, a platform administrator, or someone you shared the template with as Manager can delete it. Deleting is permanent and removes, in one go:
| What | What happens to it |
|---|---|
| The template's files, image and version history | Deleted. Push to Git first with Git sync or Export as JSON if you want to keep a copy. |
| Its listing in Labs | Removed, so no one can deploy it again |
| Stopped copies | Removed from everyone's lab lists |
| Every share and workgroup grant | Revoked |
| An App Store listing, if it was published there | Withdrawn |
| Your full editor | Keeps running — it serves your other templates |
| A repository you pushed with Git sync | Stays in your GitLab account |
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 |
|---|---|
| “Check my template for problems without building it” | build_template as a dry run, which validates only |
| “Build it and tell me when it is done” | build_template, then wait_for_build |
| “Why did the build fail?” | template_build_log |
| “Deploy the first copy” | Checks readiness with template_status, then deploy_template |
Both return as soon as they are queued, so the assistant waits for the result rather than reporting success immediately. A template's very first deploy goes through deploy_template; after that it is deployed like any other lab.
Next
- Share and publish — give others access
- Running extra labs — managing the copies you deploy