Building and running on AEL Server

AEL Server is an optional self-hosted build and run server for AEL, the Agent Engineering Language: it adds backups, staged deployments and rollback. You run it on machines you operate, and the ael command sends it work. This tutorial pairs the command with a server, sends it jobs, reconnects to one, and flashes a board through it.

Everything here is optional: you write, check, build and run projects with the ael command alone, and the programs you build never need the server to start.

Step 1: pair the command with the server

Local first. The server listens only on its own machine until you configure otherwise, and the ael command pairs with it using a short-lived code.
Remote over HTTPS only. Reaching the server from another machine needs HTTPS with a trusted certificate and explicit configuration.
Checked every time. Every job, built program and device operation is checked against who is asking, including when a job is resumed. Sessions expire and are revocable, and credentials are redacted from logs and output.

Step 2: send work as jobs

You send checks, builds, tests, evaluations and runs to the server as jobs. Each job works on a fixed snapshot of your source, prompts, configuration and locked packages:

Where	What runs there
Your machine	The `ael` command, your editor and your source; you keep working while a job runs.
AEL Server	The job: the check, build, test, evaluation or run of the snapshot it was given.
The model service you choose	The model calls of an evaluation or a run. The server does not run models.
The machine your boards are plugged into	The device connector, which flashes and monitors the boards.

An edit you make after sending a job never changes that job: the job keeps the exact snapshot it started with, so its result always belongs to one version of your project.

Step 3: disconnect and reconnect

Output survives disconnects. Reconnect to a job and read what you missed. Reconnecting never runs a job again.
Cancellation is thorough. Cancelling a job stops it and cleans up the processes it started. Work elsewhere whose outcome cannot be known is reported as unknown, not as undone.
Restarts are reconciled. After a restart of the server, queued and running jobs are reconciled. Only work you marked as restartable resumes, and a model or tool call is never made again just because the server stopped.

Step 4: keep what you built

The server keeps each executable and firmware image with its fingerprint and a record of what went into it, and keeps backups of all of it. A restore goes into a clean server and checks every fingerprint first; a partial or damaged backup is refused.

Step 5: flash a board through the server

You flash and monitor supported boards from the command line, using each board's standard flashing tools. A board plugged into your own machine takes the commands of Flashing a board:

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. Through AEL Server, the same operations go through a device connector that runs on the machine the boards are plugged into: it takes one operation per device at a time, and every device operation is checked against who is asking. Supported targets lists the boards.

Step 6: stage and roll back

The server stages deployments and rolls them back, as Deployment and rollback describes: a change reaches running programs and devices only through a plan you have reviewed.

Honest limits

AEL Server runs only the operations listed on AEL Server, never arbitrary commands, and it is designed for your own projects, not for running untrusted programs from the public.
A job whose outcome outside the server cannot be known is reported as unknown; the server does not guess.
Boards need their makers' flashing tools on the machine the boards are plugged into.