# Software Installation and Preloading

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](/agentos/docs/software#install-while-running) for the installation API.