Deploying in containers — AEL documentation

A program written in AEL, the Agent Engineering Language, runs in a container as a native program, with nothing else to start first. Programs build into standalone native binaries, including static Linux binaries, and minimal container images start with nothing to compile, install or download at startup. This tutorial puts a complete agent into an image, gives it its settings when it runs, follows its lifecycle and shows how to measure its start-up yourself.

Step 1: choose the image

Images come in two forms:

Form	What it holds
Minimal	Nothing but your program and the files it needs, with no shell and no package manager.
On a small Linux distribution	Your program and its files on a small distribution, for programs that need what the distribution provides.

Both are built from the Linux targets; Containers and Supported targets describe them. Each build records exactly what went into it, so you can check what an image contains.

Step 2: decide what goes in

Your program, as a static Linux executable built from compiled AEL.
The files it needs, each on purpose: prompts kept as files, assets, and the trust roots for verifying TLS certificates.
The runtimes you provide, if your program holds functions in other languages: they are built and run with your own toolchains, pinned by version, so the image carries the runtime each one needs.
Nothing else: no AEL toolchain and no compiler.

Step 3: give it its settings when it runs

Settings and secrets come from files or environment variables when the container runs, and are never written into the image:

What	How it reaches the program
Configuration values	Named environment variables or files, read when a run starts, as layers above your defaults.
Secrets	References to files or environment variables; a secret's value never appears in your source, the image or routine logs.
The system prompt	A file you mount, the environment or configuration, or none: the agent then runs on its input alone.
The model binding	The deployment's binding: the endpoint, the model and a reference to the credentials.

Typed, reusable configuration is locked into a snapshot for each run, so a value changed in the container's environment applies to the runs that start afterwards. A missing required setting, credential, system prompt or file stops the program promptly with a clear error, never with a false report that it is ready.

Step 4: follow the process lifecycle

Start. The program is the container's main process. No source is parsed, no package installed and no model weights downloaded when it starts.
Ready. It reports ready once its own configuration, prompts and files are validated and it can accept a request: a console agent when it can accept input, an HTTP agent when its routes are bound and it is listening. Whether a model provider can be reached is reported separately, and readiness checks never call a model.
Run. Structured logs go to standard error by default, so standard output carries only the program's result. Structured logs go to the console, a file, or custom or remote sinks, with redaction, rotation and retention; a file log needs a writable mount you declare.
Stop. On a stop signal the program finishes or cancels its work within a bounded deadline, then exits. A one-shot program keeps its exit status.
Restart. A run is durable only when its agent declares a storage point; without one, the run runs to completion and keeps nothing. So a restarted program resumes only the runs whose agent declares a storage point, keeps the budgets of the work it resumes, and never replays a side effect whose outcome is unknown.

Images run as a user other than root, with a read-only root file system. Per-agent CPU and memory limits state whether each limit is hard-enforced or accounted.

Step 5: measure start-up on your platform

Start-up depends on your program, your image, your platform and your workload, so measure it where you deploy:

Start the container on the machine and platform you deploy to.
Measure from the moment the container starts to the moment the program reports ready.
Measure the first model answer separately: it belongs to the model service, not to the image.
Repeat the measurement and record the platform, the image and the workload with every result.

Step 6: put it into service

A new image reaches your deployment through a reviewed plan:

ael deploy plan
ael deploy apply --plan <plan>

The plan stages the new image beside the running one, checks it for readiness and then switches it on, and rolling back returns to the previous compatible version. Deployment and rollback describes plans in full.

The same executable runs outside a container too: you host your built application on servers you operate, with health checks for the storage, databases and models it declares, graceful shutdown and log rotation. Self-hosting your application describes it.

Honest limits

This page states no start-up time, size or memory figure: measure your own, as step 5 describes.
A minimal image is not a sandbox for running untrusted code. Isolation belongs to a component, not to the image. You mark an agent, node or subagent as isolated: it always runs in a sandbox in its own process. Isolation needs the isolation facilities of Linux and runs only on the Linux target the documentation names for it: on any host without those facilities, an isolated component is refused, never run without isolation. Isolated components describes it, and Sandbox mode and isolated components the sandbox for functions in other languages.
A hard per-agent limit needs that agent in its own process group; see Desktop and server.
A program that is ready may still wait for a model's first answer.