Software Installation and Preloading

Understand URL package installation, process caching, readiness, and preload coordination for hosted agentOS VMs.

Each VM projects installed packages as read-only filesystem leaves. The projection is bounded by config.limits.agentosPackages.maxMounts (4,096 by default), including command aliases and provides.files directory mounts. Installing another package can fail with a resource-limit error even when the download succeeded; the existing VM projection remains in place.

Hosted VMs install immutable .aospkg files from HTTPS URLs. Embedded Core also accepts a trusted local file path. A hosted VM never receives or materializes a host path.

Resolution and projection

The resolver validates the URL, blocks ambient credentials and private network destinations, bounds redirects and response headers, downloads into a temporary file, verifies the optional SHA-256 digest, and validates the package format. The verified content digest becomes the package identity.

The sidecar projects installed packages under /opt/agentos/pkgs/<name>/<version> and command links under /opt/agentos/bin. v1.software.list reads the current installed set. v1.software.install and v1.software.uninstall are durable config mutations, so they use the same revision checks and reconciliation as v1.config.patch.

Process cache

All VMs in one worker process share the child sidecar’s content-addressed cache. Concurrent requests for the same digest are coalesced into one acquisition. The cache is bounded by bytes, entries, active downloads, pending downloads, and acquisition time. Live VM generations pin their package files. Unpinned entries are evicted in least-recently-used order.

By default, each worker gets an isolated process-lifetime temporary cache. For persistent recovery, set a distinct AGENTOS_PACKAGE_CACHE_DIR for each concurrently running worker. An OS lock prevents startup recovery or eviction from removing another worker’s live package files. Restarting a worker with the same directory recovers verified packages.

The services worker removes its temporary cache after normal shutdown or startup failure. Forced termination or a host crash can leave temporary directories behind; configure host temporary-directory cleanup for those leftovers. Persistent directories are never removed at worker shutdown.

Partial downloads and failed publications use temporary files that are removed when their operation is cancelled or fails. Package source URLs are kept only as a short-lived bounded hint. Bytes are still verified before projection.

Startup preloading

The agentOS-preload-coordinator is a central Rivet Actor that stores a low-frequency popularity hint. It is not an authoritative registry or cache. Each worker process reads one bounded plan at startup, coalesces that read for the process, and warms likely package digests with bounded concurrency. The default process warm deadline is 10 seconds.

Required packages still determine VM readiness. An advisory preload timeout or coordinator failure only reduces the cache hit rate.

See Software for the installation API.