Runtime Assets

Runtime assets are the local files MacTain needs before it can boot and run containers. Apple Containerization requires a Linux kernel and an init filesystem image; MacTain also manages tini for container process handling.

The normal first-run path is simple: install MacTain, verify the CLI and Engine, then install runtime assets before starting containers.

What Runtime Assets Are

Asset	What it does	Why it matters
Kernel	Boots the Linux environment used by container workloads.	Without a kernel, MacTain cannot start the container runtime environment.
initfs.ext4	Provides the init filesystem used to bring up the runtime environment.	Without initfs, the runtime cannot initialize containers.
tini	Runs as a small init process for signal and child-process handling when enabled.	It helps containers handle signals and process reaping correctly.

The default runtime root is:

~/Library/Application Support/MacTain/runtime/

Runtime asset paths live under the per-user MacTain storage root. Advanced users can change the Engine runtime root with MACTAIN_RUNTIME_ROOT, but the default path is the expected public install path.

Command Reference

Command	Description	Typical use
mactain runtime install	Installs or updates runtime assets.	Run before the first container or when MacTain reports missing runtime assets.
mactain runtime update	Alias for runtime install.	Use only if you prefer the update wording.
mactain runtime rollback [asset] --to previous	Rolls back all assets or one named asset (kernel, initfs, or tini) to the previous installed version.	Use after a runtime asset update appears to break container starts.
mactain runtime docs	Shows built-in runtime help and examples from the installed CLI.	Use when you want runtime help that exactly matches the installed build.

Defaults And Behavior

• Runtime assets are per-user because MacTain's Engine is per-user.
• If runtime assets are missing, Engine errors use the stable code container_runtime_assets_missing.
• In interactive CLI sessions, MacTain can prompt to install missing assets and retry the original command.
• In non-interactive contexts, the CLI prints deterministic remediation such as Run: mactain runtime install.
• The default kernel path can be auto-provisioned by the Engine. The Engine can download and install the recommended kernel used by Apple's container project when the default kernel path is missing.
• MacTain generates initfs.ext4 locally from Apple's published vminit image.
• Rollback is for recovering from a bad or incompatible runtime asset update; it is not a normal daily workflow.

Practical Use Cases

Use case: prepare a new install for containers

Use this after installation verification and before running your first container.

mactain runtime install
mactain engine status

If this fails, collect recent logs before changing container commands:

mactain system logs --lines 200

Use case: handle a missing runtime asset message

Use this when a container command reports that runtime assets are missing.

mactain runtime install
mactain container start --help

Run the same container command again only after runtime installation succeeds.

Use case: roll back after a runtime update

Use this only after an asset update appears to break container startup and you want to return to the previous installed asset version.

mactain runtime rollback kernel --to previous
mactain runtime rollback initfs --to previous
mactain runtime rollback tini --to previous

For automation, add --yes to skip confirmation:

mactain runtime rollback kernel --to previous --yes

After rollback, check Engine status and retry a small known-good container.

Troubleshooting Entry Points

• Runtime install fails: collect mactain system logs --lines 200.
• Container command still reports missing assets: confirm mactain runtime install completed successfully and retry from a new shell session.
• A rollback does not fix container startup: check Engine status, image access, and container logs before changing Blueprint or networking settings.

Next Steps

Continue to Containers and Run your first container.

Related

• Installation
• Verify installation
• Resource management
• Troubleshooting