Runners

Run containerized tasks on Nodion's infrastructure, on demand or via API.

Runners let you execute Docker containers as standalone jobs without deploying a full application. Each runner defines a Docker image, a command and a set of resource constraints. You trigger runs manually from the dashboard or via the API and Nodion takes care of pulling the image, executing the container, capturing the logs and cleaning up.

Common use cases include database migrations, one-off scripts, webhook handlers, queue consumers, CI-style build steps and sandboxed agent environments where an AI agent needs an isolated container to execute code or shell commands on demand.

Creating a Runner

Open the dashboard, switch to the Runners tab in your project and click New Runner. You will be asked for:

Name – between 3 and 50 characters.
Container Registry – pick an existing container registry for private images, or leave it empty to pull from a public source like Docker Hub.
Image Name – for example mycompany/backup-tool or postgres.
Image Tag – for example latest or 17.5.
Run Command – the command Nodion executes once the container is up. Up to 1000 characters.
Entrypoint – optional override for the image's entrypoint. Up to 500 characters.
Timeout – maximum execution time in seconds. Anything between 1 second and 24 hours (86400 seconds). Defaults to 1 hour.
Region and Instance Type – the region the run executes in and the CPU and memory budget per run.

Once saved, the runner is ready to be triggered. The configuration can be edited at any time from the runner's Settings section.

Environment Variables

Runners can have environment variables that are passed to the container at run time. Values are encrypted at rest. Keys must follow the shell variable convention [a-zA-Z_][a-zA-Z0-9_]*.

Manage runner level defaults from the Environment Variables section of the runner. These values apply to every run of that runner unless overridden.

Triggering a Run

From the dashboard, open the runner and click Run in the Run section. You can optionally provide environment variable overrides that apply only to this single run, on top of the runner's defaults.

From the API, POST to the runs endpoint of the runner.

POST https://api.nodion.com/v1/runners/:runner_id/runs

{
  "env_variables": [
    { "env_key": "BACKUP_TARGET", "env_val": "s3://my-bucket/backups" },
    { "env_key": "VERBOSE", "env_val": "true" }
  ]
}

The full request and response shape is documented in the Runner Runs API reference.

Run Lifecycle

Every run goes through these statuses:

pending – queued, waiting for a hypervisor with enough capacity.
running – the container is executing.
succeeded – the container exited with code 0.
failed – the container exited with a non-zero code or hit the timeout.

An exit code of 124 indicates the run was killed because it exceeded its configured timeout. Any other non-zero exit code is treated as a regular failure and surfaces in the run's exit_code field.

Logs

Stdout and stderr are captured line by line and stored against the run. Logs are visible in the dashboard once the run starts and remain available afterwards together with the exit code and duration. Logs are also available via the API at /v1/runners/:runner_id/runs/:run_id/logs.

Internal log lines produced by Nodion (for example registry login output) are kept private and never exposed in the dashboard or the API.

Resources and Pricing

Each run is scheduled on a hypervisor with enough free memory in the runner's region. CPU and memory are bound by the selected instance type. You only pay for the actual runtime of each run, billed per second based on the instance type's per-second price.

See Pricing for the current instance type list.

Recurring Runs

Runners do not have native cron support. To run a runner on a schedule, you have a few options:

Trigger the API from any external scheduler such as your own cron, GitHub Actions or a webhook provider.
Trigger the API from your own application code in response to events.

Limits

Timeout: 1 second minimum, 24 hours (86400 seconds) maximum.
Run command: up to 1000 characters.
Entrypoint: up to 500 characters.
Name: 3 to 50 characters.
Environment variable keys must match [a-zA-Z_][a-zA-Z0-9_]*.

API Reference

For the full API surface see:

Runners API for managing runners.
Runner Runs API for triggering and inspecting runs.