Create Your Template

There are two ways to create a template: aenv pull imports an existing OCI image directly, while aenv build runs a Dockerfile with BuildKit.

Some defaults below come from config/default.toml, or the file selected by AENV_CONFIG_PATH.

aenv pull

Pull an existing OCI image as a template and optionally give it a memorable name:

aenv pull <image> [options]

Examples:

aenv pull ubuntu:24.04
aenv pull ubuntu:24.04 --name my-base

--name is optional. Without it, AgentENV uses the image repository name. A template name can be used anywhere a template ID is accepted.

When using --detach, monitor the build with aenv template watch <template>.

aenv build

Build a Dockerfile with BuildKit inside a temporary microVM, then convert the result to OverlayBD and capture a template. Docker and a staging registry are not required on the CLI machine.

aenv build <context> --name <name> [options]
# From the repository root:
aenv build . -f deploy/docker/Dockerfile.agentenv --name aenv

Build Context and Dockerfile

COPY and ADD resolve from the context directory, independently of the Dockerfile’s location. Local directories are supported; URL and stdin contexts are not supported. BuildKit supports multi-stage builds, .dockerignore, cache mounts, and standard Dockerfile syntax. The final Dockerfile stage is always published.

There are no image, stage-selection, SSH, or builder-resource overrides in the build CLI. Select base images with FROM, including an ARG used by FROM.

Startup and Readiness

By default, image ENTRYPOINT and CMD determine template startup, and a Dockerfile HEALTHCHECK supplies the readiness command before snapshot capture. Shell health checks honor Dockerfile SHELL, and HEALTHCHECK NONE disables the check. Without a health check, startup uses the normal template readiness delay.

--start-cmd and --ready-cmd override startup and readiness independently without modifying the image configuration. Publishing boots the image and runs the selected startup command. An image can therefore compile successfully but fail during publication if its entrypoint requires devices that are unavailable in the guest. To capture the image without starting its application or running its health check, use:

aenv build <context> --name <name> --start-cmd "" --ready-cmd true

Build Capacity

Managed builder settings belong to the server configuration:

[template_build]
max_concurrent_builds = 4
builder_image = "docker.io/moby/buildkit:v0.33.0"
builder_cpu_count = 16
builder_memory_mb = 32768
cache_size_mb = 65536

Each node admits at most max_concurrent_builds managed builds, including preparation, image publication, and cleanup. When the per-node limit is reached, builder preparation returns HTTP 429. Retry the build when capacity is available.

cache_size_mb controls the persistent BuildKit cache volume. Its capacity is set when the cache is created, so changing the setting does not resize an existing cache. It must be at least 1024 MiB and cannot exceed volume.max_size_mb. A Dockerfile build is rejected if the configured cache capacity exceeds that volume limit; setting a smaller volume limit does not prevent the server from starting or serving other APIs. Builder CPU, memory, and cache capacity are independent of the CPU and memory assigned to the resulting template.

Monitor a Build

aenv pull waits for the template to become ready by default. If you submit it with --detach, monitor the build by template name or ID:

aenv template watch my-template

aenv template watch has no timeout option. Stop the local watch with Ctrl-C; the remote build continues. It reports the following statuses:

Runtime Configuration

Image configuration affects every sandbox created from the template. aenv pull retains the source image configuration, while aenv build produces it from the final Dockerfile stage. The table below distinguishes fields that affect the sandbox runtime automatically from fields that require explicit CLI options.

EXPOSE, VOLUME, and LABEL are retained as image metadata but do not create ports, mount volumes, or otherwise configure the sandbox runtime.