Logs, exec, and redeploy

An AppVM has the same lifecycle actions as a classic VM, plus the things that matter for application workloads: logs, exec, files inside a running machine, and redeploy.

Logs

The workload’s output is captured on the host and shown on the machine’s page, so you do not need a terminal to see why something failed. Logs survive a Virtainer Free restart, and the stream resumes on its own if the connection to the guest drops.

What survives is the current boot. The log is cleared when the machine starts, so a reboot, a redeploy or a rollback begins a clean file. Capture anything you need before you restart the machine.

Exec

Exec starts a process inside the running machine. It has two forms, because people want two different things from it.

The terminal is the Shell tab on the machine’s page: an interactive session with a real terminal, which is the fastest way to check what the workload actually sees. Open in new tab gives you a second one while the first keeps running.

A single command runs to completion and gives you back the result: standard output and standard error as two separate streams, and the exit code, or the signal that killed the process. The console has no field for this form; it is a call to the machine’s exec endpoint, useful from a script rather than from a browser. The command is a program plus its arguments, with no shell in between, so nothing merges the two streams or rewrites line endings on the way out. Use this form when you want an answer rather than a prompt.

Both forms start as the image’s user, with the workload’s environment, so a file either one creates is a file the workload can use. Shell (root) in the machine’s More menu is the break-glass session for when a repair genuinely needs root.

Sessions do not queue and do not replace one another. A machine carries up to 16 of them at a time, terminals and single commands alike, so a script running a check does not disturb the terminal you are looking at. The 17th is refused with that limit in the message rather than quietly pushing an existing session out. Closing a terminal ends that session and kills what was running inside it, rather than leaving it behind.

The host has a ceiling of its own across every machine at once: 64 WebSocket sessions, which covers the console and the terminal form of exec. A single command sent to the exec endpoint does not take one of those slots. A request past the ceiling is refused with too many active console/exec sessions; try again later, so a script that opens a terminal per machine will eventually be told to wait.

Only the terminal needs a shell

The terminal starts /bin/sh, so a distroless image has no terminal. A single command does not: it starts the program you name, which works as long as that program is in the image.

A single command has a size and a time ceiling

The result carries at most 1 MiB of standard output and 1 MiB of standard error. Anything past that is dropped and the result is flagged as truncated. The command gets 60 seconds unless you ask for longer, and 3600 seconds is the cap. A command that runs out of time is killed and the result reports a timeout, which is deliberately not the same as the command having failed.

Both forms need a machine that is running and a guest that is reachable. During a boot, or while the link to the machine is being re-established, they tell you so instead of holding your request until something times out.

Files in a running machine

These are API operations: the console has no file browser. Through the HTTP API you can work against a running machine’s filesystem directly: read a file, write one, delete one, list a directory, check what a path is, create a directory, and rename or move within the machine. That is how you look at the configuration an application just wrote, and get it byte for byte rather than as text a terminal has already reformatted.

What is worth knowing before you rely on it:

	What it means
Paths	The absolute path as the workload sees it. /etc/hosts means that file inside the machine, never the host’s. .. and symbolic links are resolved inside the machine’s own filesystem and cannot get out of it
Writes	A write replaces the whole file. There is no append
Ownership	A file or directory created this way belongs to the workload’s user, so the workload can read it and remove it. A path that already existed keeps the permissions it had
Deletion	A non-empty directory is refused unless the call asks for a recursive delete
Size	One call carries at most 32 MiB. Anything larger belongs on a data volume, not through this channel
Failures	A missing path, a path of the wrong kind, and a path that cannot be written are reported as different failures, so a caller can branch on what happened rather than parse a message

A file you change this way lives where the workload’s filesystem lives. A path on a data volume lands on that volume and survives a redeploy. Anything else is on the system disk and is gone after one.

Who can reach these

Of the three, only the interactive terminal has a screen in the console. The single-command form and the file operations are HTTP endpoints.

None of them is reachable with an API key. They read any file in a machine that already exists and run any program in it, so they stay with an administrator signed in to the console, and a script calling them needs that session rather than a key. Automation that holds a key drives a machine through the workload’s own interface instead.

A machine older than the host

A machine’s guest declares, when it boots, which of these it supports. A machine that was already running when Virtainer Free was upgraded is still using the guest it started with, and that one may never have heard of the single-command form or the file operations. Its terminal keeps working, and the rest answer with a refusal that names the fix: redeploy or reboot that machine. Plan the restart for a moment the workload can spare, and it comes back with a guest that supports all of it.

Editing what a machine runs

More → Edit configuration opens the workload spec of a running AppVM: the command override, its environment and secret environment, the health check, the keepalive choice, and the files and mounts the host manages for it.

Two boundaries are worth knowing before you use it. It changes what the workload process is, not what the machine is: vCPUs, memory and disks have their own editors, and this one will not touch them. And like every other declaration on an AppVM, an edit here takes effect on the next boot rather than reaching into the running process. The console says so on the form, because “I changed it and nothing happened” is the expected confusion.

Redeploy

Redeploy rolls the machine onto the current build of its template. It stops the machine, applies the new image’s process settings, gives it a fresh copy of the system disk, and boots it. When the template has drifted from the build the machine is on, the action reads Redeploy (new build).

Kept	Reset
Data volumes, with their contents	The system disk
Environment, including secrets
Network configuration and volume attachments
Keepalive and process overrides

If a redeploy fails partway, the machine is put back the way it was: the old disk returns and the record is untouched, so you can fix the cause and try again.

Redeploy resets the system disk

Anything the workload wrote outside a data volume is gone after a redeploy. That includes anything you put there through exec or the file operations. That is the point of it, but it is only safe if your persistent data is on a volume.

Health and exit codes

The workload’s exit code and signal are reported into the machine’s state, so a machine that stopped tells you how it stopped. If the guest stops responding while the machine is still running, the console flags it rather than continuing to show it as healthy. A machine that simply fails to answer is not destroyed on the strength of that: if its process is alive, Virtainer Free leaves it running and records the unresponsive state for you to look at, because a hang is not the same as a death and destroying a machine cannot be undone.

A machine created as a job reads differently, because for it an exit is the outcome you asked for: it reports that the run succeeded, failed, exceeded its deadline, or was interrupted, and nothing restarts it. See Runtime options.

No snapshots

AppVMs do not have snapshots. Redeploy is how you move a machine to a different build: point the template at the build you want and redeploy onto it. Your data volumes come through untouched, because a redeploy replaces the system disk and not the volumes.

The machine also remembers exactly one generation behind. The build it was running before its last redeploy or rollback is kept, and POST /api/instances/<id>/rollback returns to it as the same kind of durable operation, with the same progress and failure reporting. It is an API action: the console offers Redeploy, and rolling back is a redeploy onto the retained build. Because only one generation is kept, rolling back twice does not step further into the past.

To move an AppVM to another host, or to copy it off this one, see Move a machine to another host and Backup and restore.

Restart and reboot behaviour

Restarting or upgrading Virtainer Free does not disturb a running workload. After a host reboot, machines that were running come back automatically and keep their addresses. See After a host reboot.

A machine that was already running through an upgrade keeps the guest it booted with, and an older guest is what refuses the newer ways in. Its workload is untouched, and a redeploy or a reboot gives it the current guest.