ForjioHuudisIdentityPlugipayPaymentsStorlaunchE-commerceFulkrumaFulfillmentRiplloMarketingDeplloThis product
Depllo Docs
⌘K

Runners

A runner is a machine that executes your jobs. Depllo runs a fleet of shared Docker runners, so most workspaces never touch this page — your jobs just run. This page explains how runners work and how to target them with tags.

How jobs reach a runner

Runners connect out to Depllo (no inbound ports on the runner). Each runner long-polls for work: when a job is pending and its tags are a subset of the runner's tags, the runner atomically claims it, then:

  1. Creates a workspace directory for the job.
  2. Runs docker run with the job's image (default node:24-bookworm), a bind-mounted workspace, and CPU/memory caps.
  3. Clones your repo over the tokenized HTTPS URL at the build SHA.
  4. Executes before_script → script → after_script with bash -e.
  5. Streams combined stdout/stderr back in chunks — masking any masked variables before the chunk leaves the runner.
  6. Collects artifacts and pushes cache per your config.

Depllo enforces liveness server-side: a runner that stops sending heartbeats has its job marked runner_failure, and jobs that exceed their timeout fail with stuck_timeout.

Runner tags

Tags route jobs to runners. A job runs on a runner only if the runner's tags are a superset of the job's tags. A job with no tags can run on any runner.

build-arm:
  tags: [arm64]
  script: [make]

If no online runner satisfies a job's tags, the job stays pending until one appears (or the pipeline is canceled).

Seeing your runners

Dashboard → Runners lists the runners available to your workspace — shared/instance runners plus any workspace-scoped ones. Each row shows a status dot (online / offline / paused), the tags, and the last contact time. You can pause and resume a runner you own; shared runners are managed by Depllo.

Running your own runner (advanced)

The runner is a small TypeScript daemon (a systemd unit) that speaks the Depllo runner protocol over HTTP. It registers once with an instance registration token, then authenticates every call with the runner token it receives:

POST /api/v1/runners/register
  { registrationToken, name, tags, maxConcurrent }
→ { runnerId, runnerToken }   # token shown once

Requirements on the box: Docker and Node. In v1 the registration token is an instance token (set on the server); per-workspace runner tokens are planned. If you need a dedicated runner for your workspace, contact us.