Skip to main content

Headless Mode

Atmo can be run 'headless' mode, which causes it to ignore the Directive and instead make each Runnable in your application available as an individual endpoint. This can be useful for a number of things such as automated testing (being able to test each Runnable in isolation with controlled inputs).

Each function will be made available at a URI such as this:

POST /com.suborbital.test/default/get-file/v0.0.1

The format of this URL is: /[identifier]/[namespace]/[name]/[appVersion]. Your Directive defines the identifier, appVersion, the namespace and name of each Runnable. These are listed in the .runnable.yaml file within each Runnable's directory.

To define the inputs for the request, you can use the following:

Desired inputHeadless RequestRunnable API
Request bodyPOST request bodyreq::body()
Request stateX-Atmo-State header, formatted as JSON key/value pairsreq::state(key)
URL parameters (such as /:name)X-Atmo-Params header, formatted as JSON key/value pairsreq::param(key)

For example, if your Runnable expects data in the user request state key, you would set the X-Atmo-State header as such:

{"user": ""}

And if your Runnable expects to parse URL parameters such as /api/:user, you can use the X-Atmo-Params header in a similar fashion.

When running in headless mode, the unique UUID for each request will be returned in the X-Atmo-Requestid response header field.

Running in Headless mode

To run Atmo in headless mode, set the ATMO_HEADLESS env var:


In a Dockerfile, you can use the ENV command:


Or with the Docker CLI:

docker run [...] -e ATMO_HEADLESS=true suborbital/atmo atmo