Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ratect.toml Configuration Reference

This documents ratect.toml, the native configuration format the ratect binary reads by default. It is the same schema the Configuration Reference documents — the same containers, tasks, and fields, with the same meanings — re-spelled in TOML, with native additions (extends, ratect_version, and the other fields marked (native only) under Field reference), its auto-discovered local overrides file named ratect.local.toml rather than batect.local.yml, a few YAML-isms removed (anchors, the compact string shorthands), and identity in place of run_as_current_user.

Because the field semantics are identical across both formats, this reference does not repeat them: for what a given field actually does, follow the links into ratect-compat-config-reference.md. What’s covered here is the parts that are genuinely different — the TOML spelling, and the native-only rules.

The native format is ratect’s alone — ratect-compat reads batect.yml only (see Two binaries, two formats). To migrate an existing batect.yml, run ratect config convert.

The file

A ratect.toml describes a project’s containers and tasks. Named containers and tasks map onto TOML tables, so a container build-env is [containers.build-env] and a task build is [tasks.build]:

project_name = "my-app"

[containers.build-env]
image = "rust:1.90"
working_directory = "/code"
volumes = [{ local = ".", container = "/code" }]
environment = { CARGO_TERM_COLOR = "always" }

[tasks.build]
description = "Compile the project"
group = "Development"
run = { container = "build-env", command = "cargo build" }

project_name is the only top-level key the format requires, though a project must also set ratect_version or ratect refuses it. Unlike in a batect.yml loaded by ratect-compat, project_name is never inferred from the directory name. It’s taken from the root file only, and names the images the project builds and its eu.orican.ratect.project label — see Top level. ratect defaults -f to ratect.toml; point it at a differently-named file, or a batect.yml, with -f.

project_name, a container’s name, a task’s and a config variable’s follow the same rules as in a batect.yml — see Project and container names, Task names and Config variable names — and the error for one that breaks them gives the line and column of the name itself in a .toml file (of its value, for project_name), and of the entry’s value in an included .yml one.

This closely mirrors examples/rust/ratect.toml’s own real build-env container and build task — same image, same command, same task description/group — with an environment entry added here purely to show the syntax; the real file doesn’t set one.

ratect_version: the version a project was written for

A top-level ratect_version records the Ratect version the project was written for:

ratect_version = "0.13.0"
project_name = "my-app"

ratect checks it before reading anything else in the file, and refuses to run the project in two cases:

  • The project is newer than the binary. A project written for 0.13 most likely uses something 0.11 doesn’t know, so 0.11 says it needs 0.13 or later rather than failing on whichever field it meets first.
  • A later release changed what a configuration means. Ratect keeps a list of every change to what a ratect.toml means or accepts — the CHANGELOG.md entries marked ratect.toml: under Breaking. If any came after the project’s ratect_version, ratect lists them and stops; once you’ve reviewed them, set ratect_version to the version you’re running. An upgrade that crosses none of them is silent.

A refusal of the second kind also says, for each change, whether it touches the project, to help with the review — it never replaces it, and the project is refused either way. ratect run hello, captured in ratect/tests/fixtures/written-for — a project written for 0.11.0, run by 0.13.0:

Error: Refusing to load ratect.toml: This project was written for ratect 0.11.0, and ratect has changed what a configuration means since:
  - ratect 0.12.0: a '\' in an expression escapes the character after it and is dropped, and a trailing '\' fails the load — none found
  - ratect 0.12.0: every '$' or '<' in an expression starts a reference, so a malformed one ('$$', 'a < b', '${X:default}') fails the load, and an unbraced name ends at '.' or '-' (write '<{batect.project_directory}') — none found
  - ratect 0.12.0: a task or config variable name Batect refuses fails the load: a task name is letters, digits, ':', '-', '.' and '_', starting and ending with a letter or digit; a config variable name is letters, digits, '-', '.' and '_', starting with a letter and not with 'batect' — doesn't apply: it loads under these rules
  - ratect 0.12.0: 'project_name' and every container name must be a Docker image-name component, or the load fails: lowercase letters and digits, joined by a single '.', one or two '_', or any number of '-' — doesn't apply: it loads under these rules
  - ratect 0.12.0: an included file that sets 'forbid_telemetry' to true fails the load; only the root file may — doesn't apply: it loads under these rules
  - ratect 0.12.0: a string 'volumes' or 'devices' entry with an empty options segment ('a:b:') fails the load — doesn't apply: it loads under these rules
  - ratect 0.12.0: a local include's 'path' whose first component is '~' is looked for in the home directory, not in a '~' directory beside the file declaring it — none found
  - ratect 0.12.0: a 'command', 'entrypoint', 'run.command', 'run.entrypoint' or setup command that can't be split into arguments (an unbalanced quote, a trailing '\') fails the load, even where no task runs it — doesn't apply: it loads under these rules
  - ratect 0.12.0: a Git bundle is refused until the 'ratect_version' of the file its include names, or the include's 'reviewed_ratect_version', covers every change since; the root's 'ratect_version' doesn't cover a bundle — none found
  - ratect 0.13.0: 'run_as_current_user' in a TOML file, or inherited through 'extends' from a YAML file and enabled, fails the load; use 'identity' instead — doesn't apply: it loads under these rules
  - ratect 0.13.0: a home directory ('~' first in a local include's 'path' or a host path) is 'HOME' when it is set and absolute, and only otherwise the passwd entry's — none found
With this check set aside, the project loads under ratect 0.13.0's rules.
Review them (see CHANGELOG.md), then set 'ratect_version' to 0.13.0 to run it with this version.

Each change’s outcome depends on how it can be checked:

  • A change that only makes something fail to load is checked by loading the project once more under the running version’s rules, with this check set aside. That load runs nothing, but fetches what a normal load does, Git bundles included. The refusal says once whether the project loads. If it does, each such change doesn’t apply; if it doesn’t, the refusal shows the error, and each such change may apply, since the error doesn’t say which one caused it.
  • A change with a detector — one Ratect can recognise by looking, such as the one refusing a Git bundle, or one to what an expression means — is looked for in each of the project’s .toml files, read as plain TOML: none found, or found with the field and file it was found in. Its .yml files aren’t looked in, so a project with one reads not known rather than none found. Nor is it none found when the project doesn’t load: which files there are isn’t known then, so only the root file is looked in, and a use there is still found.
  • A change nothing checks would say not checked. Every change so far has a check.

So for the project above, every change is ruled out: it loads, and declares no Git include, no local include starting with ~, no host path starting with ~, a reference or an escape, and no expression a change reads differently. Once you’ve read the changes and agree, set ratect_version to 0.13.0 and it loads.

ratect doctor and ratect config validate report a refusal the same way: the refusal is a problem, each change a finding of its own — ok once it’s ruled out, warning otherwise — and whether the project loads is ok, or a problem naming the error.

Only the major and minor numbers are compared, and only the root file may set it — an included file, or any YAML file, that does is rejected, except the file a Git include names, which declares a bundle’s own. The root’s version never covers a bundle: each is checked against its own, or against its include entry’s reviewed_ratect_version — see The version a bundle was written for. A project without one counts as written for 0.3.0, the first release with ratect.toml, so since 0.12.0 changed what a configuration means it’s refused until it sets one; ratect config convert writes it for you.

A project whose root file is a batect.yml can’t set it at all — it keeps Batect’s own shape. Its YAML files mean what they mean to Batect, which nothing on the list changes, so it loads whatever the list says. A .toml file it includes doesn’t, so a project that includes one counts as written for 0.3.0 too, and is refused naming that file — once it has loaded, so a .toml include that doesn’t load gets its own error first. Making the root a ratect.toml is the way to declare a version for it: ratect config convert converts its YAML files, but reads every file as YAML, so a local .toml include has to be carried over by hand. ratect-compat rejects the field too, saying that only a native ratect.toml can declare it.

extends: inheritance instead of YAML anchors

batect.yml factors out a shared base container with YAML anchors/aliases/merge keys (&base/*base/<<:). Those are YAML syntax and don’t exist in TOML, so ratect.toml replaces them with an explicit extends field:

[containers.base]
image = "rust:1.90"
environment = { CARGO_TERM_COLOR = "always" }

[containers.build-env]
extends = "base"
working_directory = "/code"      # added
environment = { RUSTFLAGS = "-D warnings" }  # replaces base's entirely

The rules:

  • Single parent. extends names exactly one container.
  • Shallow, per field. A field the child sets replaces the inherited one outright — there is no deep-merging into nested maps. Above, build-env’s environment is { RUSTFLAGS } only; base’s CARGO_TERM_COLOR is not merged in. This matches how <<: already behaves, and Cargo’s profile inherits. To keep an inherited map and add to it, restate the whole map.
  • Chains. a may extend b which extends c; each level fills what the one below left unset. A cycle (including a container extending itself) is an error.
  • Base-only containers need no image. Only a container a task actually runs is required to have an image or build_directory, so a base that exists purely to be extended can omit both.
  • Resolved after paths. Inheritance happens after relative paths are made absolute, so an inherited build_directory or volume host path stays anchored to the file that declared it, not the child’s location — this matters when the parent came from an included file.
  • Clearing an inherited list. An empty list is a value like any other, so setup_commands = [] on a child clears the parent’s. That is how to reuse a container as a dependency without its setup steps.
  • Overriding a build with an image. Because inheritance is per-field with no way to unset one, setting image on a child is how you override a parent’s build_directory: image wins, and the inherited build_directory is simply unused. ratect-compat rejects a container with both fields (Batect does, and has no extends that would need the override) — this is a deliberate difference, not an oversight. A container used only as an extends base likewise needs neither field; the requirement is enforced when a task actually runs a container, so no abstract marker is needed.
  • Containers only. Tasks do not extends (compose task behaviour with prerequisites/dependencies instead).

One shape per list entry

volumes, ports, and devices take one object shape per entry — not the compact "local:container" strings batect.yml also accepts. Use inline tables for the terse cases and [[...]] array-of-tables blocks for longer ones; they’re equivalent:

[containers.app]
image = "postgres:16"

# Inline tables — compact.
volumes = [
    { local = ".", container = "/code" },
    { local = "./secrets", container = "/run/secrets", options = "ro" },
]
ports = [{ local = 5432, container = 5432 }]

# Or the block form — readable when there are many fields.
[[containers.app.devices]]
local = "/dev/kvm"
container = "/dev/kvm"
  • A volumes entry is a host bind (local + container [+ options]), a named cache volume ({ type = "cache", name = "...", container = "..." }), or a tmpfs mount ({ type = "tmpfs", container = "...", options = "..." }).
  • A ports entry is { local, container } [+ protocol], with port ranges written as "6000-6010" — see Port mappings.
  • A devices entry is { local, container } [+ options].

The parser itself still accepts the string forms (which is what lets a .yml include keep using them), and so does config validate, without a warning; the native schema and the docs treat the object form as canonical.

Config variables and expressions

Config variables are declared under [config_variables] and referenced with the same <name / <{name} expression syntax as batect.yml — the syntax is values inside strings, so it carries across verbatim. Which fields resolve one is not identical: this format also resolves them in image, which a batect.yml refuses — see Expressions in image, and note that the image line in the example below is exactly that case. Otherwise see ConfigVariable and Expressions.

[config_variables.tag]
default = "latest"
description = "The image tag to run."

[containers.app]
image = "myapp:<{tag}"                 # a config variable
environment = { HOME = "${HOME}" }      # a host environment variable

Local overrides

A ratect.local.toml beside the config file is loaded automatically when present (no flag), supplying config-variable values for the current developer/machine — the native default for --config-vars-file:

# ratect.local.toml — gitignore this.
tag = "dev"

It holds values only, not configuration: a flat name = "value" map, nothing else. Anything you want to vary locally should be a config variable the tracked config interpolates, keeping what varies declared and visible rather than hidden in an untracked file. Precedence, lowest to highest: a variable’s default, then the config-vars file (ratect.local.toml, or whatever --config-vars-file names), then --config-var on the command line.

Includes

include is an array of entries, each a local file or a Git bundle. Formats may mix: each included file is parsed by its extension — .toml as native, .yml/.yaml as Batect-format YAML — so a native project can still pull in an existing batect.yml fragment or bundle unchanged.

include = [
    { path = "ci/tasks.toml" },                              # local, native
    { path = "shared/legacy.yml" },                          # local, still YAML
    { type = "git", repo = "https://example.com/bundle.git", ref = "v2" },
]

A type = "git" entry with no path discovers its bundle file by looking for ratect-bundle.toml first, then batect-bundle.yml — so an unmigrated Batect bundle keeps working, and a bundle author can ship both files to support ratect and Batect at once. How included files combine, where their paths resolve and what a bundle may do are on Includes; the shared ~/.ratect/incl cache is in the batect.yml reference (ratect includes manages it); why you’d share a bundle across projects at all is Reusable Pipeline Building Blocks.

An extends in a native file may inherit from a container defined in any included file, including a YAML bundle — the container namespace is flat once includes are merged.

Some top-level keys are root-only. An included file, in either format, fails the load naming that file if it declares project_name or ratect_version — except a bundle’s entry file, which may declare its own — or sets forbid_telemetry to true — a key with no effect, accepted so a file written for Batect still loads, as in a batect.yml. Setting forbid_telemetry to false in an included file is allowed.

Shared caches

A cache mount is private to the project by default: the storage carries the project’s own key, so two projects declaring cargo-registry get two different caches. scope = "shared" drops that key, so every project on the machine naming it gets the same storage.

[[containers.build-env.volumes]]
type = "cache"
name = "cargo-registry"
container = "/usr/local/cargo/registry"
scope = "shared"        # or "project", the default

[[containers.build-env.volumes]]
type = "cache"
name = "build-output"
container = "/build"    # no scope: private to this project

This exists because the alternative is worse. A bundle that wants one Cargo registry or npm cache across projects would otherwise have to spell it as a host path (local = "~/.cache/cargo"), which means granting the bundle access to your home directory — the thing allow_host_paths exists to permit and decisions/0004 would rather solve properly. A shared cache says the same thing directly, grants no host filesystem access at all, and keeps the location under Ratect’s control.

Where it is stored. A shared cache is the Docker volume ratect-shared-cache-<name>, or the directory ~/.ratect/caches/<name> under --cache-type=directory — beside ~/.ratect/incl, where Git includes are cloned, because both belong to the machine rather than to any one project. With no home directory the directory form is refused, naming the cache. A project cache remains batect-cache-<project key>-<name>.

A name has one scope per project. Declaring cargo-registry as project in one container and shared in another is rejected when the file loads: one name would mean two different pieces of storage. Two containers naming the same cache is the ordinary way to share it between them, and is unaffected.

Removing one takes naming it. ratect caches clean with no arguments sweeps this project’s caches and never a shared one — discarding storage other projects are still using should not be a side effect. See the caches options.

Expressions in image

A container’s image takes expressions, so a pipeline can choose its image per run without a flag:

[config_variables.tag]
default = "latest"

[containers.app]
image = "my-repo/my-image:<{tag}"

[containers.tools]
image = "my-repo/tools:${IMAGE_TAG:-latest}"

Both forms work: <{tag} reads a config_variables entry (settable with --config-var tag=1.2.3), and ${IMAGE_TAG:-latest} reads the host environment with a fallback. The same rules apply as everywhere else — an unset host variable with no :-default is a hard error naming it, rather than a silent empty string that would produce a puzzling image reference.

A container inheriting an image through extends gets the expression its parent wrote, evaluated the same way, so it resolves to the same value.

Nothing is evaluated when the file loads, so ratect tasks list works whatever this machine supplies. Running a task evaluates only the containers that task uses, when the run reaches it — again like every other expression-bearing field. So an unset variable with no :-default fails only the tasks whose containers read it. The error names the container, the field and the expression, so you are not left hunting for which one. A malformed one, such as img:${, is the exception: it is a mistake in the file, so the file fails to load, located by its line and column.

Rejected in a batect.yml, rather than resolved or ignored. Batect has no expression support in image, so a file using one would load here and fail under batect itself — and unlike an exotic capability, a parameterised image tag is something a pipeline would use on every run, so the lock-in would be routine rather than incidental. ratect-compat users have --override-image, which covers most of the same ground; what it can’t express is an in-config default, which is what this adds.

The rejection is on what you wrote, not on what it would resolve to, and it knows the difference between an expression and a literal $: alpine:3.18 and repo/img:1.2.3 load exactly as before. An escaped \$ is a literal $ here, as in any expression. A batect.yml’s image is no expression at all, so a \ in it is kept as written; the rejection reads an escape as the expression syntax does, so repo/\$x loads and repo/\\$x doesn’t. Names follow the expression syntax too, so repo/img:$5 is rejected, while repo/img$, a $ with no name after it, is no expression and is used as written.

Nested Git includes

A Git include fetches configuration from a repository and merges it into yours. That bundle can declare include entries of its own — and in a batect.yml those may be further type: git entries, naming any remote, with the same trust your own includes get. In ratect.toml that is refused by default: you chose the bundle; you did not choose whatever it decides to pull in next. Opt in per bundle by setting allow_nested_git_includes on that bundle’s include entry:

[[include]]
type = "git"
repo = "https://github.com/my-org/infra-bundle.git"
ref = "1.2.3"
allow_nested_git_includes = true

The grant is one level deep, counts only in configuration you control, and has to sit on the entry that reaches the bundle’s file first — the same rules as allow_host_paths, stated once on Includes along with the refusal you see without the grant.

A nested include’s clone failure is reported without git’s own message. Whether a remote is unreachable, refusing connections, missing, or demanding credentials is a readout on a network — and for a nested include the remote was named by the bundle, not by you, so the answer is of more use to whoever wrote it than to you. In CI, where the log is often visible to anyone who can propose a change to that bundle, repeated attempts map an internal network one include at a time. The failure is still reported and still names both repositories; only the transport detail moves behind RUST_LOG=debug. An include you declared keeps git’s message in full — it describes a remote you wrote down, and hiding it would only make your own typo harder to find.

The field is rejected in any .yml rather than ignored, value and all, under either binary: it is native-only, and a native-only field follows the file it is written in (see Which fields a file may use). Setting it to false in a batect.yml would claim a restriction that format never applies. reviewed_ratect_version is refused in a .yml the same way.

run_in: setup commands in another container

A setup_commands entry normally runs inside the container that declares it. Sometimes the tooling isn’t there: seeding a database means running a client, and a postgres:16 image is not where your migration tool lives. run_in names another container to run the command in, while leaving when it runs alone — it is still part of the declaring container’s readiness gate, so nothing that depends on that container starts until the command has succeeded. On a task’s own container, which has no readiness gate, it doesn’t run at all (see Dependency Readiness).

[containers.db-seed-client]
image = "my-org/db-tools:latest"
# Stays alive, so there is a live process for the command to run alongside.
command = "sleep infinity"

[containers.db]
image = "postgres:16"
dependencies = ["db-seed-client"]
health_check = { command = "pg_isready -U postgres" }
setup_commands = [
  { command = "psql -h db -U postgres -f /seed/schema.sql", run_in = "db-seed-client" },
]

[containers.app]
image = "my-org/app:latest"
dependencies = ["db"]

app starts once db is healthy and the seeding command has exited 0 — exactly as it would if that command ran inside db itself.

  • The target must be one of the declaring container’s own dependencies (or the declaring container itself, which is what leaving run_in out means). Anything else is rejected when the file loads, naming the container you asked for. This is the rule that makes the ordering safe rather than merely likely: a dependency has already been through its own full readiness gate before the container declaring it even starts, so it is running when the command arrives. A sibling has no ordering edge to this container at all, and a container that depends on this one structurally cannot have started yet — either would be a race with no fix, so neither is offered. A dependencies entry inherited via extends counts, since the check runs after inheritance resolves. A task’s own dependencies does not, even for that task’s main container: it orders the target ahead of this container for one task only, and the same container used by another task would silently lose that ordering — so the dependency has to be declared on the container, where it holds everywhere.
  • The command runs with the target container’s environment, user and working directory, not the declaring container’s — it is running over there, so those are the ones that apply. That includes the fallback a setup command with no working_directory of its own gets: the target’s working_directory, not the declaring container’s. The entry’s own working_directory still overrides. In the example above, that is why the command reaches the database over the network (-h db) rather than through a local socket.
  • The target must stay running. It is docker exec, so there has to be a live container to exec into — hence sleep infinity above. A run_to_completion dependency has already exited by the time it counts as ready, so naming one is rejected when the file loads rather than failing mid-run.

run_to_completion: init containers

A dependency normally starts detached, waits for a health check (immediate if none is configured), then runs its setup_commands — see Dependency Readiness. run_to_completion replaces that whole gate with a simpler one: the dependency runs, and is ready once it exits with status 0 — a non-zero exit fails the task run the same way an unhealthy dependency or a failing setup command does. Kubernetes-style init-container behavior, expressed as a plain node in the existing dependency graph rather than a separate concept:

[containers.migrate]
image = "my-repo/migrate:latest"
run_to_completion = true

[containers.app]
image = "my-repo/app:latest"
dependencies = ["migrate"]
  • No health check, no setup_commands. Neither concept applies once a dependency runs to completion — setting either alongside run_to_completion is rejected when the file loads.
  • Ordinary graph participation. A run_to_completion dependency can depend on other dependencies (of either kind), other dependencies can depend on it, and it can be declared directly under a task’s own dependencies or nested under another dependency’s — no special-casing either way.
  • Concurrent when independent. Two run_to_completion dependencies for one container that don’t depend on each other run at the same time, gated purely by the graph, not a separate strictly-sequential list.
  • Inert on a task’s own container, exactly as health_check and setup_commands are. A task’s own container already always runs to completion by definition — that’s what running a task’s command means — so a container a task names via run.container runs as an ordinary task container whether or not it sets the flag. The same container still runs to completion as a gate when another task uses it as a dependency. (A task’s own run block has no field to set it on at all.)

Not a substitute for prerequisites. A prerequisites entry runs as a fully separate task execution — own network, own containers, own cleanup — strictly sequential relative to whatever named it, whether or not it ran concurrently with anything else. That isolation is the point when the two runs genuinely shouldn’t share anything. run_to_completion solves a different problem: staying inside one task’s own dependency graph, sharing its network with siblings (a cache, a long-running app) that must keep running while it finishes.

external_health_check: checking a container from outside it

A health_check runs inside the container it checks, so it needs a shell and a tool (curl, wget, pg_isready) to be present in that image. A distroless or scratch image has neither, and the usual workaround is to add tooling that exists for no reason but to be health-checked with. external_health_check checks such a container from outside instead.

It is a separate field because it is a separate concept, not a second spelling of health_check. health_check is Docker’s own HEALTHCHECK — the daemon owns its schedule, its starting/healthy/unhealthy state and its re-running for the container’s whole lifetime. This is closer to a Kubernetes readiness check: an external observer asking “can this be used yet?”, once, with no opinion about the container’s health afterwards. (Ratect has no equivalent of a liveness check in either form.) So the external check alone decides when the container is ready: if its image declares a HEALTHCHECK of its own, Docker still runs it, but Ratect doesn’t wait on it.

[containers.api]
image = "my-repo/api:1.0.0"   # scratch-based: no shell, no curl

[containers.api.external_health_check]
type = "http"
port = 8080
path = "/healthz"

[containers.app]
image = "my-repo/app:1.0.0"
dependencies = ["api"]

app now starts only once GET http://api:8080/healthz answers 200, with nothing at all having run inside api.

Two kinds of check are supported:

typeChecksFields
httpThe response status of a request to path on portport (required), path (defaults to /), expected_status (defaults to 200)
tcpThat a connection to port is acceptedport (required)

Both also take interval, retries and timeout, meaning exactly what they mean on a health_check — how long to wait between attempts, how many attempts to make before failing the task, and how long one attempt may take. The difference is what an omitted one does: a health_check inherits the image’s own value, and there is no image to inherit from here, so Ratect’s own defaults apply (interval = "1s", retries = 30, timeout = "5s"). The first attempt is made immediately rather than after interval has elapsed. A port, timeout or retries of zero is rejected when the file loads rather than taken literally — nothing listens on port 0, zero attempts would never check at all, and the tools the check is made with read a zero timeout as no timeout. So is an expected_status that isn’t three digits, which no HTTP response can carry.

  • Over the project’s own network, never a published port. The check reaches the container by its container-config name — the same network alias its siblings use — so port is the port the container listens on, and nothing has to appear in ports. Two isolated instances of one project (concurrent CI jobs on a single host) therefore never contend over a host port to check each other.
  • Reported as the container becoming healthy. The output says api has become healthy. when the check passes — the same line a health_check produces, at the same point in the run, since both mean the container is ready to use; the check itself is still a readiness check, not Docker’s health check. A check that never passes fails it the same way too, naming the container you wrote: Container 'api' did not become healthy: last status 000 from http://api:8080/healthz after 30 attempt(s), wanted 200. The external check ran in container 'ratect-health-check-api' — --no-cleanup-after-failure keeps it for inspection.
  • Ratect runs the check from a companion container, which you don’t see. Declaring one generates a container named ratect-health-check-<container> running curlimages/curl (pinned by digest, not by tag — you did not write that reference, so it must not resolve to something different later), which loops the check and exits 0 or non-zero — an ordinary run_to_completion dependency, so the waiting happens in the dependency graph rather than anywhere new. It narrates nothing of its own in any output style: it is how the check runs, not something you declared. It always logs with json-file, whatever the daemon’s default log driver, since a failure’s diagnosis is read back from its output. It is still a real container, so ratect resources and docker ps see it, and a failure names it so --no-cleanup-after-failure leaves you something to inspect.
  • The generated name is reserved. While api has an external check, anything in the project that declares or refers to a container called ratect-health-check-api — another container’s dependencies, a task’s run.container or dependencies — is rejected when the file loads, naming what referred to it. Nothing is silently replaced or quietly repurposed.
  • No health_check, no run_to_completion, no setup_commands. All three are rejected alongside it when the file loads. The first would be two answers to one question; the second has already exited by the time anything could connect to it; and the third has no ordering available to it — the companion is a sibling of the checked container rather than a gate on it, so a setup command would run against exactly the service the check is waiting for. Put such a step in a container of its own that depends on the checked one, where it waits for the check like anything else.
  • Inert on a task’s own container, exactly as health_check and setup_commands are — nothing waits on a task’s own container becoming ready, because running it is the task (see Dependency Readiness), so the same container can be one task’s main container and another task’s checked dependency.

Because the two are separate concepts, interval, retries and timeout do not quite mean the same thing in both, despite the shared names — which is why they are not one field under a type tag. Docker’s retries counts consecutive failures before flipping to unhealthy, cushioned by a start_period that has no meaning out here; this one counts attempts.

stop_signal/stop_grace_period: graceful shutdown

Cleanup stops every container the same way by default — Docker’s own default signal (usually SIGTERM), then a fixed ~10-second timeout before escalating to a forceful kill. That is fine for most containers, but not for one where an abrupt stop can corrupt something, such as a database with data shared between invocations. stop_signal and stop_grace_period — Docker Compose’s own field names for the same concept — let a container opt into different behavior:

[containers.database]
image = "postgres:16"
stop_signal = "SIGINT"
stop_grace_period = "30s"
  • Purely additive. A container that sets neither field behaves exactly as today — Docker’s own default signal and timeout, unchanged. Setting one without the other only changes that half: stop_signal alone still waits Docker’s own default timeout, and stop_grace_period alone still sends Docker’s own default signal.
  • Only changes what a task’s own cleanup sends. The other place Ratect stops a container — ratect resources clean, which removes what an interrupted run left behind — finds its containers by a label scan, with no configuration to read, so it keeps Docker’s own default signal and timeout whatever a container asked for here.
  • Durations use Batect’s Go-style string format: "2s", "1m30s", "0" — the same format health_check’s interval/timeout use. Docker’s own stop timeout is whole seconds, so anything finer is rounded up to the next second: "500ms" waits one second, never less than asked for.
  • A further signal during cleanup never waits on stop_grace_period. It only bounds the graceful stop that cleanup starts with; a second signal (Ctrl+C again, or a supervisor’s follow-up SIGTERM) force-removes whatever is left with no grace period at all, and a Ctrl+C after that abandons cleanup — see Differences from Batect.

ulimits: per-resource limits

A container can raise or lower the resource limits its processes run under — Docker’s own --ulimit, per container:

[containers.build-env]
image = "rust:1.90"
ulimits = [
    { name = "nofile", soft = 1024, hard = 2048 },
    { name = "core", soft = 0 },
]
  • name is one of the resources docker run --ulimit documents, without its RLIMIT_ prefix: core, cpu, data, fsize, locks, memlock, msgqueue, nice, nofile, nproc, rss, rtprio, rttime, sigpending, stack. (Not as, which Docker documents as deprecated.) A name outside that list is rejected when the file loads, like an unknown capability — Docker’s API checks none of this itself, so the alternative is a container that is created happily and then fails to start, as wrong rlimit value: RLIMIT_<NAME> out of the container runtime.
  • hard defaults to soft. An entry that sets only soft sets both limits to that value, matching docker run --ulimit name=limit.
  • -1 means unlimited. A soft limit above the hard limit — or an unlimited soft limit under a finite hard one — is rejected when the file loads. That is the rule the docker CLI enforces for --ulimit, though its documentation doesn’t state it; the daemon’s API doesn’t enforce it either, and a container that gets such a pair fails in the runtime with error setting rlimit type 7: invalid argument, which names a number rather than the field you wrote.
  • Per container, and only that container. A dependency’s ulimits apply to the dependency; a task’s own container is unaffected by them, and there is no task-level or project-wide default.
  • Purely additive. A container that sets no ulimits is created exactly as before — whatever the daemon’s own defaults are.

Entries are objects, like every other native list entry — and objects only: unlike volumes, ports and devices, this field has no compact string form at all.

dns/dns_search/dns_options: name resolution

A container can set its own nameservers, search domains and resolv.conf options — Docker’s own --dns, --dns-search and --dns-option, per container:

[containers.build-env]
image = "rust:1.90"
dns = ["10.0.0.53"]
dns_search = ["corp.example.com"]
dns_options = ["ndots:2"]
  • Each is a list of strings, and each is independent. Set any one, two or all three; one left unset keeps whatever the daemon would otherwise have chosen.
  • dns entries are IP addresses (IPv4 or IPv6), checked when the file loads. Docker’s API rejects anything else too, but only once the container is being created, as invalid JSON: ParseAddr(...), which names no field.
  • Containers still resolve each other by name. On the task’s own network, Docker’s embedded resolver stays each container’s nameserver and forwards to the dns servers for everything else — unlike mounting your own /etc/resolv.conf, which replaces it.
  • Fixed on the container’s own definition. Neither a task’s run block nor a dependency’s customise overlay accepts these fields: DNS is a property of the environment a container runs in, not of which task happens to use it. A dependency’s settings apply to the dependency alone.
  • Purely additive. A container that sets none of the three is created exactly as before.

network_mode: leaving the task’s network

Every container normally joins the task’s own network — or --use-network’s — reachable by its name. A container can leave it instead, with Docker’s own --network modes:

[containers.database]
image = "postgres:16"

[containers.metrics-agent]
image = "otel/opentelemetry-collector:0.110.0"
dependencies = ["database"]
network_mode = "container:database"
  • host shares the Docker host’s network namespace; none gives the container only a loopback interface; container:<name> shares the network namespace of another container in this config — its interfaces, its hostname, its /etc/hosts and resolv.conf, and its localhost. Anything else is rejected when the file loads.
  • A container:<name> target must be one of the container’s own dependencies, so it is already running when this one starts — the dependency graph stays the one thing that orders startup. This container is created once the target has been created (Docker needs the target’s id for that), and started once the target is ready. It may not be a run_to_completion container, which has exited by then. The target may share another container’s network in turn, but a chain of them that leads back round on itself is rejected: nothing in it has a network of its own.
  • It applies to that container alone. Every other container in the task joins the task’s network exactly as before, with or without --use-network, and health checks and setup_commands gate readiness the same way in every mode — neither goes over the network.
  • Name-based reachability is lost. A container in any of the three modes has no name on the task’s network, so a sibling can’t reach it as <name>. Ratect doesn’t check whether anything tries to — with host, a sibling would have to use the host’s own address instead, and with container:<name>, the target’s name reaches both containers.
  • Containers sharing a namespace share its ports. Two services in them can’t listen on the same port: Docker starts both containers, and the second service’s own attempt to listen fails with Address in use. What happens then is up to that service — most exit, which fails the run with that container’s exit code. Ratect can’t check this when the file loads, since nothing in the config says which ports a container listens on (ports only says which are published).
  • Fields that need the task’s network are refused alongside it, when the file loads: ports (a task’s run or customise ones too), additional_hostnames and external_health_check in every mode, and with container:<name> also additional_hosts, dns, dns_search and dns_options, which Docker refuses there. With host or none they have nothing to apply to. With container:<name> they belong on the target instead, whose settings apply to both containers: ports published on the target forward into the namespace the two share, so they reach a port either container listens on, and the target’s names and external_health_check reach both the same way. If the target shares another container’s network in turn, the error names the container at the end of that chain, whose network they all share — and if that one uses host or none itself, ports, additional_hostnames and external_health_check can only be removed.
  • Fixed on the container’s own definition, like dns: neither a task’s run block nor a customise overlay accepts it.

user/group/groups: running as a specific user

A container can say which user and groups it runs as. These are passthroughs: Ratect hands them to the runtime verbatim and synthesizes nothing.

[containers.build-env]
image = "rust:1.90"
user = "1000"
group = "20"
groups = ["docker", 999]

The nearest real project is ratect/tests/fixtures/user.toml.

  • Each value is a name or an id, written as a string or a bare integer, so user = 1000 and user = "1000" are the same. An empty value, one containing a : and a negative integer are rejected when the file loads.
  • user becomes the container’s user, and group its primary group. Together they are the runtime’s user:group. group without user, once extends has resolved the container, is rejected when the file loads.
  • Each field inherits on its own. A child that overrides only user keeps its parent’s group, and can’t remove it, so user = "root" under a parent with group = "staff" runs as root:staff.
  • A base is judged like any other container, unlike the need for an image: a base with group needs a user of its own, even if every child sets one.
  • groups are supplementary groups, Docker’s --group-add, and need no user: they add to whichever user the container runs as.
  • The runtime resolves names against the image’s own files. Ratect doesn’t check them, so a user or group the image lacks fails the container’s start with the runtime’s own error. An id needs no entry in the image, though with none whoami fails and $HOME is /.
  • Ratect doesn’t prepare mounts for this user. A fresh cache volume stays root-owned, so a non-root user can’t write to it; on rootful Linux the same goes for a missing host directory, which the daemon creates as root. Create them owned by that user yourself: a fresh volume takes its owner from an image directory at the same path. If what you want is mounts prepared for you, use identity instead of user, which on a rootful Linux daemon does both.
  • Setup commands run as the same user. A setup command with run_in runs as its target’s user instead.
  • A non-root user on a rootless or userns-remap daemon gets a warning, naming the container and the field, when a run reaches it. It has only other users’ access to a bind mount the host user owns, so it usually can’t write there or read anything private. The run carries on, and ratect doctor reports the same.
  • Fixed on the container’s own definition, like dns: neither a task’s run block nor a customise overlay accepts them.

identity: your files, and the same $HOME everywhere

This field does two jobs. What a container writes through a bind mount is yours, rather than root’s, except on a userns-remap daemon, or a rootless one under a non-root image USER. And $HOME is what you said it is, whatever the image or the machine, so cache mounts and mounted ssh or Git configuration can be declared once. How it gets you the first depends on the daemon: on a rootful Linux daemon the container runs as you, while Docker Desktop’s file sharing and a rootless daemon’s own mapping of root to you deliver it without that. Batect users will know this as run_as_current_user. File Ownership and the Home Directory shows the outcome on each daemon; this section is the rules behind it.

[containers.as-you]
image = "alpine:3.24"
working_directory = "/code"
identity = { home = "/home/me" }
groups = ["users"]
volumes = [
    { local = ".", container = "/code" },
    { local = "ssh", container = "/home/me/.ssh", options = "ro" },
]

That container is from examples/identity, which that page walks through.

Both places programs look then agree: $HOME, which Git reads, and the running user’s /etc/passwd entry, which ssh’s ~ reads. Who the running user is depends on the daemon, and ratect doctor says which kind you have:

  • On a rootful Linux daemon, which includes Docker Desktop on Linux, it is you: the container runs as your uid and gid. See On a rootful Linux daemon.
  • On a local Docker Desktop, OrbStack or similar on macOS or Windows, and on rootless and userns-remap daemons, it is the image’s own USER, or root if it has none. Ratect doesn’t change it.

A run warns on the remapped daemons, naming the container and identity, and carries on:

  • On a userns-remap daemon, always: every container user maps to a subordinate host uid, root included, so the container has only other users’ access to a bind mount the host user owns, and what it does write has a subordinate owner. That ownership has to be arranged on the host. The home is still guaranteed. ratect doctor reports this too.
  • On a rootless or userns-remap daemon, when the image’s USER isn’t root: it meets the same mapping as a non-root user, with only other users’ access to such a mount. doctor doesn’t report it, since it doesn’t pull the image.

These apply on every daemon:

  • home is required, and is an absolute path with a leaf name and no .., : or control characters. It can hold an expression. A literal is judged when the file loads. An expression is judged when it is evaluated, before Docker touches the container, and ratect config validate and ratect doctor report a bad one as a warning.
  • It can’t be combined with user or group, or with a relative cache destination, once extends has resolved the container. These are rejected when the file loads. groups works with it, and adds to the running user.
  • Only the running user’s entry changes, beside any lines added for additional users. Every other line of the image’s /etc/passwd stays as it was, and the file keeps its mode and owner. A name selects the entry with that name, and a uid the first entry with that uid. Only its home field changes, added to a line too short to have one.
  • A user with no entry, on the daemons where the image’s USER runs: a numeric USER gets one, named with its uid (root for uid 0), with the numeric group from USER or else 0. A named group isn’t looked up: the process runs with it, but the entry and a created home have that user’s entry’s gid, or 0. An image with no /etc/passwd at all, such as scratch, is treated as having an empty one. A named USER the image lacks gets nothing, and the runtime refuses to start the container.
  • /etc/passwd isn’t edited through anything, nor is /etc/group where it is edited. A symbolic link, a mount at that path or at /etc, or a file over 1 MiB fails the run, naming the container.
  • HOME is set in the container’s environment, over any ENV HOME in the image. A HOME in environment wins, though the passwd entry still says home.
  • The home is only created where nothing exists: owned by the running user, mode 0755, with any missing parent directories owned by root. An existing directory or symbolic link, a bind mount included, keeps its owner and mode even if the running user can’t write to it. A symbolic link isn’t followed, so one that is dangling or leads to a file leaves the home unusable. A file there fails the run, naming the container, and so does a tmpfs as the deepest mount above the home, unless something is mounted at the home itself. A tmpfs is empty when the container starts, so it hides a home the image ships as much as a missing one, and where Docker made the home for a mount below it, that mount leaves a root-owned mount point in the home’s place.
  • A mount above the home is where it gets created, since that happens before the container starts, whatever tmpfs is further up. Under a writable bind mount, a missing home lands on the host, in that directory. Under a read-only mount, a missing home fails the run, naming the container. ratect doctor and ratect config validate report both.
  • A mount below the home is the exception. With a mount at ~/.ssh or ~/.cargo/registry, Docker creates the home and ~/.cargo as root before Ratect can look at them. So each directory from the home down to a mount goes to the running user, keeping its mode, when it is owned by root, the running user isn’t root, and it isn’t at or inside another mount. A root-owned one the image shipped is handed over the same way, though not what is in it.
  • Fixed on the container’s own definition, like dns: neither a task’s run block nor a customise overlay accepts it.

What this leaves as it is:

  • Files baked into the image’s old home (/root/.npmrc, from a RUN step) stop being found via ~. They are still at their old path.
  • An entrypoint that drops privileges (postgres) runs as a user other than the running user, and that user keeps its own home.
  • A working_directory below the home that isn’t a mount. Docker creates it and any missing parents, the home included, as root. A mount at it makes the home the running user’s, as above.
  • A tmpfs at home hides the directory created there, so under a non-root running user its options have to allow that user to write.
  • No cache mount changes owner except on a rootful Linux daemon. A fresh named volume is root-owned, so a non-root image USER can’t write to one on the other daemons, even when the home above it is theirs. Fix that in the image: a fresh volume takes its owner and mode from an image directory at the same path. One owned by the image’s USER is still another uid’s on a rootful Linux daemon, where you run instead, so a mode that lets anyone write works on every daemon.
  • A cache shared between uids or groups is yours to arrange. chmod alone isn’t enough: under 1777 a second user can create files in it but not change the first user’s.

Coming from run_as_current_user

run_as_current_user and identity have the same goal: files you can edit and delete, and a home that works. They differ in how they get there. Batect’s field does one thing everywhere, while identity does what the daemon in front of it needs, so a converted project may stop running as --user and still get the outcome.

A .yml keeps run_as_current_user, with Batect’s behaviour, including one a native project includes, and ratect-compat always has it. A .toml file refuses it, enabled or not, and so does a TOML container inheriting an enabled one from a .yml through extends, which it can neither override nor remove. ratect config convert turns an enabled one into identity, its home_directory becoming home, drops a disabled one, and lists each container it converted. What changes for such a container:

  • --user depends on the daemon. On a rootful Linux daemon the container still runs as your uid and gid. On a local Docker Desktop, OrbStack or similar on macOS or Windows, and on rootless and userns-remap daemons, it runs as the image’s own USER. Desktop file sharing hands you what it writes anyway, and so does a rootless daemon when that USER is root. Otherwise nothing Ratect could apply would, so a run warns.
  • The image’s identity files aren’t replaced. run_as_current_user swaps /etc/passwd, /etc/shadow and /etc/group for generated ones, which removes the users the image shipped, such as node or postgres. identity changes only the running user’s entry, and on rootful Linux adds what is missing.
  • cache volumes change owner only on rootful Linux. Elsewhere a fresh volume stays root-owned, so a non-root image USER can’t write to it.
  • home is an expression, and holds no ... home_directory is used as written in a .yml. config convert carries a $ or < across as a reference, and lists it, and also lists a .., since the converted file is refused until that is changed.

Additional users

Some tools look up a user or group by name, and fail if the image lacks it. identity can add those on every daemon, beside the image’s own users, which are all still there:

[containers.build-env]
image = "alpine:3.18.2"
identity = { home = "/home/me", additional_users = [{ name = "svc", uid = 1500, gid = 1600 }] }
groups = ["svc"]

The nearest real project is ratect/tests/fixtures/identity.toml, whose additional-users container is this one.

  • name, uid and gid are all required. Ratect picks no ids. A name starts with a letter or _, and holds only letters, digits, _, . and -. Neither id can be 0, and no two additional users can share a name, a uid or a gid. These are rejected when the file loads.
  • /etc/passwd gets one line each: svc:*:1500:1600::/nonexistent:/bin/sh. Nothing creates that home, and /etc/shadow isn’t touched.
  • A name or uid already in /etc/passwd fails the run, naming the container and the values, with neither file written. That covers the image’s users and the running user, so on a rootful Linux daemon a declaration can clash on one machine and not on another, whose host user differs. Pick ids away from the ones your users have.
  • /etc/group gets an entry named after the user only if both that name and the gid are free, so sharing a gid with one of the image’s groups is fine, and that group is reused untouched. It is written before the container starts, so groups can name it. Where the gid was taken there is no entry of that name, so the runtime refuses to start a container whose groups names it. Where only the name was taken, groups finds the existing group, at its own gid. On a rootful Linux daemon your own group counts as taken.
  • Ratect starts nothing as an additional user. user can’t be combined with identity, so something in the container has to switch to it, as an entrypoint dropping privileges would. On the daemons where the image’s USER runs, a named USER the image lacks gets nothing even if listed here, and the runtime refuses to start the container. On a rootful Linux daemon the host user runs instead, so that image starts.

On a rootful Linux daemon

The container runs as your uid and gid, and setup commands exec as the same. If you are root, the same steps run as root. The image’s identity files are added to, never replaced:

  • /etc/passwd, your uid present (node at 1000 is the usual one): the first such entry keeps its name and gid, and only its home changes. So whoami says node, and the process still has your gid, not the entry’s.
  • /etc/passwd, your uid absent: an entry is appended with your username, or with your uid’s digits if the image uses that name for another uid or your uid has no name on the host, password *, your gid, home, and shell /bin/sh.
  • /etc/group: an entry named after your group is appended only if both its gid and that name are free. If the gid exists, that entry is reused untouched. If only the name is taken, nothing is added, and id prints your gid with no name. If your gid has no name on the host, nothing is added either, so id names it only if the image has an entry for it.
  • Host directories a mount needs are created as you before the container is, when the daemon is local: a missing bind mount source, and a mount point nested inside another host mount.
  • A cache named volume with root as its owner becomes yours, keeping its mode, unless it is read-only (options = "ro") or you are root. That is what makes a fresh volume writable. Only the volume’s top directory changes: files already in it keep their owner, so a cache filled as root needs cleaning first. A volume another uid owns is left alone, so can’t be written to by you unless its mode allows. A directory cache gets nothing, since you created it. A shared cache follows the same rule.

The home follows the rules above, so home = "/root" isn’t writable by you unless a mount below it hands it over. With a daemon on another machine (ssh://, tcp://), your uid and gid are still the ones of the user running Ratect. Ratect creates no host directories for it, on either machine, so the daemon creates a missing source as root. Windows has no uid to adopt, so a Windows client reaching such a daemon fails the run, naming the container.

Docker Desktop on Linux counts as a rootful Linux daemon, so Ratect takes these steps there, and ratect doctor calls it rootful Linux. That is deliberate: only vendor-specific signals tell it from a native daemon (why, and what was probed). On the one version probed, with default file sharing, what a container wrote to a bind mount stayed yours whichever user it ran as, so running as you may not be what delivers that there. The same project on Docker Desktop on a Mac runs as the image’s USER.

services: bringing containers up together

A service group is a named set of the project’s containers that ratect services up brings up together, shows the output of, and takes down together — a stack to work against, such as an API and its database, rather than a task that runs to an end. It names containers already declared under containers, and adds nothing to them. An illustrative project — none of the worked examples declares a group:

[containers.api]
image = "my-repo/api:latest"
dependencies = ["migrate"]
ports = [{ local = 8080, container = 8080 }]

[containers.db]
image = "postgres:16"

[containers.migrate]
image = "my-repo/migrate:latest"
dependencies = ["db"]
run_to_completion = true

[services.stack]
containers = ["api", "db"]
exit_condition = "any_stopped"
exit_code_from = { container = "api" }
FieldDefaultMeaning
containersrequiredThe group’s members, by container name: at least one, each named once.
exit_condition"all_stopped"When services up takes the group down on its own: "any_stopped" once any member has stopped, "all_stopped" once every member has.
exit_code_from"first_non_zero"Where services up takes its exit code from: "first_non_zero", the first non-zero exit code a member stopped with of its own accord, or 0; "first_to_exit", the exit code of the member that stopped first; or { container = "<member>" }, that member’s exit code whenever it stopped — even when services up stopped it, as it does the rest once "any_stopped" is met.
  • A member starts as a task’s dependency does. Its own dependencies start first, and its health check, setup_commands and run_to_completion apply — see Dependency Readiness. Each container is started once, however many members depend on it.
  • Only a member counts. A container a member depends on, migrate above, is brought up and taken down with the group, but its exit neither meets the exit condition nor gives the exit code. With run_to_completion, as migrate has, it finishes before the member that depends on it starts, and its exit 0 is its readiness. A dependency that keeps running and then stops is reported as one that exited unexpectedly, as in a task.
  • Native only. A Batect-format (YAML) file can’t declare services, included or not, and ratect-compat has no services verb.
  • Any TOML file may declare a group. Groups from every file are merged, like tasks, and a group name defined in two files fails the load. A group’s name follows the rule a container’s does: lowercase letters and digits, joined by a single ., one or two _, or any number of -.
  • What the group’s containers are called. Each is created as <project>..<group>..default..<container> on a network named <project>..<group>..default, the same names every time: that is what makes a second services up attach to the group, or wait for it, rather than start another copy.

Field reference

Every container and task field from ratect-compat-config-reference.md applies, with the same meaning except where Where the semantics differ says otherwise. Scalars, string maps (environment, labels, build_args, …) and scalar lists (capabilities_to_add, additional_hostnames, …) are a direct 1:1 spelling; the only fields whose shape differs are the object-per-entry lists above. The container fields, by area:

AreaFieldsSemantics
Imageimage, image_pull_policy, build_directory, dockerfile, build_target, build_args, build_secrets, build_sshImage building
Mountsvolumes (host / cache / tmpfs)Volumes, caches, tmpfs. A cache also takes scope (native only) — the linked section describes project-keyed storage, which scope = "shared" deliberately does not use.
Runtimecommand, entrypoint, working_directory, environment, enable_init_process, privileged, shm_size, capabilities_to_add, capabilities_to_drop, devices, labels, log_driver, log_optionsContainer
Graceful shutdownstop_signal, stop_grace_periodabove (native only)
Resource limitsulimitsabove (native only)
Name resolutiondns, dns_search, dns_optionsabove (native only)
Networkingports, additional_hostnames, additional_hosts, dependenciesPorts, readiness
Network modenetwork_modeabove (native only)
Readinesshealth_check, setup_commandsDependency Readiness. Both are inert on a task’s own container — see Where the semantics differ. A setup command also takes run_in (native only)
Init containersrun_to_completionabove (native only)
External checksexternal_health_checkabove (native only)
Useridentity, user, group, groupsidentity and user/group/groups (native only)
Inheritanceextendsabove (native only)

Where the semantics differ

Almost nothing: the two formats parse into the same model, so a field means what ratect-compat-config-reference.md says it means. The exceptions fall into four groups: places where extends gives a combination a meaning it cannot have in a batect.yml, which has no inheritance; places where this format is deliberately stricter, having no Batect compatibility to preserve; two places where it does more than Batect, resolving expressions in image and a string-form volumes entry’s host path — the first of which batect.yml has to refuse rather than quietly accept, the second of which it uses as written, as Batect does; and one where it deliberately does less — a task’s own container has no readiness gate.

Every row below about a container is decided by the format of the file that declares it, not by the project — a container written in a .yml takes the left-hand column even inside a native project (see Which fields a file may use). The first three rows follow the project instead: two are about an include entry rather than a container, and the third about how a task runs its own container. An include entry’s native-only fields, allow_nested_git_includes among them, still follow the file: only a .toml file can set them.

Behaviourbatect.yml (ratect-compat)ratect.toml (ratect)
A Git-included bundle declaring a type: git include of its ownAlways allowed, matching BatectRefused unless the bundle’s own include entry sets allow_nested_git_includes
A nested Git include failing to cloneReports git’s own errorReports that it failed, with the transport detail behind RUST_LOG=debug — see Nested Git includes
A task’s own container’s health_check/setup_commandsRun alongside the main command, matching Batect; a failure while the main command is still running fails the task unless the command exits 0 within the next two seconds, and cancels it if it hasn’t exited by then; once it has exited 0, a failure is forgiven — the cost and the race that leaves are in known limitationsInert: no health wait, no setup commands, and the task’s result is the main command’s alone — see Dependency Readiness
An expression in imageRejected when the file loads — Batect resolves nothing there; anything else, a \ included, is used as writtenResolved like any other expression, a \ escaping the character after it — see Expressions in image
Setting run_as_current_user on a containerRuns it as the host’s own user, replacing the image’s identity files, matching Batect; enabled defaults to false, and a $ or < in home_directory is part of the path — see User mappingRejected when the file loads — use identity
An expression in a string-form volumes entry’s host path ("$HOME/.m2:/root/.m2")Used as written, matching Batect — a $ or < is part of a relative path; the object form’s local is still resolvedResolved in either form
A container with both image and build_directoryRejected when the file loads, matching BatectAllowed — image wins, and this is the only way to override a build_directory inherited from an extends parent, since inheritance is per-field with no way to unset one
A container with neither image nor build_directoryRejected when the file loadsAllowed — a container used only as an extends base needs neither; the requirement is enforced when a task actually runs a container, so no abstract marker is needed
Setting stop_signal/stop_grace_period on a containerRejected when the file loads — Batect has no equivalent fieldOverrides Docker’s own default stop signal/timeout during cleanup — see above
Setting ulimits on a containerRejected when the file loads — Batect has no equivalent fieldSets that container’s own resource limits — see above
Setting dns/dns_search/dns_options on a containerRejected when the file loads — Batect has no equivalent fieldSets that container’s own name resolution — see above
Setting network_mode on a containerRejected when the file loads — Batect has no equivalent fieldTakes that container off the task’s network — see above
Setting user/group/groups on a containerRejected when the file loads — Batect has no equivalent fieldSets the user and groups that container runs as — see above
Setting identity on a containerRejected when the file loads — Batect has no equivalent fieldGives that container a guaranteed home — see above
image alongside a build-only field (build_args, build_target, dockerfile, build_secrets, build_ssh)Rejected when the file loadsAllowed and ignored, for the same inheritance reason — a child overriding a build with an image still carries the parent’s build fields

The last row is the one to watch: setting build_secrets or build_ssh on a container that also has an image does nothing at all, and the native format cannot tell you so without forbidding the override above. If a build field looks like it is being ignored, check whether the container resolves to an image.

Task fields: run (a TaskRun table — container, command, entrypoint, environment, ports, working_directory), prerequisites, dependencies, description, group, and customise (see Task). A task needs at least one of run or prerequisites.

[tasks.integration-test]
description = "Run the integration suite"
prerequisites = ["build"]
run = { container = "test-runner", command = "pytest tests/integration" }

[tasks.integration-test.run.environment]
DATABASE_URL = "postgres://db/test"

Editor support

Ratect ships a JSON schema for the native format, schema/ratect-config.schema.json (most of its fields generated from the config types, the native-only ones written alongside them, and its value patterns checked against the parser by tests). Pointing a TOML-aware editor extension at it — taplo / “Even Better TOML” for VS Code, or JetBrains’ TOML support — gives field-name autocompletion, hover documentation, and a red squiggle under a misspelled or unsupported field. It’s the native counterpart of the batect.yml schema: the same schema, adjusted to the native shape (object-only list entries, no run_as_current_user) and adding the native-only fields this page documents.

The simplest way to use it is a schema directive on the first line of your config, which taplo honors:

#:schema https://raw.githubusercontent.com/or1can/ratect/main/schema/ratect-config.schema.json
project_name = "my-project"

Structural validation only catches what the schema can express. For some of the rules it can’t (a task needing run or prerequisites, an extends cycle), ratect config validate checks a ratect.toml without a Docker daemon, so it also works as a CI gate. A container with neither image nor build_directory is still only reported when a task or services up runs it.

Differences from batect.yml, at a glance

batect.yml (ratect-compat)ratect.toml (ratect)
FormatYAMLTOML
Default filebatect.ymlratect.toml
Reuseanchors / aliases / merge keysextends
Cross-project cache—scope = "shared" on a cache mount
Init containers—run_to_completion on a dependency
Health check from outside—external_health_check on a container
Graceful shutdown—stop_signal/stop_grace_period on a container
Resource limits—ulimits on a container
Name resolution—dns/dns_search/dns_options on a container
Network modealways the task’s networknetwork_mode on a container
Named user and groups—user/group/groups on a container
Guaranteed home—identity on a container
Setup command targetalways the declaring containerrun_in on a setup command
Task’s own container’s readiness gatehealth check, then setup commandsnone — see Dependency Readiness
List entriesstring shorthand or objectobject (inline table or [[...]])
Local overridesbatect.local.ymlratect.local.toml
Git bundle defaultbatect-bundle.ymlratect-bundle.toml, then batect-bundle.yml
IncludesYAMLTOML or YAML, by extension
Written-for version—ratect_version
Bring containers up together—services

Most field meanings are unchanged; the spelling and the format-level rules above are the bulk of the difference. The exceptions are the native-only fields, the rows above with no batect.yml entry, and the handful of behaviours in Where the semantics differ.