Self-hosting and boards
With AEL, the Agent Engineering Language, 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. This tutorial builds an application for a server, runs it there, watches its health and logs, stops it cleanly, flashes and monitors a board from the command line, and puts a new version into service through a staged deployment you can roll back.
Supported targets lists the targets and boards; this tutorial writes <target> and <board> where you put one of them.
Step 1: build the application for your server
ael build --target <target> -o build/support --release
The AEL 1.0.0 build for Linux, macOS or Windows comes with target management and a health check, and desktop and server programs written in AEL alone need nothing else installed. Functions in other languages are built and run with your own toolchains, pinned by version: if your application holds any, install each toolchain on the machine that builds it and on the server that runs it.
Step 2: give it what it needs on the server
| What | How it reaches the application |
|---|---|
| Configuration values | Named environment variables or files on the server, 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 executable or routine logs. |
| The system prompt | A file on the server, 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. |
| What its agents declare | The memory, skills, knowledge, storage and database each agent uses, each bound to a package you select; the check refuses any use it did not declare. |
If an agent declares a storage point, keep its directory, object storage or SQL database where the server reaches it. A run is durable only when its agent declares a storage point; without one, the run runs to completion and keeps nothing.
Step 3: start it and watch its health
Start the executable the way you start any program on the server. Its health checks cover the storage, databases and models it declares:
- Ready means ready locally. It reports ready once its own configuration, prompts and files are validated and it can accept a request. Whether a model service or a store can be reached is reported separately.
- No tokens for health. The check of a model binding never calls a model.
- No secrets. A health report never shows a credential or the value of a secret.
- Fail promptly. A missing required setting, credential, system prompt or file stops it promptly with a clear error, never with a false report that it is ready.
Step 4: read its logs
Structured logs go to the console, a file, or custom or remote sinks, with redaction, rotation and retention. On a server, write them to a file with rotation and the retention you choose, or send them to a collector you run. Credentials are never logged.
Step 5: stop it cleanly
Send the application a stop signal. It stops taking new work, finishes or cancels the work it has within a bounded deadline, and exits:
- A run whose agent declares a storage point resumes from it when the application starts again; a run without one does not.
- Work whose outcome outside your program is not known is reported as unknown, never as undone, and is never replayed.
Step 6: flash and monitor a board
You flash and monitor supported boards from the command line, using each board's standard flashing tools. Build the firmware, find the device, flash it and watch its output:
ael build --target <board> -o build/sensors --release
ael devices
ael flash --target <board> --device <device> --artifact build/sensors
ael monitor --device <device>
ael flash writes exactly the firmware image you name to the one device you select, after checking that the device is the board the image was built for and that the image is intact. A device takes one operation at a time: while you monitor it, no one else can flash it. Boards and AEL Gateway goes further with boards.
Step 7: stage and roll back
Deployments are staged, and you can roll each one back. A new version of the application, or new firmware for a board, reaches service only through a plan you have reviewed:
ael deploy plan
ael deploy apply --plan <plan>
The plan puts the new version in place beside the running one, checks that it reports ready, then switches it on, and rolling back returns to the previous compatible version. Deployment and rollback describes plans in full.
Honest limits
- Self-hosting runs your application on machines you operate: the servers, and the stores behind what your agents declare, are yours to run.
- A run resumes after a restart only when its agent declares a storage point.
- An effect whose outcome outside your program cannot be known is reported as unknown, and rolling back does not undo an effect that already happened.
- Boards need their makers' flashing tools on the machine the boards are plugged into.