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, wrapped in sh -c so shell features like &&, pipes and variable interpolation work. Up to 1000 characters. Mutually exclusive with argv.
Argv – alternative to run_command: an array of strings executed in exec form, without a shell wrap. Recommended for SDK and programmatic callers because it avoids shell-injection and quoting issues. Example: ["python", "script.py", "--env", "staging"].
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.

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. You can override the runner's default command, entrypoint and environment variables for a single run, either via argv (exec form, recommended for automation) or command (shell form, convenient for shell one-liners). The two are mutually exclusive.

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

{
  "argv": ["python", "migrate.py", "--env", "staging"],
  "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.

Warmup

By default the first run after a long idle period pays the cost of pulling the container image onto a hypervisor. To skip that latency you can warm the runner up ahead of time. Warming up pre-pulls the image onto a hypervisor in the runner's region and pins that hypervisor as the preferred target for the next run.

Trigger a warmup from the dashboard's Warmup button on the runner, or via the API:

POST https://api.nodion.com/v1/runners/:id/warmup

The endpoint returns 202 Accepted and the warmup runs in the background. Poll the runner's warmed_at field to confirm completion. The next triggered run will reuse that hypervisor if it still has capacity, otherwise Nodion falls back to picking any hypervisor with free memory.

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.
canceled – the run was stopped by the user before it completed.

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.

Canceling a Run

A pending or running run can be stopped at any time. From the dashboard, open the run and click Stop. From the API:

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

Nodion marks the run as canceled, removes the container and cleans up any uploaded files on the hypervisor. Runs that have already finished are returned unchanged.

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.

Two API endpoints are available:

GET /v1/runners/:runner_id/runs/:run_id/logs returns the captured log lines as a paginated list. Use the after_id query parameter as a cursor to fetch only lines newer than a given log entry.
GET /v1/runners/:runner_id/runs/:run_id/logs/stream opens a Server-Sent Events stream that emits each log line as it is written. The stream sends a final state event with the run's terminal status and exit code, then closes. Reconnects can resume after a disconnect by passing ?after_id=<last-log-id>.

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 (runner default, shell form): up to 1000 characters.
Per-run command override (shell form): up to 4000 characters.
Argv (exec form): up to 200 elements, total length up to 8000 characters.
Entrypoint: up to 500 characters.
Name: 3 to 50 characters.

API Reference

For the full API surface see:

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