Config
A job is configured through plain files under its config directory, with a handful of metadata endpoints alongside. This page lists them all.
AI assisted, human approved — novem uses AI to review and keep our documentation up to date.
Like every novem resource, a job is a folder of small files: each setting is
read with GET, set with POST (plain text body), and cleared with
DELETE. The job itself is created with PUT, renamed with PATCH and
removed with DELETE on its base path, /v1/code/jobs/<job>.
GET /v1/code/jobs lists your jobs; GET .../jobs/<job> lists a single
job's entries.
Config keys
Everything under config/ controls how and when the job runs:
| Key | Values | Description |
|---|---|---|
config/type | chains (default) | The runtime. The chains runtime is the generally available one — see the note on legacy types below. |
config/chains | chain grammar | The pipeline definition — which repo images run, in what order. See chains. |
config/schedule | cron expression | Optional cron trigger, with TZ= and comment support. See schedule. |
config/enabled | true / false (default true) | Kill switch: while false, scheduled triggers are skipped (manual runs still work). |
config/env/<name> | any text | Environment variables injected into the running container. Encrypted at rest, write-only — GET config/env lists names, never values. Use lower-case names; both name and NAME are visible to your code. |
config/spaces | mount mappings | Spaces to attach to the job, one name => /u/user/s/space[,ro|,rw] per line. Each becomes a folder under /mnt inside the run. See spaces. |
config/options/comments | true / false (default true) | Whether others can comment on the job (its threads). |
Example: pause a job without touching its schedule:
false
Note: Some keys are only listed (and writable) when they apply to the
job's current config/type: chains requires the chains type, while the
legacy extract / render keys require the legacy types.
Legacy runtime keys
The route tree also carries config/extract, config/render,
config/filter and config/group, which belong to the older single-image
data / pdf runtimes. Writing those types to config/type (and
configuring extract / render) requires the f_jobs feature flag and is
not generally available. Stick with the default chains runtime.
What a run sees
Alongside your own config/env, every step of a run is told which job it is
running as and which run it belongs to:
| Variable | Example | Description |
|---|---|---|
NOVEM_JOB | /u/alice/j/daily_report | The job's path — /u/<user>/j/<job>. |
NOVEM_JOB_RUN | 20260812-101500-3f9a1c | The run id, the <run> in /v1/users/<user>/code/jobs/<job>/runs/<run> — same <user> and <job> as NOVEM_JOB. See runs. |
Together they name the run in progress, so a step carrying a novem token can
address itself — read back its own runs/<run>/log, or update the job's
status — instead of guessing which job it was launched as.
A chain that references another job splices that job's steps in place; those
steps report the job they came from and its own run, not the calling job's. If
you set a config/env variable of the same name, yours wins.
Build provenance
Every step is also told which revision of your code its image was built from:
| Variable | Example | Description |
|---|---|---|
NOVEM_SOURCE_REPO | alice/data_fetcher | The repo the step's image came from, <user>/<repo>. |
NOVEM_SOURCE_REF | latest | The ref as the chain named it, so prod for @alice/data_fetcher:prod. Defaults to latest. |
NOVEM_SOURCE_COMMIT | 1a2b3c4d5e6f7890abcdef1234567890abcdef12 | The full commit sha that image was built from. |
These answer a different question than NOVEM_JOB does. The run identity says
which job is running; the provenance says which code is running, which is what
an audit trail or a sign-off needs after the fact.
The commit is read from the same record that decides which image gets pulled,
so what a step reports and what it is actually running cannot disagree. Note
that this is the commit the image was built from, not wherever the ref
points now: push to latest and the ref advances immediately, while its image
only changes when the build finishes. A run started in that window pulls the
older image, and reports the older commit along with it.
Your repo needs no ARG, LABEL or --build-arg of its own; the answer is
looked up per run rather than baked in at build time, so images built before
this existed report their commit too.
Values are per step, from that step's own repo and ref. A chain that
references another job splices in steps built
from a different repo at a different commit, and each reports its own. As with
the run identity, a config/env variable of the same name wins.
Note: NOVEM_SOURCE_COMMIT is absent, rather than set to a placeholder,
for an image with no recorded commit. Test for the variable itself; a step
that has to tell "not stamped" from a real revision cannot do it against a
string.
The same commit is written to the run's log beside each step's ref, so a finished run stays traceable once its containers are gone.
Metadata and related endpoints
Alongside config/ and runs, each job
carries:
| Endpoint | Access | Description |
|---|---|---|
name | read/write | Display name. |
description | read/write | Longer free-form description. |
summary | read/write | One-line summary shown in job listings. |
status | read/write | Free-form status text — a place for your pipeline to surface its own state. |
shortname | read | The auto-generated short id (used in URLs). |
url | read | The job's canonical web URL, https://novem.io/j/<shortname>. |
notifications | read/write | Your notification level for this job's run events: ignore, info or important. Per caller — it doesn't affect other users. |
shared | read/write | Who can see the job: PUT/DELETE a group reference (+org~group, @user~group) or public under it. |
tags | read/write | Tags on the job — see tags. |
vars | read/write | Job variables — see vars. |
threads | read/write | Comment threads on the job; disable with config/options/comments. |