Run a Docker image

An AppVM is a Docker or OCI image booted as its own virtual machine. It has its own kernel and its own disk, and no container engine runs inside it. The machine is the boundary.

You keep the parts of the container workflow that matter: the image you already publish, environment variables, restart policies, health checks, and logs.

Import an image

An OCI image becomes a template (an AppVM image in the console) before it can boot. Open AppVM images under AppVMs and add one.

1. Find the image.

   Search the public catalog, or type a full image reference yourself. Typing the full reference is the way in for a private or self-hosted registry, with credentials when the registry needs them.

2. Let the host convert it.

   Virtainer Free pulls the image and converts it into a bootable template. This happens once per image, on the host.

3. Check the result.

   The template records what the image declared: its entrypoint, working directory, user, environment, and the volume paths it lists.

You can also build a template from a Dockerfile with a build context, or from a git repository over https://, http://, or git://, and rebuild it later from the same source. Private repositories and git credentials are not supported.

A repository that cannot be cloned is reported as a public-or-private problem, and that wording is a catch-all: it also covers a wrong URL, a wrong ref, a wrong Dockerfile path, and a build host that cannot reach the repository at all. The build log carries what the clone actually reported, so read it before changing the repository’s visibility.

Templates and machines are independent

Creating an AppVM makes its own copy of the template, so a template can be deleted without touching machines already running from it.

Create the AppVM

The AppVM form asks for less than the VM form, because the image already decides most of what the machine is. The one switch worth noticing is Start after creation: turn it off to create the machine and leave it stopped, which is what you want when the environment or a data volume has to be in place before the workload first runs.

Open Instances and create one from your template. Size it, attach it to a network the same way as a classic VM, set environment variables, and choose a restart policy.

Before you create it, it is worth knowing whether your image runs unchanged. Most service images do. Base images such as alpine, debian, node, and python exit immediately, because their entrypoint is an interactive shell. Will my image run? covers this in one page.

Keeping a template current

The AppVM images page lists each template as a card rather than a table row, because the states do not share a shape: a ready template has a digest and a size, a failed one has a paragraph of error, and one still building has a progress bar. Each card links to the template’s own page (/appvm/images/:id), which holds what a card cannot: the full digest, the root filesystem layer count and size, the entrypoint and user, the volumes the image declares, the Dockerfile or git source that would rebuild it, and the build or publish log.

A template imported from a registry tracks a tag, which is a moving pointer, while this host stays pinned to one digest. When the two part company the card reads Update available. The agent checks upstream on its own each day; Check for a newer image asks it now with a single manifest lookup that pulls no layers. A registry it cannot reach is left as the last known answer rather than reported as up to date.

Update is the step after that notice. It pulls the newer build the tag now points at and moves the template to that digest, while keeping the old build file. AppVMs already running this template keep running it, untouched, and each one switches to the new build the next time you redeploy it. The template’s own page carries the same notice, the same Check for a newer image control, and the same Update action.

A declared volume is not a data volume

The detail page lists the paths the image declares with VOLUME. An AppVM does not create data volumes for them, so anything written there is lost on a redeploy unless you mount a volume at that path. See Data volumes.

Publishing a template

A template built on this host exists only as a disk image here. Publish to a registry on a ready template’s card pushes it out so another host can pull it instead of building it again.

1. Give the Registry host, the Repository, and the Tag.
2. Supply credentials for that registry. They are required, and they are not written to logs.
3. Watch it go. The push is a background operation: its progress and any failure show on the card and in Operations, and the full publish log is on the template’s page.

What gets published is what this host is running

Publishing pushes the exact filesystem this template holds. The agent compares the image’s root-filesystem layers against the template and refuses the push when they differ, rather than putting an image on the registry that this host does not run. A template you built here keeps its own source image for this, so the check normally passes and nothing is rebuilt; a template you imported is pulled back before it is pushed. When the layers do differ, the refusal names the fix for that origin: rebuild a template built here, or adopt the newer build of a template you imported. A built image removed outside the product falls back to a rebuild that may not match, so it needs one rebuild first.

Publishing takes an explicit Registry host and never infers one, so a bare owner/repository is refused. Docker Hub, Quay, and GHCR all work, and so does any other OCI registry this host can reach, including a private one on a port. Docker Hub, Quay, and GHCR want an owner/repository path, while a self-hosted registry may keep a single repository name. For GHCR, use a classic personal access token that can write packages; a new GHCR package starts out private.

A push that fails leaves the template ready and marks its card Publish failed. Opening that marker, or the Publish log on the template’s page, shows why the host stopped along with the raw push output.

AppVM image admission

The AppVM image admission card on the AppVM images page limits which OCI images the host may import or build into AppVM images. It is enforced on image imports, refreshes, rebuilds, and publish-source recovery. Publish destinations are chosen per image and are separate from this policy.

Control	Effect
Allowed registries	One registry host per line, with an optional port. An empty list allows any source; listing a host restricts pulls to those listed
Require Cosign signatures	Accept only images signed by a key below, where the signed repository matches the one requested
Cosign public keys	One or more PEM public keys. They can be saved before enforcement is turned on

Dockerfile build steps and remote Git build contexts can still fetch other content while an image is being built; this policy governs the AppVM images the host admits.

Reclaiming space

Building and importing templates leaves layers behind on the host. The AppVM images page shows that as Host OCI image cache, with its total size and how many images are in it.

Tick the checkbox on several cards to remove a batch of old templates or failed builds in one pass, rather than opening each card’s menu in turn.

Manage cache opens Manage OCI image cache, which covers the layers themselves in two halves:

	What it does
Automatic cleanup	Off to begin with. Choose to clear at the next scheduled run, or to keep layers newer than 1, 7, 30, or 90 days
Clear cache now	Pick dangling build layers or all unprotected cache, pick a minimum age, and confirm the selection before anything is removed

Automatic cleanup runs when Virtainer Free starts and then five minutes after each run finishes. Changing the policy saves it for the next run; it does not clear anything on the spot.

What the cache never contains

The layers a template needs in order to be published stay protected until that template is deleted, so a cleanup cannot break a later publish. Your AppVMs’ own disks are not part of this cache at all, and nothing here touches a running machine or its data.

Restart policies

Policy	Behaviour
no	Never restarted automatically
always	Restarted whenever the workload exits
on-failure	Restarted on a non-zero exit, a signal, or a fatal error, and not on a clean exit

Restarts back off from 2 seconds up to a 5 minute ceiling, and the counter resets after the workload has stayed up for 30 seconds. A machine you stopped yourself is never restarted automatically.

Persistence

The system disk is a private copy of the template and survives stop and boot. It does not survive a redeploy, which resets it from the new template on purpose.

Anything you need to keep across a redeploy belongs on a data volume. See Data volumes.