Runtime options

An AppVM runs the image’s declared process by default. These options override it, and they map closely onto the docker run options you already know.

Everything set here is recorded with the machine and carried through a redeploy, so a rebuilt machine keeps its configuration. It takes effect when the machine boots: changing an option does not reach a workload that is already running, which is what the configuration editor tells you too.

Process

Option	Equivalent	What it does
Command override	the arguments after the image	Replaces the image’s entrypoint arguments
Working directory	--workdir	Sets the directory the process starts in
Run as user	--user	Runs the process as a different user
Environment variables	--env	Sets environment variables
Secret environment variables	--env from a stored secret	Sets environment variables from values the console never shows back again
Extra hosts	--add-host	Adds static hostname:ip entries to /etc/hosts
Stop grace (seconds)	--stop-timeout	How long to wait before forcing a stop, up to 300 seconds

Service or job

A machine is created as one or the other, and it stays that way, because the choice is about what an exit means rather than about the image.

A service is the default: a workload that exits is a problem, so this is the kind that takes a restart policy. The policy starts at no, and both restarts and automatic recovery follow it, so nothing restarts and nothing is recovered until you choose always or on-failure. A job runs once and the run finishing is the point, so it reports succeeded, failed, deadline exceeded, or interrupted and nothing restarts it. Its restart policy is fixed at no, a run cut short by a host reboot stays interrupted until you choose to rerun it, and an optional deadline in seconds bounds the run through the normal stop path. Each run starts from the system disk as the machine was created with, not from where the last run left it, so anything worth keeping belongs on a data volume.

Keepalive

Keepalive replaces the image’s entrypoint with a long-running shell, so a base image whose entrypoint would exit immediately stays up and you can open a terminal into it.

Keepalive is for debugging, not for services

Keepalive is for debugging. Do not use it to hold a service image up: it hides a failing entrypoint behind a shell that never exits, so a broken workload looks healthy. It is also mutually exclusive with a custom command.

Health checks

If the image declares a health check, it is used. You can replace it with a shell command and your own timings, replace it with a TCP or HTTP probe against a port on the loopback interface, or turn health checking off entirely. A TCP or HTTP probe is run by the guest’s init process without a shell, which is what makes health checking possible on an image that has none. The console offers the shell-command form and its timings; the TCP and HTTP probes are on the API. Setting your own health check, disabling it, and keepalive are mutually exclusive.

Health status feeds the machine’s state, and its automatic recovery once a restart policy turns that on, so a health check that reports honestly is worth having.

Files

Files are managed by the host and materialised into the guest. There is no bind mount from the host filesystem.

Option	Behaviour
Config files	Written into the guest filesystem in plain text at the path you choose
Secret files	Stored encrypted, decrypted only on the way into the guest, written to memory-backed storage, never shown back
Tmpfs mounts	Memory-backed directories, like --tmpfs
Data volumes	Real persistent disks, optionally read-only. See Data volumes

Writing the data volume lines

Data volumes are declared one per line, and the line says both how big the disk is and where the workload reaches it:

Line	What it mounts
10:/var/lib/postgresql	A new 10 GiB volume, registered on the host, mounted there
vol:pgdata:/var/lib/postgresql	The existing volume named pgdata from the host’s Volumes page
2:/config:ro	A new 2 GiB volume, mounted read-only

The difference between the first two is where the volume comes from, not what happens to the data. A vol: line names a volume that already exists on the host. A bare size creates a new one, which the host names after the machine. Both end up as the same kind of volume: the host registers it, so deleting the machine or detaching the volume leaves the file and its contents alone, and either one can be mounted on another machine. See Data volumes.

If the image declares its own mount points and you have not backed one of them, the form says so directly: it names the path and warns that data written there is lost on redeploy, with the line to add. Read that warning rather than dismissing it, because the common failure is a database image that declares a data directory and quietly writes it onto the system disk.

You supply the content; the host puts it in place. That is what lets a redeploy rebuild the machine from a new image and still land your configuration.

These files are written again every time the machine boots, just before the workload starts, so editing one of them inside a running machine is a temporary change: the next boot puts the declared content back. For the files the machine has of its own, and for running something while the workload is up, see Logs, exec, and redeploy.

Networking

Choose which VM network the machine attaches to, the same way a classic VM does. Leaving it unset attaches it to the host’s default VM network.

Addressing is either static or DHCP. With DHCP, the machine reports the lease it received, and that stays visible across a restart of Virtainer Free.

A DHCP address has a 30 second deadline. If no lease arrives by then the workload fails with no DHCP lease within 30s on <interface> and the machine powers itself off, which on a network with no DHCP server looks like a machine that boots and immediately dies. Choose a static address on such a network.

A hostname is optional. Without one, a DHCP machine picks its own and a static machine gets one derived from its MAC address.

Secrets

Environment variables can be marked secret. They are stored encrypted, merged in only when the machine boots, and carried through a redeploy. They are not displayed again after you set them.