Skip to content

Manifest fields

Generated from oarbank_sdk.manifest by oarbank-sdk export-schemas. Do not edit by hand. Cross-field rules are in manifest.md.

Key Type Default Description
manifest 1 1 [stable] Manifest schema major.
module ModuleInfo required
module.id str required [stable] Namespaced, globally unique module id (reverse DNS). Removed ids are tombstoned, never reused.
module.version str required [stable] SemVer of the module package.
module.compat str required [stable] Result-semantics tag. Part of every job_key: bump it only when results for the same inputs change meaning. Patch releases keep it, so caches survive.
module.publisher str required [stable] Publisher identity (today a free-form owner name).
module.license str required [stable] SPDX license expression of the module.
module.codeowners list of str [] [stable] Maintainers; modules without codeowners cannot be verified.
module.stability "experimental" | "beta" | "stable" "beta" [stable] Maturity of the module itself.
module.description str "" [stable] One-line description for the console and docs.
requires Requires required
requires.core str required [stable] Supported oarbank core versions, e.g. ‘>=2.0,<3’.
requires.agent str (optional) [stable] Supported agent versions.
requires.os OSRequirements (optional) [stable] Supported OS versions per OS (only for the declared platforms).
requires.os.darwin str (optional)
requires.os.linux LinuxRequirements (optional)
requires.os.linux.kernel str (optional) [stable] Kernel versions, e.g. ‘>=6.1’.
requires.os.linux.glibc str (optional) [stable] glibc versions, e.g. ‘>=2.35’.
requires.os.windows str (optional) [stable] Windows versions by build, e.g. ‘>=10.0.19045’.
requires.platforms list of str required [stable] Node platforms the module runs on, <os>-<arch> (spec/platforms.md). Required; an unknown token means no node of that platform, never an error.
requires.module_protocol list of int required [stable] Module protocol majors the coordinator side speaks.
requires.runner_protocol list of int [1] [stable] Runner protocol majors the runner speaks.
requires.service_protocol list of int [] [stable] Service protocol majors (only when services/probes are declared).
requires.workload_protocol list of int [] [beta] Workload protocol majors (only when workloads are declared; spec/workload-protocol.md). Needs requires.core >= 2.10.
requires.experimental list of str [] [stable] Opt-ins to experimental contract items; any opt-in blocks the verified badge.
requires.ui_contract str (optional) [beta] UI contract versions the module’s pages use, e.g. ‘>=1.0,<2’ (spec/ui-contract.md).
requires.coordinator_platforms list of str (optional) [beta] Platforms the coordinator side runs on (the coordinator host’s platform); platforms lists node platforms only. Absent: any platform. A core refuses to install or enable the module on a coordinator host not listed, and blocks a coordinator move to one. Needs requires.core >= 2.2.
requires.unsupported Unsupported "runner={} coordinator={}" [beta] Why the module does not run somewhere, shown by explain and the console. Needs requires.core >= 2.2.
requires.unsupported.runner table str → str {} [beta] Node platforms, beside requires.platforms.
requires.unsupported.coordinator table str → str {} [beta] Coordinator platforms, beside requires.coordinator_platforms (which must then be set: absent means any).
requires.features list of str [] [beta] Must-understand list: a reader that does not know a listed feature refuses the manifest. Known: placement. Needs requires.core >= 2.2.
coordinator Coordinator required
coordinator.exec list of str required [stable] argv (spec/manifest.md, “Exec”); cwd is the bundle root; the process speaks module protocol JSON-RPC on stdin/stdout.
coordinator.runtime Runtime required
coordinator.runtime.kind str required [stable] Open set. python: the host’s managed CPython with the SDK (plus the bundle’s requirements, installed from wheels); uv: a locked uv project (wheels only, resolvable for every declared platform) built offline into a per-module environment; native: argv[0] is a native executable in the bundle (Mach-O, ELF or PE, or a POSIX shebang script in darwin/linux variants). An unknown kind means the entry point cannot run on this node.
coordinator.runtime.lock str (optional) [stable] Path of uv.lock inside the bundle (kind=uv).
coordinator.runtime.python str (optional) [stable] Exact Python version for the venv (kind=uv), e.g. 3.12.14.
coordinator.capabilities list of str [] [stable] Optional verbs/features implemented, e.g. result.merge, golden.compare, study.metrics, params.distance, result.upgrade, and campaign.tick.results [beta] (campaign.tick sees each done job’s payload and artifacts; the host validates payloads against results.schema at acceptance; needs requires.core >= 2.3).
coordinator.concurrency int 1 [stable] Max in-flight requests the module accepts; 1 = serial.
coordinator.timeouts_s table str → float {"default": 10.0} [stable] Per-verb timeouts; key default applies to unlisted verbs.
coordinator.permissions list of "datasets:read" | "blobs:stat" | "settings:read:self" | "store:read:self" | "nodes:read" | "jobs:read:self" | "files:read:self" | "secrets:read:self" [] [stable] Host callbacks the module may call; everything else is denied.
coordinator.campaign_effects list of "jobs.enqueue" | "jobs.cancel" | "campaigns.create" | "campaigns.update" | "campaigns.cancel" | "datasets.create" | "datasets.update" | "datasets.delete" | "module_settings.update" | "store.write" | "store.delete" | "files.write" | "files.put" | "files.delete" | "external" [] [beta] Effects campaign.tick may request (requires the campaign.tick capability).
coordinator.workload_effects list of "store.write" | "store.delete" | "files.write" | "files.put" | "files.delete" [] [beta] Effects workload.report may request: the module’s own records only (requires the workload.report capability and requires.core >= 2.10).
coordinator.move MoveSection "rules=[] effects=[]"
coordinator.move.rules list of MoveRule [] [beta] The first matching rule wins; unmatched state is carried.
coordinator.move.rules[].files str (optional) [beta] A path prefix in the module’s files (‘’ = all of them).
coordinator.move.rules[].store str (optional) [beta] A store collection.
coordinator.move.rules[].class "carry" | "rebuild" | "drop" required [beta] carry (the default for everything): moved and verified by digest; rebuild: not transferred, the module recreates it in move.postflight; drop: scratch, deleted on the new coordinator.
coordinator.move.effects list of "jobs.enqueue" | "jobs.cancel" | "campaigns.create" | "campaigns.update" | "campaigns.cancel" | "datasets.create" | "datasets.update" | "datasets.delete" | "module_settings.update" | "store.write" | "store.delete" | "files.write" | "files.put" | "files.delete" | "external" [] [beta] Effects move.preflight, move.postflight and move.cancelled may request.
coordinator.env table str → str {} [beta] Extra environment for the coordinator process (names ^[A-Z][A-Z0-9_]*$, never a reserved name). The host also sets OARBANK_PLATFORM. Needs requires.core >= 2.2.
coordinator.variants table str → CoordinatorVariant {} [beta] Per-platform overrides for the coordinator host, keyed by platform token or OS (checked against requires.coordinator_platforms when set). Needs requires.core >= 2.2.
coordinator.variants.exec list of str (optional) [beta] Replaces coordinator.exec.
coordinator.variants.runtime Runtime (optional) [beta] Replaces coordinator.runtime.
coordinator.variants.runtime.kind str required [stable] Open set. python: the host’s managed CPython with the SDK (plus the bundle’s requirements, installed from wheels); uv: a locked uv project (wheels only, resolvable for every declared platform) built offline into a per-module environment; native: argv[0] is a native executable in the bundle (Mach-O, ELF or PE, or a POSIX shebang script in darwin/linux variants). An unknown kind means the entry point cannot run on this node.
coordinator.variants.runtime.lock str (optional) [stable] Path of uv.lock inside the bundle (kind=uv).
coordinator.variants.runtime.python str (optional) [stable] Exact Python version for the venv (kind=uv), e.g. 3.12.14.
coordinator.variants.timeouts_s table str → float (optional) [beta] Merged over coordinator.timeouts_s verb by verb.
coordinator.variants.concurrency int (optional) [beta] Replaces coordinator.concurrency.
coordinator.variants.env table str → str (optional) [beta] Merged over coordinator.env name by name.
runner Runner required
runner.exec list of str required [stable] argv (spec/manifest.md, “Exec”); the agent appends run --spec S --workdir W --out R [--events E] or doctor --json.
runner.runtime Runtime required
runner.runtime.kind str required [stable] Open set. python: the host’s managed CPython with the SDK (plus the bundle’s requirements, installed from wheels); uv: a locked uv project (wheels only, resolvable for every declared platform) built offline into a per-module environment; native: argv[0] is a native executable in the bundle (Mach-O, ELF or PE, or a POSIX shebang script in darwin/linux variants). An unknown kind means the entry point cannot run on this node.
runner.runtime.lock str (optional) [stable] Path of uv.lock inside the bundle (kind=uv).
runner.runtime.python str (optional) [stable] Exact Python version for the venv (kind=uv), e.g. 3.12.14.
runner.capabilities list of str [] [stable] By intent: cancellable (honours a stop request within stop_grace_s), freeze_ok (safe to freeze at any instruction), cooperative_pause (pauses on control.json), resumable (resumes from its own checkpoint after a restart), progress_events, deterministic_output, cooperative_throttle (honours threads and gpu_duty in control.json; only such GPU runners run beside a protected GPU program), checkpoint (writes portable checkpoints, honours a checkpoint-then-stop request and resumes from /checkpoint/; needs requires.core >= 2.5).
runner.stop_grace_s float 20.0 [stable] Seconds between the stop request and forced termination of the process container.
runner.checkpoint_grace_s float 120.0 [beta] Seconds between a checkpoint-then-stop request and forced termination of the process container. Needs requires.core >= 2.5.
runner.gpu GPUNeed "use='none' apis_any=[] min_vram_gb=None in_container=False"
runner.gpu.use "none" | "shared" | "exclusive" "none" [beta] shared/exclusive jobs are not admitted while a protected process group uses that GPU.
runner.gpu.apis_any list of str [] [beta] Any of these GPU APIs; jobs run only on nodes providing one (open set; detected: cuda, directml, metal, opencl, rocm, vulkan). Needs use shared or exclusive and requires.core >= 2.5.
runner.gpu.min_vram_gb float (optional) [beta] Minimum device memory where memory is not unified.
runner.gpu.in_container bool false [beta] The GPU is used from inside a broker-run container.
runner.bandwidth_class "low" | "medium" | "high" (optional) [experimental] Measured memory-bandwidth appetite relative to the node’s memory system (measured on Apple unified memory so far).
runner.env table str → str {} [beta] Extra environment for the runner and doctor, applied after the agent’s own variables (names ^[A-Z][A-Z0-9_]*$, never OARBANK_* or another reserved name), e.g. MKL_CBWR or OMP_NUM_THREADS for determinism. Needs requires.core >= 2.2.
runner.variants table str → RunnerVariant {} [beta] Per-platform overrides, keyed by platform token (linux-amd64) or OS (linux).
runner.variants.exec list of str (optional)
runner.variants.runtime Runtime (optional)
runner.variants.runtime.kind str required [stable] Open set. python: the host’s managed CPython with the SDK (plus the bundle’s requirements, installed from wheels); uv: a locked uv project (wheels only, resolvable for every declared platform) built offline into a per-module environment; native: argv[0] is a native executable in the bundle (Mach-O, ELF or PE, or a POSIX shebang script in darwin/linux variants). An unknown kind means the entry point cannot run on this node.
runner.variants.runtime.lock str (optional) [stable] Path of uv.lock inside the bundle (kind=uv).
runner.variants.runtime.python str (optional) [stable] Exact Python version for the venv (kind=uv), e.g. 3.12.14.
runner.variants.capabilities list of str (optional)
runner.variants.stop_grace_s float (optional)
runner.variants.gpu GPUNeed (optional)
runner.variants.gpu.use "none" | "shared" | "exclusive" "none" [beta] shared/exclusive jobs are not admitted while a protected process group uses that GPU.
runner.variants.gpu.apis_any list of str [] [beta] Any of these GPU APIs; jobs run only on nodes providing one (open set; detected: cuda, directml, metal, opencl, rocm, vulkan). Needs use shared or exclusive and requires.core >= 2.5.
runner.variants.gpu.min_vram_gb float (optional) [beta] Minimum device memory where memory is not unified.
runner.variants.gpu.in_container bool false [beta] The GPU is used from inside a broker-run container.
runner.variants.env table str → str (optional) [beta] Merged over [runner].env name by name. Needs requires.core >= 2.2.
stages list of Stage required
stages[].name str required [stable] Stage name; unique within the manifest.
stages[].after str (optional) [stable] Stage whose output this stage consumes (its artifacts become inputs).
stages[].determinism "exact" | "within_tolerance" | "none" (optional) [beta] This stage’s determinism (absent: results.determinism). none: its results depend on when it ran (an ingestion job pulling a moving feed), so the host never replicates, compares, caches or golden-tests them; when the stage also needs no capability and no pool, its jobs run before the module is certified on a node, wherever its runner starts. Only a standalone stage sets it (a chain compares as results.determinism). Needs requires.core >= 2.3.
stages[].default bool false [beta] The default stage: what a job runs when it names no stage (the single-stage form). Only a standalone stage sets it; exactly one does when several stages are standalone. Needs requires.core >= 2.3.
stages[].bootstrap bool false [beta] A bootstrap stage: its jobs run on nodes where the module’s runner starts, before the goldens pass, with only the module’s egress allowlist (no tools, GPU, containers, module data or settings), and the host registers their output only when it is exactly datasets of [[datasets.pinned]]. A standalone stage, not the default one, with determinism none and no pools. Needs requires.core >= 2.4.
stages[].cleanup bool false [beta] A cleanup stage: the agent runs it on a node, best effort and within its timeout_s (at most 600 s), before it deletes what the module left there (its data directory, cached datasets and container images), so the module can release state outside the node. No job names it. A standalone stage, not the default one, never bootstrap, comparing nothing, with no capabilities, pools, secrets or checkpoint; at most one per module. Needs requires.core >= 2.11.
stages[].secrets list of str [] [beta] Declared [[secrets]] this stage’s runner receives in OARBANK_SECRETS_FILE (no other stage, service, probe or doctor does). A job waits until each has a value for its node. Never on a bootstrap stage. Needs requires.core >= 2.5.
stages[].checkpoint StageCheckpoint (optional) [beta] The stage keeps portable checkpoints: the latest one a job’s runner wrote is uploaded, and the job’s next attempt, on any node, resumes from it. Needs the runner capability checkpoint and requires.core >= 2.5.
stages[].checkpoint.max_mb int required [beta] The largest checkpoint (all its files) the agent uploads, MB.
stages[].checkpoint.min_interval_s float 600.0 [beta] The agent uploads at most one checkpoint per interval; a checkpoint answering a checkpoint-then-stop request is always uploaded.
stages[].requires StageRequires "capabilities=[] pools={} needs_pools=[] platforms=[] resources=Resources(cpu=1.0, mem_gb=1.0, network='normal')"
stages[].requires.capabilities list of str [] [stable] Node capabilities that must be healthy (from probes/services).
stages[].requires.pools table str → int {} [stable] Countable pool tokens reserved for the job’s lifetime.
stages[].requires.needs_pools list of str [] [beta] Pools that must exist on the node but are not reserved (a short phase uses them).
stages[].requires.platforms list of str [] [beta] Only on these platforms (empty: every declared platform).
stages[].requires.resources Resources "cpu=1.0 mem_gb=1.0 network='normal'"
stages[].requires.resources.cpu float 1.0 [stable] CPU cores the job uses.
stages[].requires.resources.mem_gb float 1.0 [stable] Peak memory (GB) the job may use; the agent budgets it before admission.
stages[].requires.resources.network "normal" | "heavy" "normal" [beta] heavy: the job moves a lot of data over the node’s internet line (uploads or downloads of its own). Where the owner groups nodes into sites (nodes sharing one line), the core admits such jobs only within the site’s budget of network-heavy jobs, and pauses them (cooperative pause or freeze; released when neither) on every node of the site while a protected process there is in an upload phase. Older cores ignore it.
stages[].timeout_s float 1800.0 [stable] Hard wall-clock limit per attempt.
stages[].retry Retry "max_attempts=3"
stages[].retry.max_attempts int 3 [stable] Execution attempts before the job is quarantined.
stages[].variants table str → StageVariant {} [beta] Per-platform timeout_s, requires.resources and retry, keyed by platform token or OS. Needs requires.core >= 2.2.
stages[].variants.timeout_s float (optional) [beta] Replaces the stage’s timeout_s.
stages[].variants.requires StageVariantRequires (optional) [beta] Only resources may vary per platform.
stages[].variants.requires.resources ResourcesPatch (optional) [beta] Merged over the stage’s resources field by field.
stages[].variants.requires.resources.cpu float (optional) [beta] Replaces the stage’s cpu on this platform.
stages[].variants.requires.resources.mem_gb float (optional) [beta] Replaces the stage’s mem_gb on this platform.
stages[].variants.retry Retry (optional) [beta] Replaces the stage’s retry.
stages[].variants.retry.max_attempts int 3 [stable] Execution attempts before the job is quarantined.
stages[].placement StagePlacement (optional) [beta] Needs requires.core >= 2.2.
stages[].placement.mix str required [beta] Between this stage and its after stage: any, same-os, same-arch or same-platform (open set; an unknown value applies as same-platform). Combined with [placement].mix, the stricter one wins.
services list of Service []
services[].name str required
services[].exec list of str required [beta] argv (spec/manifest.md, “Exec”); cwd is the bundle root; the agent appends the operation (fingerprint|start|stop|status|ready|list_owned|destroy).
services[].platforms list of str [] [beta] Only on these platforms (empty: every declared platform).
services[].lifecycle "on_demand" | "always" | "manual" "on_demand" [beta] on_demand: refcounted by admitted jobs and stopped after idle_timeout_s.
services[].idle_timeout_s float 900.0
services[].start_timeout_s float 120.0
services[].stop_timeout_s float 120.0
services[].restart RestartPolicy "backoff_initial_s=10.0 backoff_max_s=600.0 max_failures=5"
services[].restart.backoff_initial_s float 10.0
services[].restart.backoff_max_s float 600.0
services[].restart.max_failures int 5
services[].provides ServiceProvides "capabilities=[] pools=[]"
services[].provides.capabilities list of str []
services[].provides.pools list of str [] [stable] Pools whose token counts the service’s fingerprint reports.
services[].reserves_host_memory bool false [beta] The fingerprint’s reserve.mem_gb is charged to the host while running.
services[].yieldable bool true [beta] The agent may stop it when idle under memory pressure, and host protection may stop it, releasing the jobs using it, when it evicts or while GPU work may not run (a GPU service).
services[].freeze_ok bool false [beta] The agent may freeze the service’s process container (freezing returns no memory).
services[].endpoint bool false [beta] Jobs reach the service: each attempt whose stage reserves one of its pools gets OARBANK_SERVICE_, and the agent hands the service every connection over its endpoint channel; the service never listens (spec/service-protocol.md, “Endpoints”). Provides at least one pool or lists at least one listener; lifecycle on_demand or always. Needs requires.core >= 2.5.
services[].listeners list of str [] [beta] [sandbox].net.inbound listeners this service serves: the agent hands it each connection a listener accepts (or, for handover listen_fd, the listening socket) and announces each listener’s external address on its endpoint channel. Needs endpoint = true, lifecycle always and requires.core >= 2.10.
services[].gpu ServiceGPU "use='none' apis_any=[]" [beta] Needs requires.core >= 2.5 when use is not none.
services[].gpu.use "none" | "shared" | "exclusive" "none" [beta] A running service that is not none is GPU-resident fleet work: host protection stops it, when yieldable, while GPU work may not run, and a job reserving one of its pools is a GPU job. Needs sandbox.devices.gpu = ‘compute’ and requires.core >= 2.5.
services[].gpu.apis_any list of str [] [beta] Any of these GPU APIs; jobs run only on nodes providing one (open set; detected: cuda, directml, metal, opencl, rocm, vulkan). Needs use shared or exclusive and requires.core >= 2.5.
probes list of Probe []
probes[].name str required
probes[].exec list of str required
probes[].period_s float 3600.0
probes[].platforms list of str [] [beta] Only on these platforms (empty: every declared platform).
workloads list of Workload [] [beta] Supervised long-running processes that are the work itself. Needs requires.core >= 2.10.
workloads[].name str required [beta] Unique among workloads and services; reports name it <module>/<name>.
workloads[].exec list of str required [beta] argv (spec/manifest.md, “Exec”); the agent appends run (the long-running process, cwd its run directory) or status (the health check). Usually the SDK’s supervisor shim (oarbank_sdk.workload).
workloads[].platforms list of str [] [beta] Only on these platforms (empty: every declared platform).
workloads[].seat "node" | "fleet" "node" [beta] node: the owner assigns it to nodes, one seat per node; fleet: the owner asks for a count and the coordinator places the seats once on eligible nodes (it never moves one on its own).
workloads[].identity "none" | "per_node" "none" [beta] per_node: the seat is named by the node’s values of the workload’s secrets and runs only under a coordinator seat lease with a fence, so at most one node runs an identity at a time; every secret must be set per node.
workloads[].secrets list of str [] [beta] Declared secrets delivered to this workload only, in OARBANK_SECRETS_FILE.
workloads[].listeners list of str [] [beta] Inbound listeners it serves through its endpoint channel ([sandbox].net.inbound).
workloads[].resources WorkloadResources "cpu_cores=1.0 mem_gb=0.5 network='normal'"
workloads[].resources.cpu_cores float 1.0 [beta] Cores it uses at full speed.
workloads[].resources.mem_gb float 0.5 [beta] Memory it holds (GB).
workloads[].resources.network "normal" | "heavy" "normal" [beta] heavy: the workload moves a lot of data over the node’s internet line. At a site (nodes sharing one line) at most the site’s budget of network-heavy work runs at once, and while a protected process at the site is in an upload phase the agent pauses it through its control (or stops and holds it when it cannot pause, or past pause_tolerance_s) on every node of the site. Older cores ignore it.
workloads[].gpu ServiceGPU "use='none' apis_any=[]" [beta] GPU use; not none needs sandbox.devices.gpu = ‘compute’.
workloads[].gpu.use "none" | "shared" | "exclusive" "none" [beta] A running service that is not none is GPU-resident fleet work: host protection stops it, when yieldable, while GPU work may not run, and a job reserving one of its pools is a GPU job. Needs sandbox.devices.gpu = ‘compute’ and requires.core >= 2.5.
workloads[].gpu.apis_any list of str [] [beta] Any of these GPU APIs; jobs run only on nodes providing one (open set; detected: cuda, directml, metal, opencl, rocm, vulkan). Needs use shared or exclusive and requires.core >= 2.5.
workloads[].control list of "cooperative_throttle" | "cooperative_pause" | "freeze_ok" [] [beta] What host protection may do besides stopping it: cooperative_throttle (it honours the control document’s threads and gpu_duty), cooperative_pause (it pauses itself on pause), freeze_ok (the agent may freeze its process container).
workloads[].pause_tolerance_s float (optional) [beta] The longest pause its peers survive: protection stops and holds it instead of pausing longer. Default: 20 when it can be paused (cooperative_pause or freeze_ok), else 0 (never paused).
workloads[].stop_timeout_s float 30.0 [beta] From the stop request to the kill.
workloads[].restart WorkloadRestart "backoff_initial_s=10.0 backoff_max_s=600.0 max_failures=5 jitter='full'"
workloads[].restart.backoff_initial_s float 10.0
workloads[].restart.backoff_max_s float 600.0
workloads[].restart.max_failures int 5 [beta] Consecutive failures before it is withdrawn (until a restart operation, a new version or a reassignment).
workloads[].restart.jitter "full" | "none" "full" [beta] full: each delay is uniform between 0 and the exponential backoff (AWS full jitter).
workloads[].health WorkloadHealth (optional) [beta] The status op’s period; absent: a running process is healthy.
workloads[].health.period_s float 15.0
workloads[].health.timeout_s float 5.0
workloads[].health.failures int 3 [beta] Consecutive unhealthy answers that end the run as a failure.
workloads[].reports bool false [beta] Its report events reach the module’s workload.report verb on the coordinator, whose effects keep the module’s own records (coordinator.workload_effects).
settings Settings "schema_=None"
settings.schema str (optional) [stable] JSON Schema (bundle path) whose properties are the module’s settings: each one’s type, default and constraints, title and description, and an x-oarbank annotation (scope fleet or node, required, unit, advanced, campaign). The core validates every value against it and hands node-scoped values to the module’s runners and services (spec/manifest.md, “Settings”).
secrets list of Secret [] [beta] Write-only credentials. Needs requires.core >= 2.5.
secrets[].name str required [beta] The secret’s name; unique. Stages and workloads list it in secrets.
secrets[].description str "" [beta] What it is for, shown where the owner sets it.
results Results required
results.schema str required [stable] JSON Schema (bundle path) for the result payload.
results.schema_version int required
results.determinism "exact" | "within_tolerance" | "none" required [stable] exact: replicas must produce the same digest; none: results are not compared (see stages[].determinism).
results.determinism_scope str "global" [stable] Open set. global: replicas on any platform must agree; platform: replicas and tie-breaks compare only within one platform (libm, BLAS and GPU differ across operating systems); os and arch [beta]: within one OS or one arch (they need requires.core >= 2.2). An unknown scope compares within one platform.
results.digest Digest required
results.digest.version int required [stable] Replica/golden comparisons happen only between equal digest versions.
results.digest.over list of str required [stable] Result payload fields the digest covers (documentation; the module computes it in result.evaluate).
results.value Value (optional)
results.value.field str required [stable] Result field studies optimise.
results.value.direction "maximize" | "minimize" "maximize"
results.max_inline_kb int 64
results.fields list of ResultField []
results.fields[].name str required
results.fields[].type "number" | "integer" | "string" | "boolean" required
results.fields[].indexed bool false [stable] Promote to a generated column with an index (sortable/filterable).
results.fields[].unit str (optional)
results.fields[].ui FieldUI "column=None format=None unit=None"
results.fields[].ui.column str (optional) [stable] Column header in result tables; absent = not shown.
results.fields[].ui.format str (optional) [stable] Restricted format spec: .Nf, .Ne, .N%, d, ,d or s.
results.fields[].ui.unit str (optional)
datasets Datasets "kinds=[] attrs=[] platform_bound=[] pinned=[]"
datasets.kinds list of str [] [stable] Dataset kinds this module registers (datasets.create refuses others). Kinds are short names scoped by the dataset’s owning module, so two modules’ kinds never collide; host.datasets.query takes the same short kind.
datasets.attrs list of DatasetAttr []
datasets.attrs[].name str required
datasets.attrs[].type "number" | "integer" | "string" | "boolean" required
datasets.attrs[].indexed bool false
datasets.platform_bound list of str [] [beta] Kinds whose datasets only make sense on one platform (an index built by a native tool): datasets.create must give their platform, and jobs using them run only there. Needs requires.core >= 2.2.
datasets.pinned list of PinnedDataset [] [beta] The datasets the module’s bootstrap stages may provide, each file with its sha256 and size. The host registers a bootstrap job’s artifact only when its files are exactly one entry’s, and datasets.create of a pinned id only with the pinned contents. Needs a bootstrap stage and requires.core >= 2.4.
datasets.pinned[].dataset_id str required [beta] The dataset id the host registers.
datasets.pinned[].kind str required [beta] One of [datasets].kinds.
datasets.pinned[].meta dict {} [beta] The registered dataset’s meta (its attrs).
datasets.pinned[].platform str (optional) [beta] Set exactly when kind is platform-bound: one of requires.platforms.
datasets.pinned[].files list of PinnedFile required [beta] Every file, with unique paths.
datasets.pinned[].files[].path str required [beta] PortablePath inside the dataset (what a job sees under the dataset’s mount).
datasets.pinned[].files[].sha256 str required [beta] The file’s sha256, 64 lowercase hex digits.
datasets.pinned[].files[].size int required [beta] The file’s size in bytes.
goldens Goldens (optional)
goldens.fixtures str required [stable] Glob (bundle path) of golden fixtures: inputs plus the expected digest, optionally per platform (Golden.platforms, Golden.expected_by_platform; oarbank_sdk.goldens.load reads them).
goldens.compare "digest" | "verb" "digest" [stable] verb calls golden.compare instead of digest equality.
ui UISection "icon=None digest_line=None pages=[] panels=[] views={} iframes=[] external_urls=[]"
ui.icon "cpu" | "gpu" | "dna" | "chart" | "flask" | "cube" | "bolt" (optional)
ui.digest_line str (optional) Restricted template: {field} or {field:FMT} only.
ui.pages list of PageDecl []
ui.pages[].id str required
ui.pages[].title str required
ui.pages[].slot "module.overview" | "module.page" | "job.detail.panel" | "node.detail.panel" | "campaign.panel" required
ui.pages[].file str required
ui.pages[].when str (optional)
ui.panels list of PageDecl []
ui.panels[].id str required
ui.panels[].title str required
ui.panels[].slot "module.overview" | "module.page" | "job.detail.panel" | "node.detail.panel" | "campaign.panel" required
ui.panels[].file str required
ui.panels[].when str (optional)
ui.views table str → ViewDecl {}
ui.views.shape "rows" | "kv" | "series" | "stat" required
ui.views.inputs list of str [] What invalidates it: results, jobs, datasets:, store:.
ui.views.params table str → Any {} Restricted JSON Schema properties for view params.
ui.views.columns list of Column []
ui.views.columns[].key str required
ui.views.columns[].label str (optional)
ui.views.columns[].type "text" | "number" | "integer" | "percent" | "bytes" | "duration" | "relative_time" | "timestamp" | "bool" | "digest" | "code" | "status" | "job_ref" | "node_ref" | "dataset_ref" | "campaign_ref" | "artifact_ref" | "link" "text"
ui.views.columns[].format str (optional)
ui.views.columns[].unit str (optional)
ui.views.columns[].direction "min" | "max" (optional) Which way is better; enables best/colouring generically.
ui.views.columns[].tone_by_sign bool false
ui.views.columns[].sortable bool true
ui.views.columns[].download bool false A dataset_ref or campaign_ref cell links to its download. [UI contract 1.2]
ui.views.refresh_s int (optional) Clock-driven refresh; floor 5 minutes.
ui.views.max_rows int 1000
ui.iframes list of IframeDecl []
ui.iframes[].id str required
ui.iframes[].entry str required Bundle path of the HTML entry (served from the module origin with its own CSP).
ui.iframes[].title str required
ui.iframes[].bridge list of "read.query" | "read.view" | "read.media" | "request.operation" | "resize" | "navigate" ["read.view", "resize"] Bridge capabilities the frame may use.
ui.external_urls list of str []
operations list of OperationDecl [] [beta] Module operations, registered as mod...
operations[].verb str required
operations[].title str required
operations[].tier "T0" | "T1" | "T2" | "T3" "T1"
operations[].min_role "viewer" | "operator" | "admin" "operator"
operations[].target "none" | "dataset" | "job" | "node" | "campaign" | "store" | "module" "none"
operations[].params_schema str (optional) Bundle path of the parameter schema.
operations[].effects list of "jobs.enqueue" | "jobs.cancel" | "campaigns.create" | "campaigns.update" | "campaigns.cancel" | "datasets.create" | "datasets.update" | "datasets.delete" | "module_settings.update" | "store.write" | "store.delete" | "files.write" | "files.put" | "files.delete" | "external" []
operations[].preview bool false Implements op.plan (required when the effective tier is T2/T3).
cli CLI (optional)
cli.exec list of str required [beta] Module CLI; oarbank cli <module> ... runs it on the coordinator, sandboxed, with a token scoped to the module (OARBANKD_URL, OARBANK_TOKEN).
sandbox SandboxSection "contract=1 net=SandboxNet(mode='none', allow=[], inbound=[]) tools=[] devices=SandboxDevices(gpu='none') containers=[] container_sets=[] exec_writable=False folders=[]"
sandbox.contract 1 1 [beta] Sandbox contract version.
sandbox.net SandboxNet "mode='none' allow=[] inbound=[]"
sandbox.net.mode str "none" [beta] Open set. none; egress-allowlist: only the allow hosts, through the agent’s local proxy (the SDK sets HTTPS_PROXY/ALL_PROXY); egress-any: any public address, a separately approved full-trust grant. Never loopback or link-local, never listening.
sandbox.net.allow list of str [] [beta] host[:port] entries (a leading *. matches subdomains); never IP addresses or CIDRs. Required with egress-allowlist; port defaults to 443.
sandbox.net.inbound list of InboundListener [] [beta] Listeners the agent opens on nodes the owner assigns, each served by one endpoint service that lists it (services[].listeners); module code never listens. A grant approved by digest, independent of mode (answering an accepted connection is not egress). Needs requires.core >= 2.10.
sandbox.net.inbound[].name str required [beta] The listener’s name, unique in the module; the node statement and every report call it <module>/<name>. Needs requires.core >= 2.10.
sandbox.net.inbound[].protocol "tcp" "tcp" [beta] tcp only (UDP is not built).
sandbox.net.inbound[].port_hint int (optional) [beta] The external port the module would like; the owner decides the real one per node.
sandbox.net.inbound[].port_policy "stable" | "flexible" "stable" [beta] stable: the external port is published somewhere costly to change (a chain, a registry), so a port someone else holds on the router is refused rather than replaced; flexible: the agent may take the next free port of a small range. The owner may override it per node.
sandbox.net.inbound[].tls "passthrough" | "none" "passthrough" [beta] The agent relays bytes untouched either way; the service terminates its own TLS, if any.
sandbox.net.inbound[].handover "connections" | "listen_fd" "connections" [beta] connections: each connection arrives on the service’s endpoint channel (every OS). listen_fd (macOS and Linux): the service’s start inherits a listening unix socket the agent made, in OARBANK_LISTEN_FD_, and only accepts on it (a third-party server that serves on an inherited socket); Windows nodes refuse such a listener.
sandbox.net.inbound[].proxy_protocol bool (optional) [beta] The agent writes a PROXY protocol v2 header before the first byte of each connection. Absent: true with handover listen_fd (the header is then the only way a server learns the client’s address), else false (the address arrives in the connection message).
sandbox.net.inbound[].max_conns int 256 [beta] Open connections at once.
sandbox.net.inbound[].max_conns_per_ip int 16 [beta] Open connections at once from one client address (IPv6: per /64).
sandbox.net.inbound[].new_conns_per_ip_per_s float 4.0 [beta] New connections per second from one client address (a token bucket with a burst of twice the rate).
sandbox.net.inbound[].idle_timeout_s float 120.0 [beta] A connection with no bytes either way for this long is closed.
sandbox.net.inbound[].max_bytes_per_s float (optional) [beta] A byte-rate cap for the listener, both directions together. Absent: none.
sandbox.tools list of ToolGrant [] [beta] Host tools runners, services and probes may read and execute: fleet tool ids with version constraints, resolved per node to one detected installation each (OARBANK_TOOLS_FILE).
sandbox.tools[].id str required [beta] The fleet’s tool definition id: jdk and python are built in; an admin defines others (tools.define).
sandbox.tools[].version str (optional) [beta] Versions the module accepts, comma-separated clauses all of which hold: =, !=, >, >=, <, <=, ~> (Nomad’s version operators), e.g. ">=17, <22". Leave it out for any version. Needs requires.core >= 2.9.
sandbox.tools[].arch "any" | "native" | "arm64" | "amd64" "any" [beta] any: any architecture, the node’s own preferred; native: only the node’s own (no x86_64 JDK under Rosetta on Apple silicon); arm64 or amd64: exactly that one. Anything but any needs requires.core >= 2.9.
sandbox.tools[].trust "read" | "code-exec" "read" [beta] code-exec: the tool runs arbitrary code (a JVM, an interpreter, a shell); the approval UI flags it. On Windows any readable binary is executable.
sandbox.devices SandboxDevices "gpu='none'"
sandbox.devices.gpu str "none" [beta] Open set: none or compute (GPU compute through the platform’s APIs, no display server; weakens isolation, so it is flagged at approval).
sandbox.containers list of ContainerImage [] [beta] Images the agent’s container broker may run for the module’s jobs (a stage that uses them reserves the containers pool).
sandbox.containers[].image str required [beta] A digest-pinned reference, e.g. docker.io/org/tool:1.2@sha256:<64 hex>.
sandbox.containers[].platform str "linux/arm64" [beta] OCI platform (open set), e.g. linux/arm64 or linux/amd64 (emulated where the node’s arch differs).
sandbox.container_sets list of ContainerSet [] [beta] Image sets approved by signature (registry and repository prefix, a pinned cosign key, optionally a signed index). A job runs a set’s images only if it lists them (jobs.enqueue images). Needs requires.core >= 2.5.
sandbox.container_sets[].name str required [beta] The set’s name; unique; shown at approval and in the audit.
sandbox.container_sets[].registry str required [beta] The registry host[:port], lowercase (docker.io for Docker Hub).
sandbox.container_sets[].repository str required [beta] A repository path; ending with / it is a prefix (every repository below it), else exactly that repository.
sandbox.container_sets[].platform str "linux/arm64" [beta] OCI platform of the set’s images.
sandbox.container_sets[].key str required [beta] Bundle path of the cosign public key: one ECDSA P-256 key, PEM PUBLIC KEY (SPKI), as cosign generate-key-pair writes cosign.pub.
sandbox.container_sets[].index str (optional) [beta] A tagged reference of a signed image index (artifact type application/vnd.oarbank.image-set.v1+json): only the digests it lists are members. Absent: every image signed by the key is.
sandbox.exec_writable bool false [beta] Runners may execute files they wrote into the data or work directory (downloaded tools). Not enforceable as false on Windows without application control; nodes report it.
sandbox.folders list of FolderGrant [] [beta] Folders on the node (registry ids the operator maps to a path per node) the runner may read, or write into as an outbox. Needs requires.core >= 2.5.
sandbox.folders[].id str required [beta] Logical folder id, e.g. inputs.
sandbox.folders[].access "read" | "write" required [beta] read: read the folder’s files and listings, never write. write: an outbox: create files and directories and write them, never read, list, rename or delete anything there (files it creates may replace files there).
bundle BundleSection "executables=[] platform_files={}"
bundle.executables list of str [] [stable] Globs (bundle paths) of files that get mode 755; every other file is 644. The argv[0] of every native exec is executable too. Modes never come from the build host’s filesystem.
bundle.platform_files table str → list of str {} [beta] Glob (bundle path) -> the platforms or OSes whose nodes receive the matching files; a file matched by several globs goes to each one’s platforms, and unmatched files go everywhere. The coordinator and the CLI always have the whole bundle. Needs requires.core >= 2.2.
placement Placement (optional) [beta] Needs requires.core >= 2.2.
placement.mix str "any" [beta] Open set: any, same-os, same-arch or same-platform. An unknown value applies as same-platform (fail safe) and oarbank-sdk check warns.
placement.unit "campaign" | "group" | "dataset" | "pipeline" "campaign" [beta] What stays together: a campaign, a job group within a campaign (jobs.enqueue group), the jobs of one dataset within a campaign, or one pipeline (head and tail stages, replicas and tie-breaks).
placement.bind "capacity" | "first-claim" | "explicit" (optional) [beta] How a unit gets its class: capacity (the feasible class with the most free certified CPU, at creation), first-claim (the class of the first node that claims one of its jobs) or explicit (only a pin). Absent: capacity for campaigns, first-claim otherwise.
placement.rebind "never" | "if-stranded" "never" [beta] When no node of the bound class has been eligible for stranded_after_s: never raises an alert naming the remedy; if-stranded rebinds to the best feasible class and re-queues the unit’s finished jobs.
placement.stranded_after_s float 1800.0 [beta] Seconds before a bound unit counts as stranded.

Source: spec/manifest-reference.md in the oarbank-sdk repository