Container runtime contract
The rules a web service's image must follow, the variables the platform sets, and how long the previous version keeps running after a new one goes live.
Rules#
| Item | Requirement | If not met |
|---|---|---|
| Start command | A CMD or ENTRYPOINT. | The version is refused. |
| Port | Serve HTTP on $PORT. | Chosen from setting → EXPOSE → 8080; see Project settings. |
| Platform | linux/amd64. | Agent Lab always builds for it. |
| User | A non-root USER is recommended. | Root or no USER runs as uid 10001, group 0. A USER the image doesn't have is refused. |
| Filesystem | Read-only apart from /tmp. | Writes elsewhere fail. |
| Cloud credentials | None are provided. | Use the project's secrets to reach outside services. |
When an image runs as uid 10001, the files it reads must be readable by group 0.
Notices#
Changes the platform made to an image show as notices on the version page. AI tools read the same codes from the deploy status.
| Code | Meaning | What to do |
|---|---|---|
imageUserForced | The image runs as root, so it runs as uid 10001. | Nothing. To clear the notice, set a non-root USER in the Dockerfile. |
imagePortFromExpose | Your service listens on the one port the image exposes. | Nothing. |
imagePortsAmbiguous | The image exposes several ports and none is 8080, so it runs on 8080, which is probably not where the server listens. | Choose the right port in Settings › Runtime settings › Port and restart the service, or EXPOSE only that port in the Dockerfile. |
Variables the platform sets#
| Variable | Value |
|---|---|
PORT | The port to serve HTTP on. |
AGENTLAB_RELEASE_ID | The id of the version this container runs, the same id AI tools get from deploy status. |
AGENTLAB_ENVIRONMENT | The environment it runs in: main for production, otherwise the environment's name. |
You can't add a variable or secret with one of these names. If your project already had AGENTLAB_RELEASE_ID or AGENTLAB_ENVIRONMENT before the platform set them, it keeps it and you can still save your other settings, but the container gets the platform's value. Remove yours when you can.
Versions deployed before these two variables were added don't have them. Deploy a new version to get them.
When a new version goes live#
- The new version starts The previous version keeps serving, with all its instances, until the new one is ready.
- Traffic switches New visitor requests and scheduled job calls go to the new version within seconds. Requests the previous version is already handling finish there.
- The previous version keeps one instance For up to 15 minutes after the switch it keeps running with one instance. It gets no new requests, but anything it does on its own keeps going: a queue consumer, a polling loop, a timer.
- The previous version stops Its process gets
SIGTERM, and 30 seconds later it is killed if it hasn't exited.
So code from the previous version can run for up to 15 minutes and 30 seconds after the switch. Two instances of the same version also overlap for a moment whenever a restart replaces instances one at a time, and a project with more than one instance always runs several at once.
Background workers#
If your project takes work from somewhere shared, such as a jobs table or a queue, write the worker so that more than one copy can run at once:
- Exit on
SIGTERM. Stop taking new work, finish or give back the item you hold, and exit within 30 seconds. - Claim each item. Take it with a row lock (
SELECT … FOR UPDATE SKIP LOCKED) or a lease with an expiry time that the worker renews, so two processes never work on the same item and an item held by a process that died is picked up again. - Leave the work to the live version.
AGENTLAB_RELEASE_IDtells a worker which version it belongs to. To learn which version is live, add an endpoint that returnsAGENTLAB_RELEASE_IDand have the worker call your own public address: only the live version answers it. A worker that gets a different id back stops taking work. - Record who did it. Write
AGENTLAB_RELEASE_IDinto your logs and into the rows a worker changes, so you can tell which version ran a task.
// Your web server also answers GET /release with process.env.AGENTLAB_RELEASE_ID.
const mine = process.env.AGENTLAB_RELEASE_ID;
let stopping = false;
process.on("SIGTERM", () => {
stopping = true; // then close the web server and exit once the loop ends
});
async function isLive() {
try {
const res = await fetch("https://your-app-address/release");
return res.ok && (await res.text()) === mine;
} catch {
return false;
}
}
async function work() {
while (!stopping) {
if (await isLive()) {
await claimAndRunOne(); // e.g. SELECT … FOR UPDATE SKIP LOCKED
} else {
await new Promise((resolve) => setTimeout(resolve, 10_000));
}
}
}Each run of a scheduled job that calls your project also records the version it was sent to: outcome.releaseId in the job's runs.
Images that write files at start-up#
Some images write outside /tmp when they start. nginx:alpine, for example, writes to /var/cache/nginx and fails on a read-only filesystem. Use an image that doesn't need to write, or move its writes to /tmp:
FROM nginxinc/nginx-unprivileged:alpine
COPY dist/ /usr/share/nginx/html/Only serving static files?
Deploy a static site instead. You don't need to run nginx yourself.