Virtual Machines

Biztraak supports virtual machines as first-class project components. The main VM deployment experience is currently disabled because deployVmEnabled is false in the current frontend configuration. The runtime and API capabilities described below apply when that experience is enabled and the selected provider and VM composition support them.

What a Virtual Machine Includes

A virtual machine in Biztraak can include:

Infrastructure: a VM provisioned in your cloud account
Runtime Operations: start, stop, status, shutdown timer, browser session, and system logs
Composition: a base VM template plus optional add-on packs
Capabilities: machine-readable support for container runtime, ingress, TLS, and managed hosted deploy
Hosted Workloads: separate project components that run inside the VM instead of deploying to their own cloud runtime

Core Concepts

VM Template

A reusable store item that defines the base VM shape and default software stack. Examples include:

Code environment VMs
n8n VMs
Ollama VMs

VM Add-on Pack

A store-backed package that extends the VM with additional software or runtime capability. Examples include Docker, terminal, node, python, or security tooling.

VM Capability

A capability is a machine-readable feature contract resolved from the VM template plus its add-ons. The platform uses capabilities to decide what a VM can safely host.

Common capabilities include:

HostedContainerRuntime
ReverseProxyPathRouting
ReverseProxyHostnameRouting
TlsTermination
ManagedHostedWorkloadDeploy

VM-hosted Workload

A separate application component that runs inside a VM. It keeps its own identity, config, and deployment tracking, but uses a selected VM and VM provider as its execution target.

Host VM and Host Provider

Host VM: the virtual machine project component selected for the workload
Host Provider: the specific deployed VM provider instance selected for a managed deploy

If a VM has multiple deployed providers, you must choose the exact provider to target.

What you can do

Create virtual machine project components
Provision VMs on supported cloud providers
Start and stop running VMs
View runtime status and system logs
Manage shutdown timers
Open browser sessions according to the VM runtime path listed in Capabilities and Availability
Compose VMs from templates and add-ons
Create VM-hosted workloads with an explicit host VM
Deploy VM-hosted workloads through the managed VM-hosted deploy path when the VM supports it

Marketplace install behavior

Marketplace packages now follow one of two public install paths:

Install on existing VM when the package resolves only to VM add-ons
Create project when the package contains components, or a mixture of components and VM add-ons

For mixed packages:

packaged components are created as project components
VM add-ons are materialized automatically for any created VM hosts
host-targeted package overrides apply automatically when the package targets a specific created VM component

Supported VM-hosted workload model

VM-hosted workloads currently use this model:

The workload is its own project component
The workload must be created with a selected host VM
The workload stores desired hosting settings such as exposure mode, route/domain, port, limits, and health checks
Managed deploy targets one explicit VM provider
Runtime state is tracked separately from desired config

Important rule:

A VM-hosted workload cannot exist without selecting a host VM

Public Exposure Modes

Path Prefix

Path-prefix exposure is the safest current default.

Requirements:

the workload must be public
the VM must support ReverseProxyPathRouting
the route prefix must be unique on that VM
the route prefix must not conflict with a reserved route from the VM template or add-ons

Hostname

Hostname exposure lets a workload use its own domain.

Requirements:

the workload must be public
the workload must have a team domain selected
the VM must support ReverseProxyHostnameRouting
the VM must support TlsTermination
the selected domain must be unique on that VM

Managed deploys

Managed VM-hosted deploys are capability-gated.

They currently require:

a VM that supports ManagedHostedWorkloadDeploy
a VM that supports HostedContainerRuntime
an explicit host VM provider selection
a workload component that already has a container image configured

This means the current managed runtime path is image-based. The existing add-from-image and add-from-repo flows can already target an existing VM, while deeper provider-specific repo artifact handoff remains narrower than the core image-backed path.

Current limits

Standard update flows do not allow moving an existing VM-hosted workload to another VM
Moving between VMs is not treated as a normal redeploy
Manual workload reassignment between VMs is available. Richer clone semantics and dedicated transfer pickers are still limited
Not every VM template or add-on combination supports managed hosted deploy
Not every VM template or add-on combination supports hostname routing

Troubleshooting

The platform says the selected host is not a virtual machine

Cause:

the selected host component is missing or is not a VM component

The platform says the VM must be in the same project

Cause:

the workload and the selected host VM belong to different projects

The platform rejects the route prefix

Cause:

the route is already used by another hosted workload on that VM
or the route is reserved by the VM’s template/add-on composition

The platform rejects hostname exposure

Cause:

the selected VM does not support hostname routing or TLS
or the selected domain is already used by another hosted workload on that VM

Managed deploy is rejected

Cause:

the selected VM composition does not advertise the required managed deploy capability
or the workload does not currently have a container image configured

Related docs

Virtual machines give you a flexible runtime for full-machine workloads and VM-hosted application deployments while keeping the VM, hosted app, and deployment target explicit.