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

Introduction

Define your development tasks — build, test, lint, a database to develop against, … — once in configuration, and run them identically on any machine that has Docker. No “works on my machine”, no per-developer setup drift, no JVM to start: Ratect is a single native binary, so it runs instantly.

If that sounds like Batect, that’s deliberate: Batect was archived in October 2023, and Ratect grew out of it — same batect.yml, running on a native binary instead of a JVM one. But it’s not just a port: Ratect already fixes real bugs Batect never got to (leaked containers and networks on anything but Ctrl+C, an eight-year-old open proxy issue) and adds tooling Batect never had — ratect doctor, ratect resources, a native ratect.toml format. See Differences from Batect for the full list, drop-in replacement included. It’s an independent project, not affiliated with or endorsed by the original Batect project.

See it in action

A real request against a real, composed stack — an app, a database, and a cache, each waiting for the last to actually be ready (not just “started”) before it starts itself — no wait-for-it.sh, no manual networking, no leftover containers once it’s done. This is the dependency graph from examples/full-stack — that project also has build/unit-test/run/lint/shell tasks, omitted here to keep this to the part that’s actually running below:

ratect_version = "0.13.0"
project_name = "ratect-full-stack"

[containers.app]
image = "node:22"
working_directory = "/code"
enable_init_process = true
ports = [{ local = 8080, container = 8080 }]
environment = { DATABASE_URL = "postgres://postgres@db:5432/postgres", REDIS_URL = "redis://cache:6379" }
volumes = [
    { local = "app", container = "/code" },
    { type = "cache", name = "full-stack-npm-cache", container = "/root/.npm" },
]
# Not just for `run` — `app` cannot even start without both (it connects to
# `cache` at module load, and `db` on its first request), so this belongs
# on the container itself rather than repeated on every task that uses it.
dependencies = ["db", "cache"]
command = "sh -c 'npm ci && npm start'"
# Checked from outside, over the project's own network, instead of by the
# `node -e` one-liner this used to be — escaping quotes inside a TOML string
# to make a single HTTP request. `node:22` is a full Debian image and could
# run that check itself; the field exists for images that can't (distroless,
# `scratch`), and is used here because the declarative form says what is
# actually meant. Nothing runs inside `app` to prove it is ready.
[containers.app.external_health_check]
type = "http"
port = 8080
path = "/healthz"
interval = "1s"
retries = 20

[containers.db]
image = "postgres:16"
environment = { POSTGRES_HOST_AUTH_METHOD = "trust" }
volumes = [{ local = "db/init", container = "/docker-entrypoint-initdb.d" }]
health_check = { command = "pg_isready -h 127.0.0.1 -U postgres", interval = "1s", retries = 90 }
# ANALYZE needs a real, committed table to work against, which is exactly
# what setup_commands is for — running once db is healthy, not baked into
# the init script that creates and seeds that table in the first place.
# Genuinely useful here, not just illustrative: a bulk INSERT this size
# leaves the query planner without fresh statistics until something
# collects them, and the journey-test/app queries below count() this table.
setup_commands = [
    { command = "psql -U postgres -c \"ANALYZE visits;\"" },
]

[containers.cache]
image = "redis:7"
health_check = { command = "redis-cli ping", interval = "1s", retries = 10 }

[containers.journey-test]
image = "node:22"
working_directory = "/code"
environment = { REDIS_URL = "redis://cache:6379" }
volumes = [
    { local = "journey-test", container = "/code" },
    { type = "cache", name = "full-stack-npm-cache", container = "/root/.npm" },
]
command = "sh -c 'npm ci && node test.js'"

[tasks.journey-test]
description = "Exercise the running app end to end, sharing `cache` with `app`"
group = "Development"
dependencies = ["app", "cache"]
run = { container = "journey-test" }

A real recording, not a mockup — fancy output shows all four containers’ status live, updating in place, each independently: db seeding a real million-row table before it’s ready (genuinely, not padded — that’s why it takes longer than app/cache), then running a real setup_commands step (ANALYZE visits, giving the query planner fresh statistics after that bulk insert) once it’s healthy but before anything depends on it, then app and journey-test both starting only once cache says it’s ready — cache itself, once, even though it’s a dependency of both. journey-test makes a real HTTP request to app (the JSON in the middle is its real response), then checks Redis directly to confirm the value app read got cached — see Dependency Readiness for the full model behind all of it. Every container is removed afterwards regardless of how the task ends.

Two binaries, two formats

Ratect ships two binaries. ratect reads its own ratect.toml format and is the one to install if you’re starting fresh — it’s the forward-looking CLI, free to add things Batect never had. ratect-compat reads a batect.yml unchanged, as a drop-in replacement for the (now unmaintained) batect binary, and stays batect.yml-only permanently — pick it if you already have a Batect project and want a maintained tool without editing any YAML. Both run the same engine and exit with the same codes, are versioned and released independently, and can be mixed: ratect -f batect.yml reads a Batect config too, a ratect.toml project can include a batect.yml fragment as-is, and ratect config convert translates a whole batect.yml when you’re ready to move.

Where to go next

Source and issue tracker: or1can/ratect.

How Ratect Compares to Other Tools

This page compares Ratect against what a project is actually likely to be choosing between today: Docker Compose, Make, Task, Earthly, Dagger, and just.

None of these six exist to lose to Ratect. Each was built to solve a real problem, several of them solve it better than Ratect does for the case they targeted, and picking the right one is usually about which problem you actually have — not which tool wins a feature count. What follows is honest about both directions.

Reach for Ratect when the problem is running development tasks identically on every machine, isolated from your host and from each other, with real dependency orchestration. Two of those are for free just by running in Docker at all: the image is built the same way regardless of what’s on your host (reproducibility), and by default each run gets its own disposable network — created fresh per invocation, named after that run, torn down after — so containers on one run can’t reach containers or ports from another (isolation), unless you deliberately opt out with --use-network. The third — a database or another service that needs to actually be ready, not just started, before your task touches it — is Ratect’s own design, not a side effect of Docker. That’s a narrower claim than “runs my project”; the sections below say plainly where it isn’t the best fit.

Docker Compose

Compose defines and runs multi-container applications — the closest match to Ratect in shape (containers, networks, dependencies between them), and the one most likely to already be sitting in a project you’re looking at.

Where Compose wins: it’s the default, not an alternative you have to choose — ships with Docker Desktop and Engine, and most developers already know it. Bringing up a stack and leaving it running (the actual point of a docker-compose.yml) needs less ceremony in Compose than expressing the same thing as a Ratect task, because that’s what Compose is for and Ratect’s task model isn’t. docker compose watch gives you a live dev loop with no equivalent in Ratect at all.

Where Ratect wins: Compose has no task layer — no prerequisites, no distinct build/test/lint verbs, no per-invocation ephemeral containers. depends_on: condition: service_healthy gates start order on a health check, which is real and useful, but Compose has nothing like setup_commands — a scripted step that runs inside a dependency once it’s healthy but before anything depends on it starts. Seeding a database before code touches it means an init container or an entrypoint script you write and maintain yourself; in Ratect it’s a config field. The isolation model differs too: a Compose stack is meant to be brought up once and left running, its network and containers shared across however many docker compose exec calls you make against it afterward. Ratect’s network and containers, by default, are scoped to one task invocation and torn down when it finishes, rather than persisting for the next run to reach. And a Compose service runs as its image’s user unless you set user: to a uid yourself, so on a rootful Linux daemon what it writes through a bind mount is usually root’s, where Ratect’s identity runs the container as you there, and gives it the same $HOME on every daemon.

Make

GNU Make — the original. Targets, prerequisites, recipes, and a dependency graph driven by file timestamps — genuinely incremental, in a way nothing else on this page (Ratect included) fully replicates.

Where Make wins: it’s already installed, on nearly every Unix-like system, with zero extra daemon and zero extra dependency — spinning up Docker for a one-line shell command is real overhead Make never pays. Make’s own incremental rebuild — skip a target outright if its prerequisites’ files haven’t changed — is a genuine capability Ratect doesn’t have; a Ratect task always runs, and whether the tool inside the container decides to skip work is between that tool and its own cache, not something Ratect tracks itself.

Where Ratect wins: Make runs on whatever’s already on your host — the exact “works on my machine” problem Ratect exists to remove, and whatever a recipe installs, writes, or leaves running stays on your host too, since Make has no isolation from it at all. It also has no native model for orchestrating dependent services (bring up a database, wait for it, run something against it); that’s shell script bolted onto a recipe, not something the tool understands.

Task

Taskfiles — YAML, explicitly positioned as “inspired by Make, designed for modern workflows.” Closest in spirit to Ratect and Batect’s own “define tasks in a file” model of any tool here — but Task runs on the host by default; Docker is something you can reach for per-task, not the execution model itself.

Where Task wins: far lighter for tasks that don’t need containerizing at all — no daemon, near-instant startup, and it works the same on Windows without Docker Desktop in the loop. Its sources/generates fields give file-based skip-if-unchanged tracking similar to Make’s, which Ratect has no equivalent of.

Where Ratect wins: the same reproducibility and isolation gap as Make — Task’s default is your host toolchain, so “works on my machine” is back on the table unless you deliberately containerize each task yourself, and even then there’s no built-in service-dependency/readiness model to reach for.

Earthly

Worth naming plainly: Earthly is no longer actively maintained — its own README says so directly, pointing at a post titled “shutting down Earthly Cloud.” Its last tagged release was mid-2025. Comparing against it now is closer to Ratect’s own relationship with Batect than a live rivalry.

While it was under active development, Earthly’s actual design point was a containerized build framework — Dockerfile-and-Makefile-flavored syntax, BuildKit-based, with a real target-level build-cache graph more sophisticated than Ratect’s cache volume mounts for the specific job of producing cacheable build artifacts identically locally and in CI.

Where Ratect wins today, practically: it’s maintained. Setting that aside, the two tools’ centers of gravity differ anyway — Earthly is oriented around building artifacts; Ratect’s health_check/setup_commands/ dependencies model is oriented around running and orchestrating live services, which was never Earthly’s target.

Dagger

A programmable automation engine, not a config format: pipelines are code, in a real language (Go, Python, TypeScript, and others), compiling down to containers as Dagger’s own primitive. The pitch is portability — the same pipeline runs on your laptop, in CI, or in Dagger’s own cloud — backed by built-in OpenTelemetry tracing.

Where Dagger wins: a real programming language for pipeline logic — loops, conditionals, functions, tests for the pipeline itself — which ratect.toml/batect.yml’s declarative shape deliberately doesn’t offer, and isn’t trying to. For a genuinely complex pipeline that outgrows what a static config file can express cleanly, that’s a real advantage, not a rounding error.

Where Ratect wins: simplicity for the common case. Most projects need “run these containers, in this order, with these dependencies” — a small TOML/YAML file to read and edit, not SDK code in a general-purpose language to write and maintain. Ratect’s Batect-compatibility story (an existing batect.yml keeps working, field-for-field) also has no Dagger analogue — Dagger is a from-scratch mental model, not a migration path from anything.

just

Its own README calls it “a command runner, not a build system” — a deliberate, stated distinction from Make, not an oversight. justfile recipes run on the host, with none of Make’s dependency-graph or incremental-rebuild machinery.

Where just wins: about as light as this category gets — a single small binary, no daemon, recipes that are just shell commands with better ergonomics (parameters, cross-platform support, no .PHONY workarounds). For “give me short, memorable names for the commands I run all the time,” reaching for Ratect and its Docker daemon is real overhead for no benefit.

Where Ratect wins: just doesn’t attempt reproducibility or isolation at all — recipes run in your own shell, on your own machine — and it has no service-orchestration model whatsoever. Neither is a flaw in just; it’s explicitly not trying to be either of those things.

If you’re choosing

Reach for…when the problem is
Ratectdevelopment tasks that need to run identically everywhere, isolated from your host, and/or real services (a database, another API) they depend on actually being ready first
Docker Composebringing up and living inside a multi-container stack, more than running discrete tasks against it
Makeyou already have make everywhere you need it, and don’t need containers, isolation, or cross-machine reproducibility
TaskMake-like ergonomics without Make’s own syntax, for tasks that don’t need Docker
Daggera pipeline complex enough to genuinely need a real programming language, not a config file
justshort, memorable shortcuts for commands you already know how to run

Earthly isn’t in that table on purpose — recommending an unmaintained tool for new work doesn’t make sense regardless of what it used to be good at; see its own section above for what that was.

Nothing here is exclusive — a real project often uses more than one of these at once (a justfile that shells out to ratect run, or a Compose stack a Ratect task talks to). This is a guide to which problem each tool was built for, not a bracket with one winner.

Coming from Batect? Its own comparison page ranged over shell scripts, Docker Compose, Dojo, Earthly, CI tools with a local runner (GitLab CI, CircleCI), and Vagrant — reasonable choices when it was written. Of those, Docker Compose and Earthly are the two this page also covers. To move a batect.yml project over, see Migrating a Batect Project to Ratect.

Starting fresh rather than from a batect.yml? Installation is next.

Installation

Prebuilt binaries

Every tagged release of ratect-compat or ratect publishes prebuilt binaries as GitHub Release assets, for five platforms:

Target triplePlatformMinimum OS
x86_64-unknown-linux-gnux64 Linuxglibc 2.34 or later
x86_64-unknown-linux-muslx64 MUSL Linux (Alpine, minimal containers)No shared libc: statically linked
aarch64-unknown-linux-muslARM64 MUSL Linux (ARM servers, Raspberry Pi)No shared libc: statically linked
x86_64-apple-darwinIntel macOSmacOS 10.12 or later
aarch64-apple-darwinApple Silicon macOSmacOS 11.0 or later

Ubuntu 22.04, Debian 12 and RHEL 9 and later ship glibc 2.34 or newer. On a distribution whose glibc is older, such as Ubuntu 20.04, Debian 11 or RHEL 8, use the x86_64-unknown-linux-musl build, which needs no shared libc at all. Raising any of these minimums is a breaking change, listed as one in the changelog.

ratect-compat and ratect are tagged and released independently (see Two binaries, two formats), so they’re listed as separate entries on the Releases page — tags look like ratect-compat/vX.Y.Z and ratect/vX.Y.Z. Find the most recent tag for the binary you want, then download the archive matching your platform from that release’s assets.

Each archive extracts to a directory (named after the archive itself) containing the binary alongside LICENSE/NOTICE/README.md/RELEASES.md — the binary isn’t at the archive’s top level:

tar -xf ratect-compat-x86_64-unknown-linux-gnu.tar.xz
mv ratect-compat-x86_64-unknown-linux-gnu/ratect-compat ~/.local/bin/

(substitute the archive name for your platform and binary; ~/.local/bin assumes it’s already on your PATH — use whatever directory you normally install user binaries into.)

macOS: Ratect’s binaries aren’t code-signed or notarized. If macOS refuses to run the extracted binary (“cannot be opened because the developer cannot be verified” or similar — some download methods, like a browser, mark a downloaded file quarantined; others, like curl, don’t), clear it:

xattr -d com.apple.quarantine ratect-compat-x86_64-apple-darwin/ratect-compat

Homebrew

Each release also publishes a formula to a shared tap (or1can/homebrew-tap) for both binaries:

brew install or1can/tap/ratect-compat
brew install or1can/tap/ratect

Install script

Each release also publishes a shell installer that downloads, verifies, and extracts the right archive for your platform in one step:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/or1can/ratect/releases/download/ratect-compat/vX.Y.Z/ratect-compat-installer.sh | sh

Substitute the tag (ratect-compat/vX.Y.Z or ratect/vX.Y.Z) for the release you want, and ratect-compat-installer.sh/ratect-installer.sh for the matching binary — see the Releases page for both. Installs to $CARGO_HOME/bin (or $HOME/.cargo/bin), adding that directory to PATH via your shell profile if it isn’t already there.

Verifying a download

Each release also includes a sha256.sum covering every archive and the source tarball, and every archive/SBOM/sha256.sum itself carries a GitHub Artifact Attestation confirming it was built by Ratect’s own CI from the tagged source, not tampered with in transit:

# Checksum (Linux: sha256sum -c sha256.sum). A trailing blank line in the
# file itself makes shasum warn "1 line is improperly formatted" — harmless,
# every real entry still verifies.
shasum -a 256 -c sha256.sum

# Provenance (requires the GitHub CLI, `gh`)
gh attestation verify ratect-compat-x86_64-unknown-linux-gnu.tar.xz --repo or1can/ratect

Not yet available

cargo-binstall needs Ratect published to crates.io to discover a release automatically, which is itself blocked — see decisions/0010’s crates.io deferral.

Building from source

The from-source path below is for contributors, or anyone on a platform without a prebuilt binary.

Prerequisites

  • Rust (stable toolchain)

  • Docker, running and reachable via the default local socket (Ratect connects the same way the docker CLI does — no extra configuration needed for a standard Docker install).

    Docker 20.10 or newer. Ratect negotiates the Docker Engine API version against your daemon at connection time, downgrading to whatever it offers, so any recent Docker install works with no extra configuration. 20.10 (December 2020) is Ratect’s own floor below that negotiation — the oldest release its features actually require, for the host-gateway sentinel behind proxy support — and a daemon older than that is refused with a clear error naming the API version it supports and the one required, rather than some later request failing for an unexplained reason. Check yours with docker version --format '{{.Server.APIVersion}}' (API 1.41 corresponds to Docker 20.10).

Build from source

Clone the repository, then build release binaries. The workspace has two binary crates, ratect and ratect-compat — Two binaries, two formats says which to pick. Building both costs little extra, since they share almost all of their code:

git clone https://github.com/or1can/ratect.git
cd ratect
cargo build --release -p ratect -p ratect-compat

The compiled binaries will be at target/release/ratect and target/release/ratect-compat.

Install the binaries onto your PATH

To make ratect and ratect-compat available as regular commands (one line per binary, so install only the one you want if that’s all you need):

cargo install --path ratect
cargo install --path ratect-compat

This installs to ~/.cargo/bin (assumed to already be on your PATH, which is the default for a standard rustup install).

Verify the install

ratect --version
ratect --help
ratect-compat --version
ratect-compat --help

Development builds

If you’re working on Ratect itself rather than just using it, a debug build is faster to compile and sufficient for local testing:

cargo build --workspace
cargo run -p ratect -- tasks list
cargo run -p ratect-compat -- --list-tasks

See AGENTS.md for the full contributor-facing tooling setup (formatting, linting, tests, coverage, dependency auditing).

Next steps

With a binary on your PATH, Getting Started walks through writing a first ratect.toml and running a task from it. If your project is in Rust, Go, Node.js, Python or the JVM, the worked example for it is a config you can copy instead.

Getting Started

This walks through defining and running your first task with Ratect. It assumes you’ve already installed Ratect and have Docker running.

Which binary? This page uses ratect and its ratect.toml format — the one to install if you’re new here (see Two binaries, two formats). If you already have a batect.yml, see Migrating a Batect Project to Ratect instead, since this page assumes you’re starting from nothing. Nothing below assumes a brand-new codebase either: writing a ratect.toml doesn’t touch any of your existing code, build scripts, or CI — it’s one new file describing how to run what you already have in a container, alongside whatever else the project does today.

Every file and transcript on this page comes from a real project checked into this repository, examples/getting-started — the page builds it up step by step, and a CI job runs every task in it against a real Docker daemon on every change, so what you read here is what actually runs. Clone that directory to follow along without typing anything.

1. Create a ratect.toml

ratect reads its configuration from a ratect.toml file in the current directory (or wherever you point -f/--config-file — see the CLI reference). The smallest file that runs something:

ratect_version = "0.13.0"
project_name = "getting-started"

[containers.build-env]
image = "alpine:3.24"
volumes = [{ local = ".", container = "/code" }]

[tasks.hello]
run = { container = "build-env", command = "ls /code" }

This defines one container (build-env, based on the alpine:3.24 image, with the current directory mounted at /code) and one task (hello, which runs ls /code inside that container). ratect_version records which Ratect the file was written for, so a later Ratect can tell you when one of its changes affects it — see ratect_version.

See the configuration reference for the full schema.

2. Run a task

ratect run hello

ratect run hello -o simple, captured on a terminal in examples/getting-started:

Running hello...
Pulling alpine:3.24...
Pulled alpine:3.24.
Running ls /code in build-env...
README.md    ratect.toml

Cleaning up...
hello finished with exit code 0 in 1.9s.

README.md and ratect.toml are ls /code’s actual output, streamed live as the container produces it — in columns, because the container was given a terminal, exactly as it would be in a shell. Everything else is Ratect’s own framing. A second run skips the pull, since the image is already local.

On a terminal, ratect defaults to its fancy output style, which draws the same milestones in place as they happen rather than one line at a time; the capture above asked for simple so it could be shown on a page. See Output Styles for the others.

3. Prerequisites

Tasks can depend on other tasks, which run first:

[tasks.build]
run = { container = "build-env", command = "echo building..." }

[tasks.test]
prerequisites = ["build"]
run = { container = "build-env", command = "echo testing..." }

Running ratect run test runs build to completion, then test. Within a single ratect run invocation:

  • Each task runs at most once, even if it’s a prerequisite of more than one other task.
  • Each container image is pulled at most once, even if multiple tasks use it.
  • A prerequisite cycle (e.g. a depends on b, b depends on a) is detected and reported as an error rather than hanging.

See Task ordering for the details.

4. Environment variables and expressions

A task’s run (and a container) can set environment variables, and a value can pull in a host environment variable or a declared config variable instead of being written as a literal:

[config_variables.environment_name]
default = "dev"

[tasks.greet.run]
container = "build-env"
command = "sh -c 'echo $GREETING in $ENVIRONMENT_NAME'"
environment = { GREETING = "hello-${WHO:-world}", ENVIRONMENT_NAME = "<environment_name" }

Running ratect run greet (with WHO unset in your shell) prints hello-world in dev. Override the config variable from the command line instead of relying on its default:

ratect run greet --config-var environment_name=staging

which prints hello-world in staging.

Note the sh -c: command is split into arguments with no shell involved, so $GREETING on its own would reach echo as literal text. Ratect’s own ${WHO:-world} and <environment_name expressions are a different thing — resolved by Ratect before the container starts, in environment values and a few other fields, never inside command. See the FAQ for the three $-syntaxes that look alike, the configuration reference for the full expression syntax (including batect.project_directory, always available without being declared), and the CLI reference for --config-var/--config-vars-file.

5. List available tasks

With four tasks in the file now, list them:

ratect tasks list
Tasks in getting-started:
- build
- greet
- hello
- test

A task’s optional description and group fields turn this flat list into a grouped one, with a line of help per task — see Worked Examples for what that looks like.

6. Reading the output

Ratect separates two kinds of output:

  • stdout: the actual output of your command — this is what your task produces, and what tasks list prints. Safe to pipe or redirect.
  • stderr: everything Ratect itself says — its progress (the lifecycle lines, shaped by --output), warnings and errors, and its internal diagnostics, logged via tracing. Only the diagnostics answer to the RUST_LOG environment variable, e.g.:
RUST_LOG=debug ratect run hello

debug also surfaces low-level Docker API activity (container create/start/remove), which is useful when troubleshooting — see Filtering RUST_LOG for scoping it to Ratect’s own diagnostics.

Next steps

See Worked Examples for a real build/test/run/lint/shell task set in Rust, Go, Node.js, Python, or the JVM — a faster starting point than building one up from scratch if your project is in one of those. Once you have a container running your own toolchain, Using Ratect With Language Ecosystems covers what to cache and a couple of correctness gotchas per ecosystem.

Worked Examples

A real, minimal hello-world project for five common ecosystems — Rust, Go, Node.js, Python, and the JVM — each with build, test, run, lint, and shell tasks using that ecosystem’s own usual tooling and base image. shell starts an interactive shell in the build environment — no config needed beyond the task itself, since interactive mode is automatic. It’s the fastest way to poke around when a build environment isn’t behaving as expected. The config below each intro is included directly from the actual project, checked into this repository under examples/ — what you read here is exactly what a CI job in this repository runs against a real Docker daemon on every change, so it can’t silently drift out of date. Clone the whole directory to run one yourself, or copy the config and adjust the commands to your own scripts.

Four of the five are ratect.toml; the same containers and tasks work identically as batect.yml with ratect-compat (see Two binaries, two formats) — the JVM example below is batect.yml itself, for reasons its own section explains. See the configuration reference for what each field does, and Getting Started if you haven’t run a task before.

Every command below that chains two steps with && wraps them in sh -c '...'. command is tokenized into literal argv, with no shell involved — an unwrapped && doesn’t fail loudly, it’s just handed to the first program as a literal extra argument, which several package managers silently ignore rather than reject. The FAQ walks through it, including the config-time $VAR syntax that looks the same and isn’t.

Try it

Cloning examples/rust and running ratect tasks list there prints:

Tasks in example-rust:

Checks:
- lint: Run clippy with warnings denied

Development:
- build: Compile the project
- run: Run the application
- test: Run the test suite

Utilities:
- shell: Start a shell in the build environment

ratect run followed by any task name (build, test, run, lint, or shell) then actually runs it — see Getting Started for what that output looks like against a real Docker daemon.

Rust

examples/rust. The official rust image doesn’t ship the clippy component by default, so lint adds it before running; the Cargo registry and the target build output are each cached separately, so only the first run is cold.

ratect_version = "0.13.0"
project_name = "example-rust"

[containers.build-env]
image = "rust:1.90"
working_directory = "/code"
volumes = [
    { local = ".", container = "/code" },
    { type = "cache", name = "cargo-registry", container = "/usr/local/cargo/registry" },
    { type = "cache", name = "cargo-target", container = "/code/target" },
]

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

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

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

[tasks.lint]
description = "Run clippy with warnings denied"
group = "Checks"
run = { container = "build-env", command = "sh -c 'rustup --quiet component add clippy && cargo clippy --all-targets -- -D warnings'" }

[tasks.shell]
description = "Start a shell in the build environment"
group = "Utilities"
run = { container = "build-env", command = "bash" }

Go

examples/go. lint uses go vet, part of the standard toolchain already in the build-env image — no second tool or container needed for a minimal project like this one.

ratect_version = "0.13.0"
project_name = "example-go"

[containers.build-env]
image = "golang:1.23"
working_directory = "/code"
volumes = [
    { local = ".", container = "/code" },
    { type = "cache", name = "go-mod", container = "/go/pkg/mod" },
    { type = "cache", name = "go-build", container = "/root/.cache/go-build" },
]

[tasks.build]
description = "Build the binary"
group = "Development"
run = { container = "build-env", command = "go build ./..." }

[tasks.test]
description = "Run the test suite"
group = "Development"
run = { container = "build-env", command = "go test ./..." }

[tasks.run]
description = "Run the application"
group = "Development"
run = { container = "build-env", command = "go run ." }

[tasks.lint]
description = "Run go vet"
group = "Checks"
run = { container = "build-env", command = "go vet ./..." }

[tasks.shell]
description = "Start a shell in the build environment"
group = "Utilities"
run = { container = "build-env", command = "bash" }

Node.js

examples/node. A TypeScript project with build/test/lint npm scripts (tsc, vitest, eslint). Each of build, test and lint runs npm ci itself, and run gets it through its build prerequisite, rather than relying on a separate install step — a task’s own container is recreated from scratch every run, so only what lands in the bind-mounted project directory or a cache mount survives to the next one. The npm cache mount is what keeps a repeated npm ci fast.

ratect_version = "0.13.0"
project_name = "example-node"

[containers.build-env]
image = "node:22"
working_directory = "/code"
volumes = [
    { local = ".", container = "/code" },
    { type = "cache", name = "npm-cache", container = "/root/.npm" },
]

[tasks.build]
description = "Compile TypeScript"
group = "Development"
run = { container = "build-env", command = "sh -c 'npm ci && npm run build'" }

[tasks.test]
description = "Run the test suite"
group = "Development"
run = { container = "build-env", command = "sh -c 'npm ci && npm test'" }

[tasks.run]
description = "Run the built application"
group = "Development"
prerequisites = ["build"]
run = { container = "build-env", command = "node dist/index.js" }

[tasks.lint]
description = "Run eslint"
group = "Checks"
run = { container = "build-env", command = "sh -c 'npm ci && npm run lint'" }

[tasks.shell]
description = "Start a shell in the build environment"
group = "Utilities"
run = { container = "build-env", command = "bash" }

Python

examples/python. A plain script rather than a packaged library, kept deliberately simple; build byte-compiles it as a minimal stand-in for a real build step (there isn’t a natural one for a script with no compiled artifact). Same reasoning as the Node example above for why test/lint each reinstall: the pip cache mount is what makes that cheap.

ratect_version = "0.13.0"
project_name = "example-python"

[containers.build-env]
image = "python:3.12"
working_directory = "/code"
volumes = [
    { local = ".", container = "/code" },
    { type = "cache", name = "pip-cache", container = "/root/.cache/pip" },
]

[tasks.build]
description = "Byte-compile the project"
group = "Development"
run = { container = "build-env", command = "python -m compileall ." }

[tasks.test]
description = "Run the test suite"
group = "Development"
run = { container = "build-env", command = "sh -c 'pip install -r requirements-dev.txt && pytest'" }

[tasks.run]
description = "Run the application"
group = "Development"
run = { container = "build-env", command = "python hello.py" }

[tasks.lint]
description = "Run ruff"
group = "Checks"
run = { container = "build-env", command = "sh -c 'pip install -r requirements-dev.txt && ruff check .'" }

[tasks.shell]
description = "Start a shell in the build environment"
group = "Utilities"
run = { container = "build-env", command = "bash" }

JVM (Gradle)

examples/jvm. Written as batect.yml rather than ratect.toml, deliberately: Batect itself is a Gradle/Kotlin project, and JVM/Gradle is where its own conventions and sample projects skew, so an existing Batect-using JVM shop is likely migrating a batect.yml that already looks close to this one — ratect-compat reads it unchanged. The task set relies on the project’s own checked-in Gradle wrapper (./gradlew), so the image itself needs nothing but a JDK; lint runs Checkstyle, the traditional choice, via its own Gradle task rather than a separate tool.

project_name: example-jvm

containers:
  build-env:
    image: eclipse-temurin:25-jdk
    working_directory: /code
    environment:
      GRADLE_OPTS: -Dorg.gradle.daemon=false
    volumes:
      - local: .
        container: /code
      - type: cache
        name: gradle-cache
        container: /root/.gradle

tasks:
  build:
    description: Compile and assemble
    group: Development
    run:
      container: build-env
      command: ./gradlew assemble

  test:
    description: Run the test suite
    group: Development
    run:
      container: build-env
      command: ./gradlew test

  run:
    description: Run the application
    group: Development
    run:
      container: build-env
      command: ./gradlew run

  lint:
    description: Run Checkstyle
    group: Checks
    run:
      container: build-env
      command: ./gradlew checkstyleMain checkstyleTest

  shell:
    description: Start a shell in the build environment
    group: Utilities
    run:
      container: build-env
      command: bash

Only batect.yml ships in examples/jvm/ — the same containers and tasks would re-spell directly into ratect.toml with no behavior change (run ratect config convert to generate one), see extends/list-entry shape for the syntax differences you’d see in the result.

Next steps

Every example above declares a cache volume or two. Using Ratect With Language Ecosystems says which directories each toolchain needs cached and why, plus the couple of correctness gotchas per ecosystem that aren’t a caching question at all.

Using Ratect With Language Ecosystems

Every toolchain below assumes its own persistence: a package manager expects its downloaded dependencies to still be there next time, a compiler expects its incremental build cache to survive between invocations. Ratect’s own container model doesn’t give you that for free — every task starts a fresh container, and anything written outside a mounted volume disappears with it. Without a cache volume pointed at the right directory, a toolchain that assumes persistence just re-downloads or recompiles everything, every single run, as if it were on a brand-new machine each time.

This page has one section per ecosystem, naming exactly which directories need to be a cache volume and why, plus the couple of correctness gotchas that aren’t a caching question at all. Every config referenced here is the real, CI-proven config under examples/ — see Worked Examples for the full files.

Rust

volumes = [
    { local = ".", container = "/code" },
    { type = "cache", name = "cargo-registry", container = "/usr/local/cargo/registry" },
    { type = "cache", name = "cargo-target", container = "/code/target" },
]

Two separate caches, for two separate things Cargo persists:

  • cargo-registry — the crate index and every downloaded/extracted dependency source. Without this, cargo build re-fetches your entire dependency tree from crates.io on every run.
  • cargo-target — compiled build artifacts (target/). Without this, every run is a cold, from-scratch compile — the difference between an incremental rebuild and a full one, which for a large dependency tree is minutes rather than seconds.

Go

volumes = [
    { local = ".", container = "/code" },
    { type = "cache", name = "go-mod", container = "/go/pkg/mod" },
    { type = "cache", name = "go-build", container = "/root/.cache/go-build" },
]

Same split as Rust, Go’s own equivalents:

  • go-mod (GOPATH’s module cache) — downloaded module sources. Without it, go build/go test re-fetches every dependency module fresh.
  • go-build (GOCACHE) — the compiler’s own build cache (compiled packages, keyed by input hash). Without it, every build recompiles the entire dependency graph rather than reusing what hasn’t changed.

A linter with its own cache (golangci-lint’s ~/.cache/golangci-lint/, for example) would need the same treatment if a project adopts one — examples/go doesn’t, so there’s nothing to demonstrate it against here, but the pattern is identical: mount whatever directory the tool itself says it caches into.

Node.js

volumes = [
    { local = ".", container = "/code" },
    { type = "cache", name = "npm-cache", container = "/root/.npm" },
]

npm-cache — npm’s own download cache, not node_modules itself. node_modules stays a plain, uncached part of the working directory (rebuilt by npm ci on each run, from what’s in the cache); what needs to persist is npm’s cache of already-downloaded package tarballs, so a repeat npm ci doesn’t re-download the same versions from the registry every time.

A long-lived Node process needs enable_init_process too — this isn’t a caching question, but Batect’s own nodejs.md covers it for the same reason it belongs here: Node doesn’t handle running as PID 1 correctly, so a container with no init process won’t forward SIGINT/Ctrl+C to it correctly. examples/node’s own run task doesn’t need this — it prints a message and exits, nothing to interrupt — but examples/full-stack’s app container is exactly the long-lived-server case, and sets enable_init_process = true for it.

Python

volumes = [
    { local = ".", container = "/code" },
    { type = "cache", name = "pip-cache", container = "/root/.cache/pip" },
]

pip-cache — pip’s own download/wheel-build cache. Without it, every pip install re-downloads and, for a package with no prebuilt wheel for the image’s platform, rebuilds it from source from scratch, every run.

JVM (Gradle)

environment:
  GRADLE_OPTS: -Dorg.gradle.daemon=false
volumes:
  - local: .
    container: /code
  - type: cache
    name: gradle-cache
    container: /root/.gradle

gradle-cache (~/.gradle) — Gradle’s dependency cache and its own build cache, in one directory. Without it, every run re-resolves and re-downloads the full dependency graph.

Disable the Gradle daemon. This one’s a correctness/performance gotcha rather than a caching question, and it points the opposite direction from everything above: Gradle’s daemon exists to stay warm across invocations, so it can skip reloading and recompiling the build script on the next run. That benefit depends on the daemon surviving between runs — which never happens in a Ratect container, disposable per task. Without -Dorg.gradle.daemon=false, every task pays the daemon’s own startup cost and then throws it away with the container, strictly worse than never starting one. examples/jvm sets this on build-env via GRADLE_OPTS.

If a Gradle build under Docker Desktop looks hung or dies without a message, the ceiling is usually Docker’s own, not Ratect’s — see the FAQ.

Not covered

Batect’s own per-ecosystem pages also cover .NET Core and Ruby — both caching-only concerns there, no correctness gotcha like Gradle’s or Node’s. Ratect has no example project for either ecosystem, so there’s nothing real to ground a section in here without inventing untested config; a real worked example for either is its own, larger undertaking than this page.

Next steps

From here, Task Lifecycle is the step-by-step account of what ratect run actually does — task ordering, per-task setup and cleanup — and Dependency Readiness is when a dependency counts as ready and how several dependencies’ waits combine; the FAQ collects the questions that come up first. When a second project wants the same containers and tasks, Includes covers pulling in a shared file or a Git bundle, and Reusable Pipeline Building Blocks why you’d want to.

Migrating a Batect Project to Ratect

This page is specifically for a project that already has a batect.yml — see Getting Started instead if you’re bringing Ratect into a project that doesn’t use Batect at all.

Most task runners assume a clean slate — convert everything, or don’t bother. Ratect doesn’t: ratect-compat reads an existing batect.yml unchanged, and a native ratect.toml project can include a batect.yml fragment as-is (see Two binaries, two formats). That makes migration a series of independent, optional steps rather than one all-or-nothing conversion — stop at whichever one matches how much of the tool you actually want.

Step 1: point ratect-compat at what you already have

The first step usually needs no config changes: run ratect-compat against the batect.yml you already have, in place of the (now unmaintained) batect binary itself. Same file, same flags, mostly the same behavior. Some checks Batect makes only when a task runs are made here when the file loads, so a latent mistake in a task you never ran can surface — see Load errors, and Differences from Batect for the other exceptions. This alone gets a maintained tool, and is a complete, permanent choice on its own if that’s all you want.

From here, two paths

Once ratect-compat is in place, there are two ways to move onto the native ratect.toml format. They aren’t sequential steps — pick one: ratect config convert only ever reads a Batect-format root file, so it has to run before the project’s root becomes ratect.toml (path A below), not after. Once the root is native, finishing off any remaining .yml includes is a by-hand job (path B). What actually changes between the two formats is tabulated in the ratect.toml reference — at a glance and where the semantics differ — and between the two binaries in the ratect CLI reference.

Path A: convert everything in one pass

ratect config convert reads a project’s actual root batect.yml — includes and all — and converts each file the project owns beside itself: the root to ratect.toml, every local included file to a .toml with the same name in its own directory, with each include entry rewritten to match, so every relative path keeps the directory it resolves against. A Git include stays a Git include. ratect config convert -f batect.yml, captured in examples/jvm — the one example kept as a batect.yml:

Converted batect.yml to ratect.toml.
Review it, then remove batect.yml.

The output is a starting point, not a finished file: config convert doesn’t carry comments over, though it does check each file round-trips losslessly before writing anything. The same configuration runs differently in a few respects under ratect: a task’s own container has no readiness gate (see Dependency Readiness), an enabled run_as_current_user becomes identity, the same goal with a mechanism that depends on the daemon, so its --user may go (see Coming from run_as_current_user), an expression in that home_directory or a string-form volumes entry’s host path is evaluated rather than used as written (see Where the semantics differ), and a Git include’s bundle may offer a ratect-bundle.toml or declare Git includes of its own (see the config convert section). config convert lists each task container whose health_check or setup_commands the first affects, each container the second does, each home_directory or volume the third does, and each Git include the fourth does, after converting and in each converted file’s own header; a health check from the image itself can’t be seen without the image. Review each file against Configuration Reference before deleting the originals — this is the fastest route to fully native, but still one diff worth reading closely, not a step to run and forget.

Path B: migrate incrementally

Try the native binary without converting anything

The native format isn’t all-or-nothing either. An include entry is parsed by its file extension (see Includes), so a ratect.toml project can pull in an entire existing batect.yml unconverted. The one adjustment needed: an included file must not declare project_name, since that’s root-only (see Includes) — move that one line out into the new root file instead.

# legacy.yml — the old batect.yml, minus its `project_name:` line
containers:
  build-env:
    image: alpine:3.18.2
    volumes:
      - .:/code
tasks:
  test:
    run:
      container: build-env
      command: echo "Hello from ratect!"
# ratect.toml
project_name = "my-project"
include = [
    { path = "legacy.yml" },
]

ratect tasks list -f ratect.toml and ratect run test -f ratect.toml now work through the native binary and a native entry point, with zero lines of the actual configuration translated — mostly the same behavior as before, with two differences worth knowing:

  • A task’s own container has no readiness gate. The native binary doesn’t wait on the health check of a container a task runs as its own run.container — whether from health_check or its image’s own HEALTHCHECK — and doesn’t run its setup_commands, wherever that container is declared: the binary running the project decides, not the file’s format (see Dependency Readiness). The same container used as a dependency is still gated.
  • Nested Git includes need a grant. A Git-included bundle that itself declares a nested type: git include is refused under the native format unless allow_nested_git_includes is set, where ratect-compat allows it unconditionally (see Where the semantics differ). It only bites if legacy.yml itself has a nested Git include of that shape.

Migrate one file at a time

From here, migration is as granular as you want it to be. Split legacy.yml into smaller files along whatever lines make sense (one per container group, one per pipeline stage — Batect’s own include already supports this), then convert each piece in turn: since config convert treats the file it’s pointed at as a root, and gives a root’s conversion a project_name (which an included file can’t declare), converting one piece means pointing it at a throwaway root — a batect.yml in a scratch directory, with an include entry naming the piece — which writes the piece’s own .toml beside it, and one beside each file the piece itself includes, their include entries pointing at each other (plus a ratect.toml beside the throwaway root, to delete with it). Swap that one include entry from .yml to .toml, and move on whenever you’re ready — there’s no deadline, and a project can stay a mix of both formats indefinitely.

What decides when a piece has to move is the feature you want. A container still declared in a .yml is a Batect container wherever it is included, so it can use no ratect-native field — see Which fields a file may use. Reaching for ulimits, extends or stop_signal on a container is therefore the signal to convert that container to TOML; nothing else in the project has to move with it.

Next steps

Wherever you stopped, Differences from Batect is what behaves differently from batect itself — the exceptions Step 1 pointed at, in full.

Differences from Batect

Ratect is a from-scratch Rust implementation inspired by Batect (which is itself no longer maintained — the upstream repository was archived in October 2023), not a wrapper or fork. It does not read Batect’s documentation or source at runtime. To move an existing project over, follow Migrating a Batect Project to Ratect; this page is what changes once you have.

Every Batect configuration field and CLI flag is supported, field-for-field and flag-for-flag, unless listed below — see config reference/ CLI reference for the full accepted schema and flags. This page lists the exceptions: a real behavioral divergence, an extension beyond what Batect does, or a restriction narrower than it. It doesn’t restate how a field or flag works — config reference/CLI reference/ task lifecycle are the authoritative source for that; this page only says what’s different and points there for the rest.

Unrecognized fields fail closed: Ratect’s YAML parsing rejects unknown keys — a typo’d field name, or (unlikely, since Batect’s own include types beyond file/git are the only thing left genuinely unsupported here) a real gap — fails config loading with an error naming it, rather than silently ignoring it. There’s no partial/best-effort mode.

Configuration format

Top-level fields

Every other top-level field is supported field-for-field — see config reference for the full list. The exceptions:

FieldNotes
config_variablesdescription: is recognized but inert — Ratect has no help/usage output to show one in.
includeRatect enforces that a Git include’s path (and anything it transitively includes) stays within that repository’s own clone, and that a bundle’s containers’ host paths (volumes, build_directory, build_secrets, build_ssh) stay inside its clone or your project directory unless your include entry sets allow_host_paths; Batect has no equivalent containment check for either. In ratect.toml specifically, a Git-included bundle also can’t declare further Git includes of its own unless allow_nested_git_includes is set — ratect-compat stays unrestricted, matching Batect. See What a bundle may do. A Git include’s clone is cached under ~/.ratect/incl, keyed by a SHA-256 of the remote and ref with each length-prefixed, with a TOML sidecar — not Batect’s ~/.batect/incl, keyed by a hash of git <remote> @<ref>, which two different remote/ref pairs can share. Neither tool reuses or sweeps the other’s clones. The sweep that removes a clone unused for 30 days counts them as 30 × 24 hours, where Batect counts 30 calendar days in your time zone, so across a daylight-saving change the two can disagree by up to an hour about whether a clone is due. It skips, with a warning, a sidecar it can’t read or parse, and goes on to the rest; Batect’s stops at the first such file, so while it’s there no clone is ever removed. See Git includes. Cloning a Git include is guarded by a lock file, as in Batect, but a lock whose holder has exited (killed during a first clone, say) is taken over by the next load that needs the include, where Batect’s waits 5 minutes and fails until the file is deleted by hand; a lock left by an older Ratect is still waited on. A load waiting on another process’s clone says so on stderr, where Batect’s waits in silence. Where the lock’s proof of exit doesn’t reach every process sharing the cache, such as a host and a container sharing ~/.ratect/incl, two loads can clone the same include at once; the second to finish uses the first’s clone. See decisions/0023 and decisions/0027. The Cloning <repo> <ref>... line, and the blank line after it, are printed only by a load that clones; Batect’s also come from a load that waited out another process’s clone and then skips its own. git’s own output is captured: a failed clone’s is part of the error (except, in ratect.toml, for a Git include a bundle declares, where it goes to RUST_LOG=debug — see Nested Git includes), where Batect prints git clone’s as it runs, its error saying only that git exited with a code, and puts only a failed git checkout’s in its error; and a successful clone’s warnings are dropped, where Batect shows git clone’s. A prompt for credentials still reaches the terminal. Wherever Ratect names an include’s repo, any credentials in its URL are shown as *** (https://***@host/repo.git), as is anything else between :// and the URL’s last @ (https://host/a@b is shown as https://***@b); Batect prints the URL whole. An include written as an object with no type loads as a file include; Batect requires type, and fails to load the file without it. The git checkout after the clone uses none of your Git configuration, nor the clone your init.templateDir, so core.autocrlf doesn’t change a clone’s line endings, no hook runs during the checkout, and a file stored in Git LFS stays a pointer file; Batect’s checkout uses your configuration. Batect’s also searches upward from the clone’s directory for a repository, so when the clone’s .git is missing it checks the ref out in whichever repository holds the cache, and both its commands use the variables naming a repository that git rev-parse --local-env-vars lists, which Ratect’s ignore, such as an exported GIT_WORK_TREE, which makes its clone fail, or the absolute GIT_INDEX_FILE a hook of git commit -a gets, under which it checks out no files.
forbid_telemetryRecognized, no effect — Ratect doesn’t collect telemetry, so there’s nothing to forbid.

Expressions

The syntax and which fields support it match Batect, field-for-field — see Expressions. The exceptions:

  • When a task’s values are evaluated. Both evaluate only what a task uses, once the run reaches it, after its prerequisites. Ratect evaluates every container in the task’s graph before starting any of them, where Batect evaluates each as it creates or builds it — so here a value that can’t be evaluated fails the task before its dependencies start, rather than after.
  • image — see Container fields below.
  • batect.project_directory has its . and .. components resolved: -f ../proj/batect.yml gives /parent/proj, where Batect gives /parent/cwd/../proj. Both name the same directory, and a volume path built from either is normalised the same way, so the difference only shows where the value is used as a string — in environment or build_args.

Container fields

Every other container field is supported field-for-field — see config reference for the full list. The exceptions:

FieldNotes
imageAn expression-looking value ($VAR) is rejected when the file loads rather than resolved or used as a literal — Batect resolves nothing here either, but silently treats it as a literal image name that then fails at pull time instead. ratect.toml does resolve them; see config reference.
volumesA cache mount’s name must use Docker’s own volume-name character set; Batect doesn’t validate it at all, so an unvalidated name could bind-mount an arbitrary host directory under --cache-type=directory. Breaking change for --cache-type=directory only — --cache-type=volume already enforced this via Docker itself. See Cache volumes. A newly generated .batect/caches/key holds a UUID rather than Batect’s six-character id, under a comment that doesn’t name Batect; each tool reads the other’s key file, so the volume names stay the same. A line of that file that starts with # after leading spaces is a comment, where Batect counts it as a key line: Batect refuses a file holding one beside the key, and takes one on its own as the key, where Ratect refuses the file as having no key line. A key path that is a symbolic link to nothing is refused, where Batect creates the key file wherever the link points.
portsA port written with a leading + (+80, '+80-+90', '+80:+80'), or unquoted as a YAML hexadecimal or octal integer (0x50, 0o120), is accepted as the port it denotes; Batect rejects each as a malformed port range. The same holds for a task’s run.ports.
dependenciesA name that isn’t a declared container is rejected when the file loads — and so is one in a task’s dependencies or run.container. Batect reports the same error in the same words, but only once a task that reaches the reference runs, so a stale reference in a container or task nothing runs never stops Batect and stops every ratect-compat command. A name given twice — here, in a task’s dependencies, or in a task’s prerequisites — is accepted, and that container starts, or that task runs, once; Batect rejects the duplicate when the file loads (The dependency 'X' is given more than once, and likewise for a prerequisite). ratect doctor and ratect config validate warn about it. See config reference.
capabilities_to_add / capabilities_to_dropAlso accepts BPF/CHECKPOINT_RESTORE/PERFMON — Docker capabilities added after Batect’s last release, so its own Capability enum predates them. A superset: every config Batect itself accepts here still parses identically.
health_check / setup_commandsA task’s own container’s readiness gate doesn’t fail the task once its main command has exited 0, whatever the failure — typically the container stopped before reporting a health status, before a setup command could exec into it, or while one was running and was killed with it; Batect’s does. A failure of that gate while the main command is still running fails the task as Batect’s does, but cancels the main command up to two seconds later, and is forgiven if the main command exits 0 within that time. That, and the race it leaves open, are in task lifecycle. Under ratect a task’s own container has no readiness gate at all — see Dependency Readiness.
dockerfileA Dockerfile that is a symbolic link, or is reached through a linked directory, is refused before the build, since Ratect’s build context doesn’t carry symbolic links and the daemon would report the Dockerfile missing. Batect builds one whose link stays inside the build directory.
log_driver / log_optionsAn absent value leaves the daemon’s own default alone; Batect’s config model bakes in a literal "json-file" default explicitly. Immaterial in practice — that’s Docker’s own out-of-the-box default too.
shm_sizeA size whose count times its unit doesn’t fit in a 64-bit number of bytes is an Invalid size error when the file loads, like any other malformed size. Batect’s multiplication overflows silently, and it sends Docker the meaningless size that results. Whitespace around a size string is ignored (' 128m '), as is whitespace that isn’t ASCII, and an unquoted YAML integer is read as the number it denotes, whatever its spelling (+5, 0x10, 0o17); Batect refuses each. Both accept whitespace between the count and its unit ('128 m') or after a bare count ('2 ').
run_as_current_userA .toml file refuses it, in favour of identity: the same goal, with a mechanism that depends on the daemon — see Coming from run_as_current_user. A .yml keeps it, and the rest of this row is about that. Host-side uid/gid lookup only works on Unix — see User mapping. A home_directory containing a : or a control character, or with no directory name to create (/, or a path ending in ..), is rejected when the file loads. Batect checks neither: it writes the first into the generated /etc/passwd as it is, where a : shifts the entry’s fields and a newline adds an entry of its own, and passes the second to Docker. A read-only cache mount (options: ro) isn’t given to the mapped user, since nothing can write to it anyway; Batect tries to change its owner like any other cache’s, which the read-only mount refuses, failing the run before the container starts. The generated /etc/passwd, /etc/shadow and /etc/group end their last line; Batect’s don’t, and musl libc (alpine’s) reads an unterminated last line one character short, so on a musl image the user’s shell reads as /bin/s and the group’s member a letter short.

Task fields

Every task field is supported field-for-field — see config reference for the full list. The exceptions are about when a mistake is caught: dependencies naming an undeclared container, and a name given twice in dependencies or prerequisites, are under dependencies in Container fields above, and a customise naming a container the task doesn’t start is under Load errors.

run fields

Every run field is supported field-for-field — see TaskRun for the full list. The exceptions are about when a mistake is caught: container naming an undeclared container is under dependencies in Container fields above, and a container also listed in the task’s dependencies is under Load errors.

Null values

A field given a YAML null (volumes: with nothing after it, ~ or null) mostly loads as if it were left out — a container’s volumes, ports, environment, health_check or run_as_current_user, a task’s prerequisites, dependencies or customise, and the top-level forbid_telemetry or config_variables, for example. Batect rejects a null on each of those. Where Batect accepts one — run’s command, entrypoint and working_directory, a config variable’s default and description, health_check’s retries — the two tools agree. Some nulls are rejected here too, such as an environment variable’s value and shm_size, in Ratect’s own words.

Load errors

Ratect checks a config when the file loads, and the report is its own:

  • Some checks Batect makes only once a task reaches them are made when the file loads here, for any command that loads it — --list-tasks included — and the first hard error stops it, so a config Batect lists, or runs a different task from, can fail to load here. Besides the undeclared names under dependencies in Container fields, they include a run_as_current_user home_directory that isn’t an absolute path, and a relative cache mount destination under run_as_current_user — Batect checks both as it configures the container, though its message for the cache path is never seen, since Docker has already refused the relative mount when the container was created; and a task’s customise naming a container its task doesn’t start, or its run.container also listed in its dependencies, checked for every task rather than only the ones run. --tag-image on a container that uses a pulled image isn’t checked at load, but fails as soon as that container’s image is resolved — after its dependencies have started and its prerequisite tasks have run, but before it runs — where Batect fails once the task using it has finished.
  • A negative health_check duration, such as -2s, is rejected when the file loads. Batect loads one, and the run fails only once Docker refuses it. A negative zero, such as -0s, is zero, and loads in both.
  • The wording is Ratect’s, not Batect’s — Configuration file "batect.yml" not found. rather than The file '<absolute path>' does not exist., and likewise for malformed volumes, ports, devices and includes, expressions, durations, duplicate build_ssh ids, an undeclared config variable given a value — which names the variable but neither which of --config-var and --config-vars-file gave it nor, for the file, its line — a name defined in more than one file, a file that contains no configuration, and an included file that sets forbid_telemetry to true. A file inside a Git include, or a container’s path inside one, is named by its path within the repository plus the remote and ref, '1.yml' from the bundle '<repo>' at '<ref>', where Batect writes <repo>@<ref>: 1.yml or 1.yml from <repo>@<ref>.
  • A check made once the file has parsed names what it’s about — the container or task — rather than giving Batect’s YAML path, line and column.
  • An error raised while the file is parsed gives its line, column and YAML path in Ratect’s own layout — deserialization error at line 8, column 23: containers.build-env.not_a_real_field: unknown field: not_a_real_field, under the Failed to parse config file "<path>" line of the cause chain below — where Batect prints <file> (at <path> on line L, column C): <message>. The wording is Ratect’s too: unknown field: X with no list of the known ones, missing field: X, and for a value of the wrong type the path and the mismatch, with no Value for 'X' is invalid: prefix — a refused null is invalid type: null, expected <what the field takes>, as in containers.app.shm_size: invalid type: null, expected a size like '128', ..., where Batect says Unexpected null or empty value for non-null field. A null where a mapping of fields is expected is read as an empty one, so it reports any field that mapping must have as missing. An unknown field’s column is its value’s, not its key’s, and so is that of a task, config variable or container name Batect refuses — though the message for one is Batect’s, verbatim. A key given twice in one mapping is tasks.t: duplicate key "t" at line 9, column 3, giving only the second occurrence’s line, where Batect’s Duplicate key 't'. It was previously given at line L, column C. also gives the first’s.
  • The full cause chain is printed: Error: <message>, then a Caused by: list when there is a cause, where Batect prints one message. A parse error’s own reason is in that list, under Failed to parse config file "<path>". The same holds for every fatal error, not only a config one.
  • With several problems, the one reported isn’t necessarily Batect’s first. Of several containers, tasks or customise entries failing the same check, the first the files declare is reported, as in Batect, but each check runs over every container before the next check starts, and over containers before tasks, so of two failing different checks the one reported can differ. Every config check runs before an --override-image container name is looked up, a duplicate build_ssh id is checked after a container’s image source, a volume’s fields are checked in a different order, and of several undeclared config variables given values, the first by name is reported, where Batect reports the file’s first, in file order, before any --config-var. A command, entrypoint or setup command that can’t be tokenized is reported after every error raised while the files are parsed, after every container’s image source, image expressions, dns entries and fields its file’s format doesn’t allow are checked, and after the same container’s volumes, build_directory and build_secrets, where Batect reports whichever the file gives first.

CLI flags

Every other flag from Batect’s own CLI reference is supported flag-for-flag — see CLI reference for the full list. The exceptions:

FlagNotes
--versionPrints one line, ratect-compat <version>, rather than Batect’s seven labelled lines (its version, build date and commit, and the JVM, OS, Docker and Git versions) and the help blurb after them. Also gets a -V short form Batect doesn’t have (a clap default). Acts as soon as it’s reached: whatever follows it on the command line is never parsed or checked, and no check across options is made, so --version --bogus and --tag-image app=t --override-image app=i --version exit 0, where Batect checks every option first and rejects them. Given with --help, whichever of the two comes first wins; Batect always shows the help.
--help / -hThe layout and text are clap’s rather than Batect’s, including <CONFIG_FILE>-style value placeholders and [default: …] for a fixed default. A description never shows an environment variable’s current value or whether batect.local.yml exists — Batect’s say, for example, whether DOCKER_HOST is currently set, and to what. Like --version, acts as soon as it’s reached, without checking what follows it, so --version --help prints the version, where Batect shows the help. Exits 0, as help conventionally does; Batect’s HelpCommand returns 1. See Options and decisions/0016.
--list-tasks / -TThe listing opens with Tasks in <project>:, followed, when any task has a group, by a blank line before the first group heading. Batect’s opens a flat list with Available tasks:, and a grouped one with its first group heading. The -o quiet listing, the one meant for scripts, has no header in either.
--config-var--config-var NAME= sets the variable to an empty value, which Batect rejects as having no value. A value containing = is split at its first =, so --config-var a=b=c sets a to b=c; Batect splits at the last, setting a=b to c. --override-image and --tag-image also split at the first =.
--tag-imageA TAG Docker would refuse is rejected while the arguments are parsed, as a usage error, on every command, --list-tasks included. Batect rejects it only when that image’s build step starts, after the task’s prerequisites have run. The check is the one docker tag makes, with its reasons, so a digest (app@sha256:…) is refused too; Batect accepts one, and the daemon then refuses the build. Batect’s parser is an older copy of the same grammar: it rejects a name whose first component has uppercase in it (MyOrg/app), which the current one takes as a registry host, and an IPv6 registry host, and it counts the 255-character limit over the whole name rather than the repository path; its uppercase message also doesn’t name the repository. See decisions/0018.
TASK_NAME (positional)A misspelled task name’s Did you mean suggestions include every task tied on edit distance; Batect keeps only one name per distance. An unknown task’s error reads Task 'X' not found., where Batect’s reads The task 'X' does not exist., and its closing hint names ratect-compat --list-tasks and ratect-compat --help rather than ./batect’s. No task name at all is a command-line error, as in Batect, reported like any other (see below): exit 125, where Batect exits 255. See Exit codes and error reporting.
-- ADDITIONAL_ARGSWhen neither the task’s run nor its container sets a command, the arguments replace the image’s default CMD, as docker run <image> <args> does; Batect refuses them with an error. Every invocation Batect accepts runs the same here. See Using ADDITIONAL_ARGS in a task command.
--output / -oAn explicit -o fancy fails up front with a clear error when stdout isn’t a terminal, and so does one on a terminal with TERM=dumb; TERM unset is accepted, as in Batect. Batect accepts both refused cases: when stdout isn’t a terminal it crashes with an unhandled exception on the first repaint, and on a terminal with TERM=dumb it writes cursor movements that terminal can’t perform, garbling the display. all’s status lines also drop Batect’s inner Batect | prefix — the outer prefix already says whose line it is. all’s | separator is unstyled, where Batect bolds and colours it with the name before it: emphasis is for names, never punctuation (decisions/0017). fancy clips a line to the terminal’s width in display columns, so a wide character counts as two; Batect counts UTF-16 units, so a line holding wide characters is clipped earlier here. Choosing a style automatically doesn’t special-case TRAVIS=true, as Batect does by picking simple; that only matters on Travis CI with a real terminal, since a CI runner without one gets simple anyway. See Output Styles.
--no-colorA superset, not a gap: Batect rejects -o fancy --no-color at parse time (its console couples color and cursor movement under one flag); Ratect’s keeps them independent, so that combination renders colorless fancy instead. Ratect also honours two environment variables Batect ignores: NO_COLOR has --no-color’s full effect, including making simple the auto-selected style, and CLICOLOR_FORCE colours output to a non-terminal. See Colour.
--no-cleanup, --no-cleanup-after-failure, --no-cleanup-after-successBatect’s own DontCleanup still stops a started container, just skips removing it; Ratect leaves it genuinely running (not just present-but-stopped) for investigation. With cleanup after success disabled, a task whose own container runs to completion exits with that container’s exit code; Batect exits 255 whatever the code was, 0 included, so a script checking the exit status can’t tell a pass from a fail.
--docker-cert-path, --docker-tls, --docker-tls-verify, --docker-tls-ca-cert, --docker-tls-cert, --docker-tls-keyBatect’s bare --docker-tls (without -verify) disables all server certificate verification, not just hostname matching. Ratect doesn’t support that mode at all — --docker-tls and --docker-tls-verify behave identically here, the daemon’s certificate always fully verified. See TLS with a private certificate authority for the supported alternative (your own CA). A superset in one respect: Batect requires all of ca.pem, cert.pem and key.pem, and Ratect none of them — without a CA the system trust store is used, and without a cert.pem/key.pem pair no client certificate is presented. A CA that is given is the only one trusted. See TLS through the options.
--docker-tls-ca-cert, --docker-tls-cert, --docker-tls-keyA file that exists but isn’t a regular file is accepted — a pipe, such as <(…), to keep a key off disk, is read like a file, once. Batect refuses one as refers to something other than a file. A missing file or a directory is refused before any command runs, as in Batect. See TLS through the options.
--docker-contextA context’s SkipTLSVerify is not honoured: the daemon’s certificate is always fully verified, as with --docker-tls. Batect honours it, skipping verification. See Which daemon is used.
--docker-hostAn https:// host connects over TLS, as if --docker-tls-verify were given — from the flag, DOCKER_HOST, or a Docker context. Batect (and the Docker CLI) connect to such a host without TLS unless the TLS options or the context’s stored files ask for it. See Options.
--docker-hostA host whose scheme isn’t unix://, tcp://, http:// or https:// — from the flag, DOCKER_HOST, or a Docker context — is refused on connecting, in Ratect’s own words: from the flag or DOCKER_HOST, Failed to connect to Docker host '<host>', caused by URI scheme is not supported: <host>. That includes ssh://, which Batect’s Docker client accepts. Where Batect refuses a host, as it does npipe:// off Windows, its message is protocol not available.
--docker-context, --docker-configA Docker CLI config.json that can’t be read or isn’t valid JSON, when the active context would be read from it, is a warning naming the file, and the default context is used, as the current Docker CLI does. Batect fails, as the Docker CLI it was built against did. See Which daemon is used.
--docker-host, --docker-contextAn empty DOCKER_HOST or DOCKER_CONTEXT counts as unset, as in the Docker CLI. Batect takes an empty value as set: an empty DOCKER_HOST still rules out every context and becomes the host, and an empty DOCKER_CONTEXT names a context called "". See Which daemon is used.
--docker-tls-verify, --enable-buildkitAn empty DOCKER_TLS_VERIFY or DOCKER_BUILDKIT counts as unset, as in the Docker CLI: no TLS, and the daemon’s own builder. Batect rejects an empty value as not a boolean. Both are also read in any case, so True and Yes are accepted; Batect takes only the all-lower and all-upper spellings. An invalid DOCKER_TLS_VERIFY is rejected only when connecting to a host without --docker-tls/--docker-tls-verify, so --list-tasks and a connection through a context never read it; Batect rejects it on every command. See Environment variables.
--docker-config, --docker-cert-pathA directory given by the flag, DOCKER_CONFIG or DOCKER_CERT_PATH that doesn’t exist or isn’t a directory is refused before any command runs, as in Batect, but in Ratect’s own words, naming the flag or variable, the path and what is wrong with it. ratect doctor reports one as a problem and carries on with its other checks. See Options.
--enable-buildkitAn invalid DOCKER_BUILDKIT (the flag’s default) is rejected the first time a run builds an image — every run of a task with a build_directory container, since Ratect always builds and leaves Docker’s layer cache to skip unchanged work — rather than on every command. A task that only pulls images, --list-tasks and --clean never read it. Batect, like the Docker CLI, rejects an invalid value on every command. A daemon whose Builder-Version ping header is none of empty, 1 and 2 is reported at the same point, and not at all when DOCKER_BUILDKIT or the flag chooses the builder; Batect fails every run that connects to it, with an unhandled exception.
--cache-typeUnlike Batect, not forced to directory for Windows containers — Ratect has no Windows support to special-case. A BATECT_CACHE_TYPE that is no cache type is refused, as in Batect, in Ratect’s own words, naming the variable, its value and the two cache types.
--clean, --clean-cacheUnder --cache-type=directory, the Docker daemon is never contacted, so cleaning works while it’s unreachable; Batect checks it can reach the daemon first, under either cache type, and fails without it. A project with no .batect/caches directory has nothing to remove, and Ratect warns that the directory isn’t there, where Batect fails with exit code 255. An entry there that is a symbolic link is skipped rather than followed, with a warning naming it: Batect follows it and deletes the contents of whatever it points to, even outside the project.
--max-parallelismBatect’s flag caps every setup/cleanup step, via a step-scheduling model Ratect doesn’t have, but one: a container’s run — its start, then the wait for it to exit — never counts, for any container, dependencies included, since it lasts the container’s whole lifetime; every container’s create counts. Ratect’s caps image pulls/builds, every container’s create (the task’s own included), a dependency’s start, and setup commands. So a dependency’s start is capped where Batect’s isn’t: under a low cap, dependencies start one at a time where Batect starts them together — timing only, the run’s outcome is the same. The task’s own container’s start and run are never gated, as in Batect. Health-check waits and cleanup teardown, which Batect’s cap covers, are deliberately excluded (teardown is concurrent, gated only by dependency order).
--log-fileBatect’s own default (no --log-file) is a silent NullLogSink, nothing anywhere; Ratect always logs to stderr regardless, so --log-file here tees into a file in addition to stderr, not instead of it. The file is plain text, each record starting on a new line — one carrying a multi-line error, such as why the run failed, continues over the lines after it — where Batect writes one JSON object per message, and logs Ratect’s own records at debug and other crates’ at info unless RUST_LOG says otherwise, where Batect logs every message. The records are Ratect’s own rather than Batect’s, ending, at that default, with why the run failed when it did: the Git include cache sweep, for example, logs only what goes wrong, in its own words, and none of Batect’s No repositories ready for clean up., Deleting repository as it has not been used in over 30 days. or Repository deletion completed. records.
--generate-completion-script, --generate-completion-task-infoNot accepted — an unrecognized-argument error. Batect’s are hidden flags for its own shell completion, which reaches them only through Batect’s wrapper script. ratect-compat has no shell completion; the native binary prints its own script with ratect completions <shell>.
--no-update-notification, --upgrade, --no-wrapper-cache-cleanupRecognized, no effect — permanently inapplicable, since Ratect is a single native binary with no self-updating wrapper script to disable notifications for, clean caches for, or upgrade. Recognized rather than rejected so an existing Batect invocation carrying one doesn’t hard-fail outright. Hidden from --help, where Batect lists all three — --upgrade under its help options, the other two under its execution options. See CLI reference.

Beyond any one flag:

  • A mistake on the command line is reported in clap’s format: an error: … line in its own words, sometimes followed by a tip or a usage line, then For more information, try '--help'. Batect prints a single message of its own instead, such as Invalid option '--bogus'. Run './batect --help' for a list of valid options. The exit code is 125 on a line meant to run a task, docker run’s code for its own failure, and 2 on one that replaces the task with --list-tasks, --clean, --clean-cache or --upgrade, the usage-error convention clap and the POSIX utilities share. So is an option value that fails its own check, such as a -f or --config-vars-file naming no file, a batect.local.yml that isn’t a file, or a BATECT_CACHE_TYPE that is no cache type. Batect’s is -1 (255) for both, the same as for any other failure (decisions/0016).
  • --help and --version exit 0 even when an option’s value or default is invalid — a --docker-config naming no directory, a batect.local.yml that isn’t a file, or a bad BATECT_CACHE_TYPE, say: they act before any value they don’t need is checked. Batect checks its options and their defaults first, so an invalid one makes --help exit -1 (255) instead (decisions/0016).
  • Short options combine, and take an attached value: -Tf batect.yml, -fbatect.yml and -oquiet are accepted. Batect looks an option up by its exact text up to any =, and rejects each of those as an invalid option.
  • An option’s value can’t start with - when it’s given as the next argument: --use-network -x and --clean-cache --list-tasks are usage errors, whose tip is the = form (--use-network=-x), which is accepted. Batect takes the next argument as the value whatever it starts with, so a forgotten value silently swallows the flag after it, while no Docker network, volume or context name and no Batect task name can start with -, and a path that does can be written ./-x.

Runtime behavior gaps

Batect behavior not implemented in task execution, beyond what’s covered by the field tables above:

  • The home directory is $HOME first, when it is set and absolute, then the passwd entry’s, as in the Docker CLI. Batect uses the JVM’s user.home, which is the passwd entry’s whenever there is one, so where it and $HOME differ Batect reads a different ~/.docker from the one docker login wrote, and the credentials and contexts there go missing. It also expands ~ in a path to that directory, where a shell would use $HOME. With no passwd entry, user.home depends on the JDK: $HOME on Java 21, ? on Java 11. Not copied, as a Batect bug, under 0013’s rule 3.

  • Cleanup on a termination signal (Ctrl+C, SIGTERM, SIGHUP): four deliberate differences from Batect, which traps SIGINT only:

    • Ratect also traps SIGTERM and SIGHUP, down the same cleanup path — a task runner is stopped by more than a keystroke (an editor closing its subprocess, docker stop, systemd, most CI cancel buttons), and under Batect each leaks a container and network.
    • The exit code names the signal: 128 + the signal’s own number (130/143/129 for Ctrl+C/SIGTERM/SIGHUP). Batect returns -1/255 for an interrupted run, as for any failure other than the task’s own command exiting non-zero.
    • A further signal during cleanup hurries it, then Ctrl+C stops it: a second signal of any kind switches whatever is left to forced removal (kill and remove, no grace period), and a SIGINT after that abandons cleanup. Batect instead lets cleanup finish and then prints manual cleanup commands. Only SIGINT abandons because a keyboard is the one thing that sends it twice — a supervisor’s timed follow-up is a SIGTERM, which only ever means “exit” — so a supervisor that escalates SIGINT → SIGTERM → SIGKILL on a timer usually gets a finished cleanup before the SIGKILL, though a slow daemon can still lose that race. A run that had already finished when the signal arrived keeps its own exit code, since the signal ended nothing — unless the cleanup is then abandoned with something still to remove, which turns a 0 into 125 (decisions/0016). Batect fails such a run with -1 (255) whatever its code was. Whatever an abandoned cleanup leaves still carries Ratect’s ownership labels, so ratect resources list/clean finds it (ratect-only; ratect-compat has no equivalent verb, so from it the sweep is docker itself, filtering the same labels).
    • The notice names the signal and the next step: a line on stderr such as Interrupted; cleaning up. Press Ctrl+C again to force-remove what's left, and Ctrl+C after that to stop cleaning up., printed in every style whatever RUST_LOG says. Once cleanup ends, Cleanup complete. follows, and no Error: Interrupted — the exit code says the run was signalled, and a cleanup that left something behind is reported, in place of Cleanup complete., as the error it is, naming what was left and the docker command that removes it. Batect prints Task cancelled: Interrupt received during execution. and that it is waiting for outstanding operations, then its manual-cleanup commands.

    SIGKILL remains untrappable by either tool, same underlying OS limitation — the same labels are what a post-hoc ratect resources clean needs to find what it left.

  • A closed stdout cleans up: a run whose stdout reader goes away (| head -n 1) stops its containers, removes them and the task network, and exits 141, with a notice on stderr saying why. Batect’s container output is written by its Go wrapper straight to its stdout, and Go’s runtime ends a process whose write to stdout meets a closed pipe by SIGPIPE — from reading its source rather than running it, the same 141, with nothing cleaned up. Ratect matches the code and declines the leak (decisions/0013 rule 3).

  • A run that fails without its task’s command exiting exits 125: a config that doesn’t load, an unknown task, an unreachable daemon, a failed image pull or build, a dependency that never becomes ready, a setup command that fails. 125 is docker run’s own code for its own failure. Batect returns -1 (255) for all of these, as for every failure other than the task’s own command exiting non-zero. Every other command — --list-tasks, --clean, --clean-cache — exits 1 on failure, or 2 for a usage error or an invalid option value; Batect’s is -1 there too. See Exit codes and error reporting and decisions/0016.

  • A cleanup that fails after a passing run exits 125; after a failing one, the task’s own code stands: the daemon refusing to remove a container or the task network fails a run whose containers all exited 0, and leaves a run that already failed with its own code. Batect fails both with -1 (255), so the task’s own code is lost whenever its cleanup fails. See decisions/0016.

  • Ownership labels: every container and network Ratect creates carries eu.orican.ratect.* labels; Batect labels nothing of its own. An additive divergence — changes no behavior. See decisions/0002.

  • Task run locks: every task run holds a lock file, ~/.ratect/runs/<run>.lock, for as long as its process drives it, so that ratect resources can tell a leftover from a task run still going; Batect writes nothing per run. A task run that cleans up fully deletes its file. A run with no home directory, or one it can’t write, takes none and runs as before. See resources options and decisions/0025.

  • Interactive mode: two known divergences. Batect’s real-TTY gate checks only whether its output is a real terminal; Ratect’s requires both stdin and stdout to be real terminals. Live terminal-resize tracking is also Unix-only — synced once at session start elsewhere, not tracked further. See Interactive Mode.

  • Proxy support: three deliberate differences — see Proxies for the full mechanics.

    • A localhost proxy is rewritten on Linux too. Batect rewrites on macOS/Windows only; on Linux it propagates the URL verbatim, where localhost means the container itself. This is Batect’s oldest open issue, eight years old.
    • A proxy bound to loopback only is diagnosed, not left to fail — Batect’s own roadmap notes the same warning is needed and never shipped one.
    • --no-proxy-vars keeps the proxies in Docker’s config.json out of a build too. Batect’s flag only stops its own proxy build arguments; its Docker client adds the config.json ones to every build regardless.

    Batect’s Docker-version-gated hostname fallback chain, which reaches back to Docker 17.06, isn’t ported: its first choice, host.docker.internal, is the one for Docker 18.03 and later, so every Docker release Ratect connects to would get it (see the Docker 20.10 entry under Runtime behavior gaps).

  • Private registry credentials: on a pull or a classic build, Batect’s own Go client swallows a credential-helper error (under BuildKit, BuildKit’s own auth provider passes it back to the daemon instead); Ratect warns, naming the registry that failed to resolve, or, for a build, the credsStore whose helper couldn’t list what it holds. See Private registry credentials.

  • A dependency exiting unexpectedly is reported, not silent. Batect has no equivalent: a dependency that dies after becoming ready — while the task’s own command, or a later dependency’s own health/setup wait, is still going — is otherwise invisible until whatever depended on it fails for a confusing, unrelated-looking reason (a connection refused, a timeout). Ratect prints a progress line naming the container and its exit code instead, in every output style except quiet. See Dependency Readiness.

  • A control character from your configuration is printed escaped. In a name or value from your configuration (a task, container, image or cache name, a path, a command, a Git include’s repo or ref), in image build output, and in a value an error message quotes, ESC prints as \u{1b} and a carriage return as \r, so neither a config file nor a Git bundle can send your terminal escape sequences. Batect prints them as they are. A container’s own output is printed as written. Which line breaks and tabs are escaped as well is in Output Styles.

  • all mode splits on a lone carriage return too, not just \n. Batect’s InterleavedContainerOutputSink splits on \n only, so a container using \r to redraw progress in place (pip/curl/apt-style) produces no output at all until its next \n, then dumps everything since as one giant concatenated line — or produces none at all, if the stream ends first. A deliberate divergence: Ratect also ends a line at a lone \r (one not immediately followed by \n — a CRLF pair still folds to a single line break), so a real progress bar prints one interleaved line per redraw tick instead of staying silent — spammier, but never silent-then-dumped. The split never adds an empty line: a \r with nothing before it since the last line ended — a line’s first byte, or one of a run of them — ends no line, and an empty line is printed only if no \r has ended a line since the previous \n. So 10%\r\r20% prints 10% and 20%, and Ratect prints as many empty lines as Batect. A setup command’s output and an image build’s Image build | lines follow the same rule; a failed classic build’s Build output: keeps each \r as Docker sent it.

  • all mode prints a container’s last line even without a trailing newline. Batect prints a line only once its \n arrives, so a container whose output ends without one loses that last line. Image build output follows the same rule.

  • BuildKit build output leaves out plain-progress’s clock. Like Batect, Ratect shows a BuildKit build in BuildKit’s plain-progress form: a #N <step> header as each step starts, steps that start together in docker-client’s order, #N CACHED and #N ERROR: …, and every line of a step’s output labelled with its #N. It leaves out elapsed times (#4 0.412 …), DONE <duration> lines and status lines (transferring context: …), so a build prints the same lines from run to run. A failed BuildKit build’s Build output: is the same labelled lines, so in it, unlike a classic build’s, a lone \r ends a line.

  • Failure messages are Ratect’s own. A task fails at the same step as under Batect — an image that won’t pull or build, a task network that can’t be created, a container that can’t be created, set up for run_as_current_user, or started, a dependency that doesn’t become healthy, a failing setup command, a dependency cycle — but Batect’s headline and wording aren’t reproduced: Failed to pull image X and its Caused by: list, for example, rather than Could not pull image X. and the daemon’s message — which, where the daemon refused a request, follows Docker responded with status code N: rather than Error response from daemon: — a failed build’s output under Build output: rather than Output from Docker was:, and Failed to start container 'X' rather than Could not run container X.. A run_as_current_user or network failure is reported as itself, not, as Batect frames it, as a failure to create the container; either way the container is named as configured. See Load errors for the cause chain. The message is an unprefixed Error: … line on stderr in every output style, all included, where Batect’s all prints <task> ! or <container> ! lines on stdout; and all reports a failed setup command or network check, two failures Batect’s all doesn’t print at all. A setup command’s output is trimmed, so output that is only whitespace counts as none.

  • A failed task ends with a summary line, not Batect’s footer. Where Batect ends a task that failed to run with a red The task X failed. See above for details. (on stderr, or on stdout as a <task> ! line under all), Ratect ends it with <task> failed after <duration>., the counterpart of finished with exit code N, in the same place: the progress console, on the task’s prefix under all, and not at all under quiet. Nor does Ratect print Batect’s blank line before the error: the bold red Error: marker separates it, and under quiet a leading newline would be the first byte on stderr.

  • No white text. Batect paints its simple status lines, all’s task-level prefix, all’s inner Setup command N | and Image build | labels, and every line fancy draws (the startup block, the cleanup line, Running <task>... and the summary), in the terminal palette’s white (SGR 37) — light grey on a dark theme, near-invisible on a light one. Ratect’s own lines are the terminal’s default foreground, with bold for emphasis, and it never sets the palette’s white or black (decisions/0017). The interrupt notice, the --no-cleanup* reminder and a cleanup that left something behind are printed on stderr in every style rather than logged; Batect prints its equivalents on stderr too, except under all, which prints them on stdout with the task’s prefix, and quiet, which prints the interrupt notice and a failed cleanup’s error but no cleanup instructions.

  • Cleanup says what it follows, and all reports every step. After a failure, simple and all open cleanup by naming it — Cleaning up after <task> exited with code <N>..., or the step and container that failed, such as Cleaning up after db did not become healthy... — rather than Batect’s Cleaning up.... Under all, each container the run started says Container stopped. and then Container removed. on its own prefix, and the task’s prefix says Removing task network... and Task network removed.; Batect’s all prints each container’s Container stopped. only (decisions/0017).

  • all‘s prefix colours. Container prefixes cycle five colours — cyan, yellow, green, magenta, blue — assigned by the containers’ sorted names, so a container keeps its colour whatever order its task’s graph lists it in, and the task’s own prefix is bold in the default foreground. Batect cycles six starting at black, assigns them in its dependency graph’s order, and paints the task prefix white (decisions/0017).

  • An unhealthy dependency’s error can lack the last health check’s details. If the container, or the daemon, goes away between Docker’s unhealthy verdict and Ratect looking up that check’s exit code and output, the error gives the verdict alone. Batect reports the failed lookup instead, or crashes.

  • A startup failure drops the rest of startup at once. When one of a task’s containers can’t be started — its image won’t pull or build, or it doesn’t become ready — whatever else was starting alongside it is dropped there and then, and cleanup begins. Batect cancels that work and waits for it to wind down first. A container whose create the daemon already had is still removed: cleanup waits for that create’s answer before it removes anything, as Batect waits for its creates to finish. A further signal ends that wait as it would a graceful stop — everything else is force-removed — and a warning names the container and the run label that finds it.

  • Docker 20.10 or newer is required. Ratect refuses a daemon whose API is older than 1.41 (Docker 20.10) when it connects — before any task runs, whether or not BuildKit is asked for — because its proxy support needs 20.10’s host-gateway address (see Installation). Batect’s floor is API 1.37 (Docker 18.03), so Docker 18.03 to 19.03 runs under Batect and is refused by Ratect. Below API 1.37 both refuse, in different words: Ratect’s error names the API version the daemon supports and the 1.41 it requires; Batect’s, in red, names the daemon’s Docker version. The exit code is any failure’s (see Exit codes and error reporting) — 125 on a run — where Batect’s is -1 (255). Batect’s refusals of BuildKit on a daemon too old for it, or without experimental features turned on, apply only below Docker 18.09, so none could fire on a daemon Ratect accepts, and they aren’t ported.

  • A task network name collision on Docker 20.10 to 24 fails later, and leaves the second run’s network behind. Batect sets the network create request’s CheckDuplicate option, which has the daemon refuse a second network with the same name. Ratect’s Docker client has no such option: API 1.44 deprecated it, since Docker 25’s daemon refuses a duplicate name without being asked. So on an older daemon a run that draws another run’s suffix creates a second network of that name, then fails at container creation or start rather than at network creation. Its network stays, and docker network rm <name> refuses to remove either. Docker 25 and later refuse the duplicate network under Batect and Ratect alike. See Cross-task isolation.

  • The daemon is first asked for its version, not pinged. Ratect’s first request is /version; Batect sends /_ping and then asks for the version, before running anything. The image builder — BuildKit or the classic one — is chosen only once a run first builds an image, from a /_ping made then (see --enable-buildkit under CLI flags). And a daemon that can’t be reached, or is too old, is reported in Ratect’s own words, not Batect’s Docker is not installed, not running or not compatible with Batect: … — for an unreachable one, naming the host tried (see What is checked on connecting).

  • A daemon running Windows containers is refused. Ratect checks the operating system the daemon reports and refuses windows before running anything, since it only supports Linux containers. Batect accepts a Windows daemon, and refuses only one reporting neither Linux nor Windows, which Ratect doesn’t check.

  • The task network is ready before any image work starts. Ratect creates it — or, under --use-network, checks that it exists — and only then pulls or builds an image, where Batect does both at once. So a network problem, such as a missing --use-network network or an exhausted address pool, fails the task straight away, rather than once the pulls and builds already in flight have finished.

  • Cleanup carries on past a container it fails to stop or remove. A container whose stop fails isn’t removed, as under Batect, but cleanup still stops and removes the task’s other containers, including the ones it depends on; Batect’s cleanup stalls there and leaves them running. Ratect also still goes on to remove the task network, where Batect keeps it and lists it among the manual cleanup commands it prints. While that container is still attached to the network, Docker refuses, and that refusal is reported in the same Cleanup failed: error as the container’s, which lists both as left behind.

  • A container or network already gone at cleanup isn’t a failure. When something else has already removed one — a dependency docker rm -f’d mid-run, say — Docker answers cleanup’s stop or removal with 404, and Ratect counts it as removed, since nothing is left behind: a passing run still exits 0, and ratect resources clean counts one that disappears mid-sweep as removed. Batect fails the task’s cleanup on any error from that stop or removal, 404 included.

  • A task with only prerequisites says so in every style but quiet. Once its prerequisites have run, The task <name> only defines prerequisite tasks, nothing more to do. is printed as under Batect, but not under -o quiet, which prints only errors, warnings and notices; Batect prints it in every style.

  • What cleanup leaves is reported in one line, in every style. A --no-cleanup* run reports Left in place (--no-cleanup): …, and a cleanup that failed Error: Cleanup failed: …; left behind: …, each naming the containers by config name and short id and ending Remove with: one docker rm -f -v for every container, then docker network rm for the network. After a --no-cleanup* run, a line per kept container gives Batect’s docker logs and docker exec -it hints, with docker start first for one that isn’t running. Where they differ from Batect’s:

    • They are printed under -o quiet too; Batect’s quiet prints none of them.
    • After a failed cleanup only what was actually left behind is listed; Batect lists a command for every container and network the run created, removed or not, and says “some or all” of them may be needed.
    • Containers are named by the twelve-character id docker ps shows, and the network by its name; Batect gives each container’s full id and the network’s id, one docker rm --force --volumes per container.
    • Under -o all a failed cleanup is that one Error: line, with no container prefix; Batect prints Could not stop container <name>. or Could not remove container <name>. on each container’s own prefix, and Could not delete the task network. on the task’s.
  • A crash skips cleanup. If Ratect itself crashes mid-run — a bug, which exits 101 and asks for a report — the run’s containers and network are left behind. Batect catches an internal error in a step and still cleans up. What a crash leaves carries Ratect’s ownership labels: ratect resources clean removes it (ratect-only), and from ratect-compat, which has no such command, docker does, filtering on the project’s label — docker rm -f -v $(docker ps -aq --filter label=eu.orican.ratect.project=<project>), then the same filter on docker network ls -q for docker network rm.

  • No pull lines for an image that’s already local. Under image_pull_policy: IfNotPresent, an image that’s already present prints no Pulling X.../Pulled X. lines; Batect prints both even though nothing is pulled. See Task Lifecycle.

  • Under image_pull_policy: Always, an image is pulled once per run, not again for each task in a prerequisite chain that uses it, as Batect does. A build_directory image is likewise built once per run, where Batect builds it again for each task — and, under Always, pulls its base image again each time. See Task Lifecycle.

  • fancy mode draws a fresh block after the terminal’s width changes. The terminal has re-wrapped the old lines by then, so moving the cursor back up over as many lines as were drawn, as Batect does, lands it in the wrong place on common terminals and corrupts the display. Ratect leaves the old block where it is and draws the new one below it, at the cost of that leftover block.

  • fancy mode names the image it pulls, and calls a ready dependency ready. A container’s line reads ready to pull image <image> and then pulling image <image>..., where Batect’s reads ready to pull image and pulling <image>.... A dependency that has passed its readiness gate — healthy, and its setup commands done — reads ready, where Batect’s reads running, which would fit a container that has started but isn’t yet healthy just as well.

  • fancy mode shows no cleanup line when cleanup is off. Under --no-cleanup or --no-cleanup-after-success, Batect briefly shows Cleaning up: N containers (...) left to remove... when the task’s container exits, though nothing will be removed. Ratect shows none.

  • fancy mode draws a multi-line setup command on one row. Each line break in it is shown as a space, and the command runs as usual. Batect can’t draw it, and fails the task with an unexpected-exception error and exit code 255 before the command runs — which a | block’s trailing newline is enough to cause, even for a one-line command.

  • fancy mode treats a reported terminal width of 0 as unknown. Some pseudo-terminals report it (script‘s, some CI runners’), and lines are then printed unclipped; Batect clips every line to nothing.

  • Under run_as_current_user, a mount point nested inside a local mount is created with the type its source needs. For a file or socket mounted inside a local mount — ./config.json at /code/config.json under . at /code — Ratect creates an empty file at the mount point, and the mount works. Batect always creates a directory there, which fails the run: a file or socket can’t be mounted over a directory, and an existing file at the mount point fails the creation itself. Ratect also follows a symlink on the way to a mount point only while it stays inside the enclosing mount’s host directory, leaving the mount point to the daemon otherwise; Batect follows it even out of that directory, creating the mount point outside the project. See User mapping.

Next steps

The behaviour both binaries share is documented in its own right rather than against Batect: Task Lifecycle for what a run does step by step, Dependency Readiness for when a dependency counts as ready, Includes for how included files combine and what a Git bundle may do, and the FAQ.

Task Lifecycle

This is the detailed, step-by-step version of what ratect run <task> (or ratect-compat <task> — the two binaries share one engine) actually does, covering task ordering, per-task setup and cleanup in depth (what a dependency has to pass before it counts as ready is on its own page — see Dependency Readiness). For the broader architecture (config loading, CLI parsing, logging), see how it works.

Task ordering

Ratect only ever runs one task’s containers at a time. A task’s prerequisites just order sequential task executions — each prerequisite task runs to completion (including its own cleanup, described below) before the next one starts, and before the originally-requested task itself runs.

[tasks.compile]
run = { container = "build-env", command = "./build.sh" }

[tasks.test]
prerequisites = ["compile"]
run = { container = "build-env", command = "./test.sh" }

Running ratect run test here runs compile to completion first, fully cleaning up after it, then runs test.

The whole order is worked out before any of it runs, as in Batect: a prerequisite that names no task, or a cycle among prerequisites, fails the run before the first task starts, so no earlier prerequisite has run by then.

A task doesn’t strictly need a run of its own — a task with only prerequisites is valid (see config reference), and exists purely to chain other tasks together:

[tasks.ci]
prerequisites = ["compile", "test"]

Running ratect run ci here runs compile then test to completion, same as above, then stops — there’s no container of ci’s own left to run — saying The task ci only defines prerequisite tasks, nothing more to do. in every output style but quiet.

Per-task steps

Every task execution gets its own Docker network, whether or not its container declares dependencies — so a task’s container is never left running on Docker’s shared default bridge network, reachable by or able to reach anything else on the host. If the container does declare dependencies, those are started on that network before the task’s own container, so the task’s container can reach them by name — and so is anything named in the task’s own dependencies (sidecars scoped to this task specifically, distinct from the container-level field — see config reference), unioned in alongside the container-level ones. (With ratect.toml, a container can leave that network with network_mode — it is then not reachable by name — while every other container still joins it.) All of this — network, dependencies, and the task’s own container — is scoped to this one task execution and torn down before moving on, regardless of whether the task succeeded (though not if Ratect itself crashes — see Differences from Batect) — unless --no-cleanup/--no-cleanup-after-failure/ --no-cleanup-after-success says otherwise, in which case everything below is left genuinely running instead, for investigation (see CLI reference):

sequenceDiagram
    participant Engine as TaskEngine
    participant Docker
    participant Dep as Dependency container(s)
    participant Main as Task's own container

    Engine->>Docker: create_network()

    par every container in the task's graph, the task's own included
        Engine->>Docker: pull_image()/build_image() (per image_pull_policy, unless already decided this run)
        Engine->>Docker: create_container(spec) — once its own image is ready
        Docker-->>Engine: created on its network, not started
    and independent branches of the dependency graph, each once every container it depends on is ready
        Engine->>Docker: start_background_container(id)
        Docker-->>Dep: started
        Engine->>Docker: wait_for_container_healthy()
        Docker-->>Engine: healthy (immediate if no health check)
        loop for each setup command, in declared order
            Engine->>Docker: exec_in_container(command)
            Dep-->>Engine: exit code 0 (non-zero fails the task)
        end
    end

    Note over Engine: a dependency's readiness gates only the *start* of what depends on it —<br/>every container is pulled or built, then created, regardless

    Engine->>Docker: run_container(id) — once every container the task's own depends on is ready
    Docker-->>Main: started
    par the main command
        Main-->>Engine: runs to completion, logs streamed live to stdout
    and ratect-compat only: the task container's own readiness gate, gating nothing
        Engine->>Docker: wait_for_container_healthy(), then exec_in_container() per setup command
        Note over Engine: a failure cancels a still-running main command;<br/>the main command's exit ends the gate (see Known limitations)
    end

    Engine->>Docker: cancel_build() for each BuildKit build the run stopped waiting for, whatever --no-cleanup* says
    Note over Engine: cleanup — runs even if the task's container failed,<br/>unless --no-cleanup* says otherwise
    Engine->>Docker: stop_and_remove_container() for the task's own container
    Engine->>Docker: stop_and_remove_container() for each dependency, in reverse dependency order
    Engine->>Docker: remove_network()

Dependencies are stopped and removed in reverse dependency order: a container only after every container that depends on it, so a dependent shutting down can still reach what it depends on. A dependency whose dependent’s stop failed is still stopped. Containers with nothing left depending on them are stopped at the same time, so independent dependencies take one grace period between them, not one each. Under -o all each step is reported as it happens: Container stopped. (for a container the run started) then Container removed. on each container’s own prefix, and Removing task network... then Task network removed. on the task’s.

An image build that hasn’t finished when the run ends — because of a termination signal, or because another container failed — is cancelled before anything is removed, and under --no-cleanup* too: a BuildKit build would otherwise run on in the daemon to the end of its steps. A cancel that fails is a warning naming the container. The classic builder has no cancel; the daemon stops a classic build on its own some seconds after Ratect disconnects from it.

If the container has no dependencies, the dependency steps (the loop above) are skipped — but the network is still created and the task’s own container still joins it, isolating it just the same as a task with dependencies.

--no-cleanup-after-failure skips the cleanup step above for a genuine infrastructure failure (a build/pull/health-check/setup-command failure, or anything else before the task’s own container gets to run — or, under ratect-compat, its own health check or setup commands failing while its main command is still running, which cancels it); --no-cleanup-after-success skips it when the task’s own container ran to completion instead, regardless of its exit code (a non-zero exit is still “success” for this purpose — it’s the task’s own container actually running that matters, not what it returned); --no-cleanup is both at once. Either way, everything above is left genuinely running, not just present-but-stopped — see CLI reference. The success flag keeps the named task’s resources alone: a prerequisite is always cleaned up after success, so only the task you asked for is left to investigate. The failure flag applies to whichever task failed, prerequisites included.

pull_image() in the diagram above is conditional on image_pull_policy (see config reference): IfNotPresent, the default, checks whether the image already exists locally first and skips the pull entirely if so; Always skips that check and pulls unconditionally. Either way, the decision (pull or don’t) is made once per image name and policy per run — a dependency and the task’s own container sharing both don’t re-decide for each other, but an Always container still pulls when another container already found the same image locally under IfNotPresent, and an IfNotPresent one still checks locally when an Always one pulled it. The container is then created from the image’s ID — the one the pull fetched, found by the digest it reported, or the local one — not from its name, so a tag moved by another pull meanwhile doesn’t change what runs, as in Batect.

Passing --use-network <name> skips network creation and teardown entirely for every task in this invocation: the named network is checked to exist up front (a clear error if it doesn’t), and reused instead — dependencies and the task’s own container all join it exactly as they would a freshly-created one, but it’s never removed at cleanup, since Ratect didn’t create it. See CLI reference.

Dependency resolution

What happens between create_network() and the task’s own container starting in the diagram above — how a dependency graph’s independent branches start concurrently, why a shared dependency starts once, and what a dependency has to pass before anything that depends on it starts — is its own page: Dependency Readiness.

Cross-task isolation

Because dependency resolution is scoped to a single task execution, two different tasks that each depend on the same container name get their own separate instance — nothing is shared or deduped across tasks, even within one ratect invocation:

[tasks.migrate]
run = { container = "app", command = "run-migrations.sh" }

[tasks.test]
prerequisites = ["migrate"]
run = { container = "app", command = "run-tests.sh" }

Both migrate and test here depend on database (via app’s container config). Running ratect run test starts a database instance, its own network, runs migrate, cleans both up — then starts a second, independent database instance and network for test. This matches Batect’s own documented behavior (“each task will start its own instance of each container, even if multiple tasks share the same container”) and is also what makes concurrent ratect invocations on the same host safe: each task execution names its network and containers with a random six-character suffix of its own — <project>-network-<suffix> and <project>-<container>-<suffix>, as Batect names them — so two runs never share a container, nor a network Ratect created. In the rare case two draw the same suffix, the second run fails rather than join the first one’s network, but how depends on the daemon:

  • Docker 25 and later refuse its network when it’s created (network with name <project>-network-<suffix> already exists), before any of its containers exist.

  • Docker 20.10 to 24 create a second network with the same name, and the second run then fails at one of two points:

    • If the first run’s containers still exist, creating the second run’s containers fails, because their names are taken (The container name "/<project>-<container>-<suffix>" is already in use).
    • If only the first run’s network is left — after --no-cleanup, say — the second run’s containers are created, and starting the first of them fails (network <project>-network-<suffix> is ambiguous (2 matches found on name)).

    In both cases the second run’s cleanup can’t remove its network by name, for the same ambiguity, so it reports that network as left behind. The docker network rm <project>-network-<suffix> it suggests is refused too, and removes neither network. Remove each one by the ID docker network ls shows, or, under ratect, with ratect resources clean, which removes by ID.

Known limitations

  • Under ratect-compat, the task’s own container’s readiness gate can race a fast main command — and “main command” is usually a task-specific override. A task’s run.command/run.entrypoint (see TaskRun) replaces whatever the container’s own command/entrypoint, or the image’s default CMD, would otherwise run — often to run a one-off command (psql, a one-shot migration script) against a container that’s really built for something else, a long-running service. That override is what actually starts the instant the container starts. It is never gated on the container’s own health_check/setup_commands — under ratect-compat the task’s own container goes through the same readiness gate a dependency does (health-check wait, then setup_commands, in order), but run concurrently with the main command rather than blocking it, because nothing else in the graph depends on the task container’s own readiness. A setup command or health-check failure while the main command is still running cancels it and fails the task, as Batect does (after up to two seconds — see below); the container is then stopped and removed like any failed run’s. That includes a health_check written for the container’s usual, non-overridden role, which a one-off command doesn’t make go away. Once the main command has exited, the gate no longer decides anything: a non-zero exit code is the task’s result, and an exit 0 succeeds whatever the gate was still doing. The health wait sees the container stop before Docker reports a health status; a setup command can’t docker exec into a container that has stopped, or is killed with it mid-run (exit code 137, typically). None of those say anything about the container’s readiness, so the task succeeds, where Batect fails it. The cost is that a setup command genuinely failing at the same moment the main command exits 0 is forgiven too. A setup command that fails because the main command has just exited can be reported before Docker has marked the container stopped, so a gate failure while Docker still reports the container running, or can’t say, waits up to two seconds for the main command’s own result before cancelling it. A main command that exits within that window decides the task as above, so one exiting 0 up to two seconds after a setup command genuinely failed is forgiven too. The race that leaves: a main command that has in fact exited 0, but whose exit Docker reports more than two seconds after the setup command’s failure, is cancelled, and the task fails with the setup command’s error. Under ratect none of this applies: a task’s own container has no readiness gate at all (see Dependency Readiness).
  • Prerequisite tasks stay sequential, matching Batect exactly — prerequisites entries run one after another, each to completion, never concurrently with each other or with the task that named them (see “Task ordering” above). This is Batect’s own behavior (TaskExecutionOrderResolver/SessionRunner), not a Ratect simplification — Batect doesn’t parallelize independent prerequisite tasks either. Running independent prerequisites concurrently remains a possible Rust-specific enhancement beyond Batect, tracked as ratect#102, not something planned.
  • Minimal networking. The network created here exists only to make dependency containers reachable by name for the duration of one task (or, with --use-network, an existing network you reuse instead). It’s not the fully-configurable Docker networking Batect offers (custom drivers, other than by pre-creating the network yourself) — see differences from Batect.

Coming from Batect? Its own task lifecycle page describes the model this one is a deliberately simplified version of; the limitations above say where the two match and where they differ.

Dependency Readiness

A dependency container being started doesn’t mean it’s ready — a database accepts connections some time after its process launches. This page is the one place for what “ready” means, how Ratect waits for it, and how several dependencies’ waits combine into one task’s start-up. The fields themselves (dependencies, health_check, setup_commands) are in the batect.yml reference; a ratect.toml dependency reads them the same way (see Field reference), which is what the running example is written in. A task’s own container is the one place the two binaries differ — see The task’s own container.

That example, throughout, is examples/full-stack’s db container — a real postgres:16 gated on pg_isready, whose init script bulk-seeds a million-row table, and which then runs a real setup_commands entry once it’s healthy:

[containers.db]
image = "postgres:16"
environment = { POSTGRES_HOST_AUTH_METHOD = "trust" }
volumes = [{ local = "db/init", container = "/docker-entrypoint-initdb.d" }]
health_check = { command = "pg_isready -h 127.0.0.1 -U postgres", interval = "1s", retries = 90 }
# ANALYZE needs a real, committed table to work against, which is exactly
# what setup_commands is for — running once db is healthy, not baked into
# the init script that creates and seeds that table in the first place.
# Genuinely useful here, not just illustrative: a bulk INSERT this size
# leaves the query planner without fresh statistics until something
# collects them, and the journey-test/app queries below count() this table.
setup_commands = [
    { command = "psql -U postgres -c \"ANALYZE visits;\"" },
]

app depends on db and on cache (a redis:7 with its own health check), and the journey-test task depends on app and, again, on cache. app itself is checked a third way — an external_health_check requesting /healthz from outside it, which reports exactly as the other two do. ratect run journey-test -o simple, captured on a terminal in examples/full-stack:

Running journey-test...
Starting cache...
Starting db...
Started cache.
Started db.
cache has become healthy.
db has become healthy.
Running setup command psql -U postgres -c "ANALYZE visits;" (1 of 1) in db...
db has completed all setup commands.
Starting app...
Started app.
app has become healthy.
Running sh -c 'npm ci && node test.js' in journey-test...

added 6 packages, and audited 7 packages in 983ms

found 0 vulnerabilities
app responded: {"message":"Hello from Ratect!","visit_id":1000001,"total_visits":1000001,"count_source":"database"}
cache holds visits:count=1000001, confirming app and this container share the same cache
journey test passed

Cleaning up...
journey-test finished with exit code 0 in 9.1s.

The recording on the homepage is the same command in fancy mode. db takes longer than cache because it’s genuinely seeding that table before its health check can pass, not because anything is padded. The rest of this page is what the lines between Starting db... and Starting app... mean.

The readiness gate

Matching Batect, a dependency must pass one readiness gate, in two steps in order, before anything that depends on it (another dependency, or the task’s own container) starts:

  1. It must report healthy. If the container has a Docker health check — from its image’s own HEALTHCHECK, from the health_check field, or both — Ratect waits for Docker’s verdict: proceeds on healthy; fails the task on unhealthy (the error includes the last health-check run’s exit code and output, unless the container or the daemon has gone by the time Ratect looks them up) or if the container exits first. A container with no health check at all is immediately considered healthy — for it, started is ready. In the transcript, this step is the gap between Started db. and db has become healthy.

    This step is Docker’s own health check, so it needs a shell and a check tool inside the image. If yours has neither — a distroless or scratch build — a ratect.toml container can be checked from outside instead, with external_health_check, which then replaces this step, image HEALTHCHECK included.

  2. Its setup_commands must succeed. Each runs inside the running container (via Docker’s exec mechanism), one at a time in declared order, with the container’s own environment and the same user/group the container runs as (under User mapping or, in a ratect.toml, user/group). A command exiting non-zero fails the task, with its output in the error. In the transcript, Running setup command psql -U postgres -c "ANALYZE visits;" (1 of 1) in db... is this step, and Starting app... doesn’t appear until db has completed all setup commands.

A ratect.toml setup command can run somewhere else: run_in (ratect-native only) names one of the declaring container’s own dependencies to exec into instead, for the case where the tooling a setup step needs lives in a different image — seeding a database from a client container, say. When it runs is unchanged: it is still the second step of the gate of the container that declares it, so nothing depending on that container starts until it has succeeded. The restriction to that container’s own dependencies is what makes it safe, and is explained in that field’s own section.

Whichever step fails, the task fails, and already-started containers are still cleaned up as usual. The error ends by suggesting --no-cleanup-after-failure, which keeps those containers in place so you can look inside the one that wasn’t ready; with that flag (or --no-cleanup) given, there is nothing to suggest, and the error ends without it.

A ratect.toml dependency can opt into a different readiness gate entirely: run_to_completion (ratect-native only — batect.yml has no equivalent) replaces “healthy, then setup commands” with running to completion and exiting 0 — Kubernetes-style init-container behavior, still just a node in the same dependency graph described below. It participates in resolution exactly like any other dependency (concurrent with an unrelated branch, deduplicated if shared, nestable either directly under a task’s own dependencies or under another dependency’s); the only difference is what “ready” means for it. What it rejects, and why it isn’t a substitute for prerequisites, is in that field’s own section.

A ratect.toml container can also be checked from outside itself: external_health_check (ratect-native only) makes an HTTP request or a bare TCP connection to the container over the project’s own network, for an image with no shell and no check tooling to run the first step with — a distroless or scratch build. The two are different concepts rather than two spellings of one: health_check is Docker’s own HEALTHCHECK, owned by the daemon and re-run for the container’s whole lifetime, while this is closer to a Kubernetes readiness check — asked once, from outside, with no opinion about the container’s health afterwards. (Ratect has no equivalent of a liveness check in either form.) It alone decides readiness: an image’s own HEALTHCHECK still runs, but Ratect doesn’t wait on it. It is config-level sugar over run_to_completion rather than a gate of its own: declaring one generates a companion container that loops the check and exits 0 or non-zero, and everything that depended on the checked container depends on that companion too. None of that surfaces — the companion narrates nothing of its own, and the checked container reports has become healthy. when the check passes, exactly as it would for a health_check. So the resolution described below is unchanged.

How Docker reaches its verdict

This is Docker’s own behavior, not Ratect’s, but it’s what actually determines how long the first step waits and when it fails, so it’s worth spelling out:

  • A freshly started container with a health check isn’t unhealthy — it’s in a third state, starting, until Docker reaches a first verdict. Docker runs command every interval; the first success makes the container healthy, and only retries consecutive failures make it unhealthy. With db’s settings above (interval = "1s", retries = 90), the earliest possible unhealthy verdict is about ninety seconds in — a health check can’t “fail fast” on its first bad run, and db’s generous retries is exactly what gives its million-row seed the time it needs.
  • Failures during start_period don’t count toward retries at all — that’s the grace period for slow-booting services — but a success during it still flips the container healthy immediately.
  • Ratect waits for that first verdict, and only the first: matching Batect, a dependency’s health is never re-checked once its dependents have started, even though Docker keeps running the check for the container’s whole lifetime and the state can flip later. See Once ready below for what Ratect does instead.

While a task appears to hang on a dependency, docker ps shows each container’s health state in its STATUS column (health: starting, etc.), and docker inspect --format '{{.State.Health.Status}}' <container> shows it directly — .State.Health.Log keeps the last few check runs’ exit codes and output, which is also where the detail in Ratect’s “did not become healthy” error comes from.

Ratect imposes no timeout of its own on the health wait (matching Batect) — Docker’s own interval/retries bound how long a verdict can take, so a health check configured to retry forever waits forever.

Resolution order

Dependencies are resolved concurrently, gated by readiness — and the gate is on starting: a container with dependencies of its own never starts before every one of them is ready, but two containers with no dependency relationship to each other start at the same time rather than one after the other. Nothing before the start waits for it: every container’s image in the task’s graph, the task’s own included, is pulled or built from the moment the task’s network exists, and each container is created as soon as its own image is ready, so a pull, build or create that fails — an image that doesn’t exist, a device or mount that doesn’t — ends the task as soon as it fails, not once every dependency is ready and its setup commands have run, and the pulls along a chain overlap rather than each following the previous container’s readiness. A container sharing another’s network (network_mode = "container:<name>", ratect.toml only) is the one exception, and only partly: it is created once its target has been created, since Docker needs the target’s id, and started once the target is ready, like anything else. For example:

[containers.app]
image = "my-app"
dependencies = ["database"]

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

[containers.cache]
image = "redis:7-alpine"
graph TD
    app["app (task's container)"] --> database
    database --> cache

Running a task against app starts pulling all three images at once, and creates each container as its image lands. cache starts as soon as it is created (nothing else is holding it back), then database once cache is ready, then app once database is ready — a straight chain, so each start is genuinely waiting on the last. All three share one network and are reachable by their container-config name (e.g. app’s command can reach database:5432 and cache:6379).

Add a second container that also depends on cache — say queue, also one of app’s dependencies, but with no relationship to database — and cache is now a shared dependency of two others, forming a diamond rather than a straight chain:

graph TD
    app["app (task's container)"] --> database
    app --> queue
    database --> cache
    queue --> cache
sequenceDiagram
    participant Engine as TaskEngine
    participant Cache as cache
    participant Database as database
    participant Queue as queue
    participant App as app (task's container)

    Note over Engine: cache has no dependencies of its own — starts immediately
    Engine->>Cache: start, wait for healthy, run setup commands
    Note over Cache: ready

    par database and queue both depend only on cache — start together,<br/>the moment it's ready, not one after the other
        Engine->>Database: start, wait for healthy, run setup commands
        Note over Database: ready
    and
        Engine->>Queue: start, wait for healthy, run setup commands
        Note over Queue: ready
    end

    Note over Engine: app depends on both database and queue —<br/>waits for whichever is slower before starting
    Engine->>App: start (runs to completion)

cache is only ever started once, even though both database and queue depend on it: whichever of the two reaches it first triggers the actual start, and the other waits on that same in-flight readiness rather than starting a second instance or pulling its image twice (see below — this holds generally, not just for a leaf like cache). database and queue then genuinely overlap in time — both start the moment cache’s readiness gate has actually passed, not just once its container exists, and neither waits on the other since they share no relationship. app is gated on whichever of the two takes longer, not just the first one to finish.

examples/full-stack has the same ingredients with real names: journey-test depends on app and cache, and app depends on db and cache. db and cache are unrelated branches, so the transcript above starts them together; app waits on both, so Starting app... follows db has completed all setup commands.; and cache, reached by journey-test directly and by app, starts once.

More generally, within one task’s resolution any dependency shared by two others — not just a leaf like cache — is only ever started once, no matter how many dependents reach it or how deep in the graph they sit, including when they reach it genuinely concurrently: the second to arrive waits on the first’s already-in-flight readiness rather than starting a second instance or double-pulling its image. A circular container dependency (a depends on b depends on a), or a container depending on itself, is detected up front and reported as an error rather than hanging: after the task’s prerequisites have run, but before the task itself starts, so there’s no Running line, no task network is created, and nothing is cleaned up.

This concurrency is unbounded by default — every container’s pull/build and create, every dependency’s start, and every setup command can all be in flight at once, across the whole invocation, not just within one task. --max-parallelism <N> caps it: at most N of those specific operations run at a time, invocation-wide. A create and a start are separate capped steps, and a container holds no slot while it waits for its dependencies to be ready, so a chain longer than N can’t deadlock. The health-check wait itself is deliberately not capped (it’s a polling wait, not real work), so two dependencies can still become healthy at the same time even under a low cap — only the pull/build/create/start/setup-command steps queue up behind it. See CLI reference and differences from Batect for exactly what’s covered.

A task’s own dependencies (sidecars scoped to that task specifically) join this same resolution at the root, alongside its container’s own — each still resolves its own container-level dependencies transitively from there, same as any other dependency, and is just as eligible to start concurrently with an unrelated branch. And a task’s customise map, if it has one, is checked against whichever dependency is starting: a match overrides that container’s environment/ports/working_directory for this task’s run of it specifically (merged the same way a task’s own run overrides its main container — see config reference), before it starts, regardless of how deep in this graph it sits.

Once ready

Health is a one-time gate in this sequence, not ongoing monitoring (the verdict lifecycle above): a dependency that turns unhealthy after its dependents have started doesn’t affect the rest of the task.

Not re-checking health doesn’t mean staying silent, though: a dependency that has already become ready and then exits on its own — while the task’s own command, or a later dependency’s own health/setup wait, is still going — prints a progress line naming the container and its exit code, in every output style except quiet. Without it, that container’s own death would otherwise surface later as a confusing symptom in whatever depended on it (a connection refused, a timeout) rather than the real cause. This is a notification only — the run isn’t failed or stopped because of it — and it’s never printed for a container cleanup itself stops: Ratect stops watching a dependency for this the moment the task’s own execution finishes, strictly before cleanup ever touches a container. Nor is it printed for a run_to_completion dependency: its exit is how it became ready in the first place, not a later surprise, so there’s nothing unexpected to report.

The task’s own container

Which rules apply depends on which binary loaded the project, ratect or ratect-compat, not on which file declares the container.

  • ratect (native): no readiness gate. Running the task’s own container is the task, and nothing depends on it becoming ready. Ratect doesn’t wait for its health check, whether from health_check or the image’s own HEALTHCHECK, and doesn’t run its setup_commands. The task’s result is the main command’s alone. Docker still runs the health check; Ratect doesn’t watch it. Nor does run_to_completion change anything: the container runs as the task, exactly as it would without it. The fields stay valid on that container, since the same container can be another task’s dependency.
  • ratect-compat (Batect-compatible): the same gate as a dependency, run concurrently with its main command rather than gating anything on it — matching Batect, which runs every container through identical per-container steps, task container included. A failure there while the main command is still running stops it and fails the task — after waiting up to two seconds for the command’s own exit, which decides the task instead if it arrives. Once that command has exited, with any code, whatever the gate was still doing — a health wait, a setup command the container’s exit killed — is dropped, and after an exit 0 a failure it already reported isn’t one. That, and the race it leaves open, are in known limitations; where Ratect differs from Batect on it is in Differences from Batect.

Includes

A project is one root configuration file and everything it includes. An include entry pulls in either another file from your own tree or a bundle — a Git repository holding a configuration file — and the result is one flat set of containers, tasks and config variables, as if it had all been written in the root file. This page is the one place for how included files combine, where their relative paths end up, and what a file that arrived through a Git include is and isn’t allowed to do. The entries’ own fields — repo, ref, path, the clone cache and how to refresh it — are in the batect.yml reference, and mean the same in a ratect.toml; what the native format adds is in the ratect.toml reference. Why you’d share a bundle across projects at all is Reusable Pipeline Building Blocks.

Every rule here holds in both formats: the two parse into one model, and an include is resolved the same way whichever file declared it. The one exception — what a bundle’s own Git includes are allowed to do — is marked where it comes up. The examples are ratect.toml, with the batect.yml spelling shown where the syntax differs.

Two kinds of include

A file include names another configuration file in your own tree, by a path relative to the directory of the file that declares it — not the root project directory — so a file in a subdirectory can include more files relative to its own location. A path whose first component is ~ means your home directory instead, by the same rule as a volume’s host path. A Git include names a repository and a ref, and Ratect clones it into ~/.ratect/incl (so it is refused with no home directory) and includes one file from the clone — the bundle’s batect-bundle.yml unless the entry’s path says otherwise, with a ratect.toml project looking for ratect-bundle.toml first (the ratect.toml reference has the lookup). A Git include’s path is taken as written within the clone, a leading ~ included. In a ratect.toml project both kinds may mix, and each included file is parsed by its own extension, so a native project can pull in an existing batect.yml fragment or bundle unchanged:

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

A batect.yml spells the same three entries as a bare path, an object with type: file, or an object with type: git:

include:
  - ci/tasks.yml
  - path: shared/other.yml
    type: file
  - type: git
    repo: https://example.com/bundle.git
    ref: v2

How included files combine

Every loaded file’s containers, tasks and config_variables are merged into one flat set. A name defined in more than one file is a hard error naming every file that defines it — it is never treated as one file overriding another, so a project can’t redefine a container that came from a bundle (see what a consuming project can and can’t change for the two narrower ways to adapt one). An included file may include further files of its own.

Includes are walked breadth-first: every entry in the root file is reached before any included file’s own, and each file is loaded exactly once, by its resolved absolute path, however many entries name it. So two files may both include a common third without it being read twice — and, for a Git include, the first entry to reach a file is the one whose settings that file is loaded with, which is what a grant goes on the entry that reaches the file first rests on.

Which fields a file may use

A file’s own format decides which fields a container may use and which rules its file loads under — not the project that includes it. A .yml is Batect’s format, so a container written in one may use no ratect-native field (extends, ulimits, stop_signal/stop_grace_period, dns/dns_search/dns_options, network_mode, user/group/groups, identity, run_to_completion, external_health_check, a cache’s scope, a setup command’s run_in) and gets Batect’s own semantics: no expressions resolved in image, and exactly one of image/build_directory. That holds even when a ratect.toml project is what pulled the file in, and it holds for a YAML root file too — ratect -f batect.yml reads a Batect file, and reads it as one. A native field fails the load whatever its value, as an unknown field does in Batect: run_to_completion: false is refused like true, and a malformed value is reported as the field that doesn’t belong, not as a bad value.

The same goes for a Git include entry’s native-only fields, allow_nested_git_includes and reviewed_ratect_version: a .yml that sets either one fails to load, under either binary, whatever its value. Under ratect the error names the field and the file, and the way out that file has: a root .yml needs the project converted (ratect config convert), since a YAML root can’t include a TOML file, and so does a .yml it includes; a .yml a TOML root includes can move that Git include into a TOML file; and a bundle file needs its author to, plus the project converted if its root is YAML. allow_host_paths isn’t one of them — both formats accept it.

What a container does at run time follows the binary instead, not the file: under ratect, a task’s own container has no readiness gate, whichever file declares it — a .yml task container in a native project, or in ratect -f batect.yml, gets no health wait and runs no setup_commands, exactly as a TOML one. Under ratect-compat it has Batect’s. See The task’s own container.

To use a native field on a container, move that container into a .toml file. Under ratect the error gives the same ways out, for that container. Incremental migration exists so a project needn’t be converted in one go (see Migrating a Batect project), not so a YAML file can grow native features — and the unit you convert is a container, which is smaller than a file.

The flow between them is one-way, which is what makes this workable: a native container may extends a container declared in a YAML file, because the container namespace is flat once includes are merged. The reverse — a YAML-declared container extending anything — is the rejected case above.

For a bundle author, the same rule is why a Git bundle can ship ratect-bundle.toml and batect-bundle.yml side by side (see Two kinds of include): the YAML one stays consumable by Batect and ratect-compat, and the TOML one is free to use native fields.

Where relative paths resolve

A relative path within a container — a volume’s host path, build_directory, a build_secrets entry’s path, a build_ssh entry’s paths — resolves against the directory of the file that declares the container, not the root project directory. For a file reached through a Git include that is the file’s own directory inside the clone — the same rule, rooted in the clone rather than in your project. The built-in batect.project_directory config variable always resolves to the root file’s directory, whichever file it is written in, and is how an included file names the project directory explicitly.

A project laid out as:

myproject/
├── ratect.toml
├── scripts/
└── containers/
    ├── extra.toml
    └── data/

with a root ratect.toml of:

project_name = "myproject"
include = [{ path = "containers/extra.toml" }]

[tasks.my-task]
run = { container = "my-other-container" }

and a containers/extra.toml of:

[containers.my-other-container]
image = "alpine:1.2.3"
volumes = [
    # containers/extra.toml's own directory is containers/, so this
    # resolves to myproject/containers/data — not myproject/data.
    { local = "./data", container = "/data" },
    # Always the root project directory, regardless of which file this
    # is written in — so this is myproject/scripts, not
    # myproject/containers/scripts.
    { local = "<{batect.project_directory}/scripts", container = "/scripts" },
]

runs my-other-container with those two volumes mounted exactly as resolved in the comments. my-task lives in the root file, but the container it runs could equally have been declared there instead; only the volume paths’ resolution depends on which file declares the container. In a batect.yml project the included file is containers/extra.yml and its two entries are ./data:/data and an object whose local is <{batect.project_directory}/scripts — not the string form <{batect.project_directory}/scripts:/scripts, whose host path a batect.yml uses as written (see Volume path resolution). (This project is illustrative; the nearest real one is ratect-compat/tests/fixtures/include.yml, whose included file mounts its own directory for exactly this reason.)

Owned files and bundle files

What a file may do depends on how it was reached, not on what kind of include named it last, and not on its extension. A file reached from the root without passing through a Git include is owned: yours, unrestricted, the same trust as the root file itself. A file reached by passing through a Git include is a bundle file — including any file the bundle then includes with a plain file include, since that is still the bundle choosing what to load. A local .yml your ratect.toml includes is owned; a .toml a bundle includes from its own clone is not. (CONTEXT.md is the glossary for these terms.)

An owned file is subject to none of what follows. A bundle file is loaded under a boundary: the containment it must stay within, together with whatever grants the include entry that reached it carried.

What a bundle may do

A bundle defines both a container and the command that runs inside it, which is the combination that matters: without a check, a bundle could declare a container mounting ~/.ssh or ~/.aws and a command that reads it, and a project including that bundle would have no way to know from its own configuration alone. decisions/0004 has the full reasoning; the rules it settled on are these.

Containment

Two things are contained, and both are a deliberate divergence from Batect, which has no equivalent check.

Which files a bundle can make part of your configuration. A Git include’s path, and every include entry declared (transitively) by the file it names, must resolve to somewhere inside that repository’s own clone — an absolute path, a ../.. traversal, or a symlink pointing back out are all rejected with a clear error rather than silently reading a file elsewhere on the machine running Ratect. A file include in an owned file has no such restriction, since it always names something already in your own checkout. A bundle can declare a further type: git include of its own — a fresh repository with its own boundary, not an escape from this one — in a ratect-compat project; a ratect project refuses that unless you opt in, see Nested Git includes below.

Where a bundle’s containers can reach on your machine. A volumes host path, build_directory, build_secrets path or build_ssh paths declared by a container in a bundle file must resolve to somewhere inside that repository’s own clone, or inside your project directory; an absolute path, a ../.. traversal, or a symlink pointing back out of both is rejected the same way. A path Ratect cannot resolve at all is also rejected rather than assumed harmless: if a directory along it can’t be searched, or a symlink loops, where the path really leads can’t be established — and the Docker daemon that would dereference it runs as root, under no such restriction. A path that simply doesn’t exist yet is fine; Ratect or Docker creates it. The project directory is allowed as a second root, rather than requiring pure containment within the clone, because referencing it explicitly via batect.project_directory (say, <{batect.project_directory}/output) is a legitimate, common thing for a shared bundle to do — the project directory is your own fully-trusted tree, distinct from the repository the container definition itself came from.

Vouching for a bundle

Some bundles legitimately need a path outside both roots — most often a shared tool cache under your home directory, like ~/.cache/trivy, so a security scanner’s own database is reused across every project rather than re-fetched per project. Since neither customise nor a local redefinition can add a volume to someone else’s container, there would otherwise be no way to use such a bundle at all. Setting allow_host_paths on your own include entry lifts the restriction for that bundle:

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

It applies only to the bundle named there — never to bundles it includes in turn — and is honoured only in your own configuration: the same flag written inside a bundle file is ignored, so a bundle can neither grant itself the permission nor pass along one you gave it. It doesn’t relax the file containment above either; that governs which files become part of your configuration, a separate question from where a container may mount. What a future allowlist form would have to preserve is in decisions/0004.

For a native bundle whose whole purpose is a shared cache, a shared cache volume says the same thing without asking any consumer for host filesystem access — reach for that before allow_host_paths.

Nested Git includes

batect.yml differs here. In a ratect-compat project a bundle’s own type: git includes are always allowed, matching Batect, and the field below is rejected rather than ignored. Everything in this section is the ratect binary’s behaviour, and the field goes in a TOML file: a .yml that sets it fails to load under ratect too (see Which fields a file may use).

A bundle can declare include entries of its own, and under ratect-compat those may be further Git includes naming any remote, with the same trust your own includes get. Under ratect that is refused by default:

The bundle 'https://github.com/my-org/infra-bundle.git' at '1.2.3' declares a
Git include of its own ('https://elsewhere.example/other.git'), which would
fetch and run configuration from a remote you have not named. Set
'allow_nested_git_includes' to true on that bundle's own include entry to
accept this; only a TOML file can set it.

You chose the bundle; you did not choose whatever it decides to pull in next, and that choice can change under you the next time its ref moves. Opt in per bundle by setting allow_nested_git_includes on the entry:

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

The entry doesn’t have to be in the ratect.toml itself — an entry in a local file the project includes is just as much your own configuration, because that file is owned. It does have to be a .toml file: the field is native-only, so a .yml that sets it fails to load. To grant from a shared .yml, move that Git include into a .toml file and include that instead. ratect config convert converts a whole Batect-format project from its root, not one included file.

The grant is one level deep. It admits that bundle’s own Git includes; it does not let those bundles declare further ones. Like allow_host_paths, it counts only in configuration you control — written inside a bundle file it is ignored, so a bundle can neither grant itself the permission nor pass on the one you gave it. If a bundle genuinely needs a chain deeper than that, include the second repository yourself, where you can see it.

The refusal happens before anything is cloned, so a bundle can’t use a nested include to probe for a remote it names. When a nested include is admitted and its clone fails, the error names both repositories but keeps git’s own transport detail behind RUST_LOG=debug — see the ratect.toml reference for why.

A grant goes on the entry that reaches the file first

A repository is cloned once and each file in it read once, however many entries reach it, so whichever entry gets there first decides what that file is allowed — and a grant on the loser would quietly do nothing. Entries in the root file are always reached before any bundle’s own, so declaring the include yourself beats a bundle to it; between two entries in the same file, the earlier one wins. Where two entries reach the same file and the losing one carries a grant, Ratect refuses to load, names the repository and gives the ordering rule above, rather than leaving you to wonder why the flag had no effect. It can’t name the winning entry for you, and that entry is often inside a bundle you can’t edit — in which case the move is to declare the include yourself, in your root file, where it gets there first. Both grants follow this rule.

It is the file that races, not the repository: two entries naming the same repository with different paths pull in two different files, and each keeps the grant written on its own entry.

That is a different case from a grant written inside a bundle, which two words could easily blur. A grant written inside a bundle file is ignored — accepted by the parser and worth nothing, because honouring it would let a bundle grant itself. A grant in your own configuration that loses the race above is refused — the load stops, because you wrote something that cannot take effect and nothing else would tell you.

The version a bundle was written for

In a ratect.toml project, a bundle is checked the way the project itself is by its ratect_version: ratect refuses it when a later release has changed what its configuration means, and lists those changes. The project’s own ratect_version doesn’t cover it — raising yours says you reviewed your configuration, not every bundle it includes. Either of two fields covers a bundle, and whichever names the later version counts:

  • The bundle’s own ratect_version, set by its author in the file the Git include names — its entry file. It covers every file reached from there, as a root’s covers its project. It is refused in any other file a bundle loads, and in a YAML file.

  • The include entry’s reviewed_ratect_version: you, as the author of the include, saying you reviewed the bundle against the changes up to that version. It lets you answer a refusal for a bundle you don’t own without waiting for its author. Like the grants it is native-only, so the entry has to be in a .toml file:

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

A bundle that sets neither counts as written for 0.3.0, the first release with ratect.toml, so it is refused under any release that has changed what a configuration means since. The refusal names the bundle’s repository, ref and entry file, and the file declaring the include, and offers both ways out — when that file is a .yml, the second starts with getting that include into TOML, the way that file allows. Like a project’s, it says for each change whether it touches the bundle, looking only in the bundle’s own files — or, if the project doesn’t load, in its entry file alone; whether it loads is the whole project’s answer.

  • Every entry is checked on its own. Two entries reaching one bundle each need covering, by the bundle’s version or their own reviewed_ratect_version — unlike a grant, no entry wins.
  • A nested bundle is a bundle of its own, covered by neither its parent’s version nor yours. The parent bundle’s entry for it may set reviewed_ratect_version if that bundle file is TOML: it widens no permission, so unlike a grant it counts in a bundle file too. A YAML bundle file can’t set it, so a TOML bundle it nests is covered only by its own ratect_version.
  • A YAML entry file follows Batect’s rules, as a batect.yml root does: it can’t set ratect_version, and a bundle whose files are all YAML loads whatever has changed. That includes a change to how Ratect reads YAML: such a change brings Ratect’s reading closer to Batect’s, which is what the bundle was written for. Once a YAML entry file includes a .toml file, the bundle counts as written for 0.3.0, until its include sets reviewed_ratect_version.
  • A version newer than ratect is refused, on either side. A bundle written for a newer Ratect is refused before anything but that field is read, rather than for a field this one doesn’t know: upgrade ratect, or point the include’s ref at a release of the bundle written for this one. A reviewed_ratect_version newer than ratect is refused too, since it can’t check a review against changes it doesn’t know.

The acknowledgement isn’t tied to a ref: it still counts after you change the include’s ref, which is itself a change to review. No command writes it — ratect config convert never does. ratect-compat rejects reviewed_ratect_version as a ratect-native field, and checks no bundle.

What this does and doesn’t buy you

None of this makes a bundle safe to include blindly — it still runs code you didn’t write, the same as adding any dependency does. What it buys you is that the one attack this project has specifically hardened against (a bundle quietly reaching for your credentials via a host mount) needs an explicit, visible grant in your own file rather than working by default. Anything that lets a bundle read or write outside its clone or the project directory without that grant is a security bug — see SECURITY.md for how to report one.

Reusable Pipeline Building Blocks

This is about why you’d reach for a Git include, not the mechanics of one — those are on Includes, with the entries’ own fields in the batect.yml and ratect.toml references. This page motivates the use case first, then the trust model it depends on, since a bundle is code you didn’t write, running in your own environment.

The use case

Several projects that share a stack tend to end up wanting the same handful of things: the same linter run the same way, the same base image with the same hardening applied, the same “scan this for vulnerabilities” task. Copying a container/task definition into every project’s own config works, right up until the definition needs to change — then it’s a find-and-replace across however many repositories remembered to keep it in sync, and however many didn’t.

A bundle — a Git repository holding a configuration file, meant to be imported rather than run on its own — is Ratect’s answer: define the containers and tasks once, version the repository like any other code (tags, releases, a changelog), and let every consuming project pull in a pinned version with one include entry. Bump the pin when you’re ready to take a change; every consumer bumps on its own schedule, not in lockstep.

# ratect.toml
include = [
    { type = "git", repo = "https://github.com/my-org/lint-bundle.git", ref = "v2.1.0" },
]

[tasks.lint]
prerequisites = ["shared-lint"]

Here shared-lint isn’t defined anywhere in this project’s own file — it came from the bundle, merged in exactly as if it had been written locally (see how included files combine). The project’s own lint task just sequences it in as a prerequisite.

A bundle is untrusted code by default

A bundle doesn’t just define a container — it also controls the command that runs inside it, so Ratect loads it under a boundary: its containers may mount only inside the bundle’s own clone or your project directory unless you vouch for it with allow_host_paths, a grant counts only when written in your own configuration, and (in ratect.toml) its own Git includes are refused until you opt in per bundle. The rules, the two grants and what they do and don’t buy you are on Includes; decisions/0004 covers the full reasoning.

What a consuming project can and can’t change

A project can’t redefine a container that came from an include — declaring a container with the same name in your own file is a hard error, not an override. Two narrower ways to adapt a bundle’s container to your own project without forking it:

  • customise (both formats) — a task can override a non-main container’s environment, ports, and working_directory. Deliberately not volumes: letting a consumer silently add a mount to someone else’s container would undercut the containment above at the one place it actually matters. See TaskContainerCustomisation.
  • extends (ratect.toml only) — a container in your own file can inherit from one defined in an included bundle and layer its own fields on top, shallow-merged per field. Useful when a bundle ships a base image and expects projects to build on it rather than use it as-is. See extends.

A cache shared across projects, without a host mount

ratect.toml’s shared caches (scope = "shared" on a cache volume) are worth calling out specifically for a bundle that wants one Cargo registry or npm cache reused across every project that includes it. The alternative is a host path — local: ~/.cache/cargo — which means asking every consumer for allow_host_paths. A shared cache says the same thing directly, grants no host filesystem access, and stays under Ratect’s own control (ratect-shared-cache-<name>, alongside ~/.ratect/incl where Git includes themselves are cloned). If you’re authoring a native bundle whose whole purpose is a shared tool cache, reach for this before reaching for allow_host_paths.

Pinning and updating a bundle

A bundle’s (repo, ref) is cloned once and cached forever at ~/.ratect/incl — never re-fetched, even if ref later moves. This is why ref must be an immutable tag or a pinned commit SHA, never a branch: a branch ref would look like it updates and never actually would, which is worse than a pin that’s honest about being frozen. To take a bundle change, bump ref to a new tag (the versioning story that makes bundles worth having in the first place). If ref itself moved (a branch, or a re-pushed tag) rather than your own config changing, ratect has a purpose-built command for that: ratect includes refresh discards every cached clone and re-fetches it — see the CLI reference. ratect-compat has no equivalent subcommand, but both binaries share ~/.ratect/incl, so ratect includes refresh refreshes what a ratect-compat run cached too; failing that, delete the corresponding directory under ~/.ratect/incl by hand.

Authoring a bundle that supports both formats

A bundle repository is just a config file at a path, so there’s nothing format-specific about being a bundle. ratect.toml’s own Git-include resolution looks for ratect-bundle.toml first, then falls back to batect-bundle.yml when no path is given — so a bundle author can ship both files, and a project on either format includes the same repository and gets the file meant for it. See Includes for the exact lookup order.

Output Styles

--output/-o controls how much Ratect says about its own progress, and never where anything goes. What the task’s command prints streams through as written in every style but all, which prefixes each of its lines with the container’s name, as it does every other line. Both binaries take it (ratect on every command, ratect-compat on every invocation) and render each style with the same code (ui.rs), so this page is the one description of the four styles; the ratect and ratect-compat CLI references only link here.

Streams

Stdout is the result; stderr is everything said about producing it (decisions/0017). For a run, the result is the task container’s own output. Everything else — progress, the summary line, notices, warnings and errors — is about the run, and -o shapes how much of it is said, not which stream it is said on.

The two binaries differ in one thing: where their progress goes.

  • ratect writes its progress — the milestones, the summary line, and under all the prefixed lines of every container but the task’s own — to stderr. Its stdout is the task container’s output and nothing else, in every style (under all, each line prefixed with the container’s name), so ratect run test > out.txt captures the result alone and 2>/dev/null silences the conversation without touching it.
  • ratect-compat writes its progress to stdout, where Batect does, because a Batect project’s scripts may read it. Under simple those lines share stdout with the task’s own output, unmarked, exactly as under Batect; -o quiet is the escape for a script that needs stdout to be the container’s output alone, and -o all prefixes every line.

Three kinds of line reach stderr in every style, quiet included, from both binaries, whatever RUST_LOG is set to: an error (Error: in bold red, then the message), a warning (Warning: in bold yellow — a deprecated flag, a proxy bound to loopback that containers can’t reach, a credential helper that failed), and a notice (unmarked: the interrupt notice with its “press Ctrl+C again” instructions, the Cleanup complete. that follows it once cleanup is over, and what --no-cleanup* left in place and how to remove it). Only the fourth kind, progress, is shaped by -o. RUST_LOG filters Ratect’s internal diagnostics (Filtering RUST_LOG), which are a separate stream of breadcrumbs on stderr; nothing a user needs to act on is behind it.

A task’s own non-zero exit is reported by the exit code and, outside quiet, by the summary line — never by an Error: line; a run ended by a signal is reported by the interrupt notice and its exit code, and ends with Cleanup complete. (or the error saying what cleanup left behind) rather than a trailing Error: Interrupted. Error: is reserved for Ratect’s own failures: it could not run the task, or could not clean up after it. A failure to run a task that has started — an image that won’t pull, a dependency that never becomes healthy — is reported when it happens, before any cleanup line, and outside quiet the run then ends with the summary line’s other form, <task> failed after <duration>., where finished with exit code N would have gone. So does a run whose command exited 0 but whose cleanup then failed, after the error saying what was left behind; a command that exited non-zero keeps its finished with exit code N line whatever cleanup does. A failure before any task starts, such as a config that doesn’t load, is printed as the run exits, with no summary line, as is a prerequisite’s failure for the task waiting on it: the prerequisite’s own line is the one printed.

In every style, and in every command’s own output, a control character in a name or value from your configuration (a task, container, image or cache name, a path, a command, a Git include’s repo or ref), or in image build output, is printed escaped: \u{1b} for ESC, \r for a carriage return. A Git bundle or a config file can’t send your terminal escape sequences that way. A name’s or value’s line breaks and tabs are escaped too (\n, \t), error messages included, so neither can add a line of its own. A command and image build output keep theirs, as does the output of a program an error quotes, such as git’s. A container’s own output is printed as it was written.

Each style is shown below from the same real run — ratect run journey-test against examples/full-stack — so you compare styles rather than projects.

When --output isn’t given, Ratect auto-selects: fancy on an interactive console (the stream its progress goes to — stderr for ratect, stdout for ratect-compat — is a real terminal, TERM is set and not dumb, the terminal size is queryable, and there is no --no-color); simple otherwise. quiet and all are never auto-selected; ratect services up is the exception, which always uses all and refuses any other -o. So ratect run test > out.txt on a terminal still gets fancy — the pipe took the result, not the conversation — where ratect-compat test > out.txt gets simple.

fancy

The same real recording as the homepage, unedited — static text can’t convey an in-place repaint:

What the recording can’t tell you: there is no spinner — the animation is purely rewriting the block’s lines in place, as Batect’s is — and lines are clipped to the terminal’s current width. After that width changes, the block is drawn afresh below the old one rather than over it, since the terminal has re-wrapped the old lines. Because it repaints, it needs a terminal: an explicit -o fancy asks less than auto-selection does — TERM may be unset, but not dumb — and fails up front, with an error naming the reason, when the stream it checked isn’t a terminal, TERM is dumb, or the terminal size can’t be determined (Batect instead accepts it, then crashes on the first repaint when stdout isn’t a terminal, or garbles a TERM=dumb terminal with cursor movements it can’t perform). Works with --no-color — the repaint stays; bold/color go — a combination Batect rejects.

simple

ratect run journey-test -o simple, captured on a terminal in examples/full-stack:

Running journey-test...
Starting cache...
Starting db...
Started cache.
Started db.
cache has become healthy.
db has become healthy.
Running setup command psql -U postgres -c "ANALYZE visits;" (1 of 1) in db...
db has completed all setup commands.
Starting app...
Started app.
app has become healthy.
Running sh -c 'npm ci && node test.js' in journey-test...

added 6 packages, and audited 7 packages in 983ms

found 0 vulnerabilities
app responded: {"message":"Hello from Ratect!","visit_id":1000001,"total_visits":1000001,"count_source":"database"}
cache holds visits:count=1000001, confirming app and this container share the same cache
journey test passed

Cleaning up...
journey-test finished with exit code 0 in 9.1s.

Append-only, with no live-updating progress detail at all, so it is safe for CI logs and redirected output. A dependency that exits on its own while the task runs is reported as a milestone (db exited unexpectedly with exit code 137.), not a warning — the run’s failure, if one follows, is what explains it. The health/setup-command milestones are shown for dependency containers only. Under ratect the task’s own container has no readiness gate to report (see Dependency Readiness); under ratect-compat its readiness runs concurrently with its command (see task lifecycle), so printing them would drop a line into the middle of that command’s own output — all shows them. A readiness failure is still reported, on stderr, in every style.

Cleanup opens with Cleaning up..., or, when it follows a failure, names it — Cleaning up after journey-test exited with code 3..., or, when the task couldn’t run, the step and container that failed: Cleaning up after db did not become healthy..., Cleaning up after db's setup command 1 exited with code 3..., Cleaning up after cache's image failed to pull.... The Error: above it says why. all opens it the same way.

quiet

ratect run journey-test -o quiet, captured the same way:


added 6 packages, and audited 7 packages in 1s

found 0 vulnerabilities
app responded: {"message":"Hello from Ratect!","visit_id":1000001,"total_visits":1000001,"count_source":"database"}
cache holds visits:count=1000001, confirming app and this container share the same cache
journey test passed

No progress at all: stdout is exactly the task container’s own output (under ratect it is in every style but all, which prefixes each line with the container’s name; quiet is where ratect-compat matches it), and stderr carries only errors, warnings and notices. Nothing from app/db/cache — a dependency’s own stdout is never shown outside all, whatever the style.

quiet also switches a task listing (ratect tasks list, ratect-compat --list-tasks) to a machine-readable format: one task per line, sorted by name, as name alone or name<TAB>description — no header, no grouping. The ratect commands with a listing of their own (services list, caches, includes, resources, doctor) each have a quiet form of the same kind, described with the command in the ratect CLI reference.

all

ratect run journey-test -o all, captured the same way — long, because every line db, cache and app wrote during the run is here too:

journey-test | Running journey-test...
db           | Starting container...
cache        | Starting container...
db           | Container started.
cache        | Container started.
db           | ********************************************************************************
db           | WARNING: POSTGRES_HOST_AUTH_METHOD has been set to "trust". This will allow
db           |          anyone with access to the Postgres port to access your database without
db           |          a password, even if POSTGRES_PASSWORD is set. See PostgreSQL
db           |          documentation about "trust":
db           |          https://www.postgresql.org/docs/current/auth-trust.html
db           |          In Docker's default configuration, this is effectively any other
db           |          container on the same system.
db           |
db           |          It is not recommended to use POSTGRES_HOST_AUTH_METHOD=trust. Replace
db           |          it with "-e POSTGRES_PASSWORD=password" instead to set a password in
db           |          "docker run".
db           | ********************************************************************************
cache        | 1:C 28 Oct 2026 19:12:43.874 * oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo
cache        | 1:C 28 Oct 2026 19:12:43.874 * Redis version=7.4.11, bits=64, commit=00000000, modified=0, pid=1, just started
cache        | 1:C 28 Oct 2026 19:12:43.874 # Warning: no config file specified, using the default config. In order to specify a config file use redis-server /path/to/redis.conf
cache        | 1:M 28 Oct 2026 19:12:43.874 * monotonic clock: POSIX clock_gettime
cache        | 1:M 28 Oct 2026 19:12:43.874 * Running mode=standalone, port=6379.
cache        | 1:M 28 Oct 2026 19:12:43.874 * Server initialized
cache        | 1:M 28 Oct 2026 19:12:43.874 * Ready to accept connections tcp
db           | The files belonging to this database system will be owned by user "postgres".
db           | This user must also own the server process.
db           |
db           | The database cluster will be initialized with locale "en_US.utf8".
db           | The default database encoding has accordingly been set to "UTF8".
db           | The default text search configuration will be set to "english".
db           |
db           | Data page checksums are disabled.
db           |
db           | fixing permissions on existing directory /var/lib/postgresql/data ... ok
db           | creating subdirectories ... ok
db           | selecting dynamic shared memory implementation ... posix
db           | selecting default max_connections ... 100
db           | selecting default shared_buffers ... 128MB
db           | selecting default time zone ... Etc/UTC
db           | creating configuration files ... ok
db           | running bootstrap script ... ok
db           | performing post-bootstrap initialization ... ok
cache        | Container became healthy.
db           | syncing data to disk ... ok
db           |
db           |
db           | Success. You can now start the database server using:
db           |
db           |     pg_ctl -D /var/lib/postgresql/data -l logfile start
db           |
db           | initdb: warning: enabling "trust" authentication for local connections
db           | initdb: hint: You can change this by editing pg_hba.conf or using the option -A, or --auth-local and --auth-host, the next time you run initdb.
db           | waiting for server to start....2026-10-28 19:12:44.910 UTC [54] LOG:  starting PostgreSQL 16.15 (Debian 16.15-1.pgdg13+2) on aarch64-unknown-linux-gnu, compiled by gcc (Debian 14.2.0-19) 14.2.0, 64-bit
db           | 2026-10-28 19:12:44.911 UTC [54] LOG:  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
db           | 2026-10-28 19:12:44.913 UTC [57] LOG:  database system was shut down at 2026-10-28 19:12:44 UTC
db           | 2026-10-28 19:12:44.915 UTC [54] LOG:  database system is ready to accept connections
db           |  done
db           | server started
db           |
db           | /usr/local/bin/docker-entrypoint.sh: running /docker-entrypoint-initdb.d/01-schema.sql
db           | CREATE TABLE
db           | INSERT 0 1000000
db           | CREATE INDEX
db           |
db           |
db           | waiting for server to shut down....2026-10-28 19:12:46.289 UTC [54] LOG:  received fast shutdown request
db           | 2026-10-28 19:12:46.290 UTC [54] LOG:  aborting any active transactions
db           | 2026-10-28 19:12:46.291 UTC [54] LOG:  background worker "logical replication launcher" (PID 60) exited with exit code 1
db           | 2026-10-28 19:12:46.291 UTC [55] LOG:  shutting down
db           | 2026-10-28 19:12:46.292 UTC [55] LOG:  checkpoint starting: shutdown immediate
db           | 2026-10-28 19:12:46.435 UTC [55] LOG:  checkpoint complete: wrote 10152 buffers (62.0%); 0 WAL file(s) added, 0 removed, 10 recycled; write=0.057 s, sync=0.071 s, total=0.144 s; sync files=45, longest=0.028 s, average=0.002 s; distance=174130 kB, estimate=174130 kB; lsn=0/BEFF470, redo lsn=0/BEFF470
db           | 2026-10-28 19:12:46.440 UTC [54] LOG:  database system is shut down
db           |  done
db           | server stopped
db           |
db           | PostgreSQL init process complete; ready for start up.
db           |
db           | 2026-10-28 19:12:46.509 UTC [1] LOG:  starting PostgreSQL 16.15 (Debian 16.15-1.pgdg13+2) on aarch64-unknown-linux-gnu, compiled by gcc (Debian 14.2.0-19) 14.2.0, 64-bit
db           | 2026-10-28 19:12:46.510 UTC [1] LOG:  listening on IPv4 address "0.0.0.0", port 5432
db           | 2026-10-28 19:12:46.510 UTC [1] LOG:  listening on IPv6 address "::", port 5432
db           | 2026-10-28 19:12:46.513 UTC [1] LOG:  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
db           | 2026-10-28 19:12:46.517 UTC [77] LOG:  database system was shut down at 2026-10-28 19:12:46 UTC
db           | 2026-10-28 19:12:46.521 UTC [1] LOG:  database system is ready to accept connections
db           | Container became healthy.
db           | Running setup command psql -U postgres -c "ANALYZE visits;" (1 of 1)...
db           | Setup command 1 | ANALYZE
db           | Container has completed all setup commands.
app          | Starting container...
app          | Container started.
app          |
app          | added 99 packages, and audited 100 packages in 993ms
app          |
app          | 18 packages are looking for funding
app          |   run `npm fund` for details
app          |
app          | found 0 vulnerabilities
app          | npm notice
app          | npm notice New major version of npm available! 10.9.8 -> 12.2.1
app          | npm notice Changelog: https://github.com/npm/cli/releases/tag/v12.2.1
app          | npm notice To update run: npm install -g npm@12.2.1
app          | npm notice
app          |
app          | > full-stack-app@1.0.0 start
app          | > node server.js
app          |
app          | Listening on port 8080
app          | Container became healthy.
journey-test | Running sh -c 'npm ci && node test.js'...
journey-test |
journey-test | added 6 packages, and audited 7 packages in 906ms
journey-test |
journey-test | found 0 vulnerabilities
journey-test | app responded: {"message":"Hello from Ratect!","visit_id":1000001,"total_visits":1000001,"count_source":"database"}
journey-test | cache holds visits:count=1000001, confirming app and this container share the same cache
journey-test | journey test passed
journey-test | Cleaning up...
journey-test | Container stopped.
journey-test | Container removed.
app          | Container stopped.
app          | Container removed.
db           | 2026-10-28 19:12:50.860 UTC [1] LOG:  received fast shutdown request
cache        | 1:signal-handler (1793214770) Received SIGTERM scheduling shutdown...
db           | 2026-10-28 19:12:50.861 UTC [1] LOG:  aborting any active transactions
db           | 2026-10-28 19:12:50.862 UTC [1] LOG:  background worker "logical replication launcher" (PID 80) exited with exit code 1
db           | 2026-10-28 19:12:50.862 UTC [75] LOG:  shutting down
db           | 2026-10-28 19:12:50.864 UTC [75] LOG:  checkpoint starting: shutdown immediate
db           | 2026-10-28 19:12:50.883 UTC [75] LOG:  checkpoint complete: wrote 14 buffers (0.1%); 0 WAL file(s) added, 0 removed, 0 recycled; write=0.001 s, sync=0.013 s, total=0.021 s; sync files=12, longest=0.002 s, average=0.002 s; distance=20 kB, estimate=20 kB; lsn=0/BF044A8, redo lsn=0/BF044A8
db           | 2026-10-28 19:12:50.884 UTC [1] LOG:  database system is shut down
cache        | 1:M 28 Oct 2026 19:12:50.933 * User requested shutdown...
cache        | 1:M 28 Oct 2026 19:12:50.933 * Saving the final RDB snapshot before exiting.
cache        | 1:M 28 Oct 2026 19:12:50.936 * DB saved on disk
cache        | 1:M 28 Oct 2026 19:12:50.936 # Redis is now ready to exit, bye bye...
db           | Container stopped.
db           | Container removed.
cache        | Container stopped.
cache        | Container removed.
journey-test | Removing task network...
journey-test | Task network removed.
journey-test | journey-test finished with exit code 0 in 7.6s.

The only style that shows dependency containers’ stdout/stderr, setup-command output, and full image-build output (Image build | ...) — everything the other styles discard. In exchange, no container is interactive in this mode: the task container gets no TTY and no stdin, and every container gets TERM=dumb (matching Batect — a full-screen program can’t render into line-prefixed output). That is why, next to simple’s capture, npm draws no spinner here.

Nothing in examples/ builds from a Dockerfile (every container uses a prebuilt image), so Image build | ... output has no real capture to point at here.

Colour

Colour in Ratect’s own output (the exit code in the summary line, all’s per-container prefixes, the Error:/Warning: markers, and the bold that picks out task, container and image names and commands in simple and fancy progress) is, by default, emitted only when the stream being written to is a terminal — each stream decides for itself, so with ratect run test > out.txt the progress on stderr is still coloured while a 2>err.txt gets plain text, RUST_LOG lines included — and a task command’s own output is never touched either way. No message depends on its colour to be read: colour only distinguishes one container’s prefix from another’s or emphasises a marker word, a name or the exit code, and Ratect never paints text in the terminal’s own white or black, which some themes render invisible. Three controls adjust that, and their precedence is fixed:

ControlEffect
--no-colorDisables colour in Ratect’s own output, on both streams. Since colour is already skipped when a stream isn’t a terminal, this only matters on an interactive console — unless CLICOLOR_FORCE is also set, which it overrides. Also makes simple, not fancy, the auto-selected style; an explicit -o fancy --no-color still gets a colourless fancy.
NO_COLORIf set — to anything, even empty, per no-color.org — exactly the same effect as --no-color.
CLICOLOR_FORCEIf set to anything other than 0, forces colour even when a stream isn’t a terminal (a CI log viewer that renders ANSI despite the pipe). Never affects which style is auto-selected.

--no-color/NO_COLOR always win: if either is set, CLICOLOR_FORCE is ignored.

Connecting to Docker

Every command that reaches a Docker daemon takes the same set of connection options, on both binaries: ratect run, ratect caches, ratect resources and ratect doctor each accept them (ratect tasks list, ratect includes and ratect config never connect, so they don’t), and ratect-compat accepts them on every invocation and uses them whenever the invocation actually connects (a --list-tasks run never does) — though it checks a Docker config or certificate directory given by an option or DOCKER_CONFIG/DOCKER_CERT_PATH, and a file given to a TLS option, on every one. On both binaries, --docker-context beside --docker-host or a TLS option is refused whether or not the command connects — ratect caches with the directory store, or a ratect-compat --list-tasks, included — and ratect doctor reports it as a problem. This page is the one description of those options; the ratect and ratect-compat CLI references only link here.

With none of them given, Ratect connects to DOCKER_HOST if it is set, otherwise through a Docker context if one resolves (DOCKER_CONTEXT, then the active context), otherwise to Docker’s own platform default, the Unix socket unix:///var/run/docker.sock — see Which daemon is used.

Options

FlagDefaultDescription
--docker-host <HOST>DOCKER_HOSTDocker host to connect to, e.g. unix:///var/run/docker.sock or tcp://1.2.3.4:5678. An https:// host connects over TLS as if --docker-tls-verify were given. Cannot be combined with --docker-context.
--docker-context <NAME>DOCKER_CONTEXT, then the active context, unless a host is setDocker CLI context to connect through — read from the Docker CLI’s own context store (~/.docker/contexts/, or --docker-config’s directory). The active context is ~/.docker/config.json’s currentContext. Cannot be combined with --docker-host or any of the TLS options below. Errors clearly if the named context doesn’t exist in the store.
--docker-config <PATH>DOCKER_CONFIG, then ~/.dockerDirectory containing the Docker CLI’s own configuration files (context store, config.json). A directory given here or by DOCKER_CONFIG must exist and be a directory; ~/.docker needn’t exist.
--docker-tls—Use TLS when connecting to the Docker host. Behaves identically to --docker-tls-verify — the daemon’s certificate is always fully verified; there is no way to skip verification.
--docker-tls-verifyDOCKER_TLS_VERIFYUse TLS when connecting to the Docker host, verifying its certificate. Needs a host: --docker-host or DOCKER_HOST.
--docker-cert-path <PATH>DOCKER_CERT_PATH, then --docker-config/DOCKER_CONFIG, then ~/.dockerDirectory containing any of ca.pem/cert.pem/key.pem to authenticate to the Docker host and verify it, unless overridden individually by the three options below. A directory given here or by DOCKER_CERT_PATH must exist and be a directory, whether or not TLS is used. None of the three files has to be there — see TLS through the options.
--docker-tls-ca-cert <PATH>ca.pem in the certificate directoryThe TLS CA certificate used to verify the Docker host’s own certificate — the only certificate authority it is checked against. The file must exist. Without this option and without a ca.pem, the system trust store is used.
--docker-tls-cert <PATH>cert.pem in the certificate directoryThe TLS certificate used to authenticate to the Docker host. The file must exist, and so must the key.
--docker-tls-key <PATH>key.pem in the certificate directoryThe TLS key used to authenticate to the Docker host. The file must exist, and so must the certificate.

A path given to --docker-config, --docker-cert-path, --docker-tls-ca-cert, --docker-tls-cert or --docker-tls-key, or by DOCKER_CONFIG or DOCKER_CERT_PATH, has a leading ~ expanded to your home directory, and . and .. removed, before it is used, as in Batect. The Docker CLI takes the two variables as written. Your home directory, here and for ~/.docker, is $HOME when it is set and absolute, else your passwd entry’s: the Docker CLI’s rule, so Ratect reads the ~/.docker that docker login writes to. The Docker CLI also takes a relative $HOME; Ratect doesn’t. With no home from either, as under a numeric docker run -u with HOME unset, there is no ~/.docker: Ratect connects with no stored credentials, and refuses a named context or TLS that would read its certificates from there unless --docker-config or DOCKER_CONFIG names a directory instead.

TLS through the options

With --docker-tls or --docker-tls-verify (or DOCKER_TLS_VERIFY), or an https:// host, the certificate directory is --docker-cert-path, then DOCKER_CERT_PATH, then the Docker config directory if one was given (--docker-config, then DOCKER_CONFIG), then ~/.docker (an empty DOCKER_CERT_PATH counts as unset). A directory given by any of those four sources must exist, and every command that connects checks it first; ~/.docker must exist unless all three files are named by their own options. What it holds decides how the connection is made:

  • --docker-tls-ca-cert, or else the directory’s ca.pem, is the only certificate authority the daemon’s certificate is checked against. With neither, the system trust store is used — for a daemon whose certificate a public certificate authority signed.
  • --docker-tls-cert and --docker-tls-key, or else the directory’s cert.pem and key.pem, are presented as the client certificate. With neither option and neither file, none is presented. Only one of the two files in the directory is an error, and so is giving one option when the directory doesn’t hold the other file.
  • A file named by an option must exist and not be a directory, whether or not TLS is used: every command that takes the option checks it before it runs. It needn’t be a regular file — a pipe, such as <(cat key.pem), is read like one, once.
  • An encrypted key, or one that doesn’t match the certificate, is an error naming the option or the directory, and the file.
  • Only a tcp:// or https:// host, or a bare host:port, can be connected to over TLS.

If the daemon’s certificate fails verification and no certificate authority was given, the error says where a ca.pem was looked for. A daemon with a self-signed or privately signed certificate needs one — see TLS with a private certificate authority.

A Docker context follows the same file rules with the files it stores — see below.

Which daemon is used

A flag always wins over its environment variable. Between the two ways of naming a daemon, the order is:

  1. --docker-context <NAME> on the command line, if given.
  2. Otherwise, a host — --docker-host, then DOCKER_HOST — if either is set. No context is consulted at all.
  3. Otherwise a context, if one resolves: DOCKER_CONTEXT, then the active context.
  4. Otherwise Docker’s own platform default.

This is the Docker CLI’s own order. A context named default — from any of the three sources — means “no context”, as in the Docker CLI: Ratect connects to DOCKER_HOST if it is set, otherwise to the platform default. An empty DOCKER_HOST or DOCKER_CONTEXT counts as unset, also as in the Docker CLI.

The active context is the currentContext in the Docker config directory’s config.json, read only when step 3 gets that far. A config.json that can’t be read, or isn’t valid JSON, has none to give: Ratect warns, naming the file, and goes on to step 4, as the current Docker CLI does.

A connection through a context uses the endpoint that context stores; the TLS options only apply to a host connection. Naming one alongside --docker-context is an error; when step 3 picks the context instead, the TLS options are ignored, as in Batect.

A context brings its own TLS settings instead — the ones docker context create stored for it — used as the Docker CLI uses them:

  • The context connects over TLS if it stores a ca.pem, a cert.pem/key.pem pair, or sets SkipTLSVerify. Otherwise it connects without TLS.
  • A stored ca.pem is the only certificate authority the daemon’s certificate is checked against. Without one, the system trust store is used.
  • A stored cert.pem/key.pem pair is presented as the client certificate. Without one, none is. Storing only one of the two is an error.
  • An encrypted key.pem, or one that doesn’t match cert.pem, is an error naming the context and the file.
  • Only a tcp:// or https:// host can be connected to over TLS.

A context naming an https:// host also connects over TLS, storing TLS material or not — the same as --docker-host https://…, and unlike the Docker CLI, which connects to such a host without TLS unless the context stores some.

SkipTLSVerify is not honoured: the daemon’s certificate is always fully verified, as with --docker-tls. If verification fails for a context that sets it, the error says so — see TLS with a private certificate authority for making the certificate verifiable instead.

What is checked on connecting

Before asking the daemon for anything else, Ratect checks three things, and stops with an error if any fails:

  • That it answers. When no connection can be made at all — nothing listening, a host name that doesn’t resolve, no route to it — the error says the daemon couldn’t be reached, names the host tried and what chose it (--docker-host, DOCKER_HOST, a context, or the platform default), and suggests checking that Docker is running and that the host or context is the right one. The underlying reason follows as its cause.
  • That it is Docker 20.10 or newer (API 1.41) — see Installation for why.
  • That it runs Linux containers. A daemon in Windows containers mode is refused, naming the operating system it reports: switch Docker to Linux containers to use Ratect.

Environment variables

VariableEffect
DOCKER_HOSTDocker host to connect to — the default for --docker-host. Setting it means no context is used unless --docker-context is given. Empty counts as unset.
DOCKER_CONTEXTDocker CLI context to connect through — the default for --docker-context. Ignored when a host is set. Empty counts as unset.
DOCKER_CONFIGDirectory containing the Docker CLI’s own configuration files — the default for --docker-config, and for --docker-cert-path when DOCKER_CERT_PATH is unset. Must exist and be a directory when set and not empty. A leading ~ is your home directory, as for the option.
DOCKER_CERT_PATHDirectory containing any of ca.pem/cert.pem/key.pem for TLS — the default for --docker-cert-path. Empty counts as unset; otherwise it must exist and be a directory. A leading ~ is your home directory, as for the option.
DOCKER_TLS_VERIFY1, yes or true enables TLS, fully verified, and 0, no or false leaves it off, in any case — the default for --docker-tls-verify. Empty counts as unset. Any other value is an error when connecting to a host, unless --docker-tls or --docker-tls-verify is given; a command that doesn’t connect, or connects through a context, never reads it — though ratect doctor reports one as a problem whichever way it connects.

TLS with a private certificate authority

--docker-tls/--docker-tls-verify always fully verify the Docker daemon’s certificate — there is no flag or environment variable that skips verification, unlike Batect’s own bare --docker-tls (which sets Go’s tls.Config.InsecureSkipVerify, disabling chain-of-trust, expiry, and hostname checks all at once, not just the hostname check). This isn’t just inherited from a missing feature: rustls, the library Ratect’s TLS support is built on, takes the same position deliberately — there’s no boolean toggle for skipping verification in rustls either, only a dangerous() accessor that requires implementing the ServerCertVerifier trait from scratch to bypass it. Ratect doesn’t reach for that. If you reach for --docker-tls (skip-verify) because your daemon’s certificate is self-signed — including for local development or CI — the fix isn’t to skip verification, it’s to make the certificate verifiable: run your own certificate authority, and trust that, rather than trusting nothing.

The daemon side of this (configuring dockerd to require TLS, generating its server certificate) is standard Docker documentation, not Ratect-specific — see Protect the Docker daemon socket. What follows is the client side: a self-contained, worked example of generating a private root CA, signing a server certificate for the daemon with it, and pointing Ratect at the result.

  1. Create a root CA. This is the one certificate you’ll trust from now on — keep ca-key.pem private; it’s the only thing standing between “verified” and “not”.

    openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
      -keyout ca-key.pem -out ca.pem -subj "/CN=my-docker-ca"
    
  2. Generate and sign the daemon’s own certificate, naming every hostname/IP clients will actually connect through as a Subject Alternative Name (SAN) — verification checks this, not the certificate’s CN:

    openssl req -newkey rsa:4096 -sha256 -nodes \
      -keyout server-key.pem -out server-req.pem -subj "/CN=docker-daemon"
    openssl x509 -req -in server-req.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial \
      -out server-cert.pem -days 3650 -sha256 \
      -extfile <(printf "subjectAltName=DNS:docker-daemon.example.com,IP:203.0.113.10")
    
  3. Configure dockerd to require TLS with this certificate (/etc/docker/daemon.json or the equivalent dockerd flags — see the Docker documentation linked above), using ca.pem/server-cert.pem/server-key.pem from steps 1–2.

  4. Point Ratect at the CA (client certificate/key are only needed if the daemon itself also requires client auth — generate a second cert signed by the same CA for that, following step 2’s pattern):

    ratect run test \
      --docker-host tcp://docker-daemon.example.com:2376 \
      --docker-tls-verify \
      --docker-tls-ca-cert ./ca.pem
    

    ratect-compat takes the same three options, before the task name. Or set --docker-cert-path to a directory containing ca.pem (and cert.pem/key.pem, if the daemon requires client auth) instead of naming each file individually — see Options. Leave the CA out altogether and the daemon is checked against the system trust store, which a private CA is not in: verification fails, and the error says where a ca.pem was looked for. A Docker context created with the same files (docker context create my-daemon --docker "host=tcp://docker-daemon.example.com:2376,ca=./ca.pem") works too, through --docker-context my-daemon — see Which daemon is used.

If verification fails, the error names the problem (expired, wrong host, untrusted issuer) rather than silently connecting anyway — that’s the entire point of not supporting skip-verify. Regenerate whichever certificate is actually at fault, rather than reaching for a flag Ratect doesn’t have.

File Ownership and the Home Directory

A task that writes through a bind mount, such as a build writing its output or a formatter its fixes, writes onto your machine. Who owns those files on the host depends on the daemon and on the user the container runs as. On a rootful Linux daemon, an image with no USER writes them as root: files you can’t edit, and directories you can’t remove. Separately, a program inside the container that looks under ~ for its configuration finds the home of the image’s user, which differs from image to image.

identity does both jobs. What a container writes through a bind mount is yours wherever the daemon allows it, and $HOME is the path you name, on every daemon and in every image, so ssh configuration and caches can be mounted below it once:

[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 the rest of this page walks through. The reference has every rule identity follows; this page is what those rules add up to on each daemon.

Who owns what a container writes

Which kind of daemon you have is the Docker daemon class line of ratect doctor. On each, a container writing to a directory of yours through a bind mount gives this:

Daemon classImage’s USERRuns asOwner on the host, without identityOwner on the host, with identity
rootful Linuxroot, or noneroot, or you with identityrootyou
rootful Linuxnon-root, such as appthat user, or you with identitythat user’s uid, where the directory lets others writeyou
desktopanythe image’s USER, or rootyouyou
rootlessroot, or nonerootyouyou
rootlessnon-rootthat usera subordinate uid, where the directory lets others writethe same, and the run warns
userns-remapanythe image’s USER, or roota subordinate uid, where the directory lets others writethe same, and the run warns

How each daemon gets there:

  • On a rootful Linux daemon a file’s owner is the uid of the process that wrote it, so identity runs the container as your uid and gid. Without it, a non-root image USER can only write where the directory lets anyone write, and a directory you created with the usual 0755 refuses it.
  • Docker Desktop, OrbStack and similar on macOS or Windows share files with the host as you, whoever wrote them in the container. identity leaves the image’s USER running.
  • A rootless daemon maps root in the container to you, so an image that runs as root writes your files without identity. Any other container user maps to a subordinate uid, which has only other users’ access to your directory.
  • A userns-remap daemon maps every container user to a subordinate uid, root included. Root in the container writes as uid 100000, say, so a directory you own with 0755 refuses it.

Where the owner is a subordinate uid, nothing Ratect can apply makes it yours, so a run warns about each identity container that meets it, naming the container, and ratect doctor reports the userns-remap case. That ownership has to be arranged on the host. The home is still guaranteed there.

Writing through a bind mount

The example has a second container, the same image and mount without identity, and a task that writes through each:

[containers.as-image]
image = "alpine:3.24"
working_directory = "/code"
volumes = [{ local = ".", container = "/code" }]

[tasks.write-as-you]
description = "Write out/as-you/ through the bind mount, with identity"
run = { container = "as-you", command = "sh -c 'mkdir -p out/as-you && id -u > out/as-you/uid'" }

[tasks.write-as-image]
description = "Write out/as-image/ through the bind mount, without identity"
run = { container = "as-image", command = "sh -c 'mkdir -p out/as-image && id -u > out/as-image/uid'" }

[tasks.clean]
description = "Remove what the write tasks left in out/, whoever owns it"
run = { container = "as-image", command = "rm -rf out/as-you out/as-image" }

ratect run write-as-image -o quiet && ratect run write-as-you -o quiet && ls -lnd out/* out/*/*, captured on a terminal in examples/identity, on a rootful Linux daemon:

drwxr-xr-x 1    0    0 6 Nov  8 22:35 out/as-image
-rw-r--r-- 1    0    0 2 Nov  8 22:35 out/as-image/uid
drwxr-xr-x 1 1001 1001 6 Nov  8 22:35 out/as-you
-rw-r--r-- 1 1001 1001 5 Nov  8 22:35 out/as-you/uid

alpine has no USER, so without identity its directory and file are root’s. With identity they belong to uid 1001, the user who ran Ratect. The same command on a desktop daemon, OrbStack on macOS, where both containers ran as root:

drwxr-xr-x@ 3 501  20  96 Nov  8 22:35 out/as-image
-rw-r--r--@ 1 501  20   2 Nov  8 22:35 out/as-image/uid
drwxr-xr-x@ 3 501  20  96 Nov  8 22:35 out/as-you
-rw-r--r--@ 1 501  20   2 Nov  8 22:35 out/as-you/uid

Both are yours there, identity or not, since file sharing makes them so.

Removing what root left behind

A root-owned directory can’t be removed without root, even in a directory you own: removing a directory means removing what is in it, and that takes write access to the directory itself. The clean task does it from a container without identity, which runs as root. rm -rf out/as-image; ratect run clean -o quiet && ls -A out, captured on a terminal in examples/identity, on a rootful Linux daemon:

rm: cannot remove 'out/as-image/uid': Permission denied
.gitignore

out/.gitignore is the one file the project keeps there, so out itself is yours from the moment you clone it. Without it, the first task to write there would create out, and on a rootful Linux daemon a container without identity would create it as root, leaving the next one with identity unable to write inside it.

To see all of this on your own daemon:

ratect run write-as-image
ratect run write-as-you
ls -lnd out/* out/*/*
ratect run clean

The same home on every daemon

[tasks.show-home]
description = "Show the running user, its groups and its home"
run = { container = "as-you", command = """sh -c 'echo "user:   $(id -un) ($(id -u)), groups: $(id -Gn)"; echo "HOME:   $HOME"; echo "passwd: $(getent passwd $(id -u) | cut -d: -f6)"; ls -ld ~ ~/.ssh'""" }

ratect run show-home -o quiet, captured on a terminal in examples/identity, on a desktop daemon:

user:   root (0), groups: root bin daemon sys adm disk wheel floppy dialout tape video users
HOME:   /home/me
passwd: /home/me
drwxr-xr-x    1 root     root             8 Nov  8 22:35 /home/me
drwxr-xr-x    1 root     root            96 Nov  8 22:31 /home/me/.ssh

and on a rootful Linux daemon:

user:   runner (1001), groups: runner users
HOME:   /home/me
passwd: /home/me
drwxr-xr-x    1 runner   runner           8 Jan  1  1970 /home/me
drwxr-xr-x    1 runner   runner          12 Nov  8 22:35 /home/me/.ssh

The running user differs, root on one and you on the other, but $HOME and that user’s /etc/passwd entry agree on /home/me on both, so Git, which reads $HOME, and ssh, which reads the passwd entry, both look there. On the rootful daemon the image had no entry for uid 1001, so one was added with your username.

The read-only mount at ~/.ssh is below the home, so Docker created /home/me before Ratect could, as root. Where the running user isn’t root, the home is handed over to them, which is why it is runner’s on the rootful daemon. groups works alongside identity, adding users to whoever runs.

An image with its own user and home

Some images run as a non-root user with a home of their own. The example builds one:

# A non-root user with its own home, as many language images have.
RUN adduser -D -u 1000 app
ENV HOME=/home/app

# A fresh cache volume takes its owner and mode from the image's directory at
# the same path, here below the `app` container's `identity` home in
# ratect.toml. Writable by anyone, so whoever the container runs as can fill
# the `prepared` cache. The `unprepared` one has no directory here.
RUN mkdir -p /home/me/.cache/prepared && chmod 777 /home/me/.cache/prepared

USER app

and runs it with identity and two cache volumes below the home:

[containers.app]
build_directory = "app-image"
identity = { home = "/home/me" }
volumes = [
    { type = "cache", name = "prepared", container = "/home/me/.cache/prepared" },
    { type = "cache", name = "unprepared", container = "/home/me/.cache/unprepared" },
]

[tasks.show-app-home]
description = "Show the running user and its home in an image with its own USER and HOME"
run = { container = "app", command = """sh -c 'echo "user:   $(id -un) ($(id -u))"; echo "HOME:   $HOME"; echo "passwd: $(getent passwd $(id -u) | cut -d: -f6)"'""" }

ratect run show-app-home -o quiet, captured on a terminal in examples/identity, on a desktop daemon:

user:   app (1000)
HOME:   /home/me
passwd: /home/me

and on a rootful Linux daemon:

user:   runner (1001)
HOME:   /home/me
passwd: /home/me

The image’s app user runs on one and you on the other, and identity’s home replaces the image’s ENV HOME on both.

Cache volumes below the home

[tasks.fill-caches]
description = "Write to the two cache volumes below the home"
run = { container = "app", command = "sh -c 'set -e; touch ~/.cache/prepared/ok; echo prepared: written; touch ~/.cache/unprepared/ok; echo unprepared: written'" }

ratect run fill-caches -o quiet, captured on a terminal in examples/identity, on a desktop daemon, where the task fails:

prepared: written
touch: /home/me/.cache/unprepared/ok: Permission denied

and on a rootful Linux daemon, where it passes:

prepared: written
unprepared: written

A fresh volume is root-owned unless the image has a directory at the same path, whose owner and mode it then takes. On a rootful Linux daemon, Ratect hands a root-owned cache volume to you before the container starts, so both caches are writable there. Everywhere else, app can’t write to the unprepared volume. The prepared one takes mode 777 from the image’s directory, so it is writable on every daemon.

chown app in the image would fix the desktop daemon and break the rootful one: there you run instead of app, and Ratect leaves a volume another uid owns alone. A volume that has already been created keeps its owner, so after changing the image, remove the cache to have it created again.

Setting HOME yourself

A HOME in environment wins over identity’s, though the passwd entry still says home:

[tasks.show-home-override]
description = "Show the home when HOME is set in environment"
run = { container = "as-you", environment = { HOME = "/code" }, command = """sh -c 'echo "HOME:   $HOME"; echo "passwd: $(getent passwd $(id -u) | cut -d: -f6)"'""" }

ratect run show-home-override -o quiet, captured on a terminal in examples/identity, on a desktop daemon:

HOME:   /code
passwd: /home/me

So Git looks in /code and ssh in /home/me. Leave HOME out of environment unless that split is what you want.

What identity leaves to you

  • It is opt-in. A container without it on a rootful Linux daemon writes as its image’s USER, or root if it has none. Unless it sets a non-root user, ratect doctor warns about each of its writable bind mounts, since it doesn’t pull the image to see its USER.
  • home is required, even if ownership is all you want.
  • An entrypoint that drops privileges, as postgres does, writes as the user it switches to, whoever the container started as.
  • A daemon on another machine (ssh://, tcp://) still gets the uid and gid of the user running Ratect, which needn’t be yours on that machine. Ratect creates no host directories for it, so the daemon creates a missing bind mount source as root.
  • Docker Desktop on Linux is a rootful Linux daemon to Ratect, so identity runs the container as you there too, although its file sharing may make what it writes yours anyway. See On a rootful Linux daemon.

Coming from Batect? identity has the same goal as run_as_current_user, and Coming from run_as_current_user says which daemons get which mechanism.

Where to go next

  • Every rule identity follows, including adding service users an image lacks, is in the identity reference.
  • Which daemon Ratect connects to, and how to choose another, is Connecting to Docker.
  • The next page, Interactive Mode, covers when a task’s container gets a terminal.

Interactive Mode

A task whose command drops you into a shell, or otherwise needs your input, works with nothing to configure: there is no interactive field in either format, and the same task is interactive under both binaries. This page is the one description of what that means — which container is eligible, what it gets, when a real terminal is allocated, and how the container learns what kind of terminal it has. The examples are ratect.toml; the batect.yml spelling is the same fields with the same meaning.

[tasks.shell]
description = "Start a shell in the app's environment"
group = "Utilities"
run = { container = "dev", command = "bash" }

ratect run shell lands you in bash inside dev, with your keystrokes reaching it and its output reaching you. That is the full-stack example’s own shell task; each project on Worked Examples carries one too.

Which container is eligible

Each task’s own container — the task named on the command line, and every prerequisite it runs, however deeply nested. A dependency’s or a sidecar’s container is never interactive. Prerequisites run one after another, and each task container is attached to Ratect’s stdin only while it runs. Whatever input is waiting meanwhile is forwarded to it, whether or not it reads it, so a prerequisite takes piped input ahead of the named task. If the pipe ends while it runs, the named task’s stdin is closed from the start. What you type at a terminal goes to the task container running at the time; what you type between two of them waits for the next.

What the eligible container gets

Always, independent of whether Ratect’s own stdin and stdout are terminals, its stdin forwarded from Ratect’s own, so piped input reaches the container — including its end: when Ratect’s own stdin closes, so does the container’s, and a process that reads until end of input (cat, a stdio server) exits. (The host’s TERM isn’t the eligible container’s alone: every container gets it — see TERM propagation below.)

Additionally, when both Ratect’s own stdin and stdout are real terminals, a real Docker TTY: the local terminal goes into raw mode for the session, so a full-screen program (an editor, top, a REPL with line editing) renders as it would in a shell. The terminal is restored when the session ends; if that fails, a warning says so and names the fix (reset or stty sane). A raw terminal sends Ctrl+C to the container as a keystroke, as docker run -it does, so it interrupts the program in the container rather than the run — and a command running as the container’s main process with no handler of its own ignores it. Piped output, a redirected non-terminal, or a CI job gets plain stdin forwarding and streamed output instead — stdin still reaches the container either way.

The one exception is --output all, whose line-prefixed output can’t host an interactive session: under it no container gets a TTY or stdin, and every container gets TERM=dumb instead, matching Batect.

Terminal resizing

When a TTY is allocated, the container’s stays in sync with the local terminal’s size for the whole session, not just once at the start — a local resize is forwarded live, via a SIGWINCH handler. That tracking is Unix-only; on other platforms the size is synced once, at the start of the session, and not tracked further. Interactive mode itself works on every platform.

TERM propagation

Ratect’s own TERM environment variable is copied into the environment of every container a run creates — the invoked task’s own, each prerequisite’s, and every dependency and sidecar — whether or not that container is eligible, matching Batect. Under --output all every container gets TERM=dumb instead. It isn’t gated on a real TTY actually being allocated either, so a full-screen program inside the container knows the terminal type even when piped output lets it detect that it isn’t attached to a real TTY. Never applied to an image build.

Where it sits among the container’s other environment variables — what overrides it on a key collision — is Environment precedence.

Coming from Batect? One known, deliberate divergence: Batect’s real-TTY gate checks only whether its output is a real terminal; Ratect’s requires both stdin and stdout to be. It is listed, with the Unix-only resize tracking, under Differences from Batect.

Proxies

When http_proxy, https_proxy, ftp_proxy or no_proxy are set in the environment Ratect itself runs in — in either case, so HTTP_PROXY too — they are injected into every container’s environment and every image build’s build arguments. A task or a build that needs to reach the network through a proxy just works, without repeating the proxy settings in environment or build_args by hand. There is no config field for this in either format; it is automatic, on both binaries, and --no-proxy-vars turns it off. This page is the one description of what is injected, how it is adjusted for a container’s point of view, and what it can’t fix.

Precedence

Where an injected variable sits among a container’s other environment variables, and among a build’s build_args — what overrides it on a key collision — is Environment precedence.

Proxies from Docker’s config.json

An image build also gets the proxies set in the proxies section of the Docker CLI’s config.json, as docker build and Batect builds do. It is the same file Ratect reads registry credentials and contexts from: in the directory --docker-config names, else DOCKER_CONFIG, else ~/.docker.

{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy.example.com:3128",
      "noProxy": "internal.example.com"
    }
  }
}

The entry used is the one keyed by the Docker host the run connects to, spelled as the Docker CLI spells it (unix:///var/run/docker.sock, tcp://build-host:2376), else default. Each of its httpProxy, httpsProxy, ftpProxy, noProxy and allProxy becomes a build argument in both cases — HTTP_PROXY and http_proxy, and so on — but only where the build doesn’t already have that argument, so a proxy from the environment and a container’s own build_args both win over it. The values are passed as written: none of the adjustments below are made to them.

This is for image builds only; a container’s environment gets nothing from config.json. A missing config.json, or one with no proxies, adds nothing.

no_proxy is extended

Every container sharing a task’s network — the task’s own container and each of its dependencies — has its own name appended to no_proxy/NO_PROXY, so traffic between them isn’t sent through the proxy. Not done for image builds: nothing is running yet during a build, so there is nothing to exempt.

A proxy on localhost

An http_proxy/https_proxy/ftp_proxy value that points at localhost, 127.0.0.1 or ::1 is rewritten to host.docker.internal, since localhost from inside a container refers to the container itself, not the machine running the proxy. A value that isn’t an http/https URL, or doesn’t refer to the local machine, is left unchanged.

This happens on every platform, including Linux — where, unlike under Docker Desktop, nothing supplies host.docker.internal by itself. So a run that rewrote a URL also adds host.docker.internal:host-gateway to every container it starts and every image it builds, using Docker’s own --add-host mechanism, which the daemon resolves to the machine running it. That entry is added on every platform too, not only the one that needs it: on macOS and Windows it names the same gateway Desktop would have answered with, so it is a new /etc/hosts line rather than a change in what the container can reach. What gates it is the rewrite, not the platform — no rewrite, no entry — and a container’s own additional_hosts entry for that name always wins over it.

A proxy bound to loopback only

Rewriting the URL can’t make an unreachable proxy reachable. A proxy bound only to 127.0.0.1 — which is what cntlm and similar default to — still refuses a connection from a container, so on Linux Ratect checks /proc/net/tcp/tcp6 and warns, once per run and naming the port:

The proxy on port 3333 is listening on loopback addresses only, so containers in this run cannot reach it even though its URL now names the host. Bind the proxy to 0.0.0.0 to make it reachable — which also exposes it to anything else that can reach this machine, so do that only on a network you trust. Use --no-proxy-vars if this run doesn’t need the proxy.

It’s a warning, not a failure: the run may never use the proxy. Note the security cost it names — binding a proxy to 0.0.0.0 opens it to everything that can reach the machine, so weigh that rather than applying it reflexively. Some proxies offer the same thing as a narrower setting: cntlm, for instance, binds 127.0.0.1:3128 by default and listens on every interface only under its Gateway option.

A host firewall

A host firewall can block the container’s traffic even when the proxy is bound wide enough, and that case Ratect can’t detect — so if the warning doesn’t fire and the proxy still isn’t reachable, check there next.

What to look for: the connection arrives on the bridge interface of the user-defined network the run is using, never Docker’s default docker0 bridge, so a firewall rule written for docker0 won’t cover it. Ratect creates a network per task, or uses the one --use-network names — and a run can’t fall back to the default bridge even if you point --use-network at it, because Ratect gives every container on it a network-scoped alias and Docker only allows those on user-defined networks (docker run refuses with network-scoped aliases are only supported for user-defined networks).

Match the rule on that network’s subnet, which docker network inspect <network> reports under IPAM.Config. Its interface name is generally not in that output — Docker only records one there when the network was created with com.docker.network.bridge.name, which is how docker0 itself gets its name — so a rule pinned to an interface is both harder to write and easier to get wrong.

Turning it off

--no-proxy-vars disables all of the above for one run: nothing is injected into any container or build — the proxies from Docker’s config.json included — no_proxy is left alone, and no URL is rewritten. A container’s own build_args are still passed. It is a ratect run option, and a ratect-compat flag.

Coming from Batect? Three deliberate differences: a localhost proxy is rewritten on Linux too, where Batect propagates it verbatim; a loopback-bound proxy is diagnosed rather than left to fail; and --no-proxy-vars keeps the proxies from Docker’s config.json out of a build, where Batect passes them whatever its flag says. All three are listed under Differences from Batect.

Troubleshooting

Where to look when a run fails, or hangs. Each of these has a home elsewhere in the documentation already; this page is the entry point — one line per symptom, linking where it lives — plus the one thing every diagnosis ends up needing, reading Ratect’s own logs, which is written here.

SymptomWhere it lives
Will this run fail? Why did it?ratect doctor (ratect only) answers both without running a task: an unreachable daemon, a configuration that doesn’t load, a build_directory or Dockerfile a build can’t use, and the warnings that bite later (a floating image tag, an absolute dockerfile, a dependency with no health check).
A dependency never becomes readyHow Docker reaches its verdict: docker ps and docker inspect show the health state Ratect is waiting on, and Ratect imposes no timeout of its own, so a check configured to retry forever waits forever.
The build failedImage building: a failing build’s whole transcript is in the error Ratect reports, under every output style; for a live transcript, see filtering RUST_LOG below.
I need to see what Ratect is doingFiltering RUST_LOG, below.
A container was left behind, or I want to keep oneratect resources lists and removes what a crash, a docker kill or a failed cleanup left; --no-cleanup, --no-cleanup-after-success and --no-cleanup-after-failure keep a run’s containers on purpose, running, so you can look inside — on ratect run and ratect-compat.
What does this exit code meanratect and ratect-compat exit with the same codes: the task’s own container’s, 128 + the signal’s number for a run ended by one, 125 for a run that fails for any other reason, a usage error included (or whose cleanup fails after it passed), 1 for any other verb that fails, 2 for one invoked wrong, 101 for a crash.
A JVM or Node build hangs or dies silentlyHow do I raise Docker Desktop’s resource limits? — every container runs under Docker’s own CPU/memory ceiling, and a heavy build under a tight one looks like a hang or an OOM kill.
Files a task wrote are root-owned, or a later write says permission deniedFile Ownership and the Home Directory: who owns what a container writes through a bind mount on each kind of daemon, what identity changes, and how to remove a root-owned directory without root. On a rootful Linux daemon, ratect doctor (ratect only) warns about each writable bind mount of a container with neither identity nor a non-root user.
&& or $VAR in a command did nothingWhy doesn’t && or $VAR work in my command? — command is literal argv, with no shell and no expression support.

Filtering RUST_LOG

Ratect’s own diagnostics go to stderr, filtered by the RUST_LOG environment variable (default info) — Logging vs. output is the split between them and Ratect’s output proper, which RUST_LOG never filters: progress, errors, warnings and notices are printed whatever it says. RUST_LOG=debug adds every container creation, start and removal, each setup_commands exec’s raw output, and every image build’s log lines, which is usually what “what is Ratect doing?” is asking for.

RUST_LOG isn’t just an on/off level switch — tracing-subscriber’s EnvFilter syntax lets you scope it to specific modules (target=level directives, comma-separated). This matters in practice once you turn on debug for anything build-related (e.g. to see a live image build transcript): bollard (the Docker API client Ratect is built on) also logs at debug, and a bare RUST_LOG=debug includes all of its raw API traffic — usually far more noise than signal.

A directive with no target (e.g. RUST_LOG=debug) applies everywhere, including dependencies like bollard. Scoping to a specific target instead — ratect_core covers everything the ratect binary logs, and all but a few of ratect-compat’s own lines, which log under ratect_compat (among them why a run failed) — excludes anything not matched, including bollard, without needing to name it:

# Only ratect_core's own logs, at debug — no bollard noise at all.
RUST_LOG=ratect_core=debug ratect run build

# Keep the normal `info` default everywhere else, but add ratect_core's debug-level
# output on top (e.g. build transcripts) — usually the more useful combination.
RUST_LOG=info,ratect_core=debug ratect run build

# Narrower still: just the Docker/build/container-runtime module, not task
# orchestration (`ratect_core::engine`) as well.
RUST_LOG=ratect_core::docker=debug ratect run build

If you do want a blanket debug sweep across everything (including bollard) but need to silence one specific dependency, add it as its own =off directive instead: RUST_LOG=debug,bollard=off.

The same variable and syntax apply to ratect-compat, which can also write its logs to a file with --log-file. With RUST_LOG unset, the file gets info,ratect_core=debug,ratect_compat=debug: Ratect’s own debug records, so it has something to read even when stderr was quiet and says why a run failed, but other crates only at info, so bollard’s request bodies (below) never reach a file nobody asked to hold them. Setting RUST_LOG replaces that default for the file as well as stderr — RUST_LOG=debug puts bollard’s records in the file too, and RUST_LOG=warn leaves out Ratect’s debug records, including why the run failed.

Before pasting a debug log anywhere, remember two things it can carry. bollard’s debug records include the body of each Docker API request and response — a container’s create request carries its whole environment, secrets passed through from the host included — so any directive that lets bollard through at debug (a bare RUST_LOG=debug) logs them. And a setup_commands exec’s output is whatever the command itself printed — so if a setup command’s own output could include something sensitive (a failed connection string, a verbose HTTP client dumping request headers), that ends up in the debug log too. Treat RUST_LOG=debug (or narrower ratect_core=debug) output with the same care you’d give the command’s own output before pasting it into a support ticket, chat message, or CI log.

RUST_LOG=off never hides why a run failed: a fatal error bypasses the filter — see Exit codes and error reporting.

Coming from Batect? Ratect’s logs differ from Batect’s on purpose — where they go, --log-file or not, and what --log-file writes — as listed under Differences from Batect.

Frequently Asked Questions

Answers to real questions that come up using Ratect — not a restatement of the configuration reference, which already covers every field mechanically. This page is expected to grow: if something surprised you, it likely surprises the next person too — open an issue.

When should I mount a directory instead of copying files into the image?

Ratect gives you both, and they trade off differently:

  • A volumes bind mount ({ local = ".", container = "/code" }) makes your working directory show up live inside the container — every one of the worked examples does exactly this for its own source tree. Edit a file on the host, rerun the task, and the container sees the change with no rebuild. The image itself stays generic (a stock language toolchain image, not your code baked into it), so pulling it is normally fast and cached.
  • build_directory instead builds a Dockerfile — your code is COPY’d in at build time, so the resulting image is fully self-contained (nothing left on the host is needed to run it) and portable (push it, run it elsewhere, get the exact same bytes). The cost is the build step itself: a docker build on every task run unless Docker’s own layer cache absorbs it, and every source edit invalidates the layers built from it.

Rule of thumb: mount while you’re iterating locally — a task-runner project, almost by definition, is exactly that case, which is why every project under examples/ mounts rather than builds. Reach for build_directory when the image itself is the artifact you actually want to produce or ship (a container you’re going to publish, or a build step whose whole point is producing that image) rather than a disposable environment to run your code in.

How do I run something at container start regardless of the task’s command?

Use entrypoint rather than command. Docker runs Entrypoint ++ Cmd — the entrypoint always executes first regardless of what command (or a task’s run.command) is set to, and the classic idiom is a wrapper script that does its setup, then hands off to whatever was actually asked for:

[containers.app]
image = "my-app"
entrypoint = "/entrypoint.sh"
#!/bin/sh
# /entrypoint.sh
set -e
# ... setup that must happen no matter which task/command runs ...
exec "$@"

The exec "$@" at the end matters: it replaces the shell process with the real command instead of running it as a child, so the real command becomes PID 1 (or inherits proper signal delivery under exec) rather than being one process removed from it. This is also why entrypoint/command combine cleanly for the well-known entrypoint = "/bin/sh -c", command = "make lint" idiom (an entrypoint tokenizes exactly like command does — see the field reference) — Ratect passes both straight through to Docker with neither side adding an extra shell layer of its own.

If what you actually need is signal forwarding and zombie reaping rather than a custom setup step, see enable_init_process instead — it runs Docker’s own init process ahead of your command for exactly that, with nothing to write.

Why does task idempotency matter?

Because Ratect doesn’t cache “already succeeded” across invocations — there’s no timestamp check, no “nothing changed, skipping” the way a build tool like make gives you for free. Within one invocation, a prerequisite reached by more than one path does run only once (see prerequisites — that’s cycle-safe dedup, not a guarantee your script is safe to run twice), but every separate ratect-compat/ratect invocation from the shell starts completely fresh, with no memory of any previous run. Take the migrate/test example from Cross-task isolation — test has migrate as a prerequisite, and migrate runs run-migrations.sh:

Every ratect run test run executes migrate again first, from a fresh container. If run-migrations.sh isn’t safe to run twice — it reapplies a migration that’s already applied, or errors on a table that already exists — every single test run breaks or corrupts state, not just the first one. The same applies to any task with real side effects reused as a prerequisite: seeding data, writing output files another task then reads. Design each task assuming it will run more than once against the same environment; Ratect’s model of “always run fresh containers” (see Cross-task isolation) means it always will.

How do I raise Docker Desktop’s resource limits?

This isn’t a Ratect setting — every container Ratect starts still runs under whatever CPU/memory ceiling Docker itself is configured with, so a heavier build (the JVM or Node examples are the ones most likely to notice) can look like it’s hanging or gets silently OOM-killed when Docker’s own default is too tight, and it’s easy to blame the task runner instead of the actual cause.

  • Docker Desktop on macOS or Windows: Settings → Resources lets you raise the CPU/memory/swap ceiling directly. On Windows with the WSL2 backend specifically, Docker Desktop’s own Resources page can instead defer to a .wslconfig file controlling the WSL2 VM’s limits — Docker Desktop’s own documentation covers which applies for your setup.
  • Linux with the Docker Engine directly (no Docker Desktop): there’s no VM in the picture, so this ceiling doesn’t exist in the same way — containers share the host’s resources directly, bounded only by whatever docker run/daemon-level limits you’ve configured yourself.

Why doesn’t && or $VAR work in my command?

command (and entrypoint) are tokenized into literal argv — quote/backslash-aware whitespace splitting, matching Batect’s own tokenizer exactly — with no shell involved and no expression support. command = "echo $HOME && echo done" doesn’t run two commands with $HOME expanded; it’s parsed as a single program named echo given the literal argv $HOME, &&, echo, done — Docker will fail to find an executable called $HOME. Anything relying on shell operators (&&, ||, pipes) or runtime environment expansion needs an explicit shell wrapper:

command = "sh -c 'echo $HOME && echo done'"

This is easy to conflate with a second, entirely different $-syntax: Ratect’s own config-time expressions ($VAR, ${VAR:-default}, <name), which do exist — but only in specific fields (environment values, a local volume’s host path, build_directory, and a few others), evaluated when the run reaches the task that uses them, never inside command itself. So there are three different things that can look like “the same” $VAR: Ratect’s own config-time expression syntax (only in the fields listed above), command’s literal tokenizer (no substitution of any kind), and real shell expansion once you’re actually running inside a container via sh -c (using the container’s runtime environment, resolved by the shell, not by Ratect). Which one applies depends entirely on which field you’re looking at.

Why isn’t my host environment variable visible inside the container?

Containers don’t inherit the host’s environment automatically — not Ratect’s own choice, just how Docker containers work, but a common first surprise for anyone coming from local shell scripts where every variable is already there. Any host variable a container’s command needs has to be passed through explicitly via environment, using Ratect’s own expression syntax:

[containers.app]
image = "my-app"
environment = { API_KEY = "$API_KEY" }

Nothing here is a default worth changing — declaring every environment variable a container actually uses is deliberate, not boilerplate: it makes a task’s real inputs visible in the config itself instead of depending on whatever happened to be exported in whoever’s shell ran it.

What’s the difference between a dependency and a prerequisite?

They sound like synonyms but are two unrelated mechanisms:

  • A dependency (a container’s own dependencies list) is another container, started alongside the one that needs it, kept running for the whole task, and torn down together at the end. Use it for something your task’s container talks to over the network while it runs — a database, a cache, a queue. See Dependency Readiness for how several of these combine.
  • A prerequisite (a task’s own prerequisites list) is another task, run to completion — including its own full cleanup — strictly before the task that names it starts. Use it to sequence work: compile before test, a migration before the tests that need it migrated. See Task ordering.

A dependencies container is there for the duration of the run; a prerequisites task runs and finishes, with nothing of its own left when the next task starts.

How It Works

This describes Ratect’s internal pipeline, for anyone extending Ratect or trying to understand its behavior in detail. For the code itself, see AGENTS.md for a map of the source layout.

1. CLI parsing

Each binary has its own main.rs, and both parse arguments with clap: ratect-compat/src/main.rs for Batect’s flat flag interface (CLI reference), and ratect/src/main.rs for the subcommand interface (ratect CLI reference). Everything below this step is shared — both call into ratect-core, which is where the rest of this document lives. Parsing has to happen before config evaluation (step 2) can run, since --config-var/--config-vars-file feed into it.

2. Config loading and evaluation (ratect-core/src/config.rs)

This is two separate steps, not one: loading checks what the file says, and evaluation reads what the machine running it supplies — see decisions/0014.

  1. load_project (or load_project_native, for ratect.toml) starts with Config::load_from_file_with_git_cache (or load_from_file_native_written_for): the root file is parsed into Config/Container/Task/TaskRun/ConfigVariable/ServiceGroup structs — YAML via noyalib, TOML via toml, one struct set for both formats — and its top-level include list (if any) is resolved, with every loaded file’s containers/tasks/config_variables, and a TOML file’s services, merged into one Config (see how included files combine).

    Includes are walked breadth-first, so every entry in the root file is reached before any included file’s own, and each file is loaded exactly once however many entries name it. A type: git entry clones its repository into ~/.ratect/incl first (ratect-core/src/git_include.rs), and everything reached through one is confined to that clone and may do only what the entry granted it — see What a bundle may do for the rules, and CONTEXT.md for what bundle, grant and boundary each denote.

    It then checks the result — references, field combinations, and the shape of every value it can judge without the machine — applies extends (native only), and returns a LoadedProject. No expression is evaluated: a field that may hold one is judged here only when it holds a literal, so a container reading a variable this machine doesn’t have stops nothing that doesn’t use it. The LoadedProject keeps what evaluation needs: the directory each container was declared in, the clone a Git-included container must keep its host paths within, and which container in an extends chain supplied each path-bearing field. Listing tasks needs nothing more.

  2. LoadedProject::evaluate: given the containers and tasks a caller needs, and the --config-var/--config-vars-file overrides it parsed:

    • Evaluates expressions ($VAR, ${VAR:-default}, <name, <{name}, plus the built-in batect.project_directory) in every field that takes one: environment values (container, task run, and task customise.<container>), local volume mount host paths (in a Batect-format file, only the object form’s), build_directory, build_args, a build_secrets entry’s path, a build_ssh entry’s paths, and — ratect.toml only — image and identity.home. A cache mount’s name/container are plain strings, matching Batect: nothing to evaluate (see Cache volumes). A value that can’t be evaluated is an error naming the container or task, the field and the expression.

    • Host path resolution: after evaluating a host path, if the result is relative, it’s resolved to an absolute path relative to the directory of the file that declared the value — the container’s own, or for an inherited field the ancestor’s that supplied it; the root config’s directory when there’s no include involved — not the current working directory. Done in this order because an expression can itself resolve to an absolute path, which mustn’t be treated as a relative fragment. batect.project_directory itself always resolves to the root config’s directory regardless of which file a container came from. A cache mount’s Docker volume name/host directory is resolved later instead (ratect-core/src/cache.rs, via engine.rs’s resolve_volumes), once --cache-type and the project’s own cache key are known — neither available at this stage.

      The resolved path is then checked against the container’s Git boundary, if it has one: a container that came from a Git-included file may only reach inside its own clone or your project directory, unless that include was granted allow_host_paths. Checked twice: once lexically, with both the check and the path normalized first, since Path::starts_with does not interpret ..; then against the real locations, with symlinks resolved as far as the path exists, since a bundle can commit one inside its own clone. A literal path gets the same check at load.

    The engine evaluates each task as it reaches it — see step 3 of the task engine below.

    See the configuration reference for the full expression syntax, precedence, and error rules.

3. Task engine (ratect-core/src/engine.rs)

TaskEngine::run_task(name) first walks the task’s whole prerequisite order — wildcards expanded, each task once — without running anything, so a prerequisite naming no task, or a cycle among them, fails the run before any task starts, as in Batect. Then it runs a recursive async function. The order of its five steps is the part worth knowing here; for what each one does in detail, read engine.rs’s own module comment (cargo doc --open -p ratect-core), which is where that lives and stays current.

  1. Already executed? If this task has already run successfully in this invocation, return immediately. This is what makes shared prerequisites run only once.
  2. Cycle detection: a task already in the middle of being run — an ancestor of itself in the current call stack — errors immediately rather than recursing forever. A backstop: the walk above has already refused every cycle.
  3. Run prerequisites, each through the same recursive function, before the task’s own container step. They run with top_level: false, unlike the task actually named on the command line, and with no -- ARGS. The flag keeps --skip-prerequisites to the named task, and leaves a prerequisite’s resources out of --no-cleanup-after-success. It plays no part in interactive eligibility: every task’s own container is eligible, however deeply nested, as in Batect — see Interactive Mode. The task is then evaluated, before any Docker work of its own: every container in its graph, its run.environment and its customise environments go through LoadedProject::evaluate, and the rest of the task reads only those values. A container no task in the run uses is never evaluated. Its container graph is built then too, and a cycle in it fails the task before it starts — no network is created, as in Batect. A task with no run of its own stops here and succeeds — it exists purely to chain prerequisites (see config reference), matching Batect’s own TaskRunner.
  4. Create the task’s network, then pull or build every image and create every container in the task’s container graph on it — the task’s own included — as soon as each one’s image is ready, and start each dependency once every container it depends on is ready, before the task’s own container, so it can reach them by name. The graph is the container’s own dependencies unioned with the task’s, resolved recursively, with any customise overrides applied to whichever container they target at whatever depth. Every task execution gets its own network — a task’s container is never left on Docker’s shared default bridge — and it is torn down afterwards. With --use-network an existing network is validated and reused instead, and never removed, since Ratect didn’t create it. See the task lifecycle for the step-by-step and diagrams.
  5. Resolve and run the image. resolve_image turns a container’s image or build_directory into something runnable — pulling (per image_pull_policy) or building, or erroring if neither is set — and is used identically for the task’s own container and for dependencies. The container then runs with the task’s command, created on the task’s network (unless its own network_mode says otherwise), its environment layered as Environment precedence states. Everything else on the container — ports, hostnames, working directory, entrypoint, capabilities, devices, and the rest — is assembled by container_spec.rs from the config and handed to docker.rs as plain values; the config reference is the list of what those fields mean, and which accept a task-level run override.

The “run once”, “pull once” and “build once” guarantees are in-memory and scoped to a single invocation — nothing persists between runs, so a build_directory container is rebuilt every time. Pulls and builds are memoized as once-cells holding their outcome rather than plain sets, so two containers resolving the same image under the same pull policy share one in-flight operation instead of racing. Dependency readiness, by contrast, is scoped to a single task execution and discarded when it finishes.

Concurrency follows Batect’s in outline: prerequisites run sequentially, one to completion after another, even when independent — while one task’s startup is concurrent. Every container’s image — each dependency’s and the task’s own — is pulled or built at once, the moment the task’s network is ready, and each container is created as soon as its own image is (and, under network_mode = "container:<name>", its target has been created), so a pull, build or create that fails ends the task as soon as it fails — not once every dependency is ready, by which time their setup commands have run. Starting is what a container’s own dependencies gate: independent branches of the graph start and health-wait at the same time, and a container — already created — starts once every container it depends on has passed its readiness gate (see decision 0019). Cleanup is concurrent the same way, in reverse: a container is stopped once every container depending on it has been, and every container ready to stop is stopped at once, so independent dependencies wait out their grace periods together. The task’s network is created before any of that starts, where Batect creates it alongside — see Differences from Batect. Running independent prerequisites concurrently too is a possible Rust-specific enhancement beyond Batect — tracked as ratect#102 — and Dependency Readiness has the detail.

Testability

The engine talks to Docker through a ContainerRuntime trait (defined in ratect-core/src/docker.rs) rather than depending on the concrete Docker client directly. This is what lets the engine’s prerequisite/cycle/dedup logic be unit-tested with a fake implementation instead of a real Docker daemon.

4. Docker integration (ratect-core/src/docker.rs)

DockerClient wraps bollard and implements ContainerRuntime. What each method is for:

  • pull_image and build_image: fetch or build the image a container needs, streaming the daemon’s progress to the output layer as events — what, if anything, those render as is the selected output style’s decision, not docker.rs’s (see Logging vs. output). build_image first packs the build directory into an in-memory tar, honouring .dockerignore via the dockerignore crate.
  • create_container: creates a container — a dependency’s or the task’s own — ready to be started: Docker’s create, which attaches it to its network, then the user-mapping uploads. It hands the container’s id back the moment that is done (inside its error, if an upload failed after Docker’s create), and the engine registers it for cleanup there and then, so a container whose start later fails or is cut short by another dependency failing is still removed. For a container with identity, the engine then edits the created container’s identity files, prepares its home and, on a rootful Linux daemon, takes its root-owned caches, and a failure there counts as a failed create. Its own step, separate from starting, because it waits for less: a container is created once its image and the network are ready (and any network_mode = "container:<name>" target has been created), and started only once the containers it depends on are — see Dependency readiness.
  • run_container: starts and streams the task’s own container until it exits. Three attach-and-start paths sit behind it — fully non-interactive, stdin-forwarding, and a real TTY with raw mode and live resize — chosen by whether the task is interactive-eligible and whether Ratect’s own stdin and stdout are terminals. All three attach to the container before Docker’s start and read its output from that attach, as Batect does, so nothing typed or printed early is lost and any log driver works. It does not remove the container: the engine’s cleanup stage removes everything a task created, its own container included, so --no-cleanup-* is interpreted in exactly one place.
  • create_network / remove_network / network_exists: the per-task network, or a service instance’s (decisions/0026), plus the up-front validation that makes --use-network fail with a clear error rather than an unrelated API failure later.
  • start_background_container / stop_and_remove_container: the same, for a dependency, sidecar or service group’s container — started and left running alongside the task rather than waited on, so no task command applies; its output is shown only under -o all, read from an attach made before it starts.
  • follow_container: the output of a service group’s container that another ratect services up started, attached to after the fact, under -o all.
  • wait_for_container_healthy / exec_in_container: the two steps of the dependency readiness gate. The first blocks on Docker’s own event stream, replayed from the beginning so a verdict that arrived before the stream opened still counts, and turns an unhealthy verdict into an error carrying the last health check’s exit code and output, when the container and daemon are still there to report them. The second runs one setup_commands entry in the running container and returns its exit code and output for the engine to judge.

Nothing here depends on config types: container_spec.rs converts config into a plain ContainerSpec first, which is what the methods that create and start a container take; the rest take its id and plain values. The module’s own comment carries the gotchas — where each path calls Docker’s start relative to attaching, why cleanup ownership is not to be split again, how build_ssh paths are classified — and is the thing to read before changing any of this.

Container creation/start/removal events are logged at debug level via tracing (see below), as is each setup_commands exec’s raw output — which is why Troubleshooting warns about pasting a debug log anywhere.

5. Logging vs. output

Ratect keeps two channels deliberately separate — and output itself follows one rule: stdout is the result, stderr is everything said about producing it (decisions/0017).

  • Output is what a user with RUST_LOG unset would be worse off without, and doesn’t go through tracing, apart from two terminal-resize failures that are logged instead. The result — a run’s task-container output, a tasks list listing — is stdout. Everything about the run is stderr: errors (Error: ), warnings (Warning: ), notices (the interrupt notice, what --no-cleanup* left in place), in every style including quiet; and progress (“Running build…”, “Pulling alpine:3.18…”, “build finished with exit code 0 in 2.3s.”), the one class --output/-o shapes. Progress is the one place the binaries differ: ratect writes it to stderr, ratect-compat to stdout, where Batect puts it — see Streams. Internally these lines are typed events (ratect-core/src/ui/): engine.rs and docker.rs post task-execution milestones, and the three stderr classes, to an event sink instead of printing, and the selected output style decides what each renders as — fancy’s live per-container status block on an interactive terminal, simple’s append-only lines otherwise, no progress at all under quiet, or all’s per-container prefixed lines (the one style where even container output routes through the event sink, line-buffered, instead of streaming to stdout directly — the task container’s own lines still landing on stdout). Each main names which stream its progress console is; nothing inside the loggers chooses.
  • Diagnostics are breadcrumbs — Docker API calls, what resolved to what, a best-effort retry that then succeeded — via tracing / tracing-subscriber on stderr, filtered by RUST_LOG (defaults to info; ratect-compat’s --log-file defaults to debug for Ratect’s own targets). A fatal error is never only one of these: main.rs prints it directly (Error: <message>), so it stays visible under RUST_LOG=off and -o quiet alike — except for a run’s failure the run has already reported by another route (the task’s own non-zero exit, a signal or a closed stdout, or a failure to run the task once it had started or to clean up after it, which the engine reported as it happened), which gets no second line, and for a verb that printed its own Error: line for each thing it couldn’t do (ratect includes clean/refresh). A failed ratect services up is a run, and reports as one. ratect-compat also records every one at debug, so --log-file says why the run failed unless RUST_LOG filters that record out.

Colours (e.g. the exit code in the task summary line, the Error: marker) are, by default, only emitted when the stream being written to is actually a terminal — each stream decides for itself, tracing’s lines included — see Colour for the controls that change that.

Filtering RUST_LOG

Scoping RUST_LOG to Ratect’s own targets (ratect_core, ratect_core::docker, and ratect-compat’s ratect_compat) rather than every dependency’s is on Troubleshooting, which owns it.

ratect CLI Reference

This documents the ratect binary — the forward-looking CLI, with its own subcommand-based interface. For the compatibility binary, see the ratect-compat CLI reference instead; the two are described separately because they are deliberately different interfaces, not two spellings of one (Two binaries, two formats says which to pick). If you haven’t run a task yet, Getting Started runs a first one end to end, and the worked examples show a real project per language.

Configuration. ratect reads its own native TOML configuration (ratect.toml by default) — see decisions/0003 for why. Its full schema is the ratect.toml reference; it’s the same schema Configuration Reference documents for batect.yml, re-spelled in TOML, with extends in place of YAML anchors, identity in place of run_as_current_user, and native-only additions such as services. A batect.yml is still readable by naming it with -f, so a project can migrate incrementally — ratect config convert translates one automatically.

The native config format

The format itself — the TOML spelling of every field, extends, includes, and the auto-loaded ratect.local.toml — is the ratect.toml reference (the file, local overrides).

Commands

Grouped by purpose. Within a command, the sub-verbs follow their natural workflow order (list before clean/refresh) rather than alphabetically. ratect --help lists the commands in this same order — clap can’t render the group headings there, so the order alone carries them.

Running tasks

CommandWhat it does
ratect run <task> [-- ARGS...]Runs a task. Anything after -- is appended to the task command’s own arguments, or replaces the image’s default CMD when the task has no command.
ratect tasks listLists the tasks this project defines.
ratect services up <group>Brings a service group up, or attaches to it if it already is, shows every member’s output, and takes it down once its exit condition is met — see services options.
ratect services down <group>Takes a service group down, whatever state its containers are in.
ratect services listLists this project’s service groups that have containers or a network on the daemon, in any state.

Managing resources

CommandWhat it does
ratect caches listLists the caches this project can see, project-scoped and shared, with the scope of each.
ratect caches clean [NAME...]Removes this project’s caches, or just the named ones — which may be shared.
ratect includes listLists the cached Git includes shared by every project on this machine.
ratect includes clean [--all]Removes cached Git includes.
ratect includes refreshRe-clones them, picking up a ref that has moved.
ratect resources list [--all]Lists containers and networks left over from task runs that have ended.
ratect resources clean [--all]Removes them.

Configuration & diagnostics

CommandWhat it does
ratect config validateChecks the configuration loads and is problem-free, without a daemon — a CI-friendly gate.
ratect config convertConverts a batect.yml project (read unless -f names another file) into native .toml files, one per file.
ratect doctorChecks this project and this machine for problems, without running anything.

Shell integration

CommandWhat it does
ratect completions <shell>Prints a shell completion script (bash, zsh, fish, powershell, elvish) to stdout — see Shell completion.

There is deliberately no ratect <task> shorthand. ratect-compat takes a task name as a bare positional argument, which works only because it has no subcommands; as ratect grows verbs, “is doctor a task or a command?” becomes a question the interface can’t answer, so run is always explicit.

ratect run build
ratect run test -- --filter integration
ratect tasks list
ratect services up stack
ratect services list
ratect services down stack

ratect caches list
ratect caches clean gradle-cache
ratect includes list
ratect includes refresh
ratect resources list
ratect resources clean --older-than 1d

ratect config validate
ratect doctor

ratect completions zsh

Global options

These work with every command, before or after it — ratect -f custom.yml run build and ratect run build -f custom.yml are the same invocation.

OptionDefaultDescription
-f, --config-file <PATH>ratect.tomlThe configuration file. Parsed by extension — .toml as the native format, .yml/.yaml as Batect-format YAML — so -f batect.yml keeps reading a Batect config while migrating — until it includes a .toml file, which needs a ratect_version only a ratect.toml root can declare. caches uses it only to locate the project directory — it never reads the contents.
-o, --output <STYLE>autofancy, simple, quiet or all; unset auto-selects fancy when stderr is an interactive console, simple otherwise. ratect’s own progress is on stderr in every style; stdout is the task’s own output — see Output Styles.
--no-color—No color in Ratect’s own output (never affects a task’s own output), and simple becomes the auto-selected style — see Colour for how it combines with NO_COLOR/CLICOLOR_FORCE.

Narrower options attach to the commands that actually use them, rather than being global: a flag that’s accepted and then ignored reads as a promise. So the config-variable options below belong to run, services up, config validate and doctor (the commands that evaluate configuration), and the Docker connection options to run, services, caches, resources and doctor (the ones that reach a daemon).

OptionApplies toDescription
--config-var <NAME=VALUE>run, services up, config validate, doctorSets a config variable. Repeatable; wins over --config-vars-file and the variable’s own default.
--config-vars-file <PATH>run, services up, config validate, doctorA file of config variable values (a flat NAME = VALUE map), parsed as TOML or YAML by extension. In a YAML file an unquoted number or boolean is read as written, as in ratect-compat. Defaults to an auto-discovered ratect.local.toml beside the config file, when present.

A path given to -f or --config-vars-file has a leading ~ expanded to your home directory, and . and .. removed before the path is used, so link/../ratect.toml is ./ratect.toml whether or not link is a symlink. A leading .. stays. A --config-vars-file you give must name a file: run refuses one that doesn’t before reading the config, and config validate and doctor report it as a problem.

tasks list still accepts both, deprecated: they have no effect there, since listing tasks evaluates no value, and passing either prints a warning saying so. They’ll be removed in a later release.

Docker connection options

Taken by run, services, caches, resources and doctor — every command that reaches a daemon — and never by tasks list, includes or config, which don’t. Which daemon they reach, their DOCKER_* environment-variable defaults, and TLS with a private certificate authority are on Connecting to Docker, shared with ratect-compat.

OptionDefaultDescription
--docker-host <HOST>DOCKER_HOSTDocker host to connect to — see Connecting to Docker.
--docker-context <NAME>DOCKER_CONTEXT, then the active context, unless a host is setDocker CLI context to connect through — see Connecting to Docker.
--docker-config <PATH>DOCKER_CONFIG, then ~/.dockerDirectory containing the Docker CLI’s own configuration — see Connecting to Docker.
--docker-tls—Use TLS, identically to --docker-tls-verify — see Connecting to Docker.
--docker-tls-verifyDOCKER_TLS_VERIFYUse TLS, verifying the daemon’s certificate — see Connecting to Docker.
--docker-cert-path <PATH>DOCKER_CERT_PATH, then --docker-config/DOCKER_CONFIG, then ~/.dockerDirectory containing any of ca.pem/cert.pem/key.pem — see Connecting to Docker.
--docker-tls-ca-cert <PATH>ca.pem in the certificate directoryThe TLS CA certificate — see Connecting to Docker.
--docker-tls-cert <PATH>cert.pem in the certificate directoryThe TLS client certificate — see Connecting to Docker.
--docker-tls-key <PATH>key.pem in the certificate directoryThe TLS client key — see Connecting to Docker.

run options

OptionDefaultDescription
--enable-buildkit—Force BuildKit for image builds, over the daemon’s default and DOCKER_BUILDKIT. Only run and services up build images, so only they take it.
--use-network <NAME>—Reuse an existing Docker network for every task in this invocation instead of creating one per task — see ratect-compat’s description.
--disable-ports—Never bind container ports on the host — see ratect-compat’s description.
--no-proxy-vars—Don’t propagate proxy environment variables to image builds or containers, nor the proxies in Docker’s config.json to image builds — see Proxies.
--skip-prerequisites—Run the task alone, without its prerequisites — see ratect-compat’s description.
--override-image <CONTAINER=IMAGE>—Replace a container’s image. Repeatable — see ratect-compat’s description for what it replaces and when it errors, except that here an empty CONTAINER or IMAGE, or a CONTAINER given twice (the last one wins), isn’t rejected.
--tag-image <CONTAINER=TAG>—Extra tag for an image a container builds. Repeatable — see ratect-compat’s description for when it errors, except that here an empty CONTAINER isn’t rejected.
--no-cleanup, --no-cleanup-after-success, --no-cleanup-after-failure—Leave the task’s containers and network in place, running, after success (the task’s own container ran, whatever its exit code), after failure (something failed before it could), or both. After success that is the named task’s alone — its prerequisites are still cleaned up; after failure it is whichever task failed — see ratect-compat’s description.
--max-parallelism <N>unboundedCap concurrent image pulls/builds, container creates, dependency container starts and setup commands — see ratect-compat’s description.
--cache-type <TYPE>volumevolume or directory — see ratect-compat’s description and cache volumes.

services options

services up <group> brings up the service group’s containers — each member, and whatever it depends on, started as a task’s dependency is — then shows every member’s output on stderr, each line under its container’s name as -o all shows it, until the group’s exit_condition is met. It then takes the group down: every container stopped and removed, each before what it depends on, then its network. It exits with the code the group’s exit_code_from selects, and otherwise as a run does: 125 for Ratect’s own failure, 128 + the signal’s number for a termination signal — see Exit codes. Its output style is always all, the one that shows several containers’ output at once, so -o with any other style is refused.

A group that is up belongs to no services up. It is the containers and network carrying its labels, wherever they came from, so a second services up of the same group never starts another copy. What it does depends on what it finds, the first of these that applies deciding:

  • A container only created or being removed, or a network with no container: another services up or services down is bringing the group up or taking it down, so it waits, saying so once, and looks again. A group left that way — by a services up killed outright while bringing it up, or a take-down that couldn’t remove the network because a task was still running on it — is waited on until you end the wait and run services down.
  • Its network gone, or no member up: it replaces the group, saying Replacing service group 'stack': none of its members is up, or its network is gone., then takes it down and brings it up anew.
  • A member up — running, or paused or restarting: it attaches, saying Service group 'stack' is already up; attaching to it. Ending this takes it down., and from then on shows the output of each of the group’s containers that was running as it attached, and waits for the exit condition. It starts nothing: a member that has already exited stays exited and doesn’t count towards the condition, though exit_code_from = { container = "<member>" } still takes the code that member left.

Two services up started at once end up the same way: one brings the group up and the other waits for it, then attaches. Whichever ends:

  • Its exit condition being met, or a termination signal, takes the group down, whoever brought it up — Ctrl+C in an attached services up stops a group another terminal started. Every other services up attached to it then sees its members stop, and ends, finishing whatever of the take-down is left. A further signal during the take-down force-removes what is left, as it does a task’s cleanup.
  • Killed outright (kill -9, a terminal closed under it), a services up takes nothing down and can’t say so: the group stays up. The next services up attaches to it, saying so, and services down ends it.

The group is labelled with the directory of the configuration file up was given. Every checkout of a project shares its project name, so services up in a second checkout attaches to the group the first brought up, and warns that its containers’ bind mounts point into the first: Attaching to service group 'stack', which was brought up from /work/first, not /work/second: its containers' bind mounts point there.

A container already holding one of the group’s names, <project>..<group>..default..<container>, without the group’s labels stops services up with the daemon’s error; Ratect neither attaches to it nor removes it. A container running when services up attaches is used as it is, and a container the configuration has gained since the group came up is not added: to apply a change to the group’s configuration or images, take the group down first.

A task reaches a group that is up by running on its network, whose name is fixed: ratect run <task> --use-network <project>..<group>..default runs the task’s containers there, where each of the group’s containers answers to its name in the configuration, and leaves the network alone afterwards.

services down <group> stops and removes the group’s containers and network, whatever state they are in — running, stopped, or half brought up. While the configuration declares the group, it stops them as up does, each before what it depends on and with its own stop_signal and stop_grace_period; it needs only the project_name the root configuration file sets, though, so it also takes down a group the configuration no longer declares, or one whose configuration fails to load after the root file parses, stopping its containers all at once. A group that isn’t up is no failure. services list shows each group that has containers or a network on the daemon, whatever their state, with each container’s state and the directory it was brought up from; with -o quiet, each group’s name alone.

resources never selects a service group’s containers or network, whatever their state and whatever its options, and doctor doesn’t count them as leftovers: services down is how a group ends.

OptionApplies toDescription
--config-var, --config-vars-fileupAs for run.
Docker connection optionsup, down, listSee Docker connection options.
--enable-buildkitupAs for run.
--cache-type <TYPE>upAs for run: use the same type as the tasks sharing the group’s caches.

caches options

--cache-type <volume|directory> (default volume) selects which storage to act on, for both list and clean — a cache in one is invisible to the other, so this has to match how the project runs its tasks. Under directory, this project’s caches are host directories under <project>/.batect/caches/<name> and shared ones live at ~/.ratect/caches/<name>; with no home directory there are no shared ones. A .batect/caches or .batect that is a symbolic link is followed, as in Batect, so caches clean removes the cache directories wherever it points — see Cache volumes.

caches never reads the configuration file. A cache belongs to the project directory, so both commands work on a project whose configuration is broken or missing entirely — which is exactly when clearing a cache tends to be what’s needed.

caches list prints each cache under the name a volumes entry gives it, not the Docker volume it’s stored in; that name is what caches clean takes back. Under -o quiet it’s one name per line and nothing else, for scripting — and it prints this project’s caches only, unless --scope shared asks otherwise. What it emits is exactly what a caches clean carrying the same flags would act on, so the output can be piped straight back. Naming a cache that doesn’t exist warns on stderr rather than passing silently, since the likeliest cause is a typo. Under --cache-type directory, caches clean also warns when the project has no .batect/caches directory, and names each entry there that it skips because it is a symbolic link, which is never followed. caches clean reports each cache as it is removed, so a removal that fails, which stops the clean, leaves everything removed before it already reported above the error.

--scope <project|shared> restricts both commands to one kind of cache. A shared cache is one every project on the machine can use, so the listing keeps them apart — a shared cache is not this project’s, and most of the ones shown will belong to other projects. ratect caches list, captured on a terminal in examples/full-stack after a run, while ratect/tests/fixtures/shared-cache.toml’s warm-cache task had created its shared cache:

Caches for this project:
- full-stack-npm-cache

Shared caches on this machine:
- shared-tools

Removing a shared cache always takes --scope shared — whether it is named or not, and whether or not this project has a cache of the same name. A shared cache holds storage every other project on the machine is using, so it is never reached by an unqualified clean. ratect caches clean shared-tools, in the same state:

Error: 'shared-tools' is a shared cache, used by every project on this machine. Re-run with '--scope shared' to remove it.

caches clean with no names therefore sweeps this project’s caches only.

Both scopes are read from storage, not from the configuration — a project cache is found by its batect-cache-<key>- prefix, a shared one by ratect-shared-cache-. That is what keeps these commands working on a project whose configuration is broken. With --scope shared, they never read or create the project’s key file, .batect/caches/key, since only a project cache is named after it.

includes options

The Git include cache under ~/.ratect/incl — where a type: git include is cloned and kept. With no home directory there is no cache, and these find nothing. ratect includes list, captured after the one checked-in project with a Git include had been loaded once into an otherwise empty cache:

1 cached Git include(s), 261.3 KiB on disk:

  https://github.com/batect/hello-world-bundle.git at 0.12.0
    261.3 KiB, last used 0 seconds ago

Unlike caches and resources, this cache is global — one directory shared by every project on this machine, keyed by (repo, ref). So there’s no project scoping, and clean reaches other projects’ includes as well as your own. That matters less than it sounds: everything here is re-cloneable, so the worst case is a fetch.

A command that loads the project and has to clone an include for it prints Cloning <repo> <ref>... on stderr first, and a blank line once the clone has succeeded, in every style but quiet; includes refresh prints neither.

CommandDescription
includes cleanRemoves includes nothing has used for 30 days — the same threshold the automatic sweep applies, done on demand.
includes clean --older-than <AGE>A different threshold (30m, 2h, 7d).
includes clean --allEverything, regardless of age.
includes refreshDiscards every cached clone and fetches it again.

Every form of clean also removes the temporary directories left by clones that were interrupted, once unchanged for 30 days: a more recent one may be a clone still in progress. It removes what an interrupted clean, refresh or ratect-compat sweep left at once: each moves a clone aside before deleting it, so one cut short never leaves part of a clone for a later command to use. The next command that needs the include, or includes refresh, clones it again; until then includes list may still show it, at 0 bytes.

clean and refresh carry on past an include they can’t remove, or clone again, and then print an Error: on stderr for each, naming it and why, in every style, and exit 1. A refresh whose clone fails leaves that include removed: the next command that needs it clones it again.

clean names each leftover it removes by its path, after the includes, and counts the leftovers on the total line only when it removed some. One it can’t remove is an Error: and exit 1, as an include it can’t remove is. Here ratect includes clean --all, run with HOME pointed at a scratch directory holding three leftovers and no includes, one of them made unremovable by a read-only subdirectory, removes two and prints an error for the third:

Removed /tmp/ratect-home/.ratect/incl/ec3564423a4b2c600611e288ce72ff419cc95541211b9381ce8b741e9aaad18b.tmp-736f329f71b94dbbb8b10d25461379b0, left by an interrupted clone.
Removed /tmp/ratect-home/.ratect/incl/ec3564423a4b2c600611e288ce72ff419cc95541211b9381ce8b741e9aaad18b.del-bbb06d33962b4e77a2971e0d462b9a1c, left by an interrupted removal.
Removed 0 cached Git include(s) and 2 leftover(s) of interrupted clones and removals.
Error: Could not clean /tmp/ratect-home/.ratect/incl/ec3564423a4b2c600611e288ce72ff419cc95541211b9381ce8b741e9aaad18b.tmp-fda60e700d77468b937c8fd7de2bc4cf, left by an interrupted clone: Permission denied (os error 13)

Under -o quiet only the error is printed. refresh leaves leftovers to clean. Removing part of what an interrupted clone left counts as changing it, so once the cause of an error like this is fixed, clean leaves the rest for another 30 days.

refresh is how you pick up a moved ref. A (repo, ref) pair is cloned once and then never re-fetched, so if ref is a branch — or a tag someone re-pushed — your project keeps using whatever it pointed at the first time, indefinitely. The automatic sweep doesn’t help, because it removes entries that go unused, and an include you’re actively using never becomes stale. Pinning ref to something immutable remains the better answer; refresh is for when it isn’t.

Under -o quiet, list prints repo<TAB>ref<TAB>key per line and nothing else, where key is the entry’s directory under ~/.ratect/incl. In every style, credentials in a repo URL are shown as ***, as everywhere Ratect names one — and so is anything else between its :// and last @, so https://host/a@b shows as https://***@b. Two entries can then look alike only if their remotes differ in nothing but what was hidden, so in the other styles an entry with part of its repo hidden is also named by the first 12 characters of its key: https://***@host/repo.git at v1 (key 45de9a2d81c0).

resources options

Containers and networks outlive a run when something goes wrong — a crash, a kill -9, a --no-cleanup run, or a cleanup that failed. resources finds them by the labels Ratect stamps on everything it creates, so they’re identifiable however long ago they were made. ratect resources list, captured in examples/full-stack after ratect run journey-test --no-cleanup-after-success:

6 left over from 1 previous run:

  journey-test (7 seconds ago, run 11ac2452-81ed-412f-9dd5-3115c03563a9):
    - container db (running)
    - container cache (running)
    - container app (running)
    - container journey-test (exited)
    - container ratect-health-check-app (exited)
    - network ratect-full-stack-network-u4f9aa

Remove them with: ratect resources clean

Grouped by run, because that’s the unit a leftover belongs to: a run that was killed outright, or crashed, leaves a network and every container it started, and they only make sense together. (Ctrl+C, SIGTERM and SIGHUP aren’t those cases any more — each cleans up after itself. SIGKILL can’t be trapped by anything, so it still is; see Differences from Batect.) A container is named as your configuration names it, not by the <project>-<container>-<suffix> name it has in Docker — or, for the companion an external_health_check runs, by the ratect-health-check-<container> name Ratect gives it.

OptionApplies toDescription
--alllist, cleanTask runs Ratect can’t tell have ended, as well as those it can. Never a task run still going.
--all-projectslist, cleanEvery Ratect project’s leftovers, not just this one’s — never anything Ratect didn’t create. Also the way to use resources from outside a project directory, since the project scope is read from the configuration.
--older-than <AGE>list, cleanOnly task runs older than AGE — 90s, 30m, 2h, 7d. A task run’s age is its oldest container’s or network’s.

resources list is clean’s dry run. Both take the same options and select identically, so whatever list shows you is exactly what clean with those same options will remove — there’s no separate --dry-run because there’s nothing for it to do differently.

A task run still going is never selected. A task run carries the same labels whether it is going or left over, so each one holds a lock for as long as its process drives it, cleanup included — both binaries take it — and resources reads it. The kernel frees a lock when its process ends, however it ends, kill -9 included. Each task run is one of three things:

A task run isWhenSelected
endedits lock is free, and was written on this machine since it last bootedby default
still goingits lock is heldnever
unknownRatect can’t tell: there is no lock, it was written before a reboot or by another kernel (Ratect in a container sharing your home), or the lock can’t be read, as on some network filesystemswith --all

A task run’s containers and network are selected or left out together, and one selected by --all is listed as one Ratect can't tell it has ended. A task run is unknown in particular when it was left by a Ratect too old to take the lock, so a leftover from before an upgrade needs --all. So does every leftover once the machine has rebooted, though it has certainly ended. --older-than is the guard for those: resources clean --all --older-than 1d. On any platform but Linux and macOS, Windows included, every task run is unknown.

When the selection leaves task runs out for their state, both commands say so on stderr — Left out 2 task runs still going, and 1 task run Ratect can't tell has ended (pass --all to include it). A task run too young for --older-than isn’t counted there. Containers and networks carrying Ratect’s project label but no task run’s are neither selected nor counted, and nor is a service instance’s container whose image or configured labels gave it a task run’s label.

--all here composes with --older-than, where includes clean’ --all conflicts with it: that one means every cached include, whatever its age, while this one means every state a leftover can be in short of still going. Neither is --all-projects, which widens the scope to every project, not the states.

Each lock is a file, ~/.ratect/runs/<run>.lock, named for the task run’s id. A task run that cleaned up fully deletes its own, and clean deletes an ended task run’s once it has removed everything of it. Nothing else does: one kept by a task run that, cut short, stopped waiting for the daemon to answer a create (it may have made something), one left by a task run whose leftovers went another way (docker rm, or ratect-compat alone), or from before a reboot, stays, a few dozen bytes each. Delete them by hand only when nothing is running and nothing is left over, on this daemon or any other the home directory is used with: deleting a leftover’s file makes it unknown.

Under -o quiet, list prints resource ids one per line and nothing else, ready to pipe into docker rm. Removal takes containers before networks, since a network still holding an endpoint can’t be removed; a resource that fails to remove doesn’t stop the rest, but clean then exits 1 with one Error: naming each refusal.

resources reads one thing from the configuration — the root file’s project_name, to scope itself to this project — and nothing else in it, so neither the ratect_version check nor a value this machine can’t evaluate gets in the way. What to remove comes from the labels alone.

Nothing without Ratect’s own labels is ever listed or removed, --all-projects included: containers started by other tools, and Docker’s built-in bridge/host/ none networks, are invisible to both commands.

What this doesn’t cover: cache volumes/directories are caches’ territory, not resources’ — they’re a deliberate cache, not a leftover. Likewise the Git include cache under ~/.ratect/incl is includes’ own command. Built images are tagged <project>-<container> and reused/overwritten on every run rather than tracked as a resource — also a deliberate cache. Tmpfs mounts and exec instances die with their container, so there’s nothing left to find.

config

ratect config validate is doctor’s configuration half on its own — it loads the config, evaluates every container and task against this machine, and runs the same config-only checks (values this machine can’t evaluate, a build_directory/Dockerfile a build can’t use, an absolute dockerfile, floating image tags, dependencies with no health_check, an entry given more than once in one dependencies or prerequisites list, a mount above an identity home), exiting non-zero on a problem. It never touches Docker, so it’s the gate to run in CI when all you want to know is “is the config valid?”, without a daemon. It takes the same --config-var/--config-vars-file options as run, and reads ratect.local.toml the same way, since evaluating the config can need them. A config that doesn’t load stops at its first error.

ratect config convert migrates a Batect-format batect.yml project to the native format. It reads batect.yml unless -f names another file: -f’s usual ratect.toml default is the file it writes, not the one it reads.

ratect config convert          # writes ratect.toml beside it, and a .toml beside each include
ratect config convert --stdout  # prints instead, to review or pipe

It’s one-directional (ratect-compat stays YAML; the reverse would be lossy) and converts each file the project owns beside itself: the root becomes ratect.toml, and every local included file, at any depth, becomes a .toml with the same name in its own directory (more/c.yml → more/c.toml ), with each include entry rewritten to point at the converted file. Nothing is re-based — every value is copied exactly as written — so a relative path in more/c.toml resolves against more/, exactly as it did in more/c.yml (see Where relative paths resolve). A Git include stays a Git include, its repo, ref, path and allow_host_paths carried across: nothing from a bundle is copied out, and no file in one is converted. A root batect.yml with no project_name converts to a ratect.toml naming the project as ratect-compat does — after the root file’s directory — since ratect.toml requires one. Nothing is written if any converted file already exists — the error lists them all; pass --force to overwrite them, or --stdout to print instead. With more than one file, --stdout prints each document in order, the root first, each under a # === … === banner naming its file (more/c.toml ).

The conversion preserves each file’s configuration, not formatting: YAML anchors/aliases/merge keys are expanded inline and comments are dropped — so each output carries a header and is a starting point to review, not a blind drop-in. Before anything is written, every conversion is checked to round-trip losslessly back to the same configuration, so each file encodes the configuration you started with — and every way ratect runs that configuration differently is listed, as below.

A task’s own container has no readiness gate, so its health check — from health_check or from its image’s own HEALTHCHECK — isn’t waited on, and its setup_commands don’t run (see Dependency Readiness). An image’s HEALTHCHECK can’t be seen without the image, so check those yourself. An enabled run_as_current_user becomes identity, which doesn’t replace the image’s identity files, and applies --user and changes a cache volume’s owner only on a rootful Linux daemon, and a disabled one is dropped (what changes). Its home_directory is used as written in a batect.yml but evaluated as identity.home in a ratect.toml, so one containing a $ or < expression changes value, and one holding a .. is refused until that is changed. Likewise, a string-form volumes entry’s host path is used as written in a batect.yml but evaluated in a ratect.toml. A \ in either stays a backslash (foo\bar becomes foo\\bar), since a batect.yml never reads one as an escape, so a $ or < after one is still converted as an expression, and listed. One that would then be no valid expression — img$, a $ with no name after it — can’t have meant one, so convert escapes it whole (img\$) and it keeps its value, unlisted. An image is always escaped whole: a batect.yml refuses an expression there, so nothing in one was meant as one. Two more concern a Git include. A pathless entry whose bundle also offers a ratect-bundle.toml would have ratect load that file instead of the batect-bundle.yml the batect.yml loaded, so convert sets its path to batect-bundle.yml and says so; remove path to switch to the native file. And a bundle declaring Git includes of its own is refused by ratect unless allow_nested_git_includes is set on that entry (see Nested Git includes) — a grant convert never writes for you.

config convert lists each place in the converted project where one of these applies — per converted file, its include entries’ items first, then its containers’ in order of container name — after converting, and again in that file’s own header, so the list travels with the file. ratect -f batect.yml config convert --stdout, captured in ratect/tests/fixtures/convert — a project with something to check:

# Generated by `ratect config convert` from batect.yml.
# Review before use: comments were not carried over.
#
# Check before use:
# Task 'test' runs container 'app' as its own, so under ratect the container's 'setup_commands' don't run — a task's own container has no readiness gate (see https://github.com/or1can/ratect/blob/main/docs/dependency-readiness.md#the-tasks-own-container).
# Container 'app' has a volume host path '$HOME/.cache', which batect.yml uses as written but ratect evaluates as an expression — check what it resolves to under ratect.

ratect_version = "0.13.0"
project_name = "convert-fixture"

[containers.app]
image = "alpine:3.18.2"

[[containers.app.setup_commands]]
command = "./warm-cache.sh"

[[containers.app.volumes]]
container = "/cache"
local = "$HOME/.cache"

[tasks.test]
description = "Runs the tests"

[tasks.test.run]
command = "./run-tests.sh"
container = "app"
Check before using ratect.toml:
  warning Task 'test' runs container 'app' as its own, so under ratect the container's 'setup_commands' don't run — a task's own container has no readiness gate (see https://github.com/or1can/ratect/blob/main/docs/dependency-readiness.md#the-tasks-own-container).
  warning Container 'app' has a volume host path '$HOME/.cache', which batect.yml uses as written but ratect evaluates as an expression — check what it resolves to under ratect.

With --stdout, the documents are all that reaches stdout; each heading and its list after it are on stderr. Without it, they follow the success message on stdout, naming the file written. With nothing to check, neither the list nor the header block appears. Either way the conversion succeeds and exits 0, and the list prints whatever RUST_LOG is set to, under -o quiet too.

The result declares the converting binary’s own version as its ratect_version. It writes each volumes, ports and devices entry as an object, the only form the native schema admits, whichever form batect.yml used.

doctor

Answers “why did that fail?”, or “will it?”, without running a task. ratect doctor, captured in ratect/tests/fixtures/doctor — a project written to trip each warning and a problem — after ratect run build --no-cleanup-after-success there:

Checking ratect.toml...
  ok      Docker daemon reachable (29.8.2)
  ok      Docker daemon class: desktop
  warning 'batect' is a Batect wrapper script and still runs Batect, not Ratect — delete it and run ratect (or ratect-compat) from your PATH
  ok      ratect.toml loads (6 container(s), 2 task(s))
  warning Container 'deploy': cannot evaluate 'environment.TOKEN' ('$DEPLOY_TOKEN'): Host environment variable 'DEPLOY_TOKEN' is not set, and no default was given (e.g. '${DEPLOY_TOKEN:-default}') — a run that reaches it fails on this machine
  warning container 'database' uses a floating image tag — pin it, or the same configuration will run a different image later
  warning dependency 'cache' has no health_check — unless its image defines one, it counts as ready the moment it starts
  warning container 'app' gives 'cache' more than once in its 'dependencies' — it starts only once
  problem container 'app': build_directory '/private/tmp/ratect/ratect/tests/fixtures/doctor/missing-dir' doesn't exist
  warning container 'scratch' has identity.home '/work/me' under the writable bind mount at '/work' — a home that doesn't exist yet is created on the host, in that directory
  warning 1 task run(s) left over from previous runs — see `ratect resources list`

11 check(s): 1 problem(s), 7 warning(s).
Error: 1 problem(s) found.

The Docker daemon class line says which kind of daemon this connection reached: rootless or userns-remap when the daemon reports it, desktop when Ratect runs on macOS or Windows and reaches it over a local socket, and rootful Linux otherwise. A daemon reached over the network is classified by what it reports, so it is never desktop. Docker Desktop on Linux is rootful Linux, deliberately: only vendor-specific signals tell it from a native daemon (why), and identity treats it as one. If the daemon answers but its class can’t be read, that is a warning.

The class also decides two warnings a run gives too, about containers in the project, whichever task reaches them, leaving out a base with no image or build_directory, which nothing can run:

  • identity on a userns-remap daemon. 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. Its home is still guaranteed.
  • A non-root user on a rootless or userns-remap daemon. The container has only other users’ access to a bind mount the host user owns, so it usually can’t write there or read anything private. A user of 0 or root isn’t reported.

Neither stops a run, and a run reaching such a container warns about it too. doctor can’t report the third thing a run warns about, an identity container whose image runs it as a non-root user on either daemon: the image’s user isn’t in the configuration, the image may not be local, and doctor doesn’t pull it. config validate reports none of these, since it doesn’t connect to a daemon.

On a rootful Linux daemon, doctor also warns about each writable bind mount of a container that writes there as root, whose files may end up root-owned on the host, and suggests identity, or run_as_current_user for a container in a .yml file, which can’t set identity. That is a container with no identity, no enabled run_as_current_user, and either no user or a user of 0 or root. With no user it assumes root, since it doesn’t pull the image to find out. It fires on Docker Desktop on Linux too, where the files are in fact the host user’s, because that file sharing is what the class can’t see. identity is still sound there. A mounted socket or single file isn’t reported, since a write can’t change its owner, except from a daemon reached over the network, whose paths aren’t on this machine to look at. It says nothing when you are root, since root-owned files are then yours. A run doesn’t warn about this, and neither does config validate.

Over a local socket to a rootful Linux daemon, doctor also reads who owns each writable bind mount’s host path, for a container that runs as you: one with identity, or an enabled run_as_current_user. If another uid owns it, it warns that a write there may be refused, as it can be for a directory an earlier run left root-owned. “May”, since group or other permissions can still allow it, and on Docker Desktop on Linux a bind mount looks like the container user’s own, so the write may well succeed. A missing path isn’t reported, since a run tries to create it as you, and nor is one whose owner can’t be read, or anything when you are root. A daemon reached over the network isn’t checked, because its mounts are on its own filesystem, and neither is any other class, where the container doesn’t run as your uid. It’s a warning, and config validate doesn’t report it.

A problem will fail a run — an unreachable daemon, a configuration that doesn’t load, a build_directory or Dockerfile a build can’t use. A warning works but is likely to bite: a floating image tag (latest, or no tag at all) means the same configuration runs a different image next week, an absolute dockerfile only works where the project is checked out at that path, and a dependency with no health_check counts as ready the moment it starts unless its image defines one, which is where “connection refused” on the first run comes from.

So is each value this machine can’t evaluate — an unset $VAR, a <var with no value — naming its container or task, its field and the expression, as deploy’s $DEPLOY_TOKEN above. Every one is reported, not only the first. It’s a warning rather than a problem because a variable only CI sets is expected to be missing on a laptop, and it fails only a run that reaches it: ratect run build there never evaluates deploy. The same goes for a value that evaluates but can’t be used — an expression-valued identity.home that isn’t an absolute path, or a Git-included container’s host path that evaluates to somewhere outside its boundary. A container with such a value is left out of the checks that read its values, so its image tag and build_directory aren’t judged until it evaluates. When everything evaluates, doctor says so on its own ok line.

A dependencies or prerequisites list that gives the same entry twice is a warning, as app’s cache above. Batect refuses such a file; Ratect loads it and starts or runs the entry once, so the repeat is reported rather than refused. Entries are compared as written: a wildcard prerequisite given twice is a repeat, but a wildcard beside a task it matches is not.

A mount above a container’s identity home is reported for what it does to that home, which is created through the mount before the container starts. The deepest mount strictly above the home decides, with a bind mount or cache going over a tmpfs at the same path, and a mount at the home itself supplies it, so that gets no finding whatever is above it:

Deepest mount above the homeFinding
tmpfsProblem: the run fails, whether or not the home already exists
Read-only bind mount or cacheWarning: the run fails unless the home already exists there
Writable bind mountWarning: a missing home is created on the host, in that directory
Writable cacheNone

A tmpfs higher up changes nothing, since a deeper mount goes on top of it when the container starts. A cache under --cache-type=directory, a host directory, is judged as a volume, since neither doctor nor config validate takes that flag. Only the configuration’s mounts are read, so a VOLUME the image declares between a tmpfs and the home gets the tmpfs’s problem, though the home is created in that volume and the run works.

If you’re migrating from Batect, doctor also flags a leftover batect/batect.cmd wrapper script. Those aren’t harmless: ./batect still downloads and runs the unmaintained JVM binary, so you can think you’ve switched to Ratect while ./batect quietly runs the old tool.

Delete the wrapper and run ratect (or ratect-compat, for strict Batect compatibility) from your PATH. Batect’s committed wrapper was its installer — it fetched the right JVM version on demand — whereas Ratect is an ordinary binary you install once, so there’s nothing for a committed wrapper to do. (Don’t repoint the wrapper at Ratect by symlinking it: a committed symlink is machine-specific and doesn’t work for batect.cmd on Windows, and it still needs the binary on the PATH anyway.)

The one exception is a codebase with ./batect hardcoded across CI jobs, Makefiles and docs that you can’t change all at once: there, replacing the wrapper with a one-line transitional shim — exec ratect-compat "$@" — keeps those call sites working while you migrate them (it still needs ratect-compat on the PATH). A wrapper that no longer runs Batect isn’t flagged.

doctor exits non-zero if it found any problem, and zero for warnings alone, so it works as a CI step. Under -o quiet it prints only warnings and problems.

The environment checks run even when the configuration itself won’t load — “your config is broken and your daemon isn’t running” is more useful than fixing one to discover the other. It also reports leftovers unprompted, since the whole reason resources exists is that nobody thinks to look: a warning counting the leftover task runs that have ended, which is what a bare resources clean removes, and another counting those Ratect can’t tell have ended, pointing at resources list --all. A task run still going isn’t reported.

Shell completion

ratect completions <shell> prints a completion registration script to stdout for bash, zsh, fish, powershell or elvish. Source it from your shell’s startup file:

# bash — in ~/.bashrc
source <(ratect completions bash)

# zsh — in ~/.zshrc, *after* compinit has run (see the note below)
source <(ratect completions zsh)

# fish — in ~/.config/fish/config.fish
ratect completions fish | source

zsh needs its completion system initialized first. The zsh script ends with a compdef call, and compdef only exists once compinit has run — so the source line must come after autoload -U compinit && compinit in your ~/.zshrc (frameworks like oh-my-zsh already run compinit for you; just keep the source line after they load). Sourcing it in a bare shell that hasn’t run compinit fails with command not found: compdef; run autoload -U compinit && compinit first to try it interactively. bash and fish need no such initialization.

It completes command and flag names, their fixed values (-o fancy|simple|…, --cache-type volume|directory), file-path arguments, and — the part that earns its keep on a task runner — task names: ratect run <TAB> lists the tasks your config defines. That last one is dynamic: the installed script re-invokes ratect at completion time to read the config, always without cloning, pulling, or touching Docker, so a <TAB> is instant and safe.

Task completion honours an explicit -f, and follows the config’s includes — local files, and Git includes that are already cached. It never clones or pulls, so tasks from a Git include that hasn’t been fetched yet won’t appear until the first real run caches it.

Built on an unstable API. Task-name completion uses clap’s unstable-dynamic engine, so it may occasionally need a fix as that API settles. The static parts (commands, flags, values, paths) don’t depend on it.

Exit codes and diagnostics

Identical to ratect-compat’s: both binaries share one mapping, whose design is decisions/0016. An invocation is on one of two paths, and its exit code depends on which. ratect run is a run, even when its arguments don’t parse, and so is ratect services up; every other verb isn’t. For a line that doesn’t parse, the subcommand counts where it would be read as one — not after --, and not as another option’s value — so ratect --bogus run test is a run. --help and --version exit 0 on either path, once the arguments reach them.

ratect services up is a run too, whose exit code is the one its group’s exit_code_from selects in place of the task’s own (see services options); the rules below hold for it with that change.

A run exits with one of three things, answering one question: did the task’s own container run to an exit code of its own?

  1. It did: that exit code, 0 included. A task’s own 125, 126 or 127 passes through the same way, and a prerequisite that fails this way stops the chain. One exception: if every container exited 0 but Ratect then fails to clean up — a removal the daemon refused, or a cleanup stopped with Ctrl+C with something still to remove — the run exits 125 instead, and a prerequisite whose cleanup fails stops the chain there. A task’s own non-zero code is never overridden. A container or network that something else already removed, such as a dependency docker rm -f’d mid-run, isn’t a cleanup failure, since nothing is left behind.
  2. A termination signal ended it: 128 + that signal’s own number — 130 for Ctrl+C (SIGINT), 143 for SIGTERM, 129 for SIGHUP. Any of the three abandons the run and then cleans up after it; a second one during that cleanup force-removes whatever is left, a Ctrl+C after that stops the cleanup, and ratect resources list finds whatever that leaves (for services up, ratect services down <group> removes it instead). A signal that arrives only during the cleanup of a run that had already finished doesn’t change its exit code; one during a prerequisite’s cleanup ends the run before the next task starts; one while the run is still connecting to Docker ends it at once, with nothing yet to clean up. A run whose stdout reader goes away — ratect run test | head -n 1, once head has its line — ends the same way, as though SIGPIPE had ended it: 141, after the same cleanup. A closed stderr never ends a run.
  3. It never ran, or never finished, for any other reason: 125 — an unknown or misused flag (ratect run --bogus, ratect -o bogus run test), a config file that isn’t there, a config that doesn’t load, an unknown task, an unreachable daemon, a failed pull or build, a dependency that never became ready. An unknown task’s error ends with how to list the tasks: (Run 'ratect tasks list' for a list of all tasks in this project, or 'ratect run --help' for help.).

Every other verb runs nothing, so it exits 0 when it succeeds; 1 when it fails (config validate on a file that doesn’t parse, caches list with the daemon down, doctor finding a problem); and 2 when it was invoked wrong — a flag that’s rejected (ratect --bogus, ratect tasks list --bogus, a missing subcommand), or an option value that fails its own check, such as a -f naming no file (ratect tasks list where there is no ratect.toml) or a --docker-config naming no directory. doctor and config validate report a -f naming no file as a problem they found instead, and exit 1, as doctor does a Docker directory that isn’t one; a flag rejected in their own arguments is still 2.

Every failure of Ratect’s own reaches stderr as Error: <message>, in every output style including quiet, whatever RUST_LOG says. Two kinds of failed run print no Error: line, because something else already reported them: a task’s own non-zero exit (rule 1 — the code itself and, outside quiet, the finished with exit code N summary line), and a run ended by a signal or a closed stdout (rule 2 — the notice saying so). A failure to run a task that has started is reported when it happens, before cleanup; one before any task starts, as ratect exits. ratect-compat’s section has each rule in full.

  • RUST_LOG controls Ratect’s own internal logging (default info, on stderr — see Filtering RUST_LOG). Unlike ratect-compat there’s no --log-file; redirect stderr if you want one.
  • A crash (a genuine bug) exits 101 and prints where to report it, ratect’s version and platform, and a reminder to re-run with RUST_BACKTRACE=1 if it isn’t already set — see ratect-compat’s own note on this, which applies identically here.

Differences from ratect-compat

ratect-compatratect
Run a taskratect-compat <task>ratect run <task>
List tasksratect-compat --list-tasksratect tasks list
Cache cleanup--clean/--clean-cacheratect caches clean [NAME...]
Listing cachesnot availableratect caches list
Finding leftovers from a previous runnot availableratect resources list/clean
Bringing a group of containers up togethernot availableratect services up/down/list
Checking a project without running itnot availableratect doctor
Managing the Git include cachenot available (only the automatic sweep)ratect includes list/clean/refresh
Batect-inert flags (--upgrade, --no-update-notification, --no-wrapper-cache-cleanup)accepted, no effectnot offered
--log-filesupportednot offered
Configurationbatect.ymlnative ratect.toml (with extends); batect.yml still readable via -f

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.

ratect-compat CLI Reference

ratect-compat [OPTIONS] [TASK_NAME] [-- ADDITIONAL_ARGS...]

This reflects the flags Ratect implements (ratect-compat/src/main.rs) — every Batect CLI flag is supported, flag-for-flag, unless listed in differences from Batect.

This is the ratect-compat binary, whose interface deliberately matches Batect’s. The forward-looking ratect binary has its own, subcommand-based interface — see the ratect CLI reference, and Two binaries, two formats for which to pick.

Where options go

Options go before the task name, as in Batect. The first argument that isn’t an option or an option’s value is the task name, and nothing after it is read as an option. Only -- and arguments for the task may follow the task name: anything else, such as ratect-compat build --disable-ports or ratect-compat build extra, is refused before anything runs, with an error naming the task name and the first extra argument. Under --list-tasks, --clean, --clean-cache or --upgrade, which replace the task, whatever follows the options is ignored, so ratect-compat --list-tasks a b lists the tasks.

An option’s value that starts with - has to be given after =, as in --use-network=-x: given as the next argument, it’s refused — see differences from Batect.

A path given to -f, --config-vars-file or --log-file is resolved as Batect resolves it: a leading ~ is your home directory, even where the shell leaves it alone (--config-file=~/batect.yml), and . and .. are removed before the path is used, so link/../batect.yml is ./batect.yml whether or not link is a symlink. A leading .. stays. Before any command runs — --clean included — an -f you give must name a file, and so must --config-vars-file; a --log-file must name a file or nothing yet.

Options

Grouped by purpose, matching ratect-compat --help. The grouping is presentational only — every flag parses the same regardless of the section it’s listed under. A value placeholder here, such as <CONTAINER=IMAGE>, describes the shape of the value; --help prints clap’s own instead, named after the option (--override-image <OVERRIDE_IMAGE>).

FlagShortDefaultDescription
--config-file <PATH>-fbatect.ymlPath to the configuration file to load.
--list-tasks-T—List all tasks defined in the config file, then exit. Doesn’t run anything.
--help-h—Print help (auto-generated by clap).
--version-V—Print the Ratect version.

Configuration variables

FlagShortDefaultDescription
--config-var <NAME=VALUE>——Sets a config variable’s value; repeatable, once per NAME — a NAME given twice is rejected while the arguments are parsed. Takes precedence over --config-vars-file and the variable’s default.
--config-vars-file <PATH>—batect.local.yml if it existsA flat YAML file of config variable name: value pairs, in the same format as batect.yml itself. Every value is a string, as in Batect: an unquoted number or boolean is read as written (3.10 is 3.10, not 3.1), and a null or empty value is refused. Lower precedence than --config-var. When not given, defaults to batect.local.yml in the current directory if that file exists (an absent default file just means no overrides from a file, not an error); one that exists but isn’t a file fails every command, as in Batect. Read only when a task runs, as in Batect: every command checks only that a named file is a file, so nothing in it, nor a --config-var naming an undeclared variable, stops --list-tasks.

Task execution

FlagShortDefaultDescription
--use-network <NAME>——Reuses an existing Docker network for every task in this invocation instead of creating (and removing) a fresh one per task. Errors clearly if the named network doesn’t exist. See task lifecycle.
--disable-ports——Disables publishing of any container’s ports to the host, regardless of what’s configured.
--no-proxy-vars——Don’t propagate proxy environment variables (http_proxy, https_proxy, ftp_proxy, no_proxy) to image builds or containers, nor the proxies in Docker’s config.json to image builds — see Proxies.
--skip-prerequisites——Don’t run the named task’s own prerequisites. Only ever affects the task actually named on the command line — if that task is itself reached as someone else’s prerequisite in a later invocation, this flag has no bearing on that.
--override-image <CONTAINER=IMAGE>——Overrides the image used by CONTAINER; repeatable. Replaces the container’s image/build_directory and image_pull_policy entirely — the override is always pulled under the default IfNotPresent policy, regardless of what the container itself configures. An empty CONTAINER or IMAGE, a CONTAINER given twice, or one also given to --tag-image, is rejected while the arguments are parsed. A CONTAINER the config doesn’t define fails the run once it reaches its first task with a run, before anything of that task starts; a run that reaches no such task, such as --skip-prerequisites on a task with only prerequisites, doesn’t check it.
--tag-image <CONTAINER=TAG>——Tags the image built by CONTAINER with TAG, in addition to the default <project_name>-<container_name> tag; repeatable, and CONTAINER may be given more than once to apply multiple tags. Only valid for a container that actually builds an image — errors immediately if CONTAINER is configured to use a pulled image, and errors once the whole task (and its prerequisites) finishes if CONTAINER never actually ran. An empty CONTAINER or TAG, or a TAG that docker tag would refuse, such as _nonsense or one with uppercase in its repository name, is rejected while the arguments are parsed, before anything runs, and so is a CONTAINER also given to --override-image, before the config is loaded.
--enable-buildkit——Use BuildKit for image builds, taking precedence over the DOCKER_BUILDKIT environment variable — see config reference. No --disable-buildkit counterpart; force the classic builder via DOCKER_BUILDKIT=0 instead.
--max-parallelism <N>—unboundedFrom 1 to 2147483647, as in Batect. Caps how many image pulls/builds, container creates, dependency container starts, and setup-command executions run concurrently across the whole invocation — a create and a start are separate capped steps, and no slot is held while a container waits for its dependencies. Health-check waits, the task’s own container’s run, and container stop/removal are never gated — see Differences from Batect.
--cache-type <volume|directory>—BATECT_CACHE_TYPE, then volumeStorage mechanism for a cache volume mount (see Cache volumes): volume resolves it to a Docker named volume, directory to a host directory under <project_directory>/.batect/caches/<name>/. Has no effect on a config with no cache mounts — but does still select which storage --clean/--clean-cache act on. A BATECT_CACHE_TYPE that is neither volume nor directory, exactly, fails every command unless this flag is given.

Cleanup after a run

FlagShortDefaultDescription
--no-cleanup——Equivalent to providing both --no-cleanup-after-failure and --no-cleanup-after-success.
--no-cleanup-after-failure——If an infrastructure error occurs (a build/pull/health-check/setup-command failure, or anything else before the task’s own container gets to run — or the task container’s own health check or setup commands failing while its main command is still running, which cancels it), leave every container and network created for the task that failed in place instead of removing them, so the issue can be investigated — a prerequisite’s failure included. A task’s own container exiting non-zero is not “failure” for this purpose — see --no-cleanup-after-success. One divergence from Batect: containers are left genuinely running, not just present-but-stopped — see Differences from Batect.
--no-cleanup-after-success——If the named task’s own container runs to completion — regardless of its exit code — leave every container and network created for that task in place instead of removing them. Prerequisites are still cleaned up after success, so only the named task’s resources are kept. Same divergence as --no-cleanup-after-failure: left genuinely running, not stopped-but-present. The exit code is still the task container’s own, where Batect’s is always 255 here — see Differences from Batect.

Docker connection

Which daemon these reach, their DOCKER_* environment-variable defaults, and TLS with a private certificate authority are on Connecting to Docker, shared with ratect. Every invocation accepts them; they’re used only when it actually connects. --docker-context beside --docker-host or a TLS option is refused whether or not the invocation connects, as in Batect.

FlagShortDefaultDescription
--docker-host <HOST>—DOCKER_HOSTDocker host to connect to — see Connecting to Docker.
--docker-context <NAME>—DOCKER_CONTEXT, then the active context, unless a host is setDocker CLI context to connect through — see Connecting to Docker.
--docker-config <PATH>—DOCKER_CONFIG, then ~/.dockerDirectory containing the Docker CLI’s own configuration — see Connecting to Docker.
--docker-tls——Use TLS, identically to --docker-tls-verify — see Connecting to Docker.
--docker-tls-verify—DOCKER_TLS_VERIFYUse TLS, verifying the daemon’s certificate — see Connecting to Docker.
--docker-cert-path <PATH>—DOCKER_CERT_PATH, then --docker-config/DOCKER_CONFIG, then ~/.dockerDirectory containing any of ca.pem/cert.pem/key.pem — see Connecting to Docker.
--docker-tls-ca-cert <PATH>—ca.pem in the certificate directoryThe TLS CA certificate — see Connecting to Docker.
--docker-tls-cert <PATH>—cert.pem in the certificate directoryThe TLS client certificate — see Connecting to Docker.
--docker-tls-key <PATH>—key.pem in the certificate directoryThe TLS client key — see Connecting to Docker.

Cache management

FlagShortDefaultDescription
--clean——Removes every one of this project’s own cache volumes/directories (per --cache-type or BATECT_CACHE_TYPE) and exits — doesn’t run anything, and never reads the config file, though a --config-file you give must name one. See Cache volumes.
--clean-cache <NAME>——Removes just the named caches and exits, instead of every one of them. Takes a comma-separated list of names, each trimmed of surrounding whitespace, and is repeatable. Given together with --clean, the explicit name(s) win — --clean’s own “everything” behavior only applies when --clean-cache is never given at all.

Output

FlagShortDefaultDescription
--output <STYLE>-oautofancy, simple, quiet or all; unset auto-selects fancy on an interactive console, simple otherwise — see Output Styles.
--no-color——No color in Ratect’s own output (a task’s own output is never affected), and simple becomes the auto-selected style — see Colour for how it combines with NO_COLOR/CLICOLOR_FORCE.
--log-file <PATH>——Writes Ratect’s own internal logs to this file, in addition to stderr: Ratect’s own at debug and other crates’ at info, ending with why the run failed when it did — unless RUST_LOG is set, in which case it governs the file too (see Environment variables). Bollard’s debug records, which carry each Docker request’s body, a container’s environment included, reach the file only when RUST_LOG asks for them. Plain text, one record per line, no ANSI color codes; stderr’s own output, colour included, is the same with or without it.

Recognized, no effect

--upgrade, --no-update-notification, and --no-wrapper-cache-cleanup are accepted but change nothing Ratect does — hidden from --help, since they’re not real Ratect features, just recognized so an existing Batect invocation carrying one doesn’t hard-fail outright (an unrecognized flag is a clap parse error that kills the entire invocation before anything runs at all, including --list-tasks — unless it comes after --version or --help, which act as soon as they’re reached). All three only make sense for Batect’s own self-updating wrapper script, which Ratect — a single native binary — doesn’t have and isn’t planning to grow. --upgrade specifically prints a one-line notice to stderr and exits 0 rather than running silently, since a user invoking it is likely expecting some visible response; reinstall or rebuild Ratect to get a newer version instead. As in Batect, it’s still a command of its own: it replaces a task name and --clean/--clean-cache, which then don’t run, while --list-tasks replaces it, which then lists the tasks and prints no notice. The other two have no wrapper-cache/update notification to disable in the first place, so they’re silently accepted with no message at all.

Output styles

The four styles (fancy, simple, quiet, all), their captures and the auto-selection rule are on Output Styles, shared with ratect — the rendering is the same code in both binaries.

TLS with a private certificate authority

Why Ratect never skips certificate verification, and the worked example of running your own CA instead, are on Connecting to Docker, shared with ratect.

Positional arguments

ArgumentDescription
TASK_NAMEThe name of the task to run, as defined under tasks: in the config file. Required unless --list-tasks, --clean, --clean-cache or --upgrade is given — see Exit codes and error reporting.
-- ADDITIONAL_ARGS...Anything after a literal -- is appended as literal argv entries after the task’s own tokenized command — see below. Only applies to the task named on the command line, never to its prerequisites.

Examples

# List tasks defined in ./batect.yml
ratect-compat --list-tasks

# Run a task from ./batect.yml
ratect-compat test

# Use a config file in a different location
ratect-compat -f ./ci/batect.yml build

# Pass extra arguments through to the task's command
ratect-compat test -- --verbose some/specific/file.rs

# Set a config variable referenced via `<name`/`<{name}` in `environment`
ratect-compat --config-var environment_name=staging test

# Load config variable values from a file instead
ratect-compat --config-vars-file ./ci/config-vars.yml test

Using ADDITIONAL_ARGS in a task command

run.command is tokenized into literal argv (quote/backslash-aware whitespace splitting, no shell involved — matching Batect’s own tokenizer exactly), and anything after -- is appended as further literal argv entries — no special syntax needed in command itself to receive them:

tasks:
  test:
    run:
      container: build-env
      command: cargo test

Running ratect-compat test -- --nocapture here runs cargo test --nocapture inside the container. Args are appended as literal argv entries (never concatenated into the command string and re-parsed), so they’re safe even if they contain characters that would be shell metacharacters elsewhere, like ;, &&, or backticks — Ratect never passes command/ADDITIONAL_ARGS through a shell at all.

If neither the task’s run nor its container has a command, ADDITIONAL_ARGS (when given) replace the image’s default CMD, as plain docker run <image> <args> does; the image’s ENTRYPOINT is kept. So for an image built with ENTRYPOINT ["server"] and CMD ["--port", "80"], ratect-compat <task> -- --debug runs server --debug, not server --port 80 --debug. With RUST_LOG=debug, the run logs the CMD the arguments replaced.

Exit codes and error reporting

An invocation is on one of two paths, and its exit code depends on which. A line is a run unless it has one of the flags that replace a task: --list-tasks/-T, --clean, --clean-cache or --upgrade. That holds whether or not a task is named and whether or not the arguments parse; a flag counts only where it would be read as one, not after -- or as another option’s value. --help and --version exit 0 on either path, once the arguments reach them. The design is decisions/0016.

A run — ratect-compat <task> — exits with one of three things, answering one question: did the task’s own container run to an exit code of its own?

  1. It did: that exit code, 0 included. Ratect waits for the container to exit and inspects its status — a task whose command is exit 42 makes ratect-compat itself exit 42, matching docker run’s convention rather than collapsing every failure to one code. A task’s own 125, 126 or 127 passes through the same way. A task that runs as a prerequisite and fails this way stops the rest of the chain immediately — no other prerequisites, and not the task that depended on it, will run — matching Batect’s documented behavior. One exception: if every container exited 0 but Ratect then fails to clean up — the daemon refuses to remove a container or the task network, or a Ctrl+C stops the cleanup with something still to remove — the run exits 125 instead, and a prerequisite that fails this way stops the chain there. A task’s own non-zero code is never overridden, and what --no-cleanup, --no-cleanup-after-success or --no-cleanup-after-failure leaves in place on purpose isn’t a cleanup failure — nor is a container or network that something else already removed, such as a dependency docker rm -f’d mid-run, since nothing is left behind.
  2. A termination signal ended it: 128 + that signal’s own number — 130 for Ctrl+C (SIGINT), 143 for SIGTERM, 129 for SIGHUP — the shell’s own convention, so a script or CI job can tell a cancelled run apart from a failed one and tell what cancelled it, whatever cleanup does afterwards. All three abandon the run and then clean it up — see Differences from Batect for the full behavior, including what --no-cleanup-after-failure does to it and what a second signal does. A signal that arrives only during the cleanup of a run that had already finished ended nothing, so rule 1 applies: a passing run whose cleanup then completes still exits 0. One that arrives during a prerequisite’s cleanup ends the run before the next task starts, and exits 128 + its number. One that arrives while the run is still connecting to Docker ends it at once, with nothing yet to clean up, however long the connection would have taken. A run whose stdout reader goes away — ratect-compat test | head -n 1, once head has its line — ends the same way, as though SIGPIPE had ended it: it exits 141, after the same cleanup, with a notice on stderr saying the stdout closed. A closed stderr never ends a run.
  3. It never ran, or never finished, for any other reason: 125 — docker run’s own code for “the docker command itself failed”. An unknown or misused flag (ratect-compat --bogus build, or a bare ratect-compat --bogus), no task name, a missing or malformed config file, a --config-vars-file that isn’t a file, a task or container referenced by name that doesn’t exist, a dependency cycle, an unreachable daemon, an image pull or build that fails, a dependency that exits or never becomes ready, a setup command that fails, a --log-file that can’t be opened: all 125, one code, with the reason on stderr.

Everything other than a run — --list-tasks, --clean, --clean-cache, --upgrade — runs nothing, so it exits 0 when it succeeds, 1 when it fails (a config that doesn’t parse under --list-tasks, a --log-file that exists but can’t be opened), and 2 when it was invoked wrong: a flag that’s rejected (ratect-compat --bogus --clean), or an option value that fails its own check — a -f or --config-vars-file naming something that doesn’t exist or isn’t a file, a batect.local.yml that isn’t a file, a BATECT_CACHE_TYPE that is no cache type, a --docker-config, --docker-cert-path, DOCKER_CONFIG or DOCKER_CERT_PATH naming something that doesn’t exist or isn’t a directory, --docker-context beside --docker-host or a TLS option, or a --log-file in a directory that doesn’t exist, or that exists but isn’t a file.

Every failure of Ratect’s own is printed to stderr as Error: <message> (the marker in bold red when stderr is a terminal) — deliberately not through tracing::error!/RUST_LOG (which Ratect’s internal diagnostics go through — see how it works): a fatal error is the reason the process is about to exit non-zero, not an optional diagnostic, so it stays visible even under RUST_LOG=off or a filter that excludes Ratect’s own target — including under -o quiet. Two kinds of failed run print no Error: line, because something else already reported them: a task’s own non-zero exit (rule 1 — the exit code, and outside quiet the finished with exit code N summary line, say it, and the container’s own output says why), and a run ended by a signal or a closed stdout (rule 2 — the notice said so when it happened). A cleanup failure is reported once, as it happens, by a line naming what was left behind and the docker command that removes it. A failure to run a task that has started (an image that won’t pull or build, a container that can’t be created or started, a dependency that never becomes ready) is reported once too, when it happens — before the cleanup that follows it, as under Batect; any failure before a task starts is printed as the process exits.

  • Running with no task name, and none of --list-tasks, --clean, --clean-cache or --upgrade, is a command-line error, found before the config-variables file or the config is read — so a missing or broken -f still reports the missing task name. It exits 125, like any other usage error on a run, and the error, which points at --list-tasks and --help, is always on stderr, whatever RUST_LOG or -o says. So is -- ADDITIONAL_ARGS with no task name before it.
  • A misspelled task name (whether given directly on the command line, or as a prerequisites entry) gets a Did you mean 'x'? suggestion appended to the error, for every existing task name within a Levenshtein edit distance of 3 — ported from Batect’s own TaskSuggester/EditDistanceCalculator (confirmed by reading Batect’s source). Multiple equally-close matches are all suggested, e.g. Did you mean 'build' or 'bulid'? — Batect’s own implementation can silently drop one of two equally-close suggestions (its sorting comparator doubles as its de-duplication key), which Ratect’s deliberately doesn’t replicate.
  • A task named on the command line that doesn’t exist ends its error with how to list the tasks, after any suggestion: Task 'tst' not found. Did you mean 'test'? (Run 'ratect-compat --list-tasks' for a list of all tasks in this project, or 'ratect-compat --help' for help.), in every output style. A missing prerequisites entry gets no such hint, as in Batect.
  • A crash (a genuine bug, not one of the above) exits 101, Rust’s own default for an unhandled panic. ratect-compat prints where to report it (https://github.com/or1can/ratect/issues/new), the binary’s version and platform, and — if RUST_BACKTRACE isn’t already set — a reminder to re-run with it set, since a backtrace makes a much more useful report.

Environment variables

VariableEffect
RUST_LOGControls log verbosity on stderr (error, warn, info [default], debug, trace) — and, if --log-file is given, in the file too, which logs Ratect’s own records at debug when it’s unset. See Filtering RUST_LOG for scoping it to Ratect’s own targets. Unlike Batect, Ratect always logs to stderr regardless of --log-file; Batect’s own default with no --log-file is silent. See Differences from Batect.
BATECT_CACHE_TYPEThe default for --cache-type: volume or directory, exactly. Any other value, empty included, fails every command but --help and --version, unless --cache-type is given.
DOCKER_HOSTThe default for --docker-host — see Connecting to Docker.
DOCKER_CONTEXTThe default for --docker-context — see Connecting to Docker.
DOCKER_CONFIGThe default for --docker-config — see Connecting to Docker.
DOCKER_CERT_PATHThe default for --docker-cert-path — see Connecting to Docker.
DOCKER_TLS_VERIFYThe default for --docker-tls-verify — see Connecting to Docker.
DOCKER_BUILDKITForces the image builder on (1, yes or true) or off (0, no or false), in any case; empty counts as unset, and any other value fails the first build — see --enable-buildkit and config reference.
NO_COLORIf set, exactly the same effect as --no-color — see Colour.
CLICOLOR_FORCEForces colored output even when the stream isn’t a terminal, unless --no-color/NO_COLOR is set — see Colour.

Ratect supports interpolating host environment variables and config variables into environment values, volume host paths, build_directory, build_args, build_secrets’ path, and a build_ssh entry’s paths in batect.yml ($VAR, ${VAR:-default}, <name — see config reference) — see differences from Batect.

batect.yml Configuration Reference

Ratect reads a YAML file (batect.yml by default) describing containers and tasks. This documents the schema Ratect parses (ratect-core/src/config.rs) — every Batect configuration field is supported, field-for-field, unless listed in differences from Batect.

A field documented as a string also takes an unquoted number or boolean, read as the text written: description: 12.6000 is 12.6000, and PYTHON_VERSION: 3.10 in build_args is 3.10, not 3.1. An empty value, ~ or null is not read as text: as a map value such as a build_args entry, or as a list entry, it is refused.

Standard YAML features — anchors (&name), aliases (*name), and merge keys (<<:) — work throughout the file, not just in specific fields: they’re core YAML syntax handled by the parser itself (noyalib) before any of the schema below ever sees the document, not something Ratect implements or could disable. Useful for factoring out a shared base container definition, for example:

containers:
  base: &base
    image: alpine:3.18
    environment:
      COMMON_VAR: shared-value
  worker:
    <<: *base
    working_directory: /worker

Extensions

An anchor has to live on something, and sometimes the value you want to share isn’t a container or task at all — a block of environment variables, say. For that, a top-level key whose name starts with . is an extension: Ratect ignores it entirely, so it can hold an anchor for the rest of the file to alias (matching Batect, which sets kaml’s extensionDefinitionPrefix to .).

.common-environment: &common-environment
  TZ: UTC
  CI: "true"

containers:
  build-env:
    image: alpine:3.18
    environment:
      <<: *common-environment
      EXTRA_VAR: extra-value

Only top-level keys are extensions. A .-prefixed key anywhere else is an ordinary field name, and rejected if it isn’t a real one — so a typo nested inside a container still gets caught.

Top level

project_name: my-project
containers:
  <name>: <Container>
tasks:
  <name>: <Task>
config_variables:
  <name>: <ConfigVariable>
FieldTypeRequiredDescription
project_namestringnoNames the images the project builds (<project_name>-<container name>) and its eu.orican.ratect.project ownership label. Defaults to the lowercased name of the directory holding the root file. Root file only. See Project and container names for what it may contain.
containersmap of name → ContainernoContainer definitions, keyed by name. Referenced from tasks via run.container. See Project and container names for what a name may contain.
tasksmap of name → TasknoTask definitions, keyed by name. Run by name via ratect-compat <task-name>. See Task names for what a name may contain.
config_variablesmap of name → ConfigVariablenoDeclares the config variables usable via <name/<{name} expressions. A name must be declared here before it can be referenced — see Expressions — and follows Config variable names.
includelist of string or IncludenoSplits configuration across multiple files — see Includes below.
forbid_telemetrybooleannoRecognized but inert — Ratect collects no telemetry, so there’s nothing to forbid.

Project and container names

A built image is tagged <project_name>-<container name>, so project_name and every container’s name — a pull-only container’s too — must be a Docker image-name component: lowercase letters and digits, joined by a single period, one or two underscores, or any number of dashes. my-app, api.v2 and build_env are names; My-App, -api, a..b, a:b and org/app are not. A name that breaks the rule is refused, never changed to fit it. The rule is Batect’s, and so are the messages such a name fails the load with, for every command, --list-tasks included:

Invalid project name 'My-App'. The project name must be a valid Docker reference: it must contain only lowercase letters, digits, dashes (-), single consecutive periods (.) or one or two consecutive underscores (_), and must not start or end with dashes, periods or underscores.
Invalid container name '-api'. Container names must be valid Docker references: they must contain only lowercase letters, digits, dashes (-), single consecutive periods (.) or one or two consecutive underscores (_), and must not start or end with dashes, periods or underscores.

Like any error raised while the file is parsed, each gives a line, column and path — for a container name, the entry’s value’s, as for a task name.

A root file with no project_name is named after the directory holding it, lowercased as Batect lowercases it: a batect.yml in My-App/ names the project my-app. A directory whose lowercased name still breaks the rule (-app/) fails the load, naming the inferred name and the file and saying to set project_name, as does a root file directly in the filesystem root, whose directory has no name.

Includes

include:
  - some-include.yml
  - path: some-other-include.yml
    type: file
  - type: git
    repo: https://github.com/my-org/my-batect-bundle.git
    ref: v1.2.3
    path: bundle.yml

Each entry is either a bare string path (a local file include), or an object form — {path, type: file} for another local file, or {type: git, repo, ref, path} for a Git include (a “bundle”: shared tasks/containers imported from a separate Git repository). Any other type is rejected with a clear error.

An included file uses the same schema as the root file, with three differences:

  • It must not declare project_name — that’s root-only.
  • It must not set forbid_telemetry to true — only the root file can forbid telemetry. Setting it to false is allowed.
  • containers, tasks, and config_variables may each be omitted entirely (they default to empty) — a file that exists only to include further files, or only to add one task, doesn’t need to restate the others.

Every file, root or included, must hold some configuration: one that is empty, or holds only whitespace, comments or a null document (---, ~), fails to load, naming the file. A file holding just {} loads.

How every loaded file’s containers, tasks, and config_variables merge into one set, and where an included file’s relative paths resolve, are on Includes — one page for both formats, from the plain file include through what a Git-included bundle may do and why. Why you’d share a bundle across projects at all is Reusable Pipeline Building Blocks.

Local file includes

A local include’s path is resolved relative to the directory of the file that declares the include — not the root project directory — so an included file further down a subdirectory can itself include more files using paths relative to its own location. A leading ~ is expanded to the host user’s home directory, by the same rule as a volume’s host path; a Git include’s path is never expanded.

Git includes

FieldTypeRequiredDescription
repostringyesA Git remote — anything git clone itself accepts (an HTTPS/SSH URL, a local path, or a remote helper’s <helper>::<address>).
refstringyesThe tag, branch, or commit to check out. Must be a value that never changes (in practice, an immutable tag or a pinned commit SHA, not a branch) — see below.
pathstringno, default batect-bundle.ymlThe path, within the repository, of the file to include — resolved relative to the repository’s own root, not the file that declared the include.
allow_host_pathsbooleanno, default falseVouches for this bundle: lets a container it defines use a host path outside both the clone and your project directory. Honoured only on an entry in your own configuration — see Vouching for a bundle.

A (repo, ref) pair is cloned once and cached forever at ~/.ratect/incl/<hash>, keyed by a hash of the pair — it is never re-fetched, even if the remote’s ref later moves (e.g. a branch, or a tag someone re-pushed). This is why ref must be pinned to something immutable: ratect-compat has no update/refresh mechanism of its own, matching Batect, whose own cache clones only when the working copy is missing too — the ratect binary can force a re-clone via ratect includes refresh (see the ratect CLI reference), which also refreshes entries a prior ratect-compat run cached, since both binaries share ~/.ratect/incl. Note that the 30-day eviction sweep doesn’t help here — it removes entries that go unused, and an include you’re actively using never becomes stale, so it stays frozen at whatever its ref pointed to when first cloned. If you need to pick up a change made to a bundle, choose a new ref (e.g. bump the tag) or delete the corresponding directory under ~/.ratect/incl by hand.

The same sweep removes a temporary directory a clone left in ~/.ratect/incl when it was interrupted, once that directory has been unchanged for 30 days, and whatever an interrupted removal left, at once. A removal moves a clone aside before deleting it, so one cut short never leaves part of a clone for a later run to use; the next run that needs the include clones it again.

The sweep runs in the background and nothing waits for it, so there is no command to report to: an entry or leftover it can’t remove is logged as a warning through RUST_LOG, if the sweep gets that far before the run exits, and never changes the exit code. The ratect binary’s includes clean reports each one.

Everything reached through a Git include is treated as untrusted input: the file it names must stay inside the clone, a container it defines may mount only inside the clone or your project directory unless allow_host_paths vouches for it, and a grant counts only on the entry that reaches a file first. The rules — and the one place the two formats differ, a bundle’s own Git includes, which batect.yml always allows — are on What a bundle may do.

Cloning requires the system git binary to be installed and on PATH — Ratect shells out to it (git clone --quiet --no-checkout --template= followed by git checkout --recurse-submodules <ref>, Batect’s two commands with no template) rather than embedding a Git library, so any Git configuration (credentials, .gitconfig rewrites, protocol policy, etc.) that your normal git clone already relies on works the same way for the clone, except a template (init.templateDir), which it doesn’t use. The checkout, which fetches nothing, uses none of your Git configuration: core.autocrlf doesn’t change its line endings, no hook runs during it, and a file stored in Git LFS is left as its pointer file. The repository’s own .gitattributes still applies, so a bundle that needs particular line endings sets them there. A load that clones prints Cloning <repo> <ref>... on stdout first, and a blank line once the clone has succeeded, in every output style but quiet. git’s own output is shown only if the clone fails, as part of the error; a prompt for credentials still reaches the terminal. Wherever Ratect names a repo, credentials in its URL are shown as *** (https://***@host/repo.git); the clone is given the URL as written. Since a credential may contain an unencoded /, everything between :// and the URL’s last @ is hidden, even a path’s own: https://host/a@b is shown as https://***@b. An included repository’s submodules are never checked out, here or under Batect: a fresh clone has no active submodules for --recurse-submodules to update.

Container

containers:
  build-env:
    image: alpine:3.18
    volumes:
      - .:/code
FieldTypeRequiredDescription
imagestringone of image/build_directoryA Docker image reference to pull and run (e.g. alpine:3.18). Exactly one of image/build_directory is required, and giving both is an error rather than one silently winning. image also can’t be combined with any build-only field (build_args, build_target, dockerfile, build_secrets, build_ssh) — those apply only to a container built from a build_directory. All of this is ratect-compat behaviour; ratect’s native format deliberately allows these combinations because extends needs them — see where the semantics differ. No expression support: Batect resolves none here, so one is rejected when the file loads rather than resolved, which would make the file unusable under batect itself. ratect.toml does resolve them — see Expressions in image.
image_pull_policyIfNotPresent or AlwaysnoOn an image container: whether to pull it fresh or only when it’s missing locally. On a build_directory container: whether to force-pull the build’s own base image (docker build --pull) before building, or leave Docker’s own local-cache-if-present behavior alone — Batect’s own second, distinct use of this same field. Defaults to IfNotPresent either way, matching Batect. No expression support.
build_directorystringone of image/build_directoryBuilds an image from a Dockerfile in this directory (see Image building below) instead of pulling a pre-built one. Supports expressions and is resolved to an absolute path the same way a local volume’s host path is — see Volume path resolution.
build_argsmap of string → stringnoBuild-time variables passed to docker build (Docker’s own --build-arg mechanism), e.g. VERSION: "1.2.3". Only meaningful alongside build_directory. Values support expressions.
dockerfilestringnoThe Dockerfile to build, as a path relative to build_directory’s own root, or an absolute path inside build_directory. Defaults to Dockerfile at build_directory’s root. Only meaningful alongside build_directory. No expression support. Checked when the container’s image is about to be built, before Docker is asked anything: a build_directory that doesn’t exist or isn’t a directory, and a Dockerfile that doesn’t exist, isn’t a regular file, is a symbolic link or is reached through one, or isn’t inside build_directory, each fail the build naming the field. ratect doctor and ratect config validate report the same, and warn about an absolute path, which only works where the project is checked out at that path.
build_targetstringnoThe build stage to stop at (Docker’s own --target mechanism), for a multi-stage FROM ... AS <name> Dockerfile. Only meaningful alongside build_directory. No expression support.
volumeslist of strings/objectsnoHost bind mounts (local), named cache volumes (cache), and in-memory tmpfs mounts (tmpfs) — see Volume path resolution, Cache volumes, and Tmpfs mounts below.
dependencieslist of stringsnoNames of other containers to start (recursively, if they themselves have dependencies) before this one, reachable by name over a Docker network created for the duration of the task. Each must name a container declared under containers; one that doesn’t is rejected when the file loads, naming the container that referred to it. Each dependency must become ready — healthy, with all its setup_commands completed — before its dependents start; see Dependency Readiness for the full model, and Dependency readiness below for the two fields it rests on.
environmentmap of string → stringnoEnvironment variables to set in the container, e.g. FOO: bar. Values support expressions ($VAR, ${VAR:-default}, <name). An unquoted number or boolean (PORT: 8080, DEBUG: true) is accepted and passed on as written — VERSION: 3.10 is 3.10, not 3.1, and MODE: 0x10 is 0x10. An empty value, ~ or null is refused. For what overrides these, and what they override, see Environment precedence.
run_as_current_userobject (enabled, home_directory)noRuns this container as the host’s own user/group instead of the image’s default (see User mapping below).
additional_hostnameslist of stringsnoExtra network aliases this container is reachable by, beyond its own name. No expression support.
additional_hostsmap of string → stringnoExtra /etc/hosts entries in this container, hostname: ip, Docker’s own --add-host mechanism. No expression support.
portslist of strings/objectsnoPublishes container ports to the host (see Port mappings below). No expression support. Suppressed entirely by --disable-ports, regardless of this field. See CLI reference.
health_checkobjectnoOverrides the health check configuration baked into the container’s image (see Dependency readiness below). No expression support.
setup_commandslist of objects (command, working_directory)noCommands run inside the started container after it becomes healthy; a dependency’s must succeed before its dependents start (see Dependency readiness below). No expression support.
working_directorystringnoOverrides the image’s own WORKDIR. No expression support. A task’s own container’s working_directory can be further overridden by the task-level run.working_directory — see TaskRun. A setup_commands entry with no working_directory of its own falls back to the container’s effective working directory — this, or the task’s run.working_directory or customise override where one applies — then to the image’s own default. Batect’s own documentation says a task container’s setup commands ignore run.working_directory; Batect’s code applies it, and Ratect follows the code.
commandstringnoOverrides the image’s own default CMD. Tokenized into literal argv (quote/backslash-aware whitespace splitting, no shell involved — matching Batect’s own tokenizer exactly). One that can’t be tokenized — an unbalanced quote, a trailing \ — fails the load, as in Batect, even on a container no task uses. No expression support. Applies as-is to a dependency/sidecar container; a task’s own container’s command can be further overridden by the task-level run.command — see TaskRun.
entrypointstringnoOverrides the image’s own ENTRYPOINT. Tokenized into literal argv, and checked when the file loads, the same way command is. No expression support. A task’s own container’s entrypoint can be further overridden by the task-level run.entrypoint — see TaskRun.
labelsmap of string → stringnoDocker labels applied to the container. Container level only — no task-level run override. No expression support.
capabilities_to_addlist of stringsnoLinux capabilities to add beyond Docker’s own default set (Docker’s --cap-add), e.g. NET_ADMIN. Validated at config-load time against a fixed list based on Batect’s own Capability enum plus BPF/CHECKPOINT_RESTORE/PERFMON (added to Docker after Batect’s last release) — an unknown name is rejected with a clear error. Container level only. No expression support.
capabilities_to_droplist of stringsnoLinux capabilities to drop from Docker’s own default set (Docker’s --cap-drop), e.g. CHOWN. Same validation/scope as capabilities_to_add.
privilegedbooleannoRuns the container with extended (nearly all host) privileges — Docker’s --privileged. Defaults to false. Container level only. No expression support.
shm_sizestring or integernoThe size of /dev/shm — Docker’s --shm-size. Accepts Batect’s own size-string format ("128", "128b", "128k", "128m", "128mb", "128g" — a bare number means bytes) or a plain YAML integer (also bytes), which must not be negative. Defaults to Docker’s own default (64 MiB). Container level only. No expression support.
deviceslist of strings/objectsnoHost devices to make available inside the container — Docker’s --device (see Volume path resolution for the similar volumes string form; devices use the same local:container[:options] shape and object form, but with no path resolution — no expression support either). options (cgroup permissions, e.g. "rwm") defaults to "rwm" when omitted, matching the docker CLI’s own default. Container level only.
enable_init_processbooleannoRuns Docker’s own init process as PID 1 ahead of the actual command (reaping zombie processes, forwarding signals) — Docker’s --init. Defaults to false. Container level only. No expression support.
log_driverstringnoDocker’s logging driver (Docker’s --log-driver), e.g. "json-file", "syslog", "none". Defaults to leaving Docker’s own daemon-configured default alone. Container level only. No expression support.
log_optionsmap of string → stringnoDriver-specific options (Docker’s --log-opt, repeatable) for log_driver — meaningless without it. Container level only. No expression support.

Note: if a container has neither image nor build_directory set, running a task against it is an error naming the container. A dependency container without either is also an error, since it needs to actually run to serve its purpose — build_directory works for dependency containers too, not just a task’s own.

Every container’s Docker hostname is always set to its own container name (matching Batect) — not just its network alias. Without this, a container is reachable by its name on the network, but hostname/$HOSTNAME inside it would resolve to Docker’s random short container ID instead, which is easy to be surprised by if anything logs or checks its own hostname.

Image building

A container with build_directory set is built (not pulled) the first time it’s needed, and reused for the rest of that ratect invocation if referenced again (as a task’s own container, as a dependency, or by more than one task) — but never reused across separate ratect invocations; each run builds fresh. A few things to know:

  • Builder selection: builds use the builder the Docker daemon itself advertises as its default — BuildKit on any modern daemon — exactly matching Batect. The DOCKER_BUILDKIT environment variable overrides this either way (1, yes or true forces BuildKit, 0, no or false the classic builder, in any case; empty counts as unset; any other value is an error) — the same variable the docker CLI honors, read with Batect’s vocabulary, since the docker CLI accepts no yes/no. --enable-buildkit (see CLI reference) forces BuildKit on, taking precedence over DOCKER_BUILDKIT too — there’s no --disable-buildkit counterpart; force the classic builder via DOCKER_BUILDKIT=0 instead. A daemon old enough not to advertise a default builder at all falls back to the classic builder; one advertising a builder Ratect doesn’t know is an error unless DOCKER_BUILDKIT or --enable-buildkit chooses the builder. Note that build_secrets and build_ssh require BuildKit — combining them with a forced (or daemon-imposed) classic builder is a clear error rather than a silent build without them.

  • The Dockerfile built is dockerfile (a path relative to build_directory’s own root, or an absolute path inside it), defaulting to Dockerfile at build_directory’s own root when omitted.

  • build_target stops the build at that stage, for a multi-stage FROM ... AS <name> Dockerfile — Docker’s own --target mechanism.

  • A .dockerignore file at build_directory’s root, if present, excludes matching files from the build context — see .dockerignore semantics below for the (non-obvious) matching rules. No .dockerignore means the whole directory tree becomes the build context. dockerfile and .dockerignore itself are always included in the build context regardless of exclusion patterns, matching Docker’s own special-casing.

  • build_secrets exposes secrets to the build via BuildKit’s secret-mount mechanism (a Dockerfile’s RUN --mount=type=secret,id=<key>), without persisting them into the built image’s layers — keyed by the id such a RUN instruction references. Each entry is either {environment: NAME} (read from this ratect process’s own environment at build time) or {path: ...} (read from a file on the host, resolved like build_directory); exactly one of the two is required. A path must exist and be a file, not a directory: as in Batect, one that isn’t fails the build before it begins, whether or not a RUN instruction mounts it. Requires the BuildKit builder (see builder selection above). Using build_secrets disables the build cache for that build entirely — BuildKit deliberately excludes a secret’s value from its cache key (so it can’t leak into one), which would otherwise let an unrelated Dockerfile change reuse a cached layer built with a now-stale secret value.

  • build_ssh makes SSH keys available to the build, for a Dockerfile’s RUN --mount=type=ssh instructions. Each entry is one agent, named by an id a RUN instruction selects with --mount=type=ssh,id=<id>. id is required, and ids must be unique across the list. Write default for the agent a bare RUN --mount=type=ssh uses — BuildKit’s implicit id is not applied for you, because Batect requires id too and a config that omitted it would work here but not under batect. Each entry’s paths decides where its keys come from, following BuildKit’s own rules:

    build_ssh:
      - id: default             # required; `default` is the id a bare
                                # `RUN --mount=type=ssh` selects. No paths:
                                # forwards the host's own running
                                # ssh-agent, via its SSH_AUTH_SOCK
      - id: deploy
        paths:
          - ~/.ssh/deploy_key   # one or more private key files, served with no
          - keys/ci_ed25519     # agent running at all
      - id: other
        paths:
          - /tmp/other-agent.sock   # a path that *is* a Unix socket forwards
                                    # that agent instead; it must be the entry's
                                    # only path
    

    A path listed more than once in one entry’s paths counts once, as in Batect, so the same socket twice is still that entry’s only path.

    paths values support expressions and are resolved relative to the config file, the same way build_directory and build_secrets’ path are. Key files are served by an ssh-agent Ratect runs in-process for the duration of the build: the keys themselves never leave the ratect process — only signatures cross into the build — and the socket they’re served on lives in a directory only the current user can open. This is the form that works in CI, where a deploy key usually exists but no agent is running.

    Keys must not be protected by a passphrase, and must be Ed25519, RSA or ECDSA (Ratect rejects anything else up front, naming the file, rather than failing mid-build). An RSA key whose parts don’t make a valid key is rejected the same way, and so is an unusual one whose private exponent isn’t reduced below its modulus. RSA keys are signed with rsa-sha2-256/rsa-sha2-512; the legacy SHA-1 ssh-rsa algorithm, which OpenSSH has disabled by default since 8.8, is not offered.

    Requires the BuildKit builder (see builder selection above). Agents are proxied over the build’s session, not mounted as sockets — so this works unchanged on macOS/Windows, where Docker Desktop’s VM boundary otherwise blocks mounting host sockets into containers (no /run/host-services/ssh-auth.sock workaround involved).

  • The built image is tagged <project_name>-<container_name> (matching Batect’s own default), so it’s identifiable in docker images rather than showing up as an opaque generated name. That tag is reused/overwritten on every run, though — it’s for identification only, not caching or correctness (Ratect always runs the image it just built, regardless of what the tag currently points to by the time the container starts).

  • Built images aren’t cleaned up automatically — since the tag is reused, the image a build replaces becomes a dangling (<none>) image rather than disappearing, and accumulates until manually pruned (docker image prune), same as repeatedly running a plain docker build -t ... . would leave behind. Docker’s own build cache is likewise untouched by Ratect. Matches Batect exactly — its BuildImageStepRunner/ CleanupStagePlanner have no cache-control flag or image-removal step either.

  • How much of a build’s output you see depends on the output style: -o all streams every build log line as <container> | Image build | ... — under BuildKit, each labelled with its step’s #N, as in app | Image build | #5 cc -o app main.c; fancy shows the latest line in the container’s status row; simple prints only Building <container>... and Built <container>.; quiet prints nothing. Independently of the style, each build log line is also emitted at debug level (set RUST_LOG=info,ratect_core=debug for a live transcript without unrelated dependency noise — see filtering RUST_LOG), and if the build fails, the entire transcript is included in the error Ratect reports — not just Docker’s one-line failure summary — so a failing RUN step’s own output is always visible, under every output style, without needing RUST_LOG set.

.dockerignore semantics

Ratect’s .dockerignore handling is a from-scratch reimplementation of Docker’s own matching rules (github.com/moby/patternmatcher, which Docker’s documentation cites as the reference implementation), not a .gitignore-compatible matcher — the two are not the same, and the difference is easy to get surprised by:

  • A bare pattern with no wildcard only excludes at the build context root. node_modules excludes a top-level node_modules directory, but not a nested one like packages/foo/node_modules — unlike .gitignore, where a slash-free pattern matches at any depth by default. Use **/node_modules for that.
  • ** matches any number of directories (including zero), usable as a prefix, suffix, or standalone segment (**/dir2/*, dir/**, **).
  • Later lines take precedence over earlier ones — a !-prefixed line re-includes a path an earlier pattern excluded.
  • Leading and trailing slashes are no-ops (/foo/bar, foo/bar/, and foo/bar are all equivalent) — including a trailing slash not restricting a match to directories only, unlike .gitignore.
  • Dockerfile and .dockerignore themselves are always included in the build context regardless of exclusion patterns, matching Docker’s own special-casing (otherwise a broad * pattern would exclude the file the build needs).

Private registry credentials

Both pulling an image and building one (a Dockerfile FROM a private base image) resolve credentials from your Docker configuration (~/.docker/config.json by default, or DOCKER_CONFIG, or --docker-config) — running docker login once beforehand is enough, including a keychain-backed store (Docker Desktop/OrbStack’s default) or a cloud registry’s credential helper (ECR/GCR). Building resolves every registry your Docker config declares (auths and credHelpers), and every registry its default credsStore holds, as that store’s credential helper lists them, since Ratect doesn’t parse a Dockerfile’s FROM lines to scope this more precisely.

A registry whose credential helper fails to resolve doesn’t block the pull or build — a warning names the registry, so a problem with one registry’s helper can’t stop work that never needed it, but also doesn’t stay invisible until the day that registry actually matters. A credsStore whose helper can’t list what it holds is a warning naming the store, and the build goes ahead with the registries the config declares.

Volume path resolution

Each volumes entry is a local bind mount (a host path), a cache volume (see Cache volumes below), or a tmpfs mount (see Tmpfs mounts below) — either the compact string form or the expanded object form:

containers:
  build-env:
    image: alpine:3.18
    volumes:
      - .:/code
      - local: ./logs
        container: /var/log/app
        options: ro
      - type: cache
        name: apk-cache
        container: /var/cache/apk
      - type: tmpfs
        container: /code/tmp

A bare string (local_path:container_path or local_path:container_path:options) is always a local mount — there’s no compact string form for cache/tmpfs. The expanded object form additionally accepts type: cache (with name instead of local) or type: tmpfs (with neither local nor name); type: local, the default when omitted, requires local and forbids name.

For a local mount, local (the host path) is resolved:

  • In the object form, the path is interpolated first (see Expressions) — so a config variable that itself resolves to an absolute path is taken as absolute, not treated as a literal relative fragment. The string form’s host path is used as written, as in Batect: a $ or < in $HOME/.m2:/root/.m2 is just part of a relative path, so a host path that needs an expression is written as an object. (ratect.toml interpolates both forms.)
  • A leading ~ is then expanded to the host user’s home directory — $HOME when it is set and absolute, else the passwd entry’s, as for the Docker CLI — so ~/.cache/tool mounts the real cache directory. With no home from either, the path is refused. Only a whole leading ~ component expands: ~user/… (another user’s home) isn’t supported, and a ~ anywhere but the front is a literal character. Note that a bare ~ must be quoted (local: "~") — unquoted, YAML reads it as null.
  • After any interpolation, if the result is relative, it’s resolved to an absolute path relative to the directory containing the config file (not the current working directory). If it’s already absolute (whether literally written that way, expanded from ~, or because that’s what an expression resolved to), it isn’t joined onto anything. Either way, its . and .. components and any trailing / are then collapsed lexically, as in Batect — without following symbolic links, so /a/link/.. is /a wherever link points.
  • This all happens when a task is run, with CLI-supplied config variable overrides (--config-var/--config-vars-file) applied — not when the file loads.
  • build_directory is resolved the same way (it has no :container_path part to split off, obviously, but otherwise follows identical rules).

A mount identical to an earlier one once resolved — ./a:/a and a:/a, or a cache mount listed twice — is mounted once, as in Batect. The same paths with different options (./a:/a and ./a:/a:ro) are two mounts, which Docker refuses as a Duplicate mount point, as it does under Batect.

container/options are always used as literal strings — no expression support. A cache mount’s name/container are also plain strings, matching Batect — no expression support there either.

Cache volumes

ratect’s native format adds a scope field here, for a cache shared across projects. Everything below describes the project-scoped kind, which is the only one batect.yml has.

Which directory to point a cache at for each toolchain — Cargo, Go, npm, pip, Gradle — is in Using Ratect With Language Ecosystems.

A cache name must start with a letter or digit and contain only letters, digits, underscores, dots and dashes — Docker’s own volume-name character set. The name becomes a host directory under --cache-type=directory, so a name like /etc or ../../.ssh would otherwise have an arbitrary host directory bind-mounted into the container; Batect performs no such check, and Ratect diverges here for the same reason it applies containment to Git includes. Under --cache-type=volume Docker already enforces this, so nothing that worked there is affected. Under --cache-type=directory the same rule applies, so a name: my cache or name: node/modules fails to load. Rename the cache — the storage is rebuilt on the next run, which is what a cache is for.

A cache mount persists between separate ratect invocations — unlike local, its contents aren’t tied to a specific host path in batect.yml. name identifies it, combined with a per-project key into either a Docker named volume (the default) or a host directory, selected by --cache-type, or else BATECT_CACHE_TYPE (see CLI reference):

containers:
  build-env:
    image: alpine:3.18
    volumes:
      - type: cache
        name: apk-cache
        container: /var/cache/apk
        options: rw   # optional
  • --cache-type=volume (the default): resolves to a Docker named volume, batect-cache-<project-key>-<name> — the exact naming convention Batect itself uses, deliberately, so a project already run under real Batect has its existing cache volumes recognized and reused rather than starting cold.
  • --cache-type=directory: resolves to a host directory under <project_directory>/.batect/caches/<name>/, created if it doesn’t exist yet. Same reasoning as above — this is where an existing Batect project already keeps its own directory-type caches.
  • <project-key> is a value unique to this project, generated once and persisted at <project_directory>/.batect/caches/key (created lazily — the first time a run resolves a cache mount, or --clean looks for cache volumes, under --cache-type=volume, never eagerly; a --cache-type=directory run never reads, creates or changes it) — without it, two unrelated projects that happen to declare a same-named cache (e.g. gradle-cache) would collide on the exact same Docker volume, since Docker volumes live in one flat, global namespace, not scoped by directory. If that file already exists (e.g. from a prior real-batect run), its existing key is read and reused as-is, never regenerated — even though Ratect’s own generated keys look different (a full UUID, rather than Batect’s own shorter id): nothing depends on matching that format, only on reusing whatever key is already on record for this project. The file must hold exactly one line that isn’t blank or a comment (#), the key; one with none or more than one, or that can’t be read, fails the run or --clean, as in Batect, and is left as it is — replacing it would orphan every cache volume named after the key it held.

The cache root, .batect/caches, belongs to the project. If it, or .batect, is a symbolic link, Ratect follows it, as Batect does: the key file and every --cache-type=directory cache are created wherever it points, a run bind-mounts the cache directory there, and a directory-type --clean removes every cache directory it finds there. A link only moves storage the project’s own configuration could already reach, since a local mount can name any host path, so it’s trusted as that configuration is. Link the root to storage shared with something else, and a clean removes what it finds there. An entry under the root that is itself a symbolic link is different: a clean skips it, with a warning, though a run’s mount of that cache still follows it.

--clean removes every one of this project’s own cache volumes/directories (per --cache-type or BATECT_CACHE_TYPE) and exits, without running anything; --clean-cache <NAME> (repeatable) restricts this to the named cache(s) instead of all of them — see CLI reference.

Tmpfs mounts

A tmpfs mount is an in-memory filesystem — its contents are lost when the container exits. Unlike local/cache, it has no host path or name — only the expanded object form is accepted:

containers:
  build-env:
    image: alpine:3.18
    volumes:
      - type: tmpfs
        container: /code/tmp
        options: size=64m   # optional

options is a standard Docker tmpfs mount options string (e.g. size=64m, mode=1770) forwarded verbatim to Docker — Ratect does no parsing or validation of its contents, matching Batect.

User mapping

ratect.toml differs here. A .toml file refuses this field: see Coming from run_as_current_user.

containers:
  build-env:
    image: alpine:3.18
    run_as_current_user:
      enabled: true
      home_directory: /home/container-user

By default, a container runs as whatever user the image defaults to — often root — so files a task writes to a bind-mounted volume come back host-root-owned. Setting run_as_current_user.enabled: true runs the container as the host’s own user and group instead.

enabled defaults to false, as in Batect, so run_as_current_user: {} loads and maps no user.

Note: enabled: true and home_directory are only ever valid together — which configs this accepts and refuses matches Batect’s own behavior exactly (the error messages are Ratect’s own), not a Ratect-specific restriction. Setting enabled: true with no home_directory is an error (Ratect never guesses one, since the container’s own image has no home directory prepared for an arbitrary host uid/gid). The reverse is also an error: enabled: false (or omitted) with home_directory still set — e.g. simply flipping enabled back to false without also deleting home_directory fails config loading. Remove home_directory entirely to disable user mapping, not just enabled.

home_directory is used exactly as written, as in Batect: it isn’t an expression, so a $ or < in it is just part of the path. Unlike build_directory or a volume’s host path, it is not resolved against the config file’s directory — it names a path inside the container, so a relative value would be meaningless there and is rejected as not absolute. A : or control character in it is also rejected: it is written into the generated /etc/passwd entry, where either would corrupt the line. So is / itself, or a path ending in ..: the directory is created by name inside its parent, and neither has a name to create.

A few things happen automatically to make this actually work, not just set --user:

  • Any local mount’s host path (or a cache mount’s own host directory, under --cache-type=directory) that doesn’t exist yet is created before the container is even created, as the current host user. Otherwise Docker’s daemon (running as root) would auto-create it as root:root on first use, defeating the point for the common “mount my code directory, get build artifacts back with sane ownership” case. Doesn’t apply to a cache mount under the default --cache-type=volume — there’s no host path at all there, just a Docker volume name.
  • A mount point that falls inside a local mount (or a directory-type cache mount) — another local mount, a cache mount, or a tmpfs mount, at any depth — is created inside that mount’s host directory the same way, with every directory above it, so the daemon doesn’t create those as root:root in your project either. It’s an empty file when what’s mounted there is a file or socket, and a directory otherwise (see Differences from Batect). Only the closest enclosing mount counts, and only when it mounts a directory: nothing is created for a mount point inside a Docker volume, or inside a file or socket mount. A mount point that already exists is left alone, and so is one for Docker Desktop’s own /run/host-services//run/guest-services paths, one past a file in the host directory, and one in a directory you can’t write to (one the daemon created as root on an earlier run, say) — those are left for the daemon to create. A symlink on the way is followed only while it leads to a directory still inside that mount’s host directory; one leading out of it, or nowhere, leaves the mount point to the daemon.
  • The container’s own image has no /etc/passwd//etc/group entry for an arbitrary host uid/gid — many programs misbehave or refuse to run at all without one (no $HOME, no username resolution). Minimal synthetic /etc/passwd, /etc/shadow, and /etc/group entries are uploaded into the container before it starts, named after your user and group, or with the uid’s or gid’s digits where the host has no name for it, as in Batect.
  • home_directory itself is created inside the container (owned by the mapped uid/gid) before it starts — it’s a path inside the container’s own filesystem, not host-mounted, so it doesn’t persist across runs, matching Ratect’s existing ephemeral-container model.
  • Every cache mount on the container gets the same ownership treatment, except a read-only one. A Docker volume is created root-owned, so without this the container would mount its cache and then fail on the first write — the mount having succeeded, which makes it a confusing place to find out. Applies to a cache anywhere, including one nested inside home_directory. A cache mounted with ro among its options keeps its owner: nothing can write to it, and the read-only mount would refuse the change.

Applies per-container, independently — a task’s own container and each of its dependencies can each set run_as_current_user on their own; it isn’t inherited or shared task-wide.

One limitation: host-side uid/gid lookup is Unix-only, and errors clearly on other platforms rather than guessing.

Port mappings

containers:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
      - "9000-9002:9100-9102/udp"
      - local: 8443
        container: 443

ports publishes container ports to the host — Docker’s own -p/--publish mechanism — and takes either form Batect itself supports, freely mixed within one list:

  • A string, "local:container[/protocol]" (protocol defaults to tcp), e.g. "8080:80" or "8080:80/udp".
  • A port range string, "from-to:from-to[/protocol]", e.g. "9000-9002:9100-9102" — each local port maps to the corresponding container port by position (9000 → 9100, 9001 → 9101, 9002 → 9102); local and container must cover the same number of ports.
  • The expanded object form, {local, container, protocol} — local/container each accept a single port or a range (8443 or "8000-8002"), protocol is optional (defaults to tcp).

Validated at config-load time, as volumes is: a malformed entry, a non-positive port, or mismatched-size local/container ranges are all rejected before anything runs. No expression support.

TaskRun.ports (see TaskRun) adds additional port mappings for a specific task’s run — combined with the container’s own ports as a union, not an override; there’s no concept of one replacing an entry from the other. A mapping given more than once, on either side or both, is published once — compared port by port, so "8080:80" alongside "8080-8081:80-81" publishes 8080 → 80 once. One container port may be published on several host ports ("9000:80" and "9001:80", whether both on the container or one in TaskRun.ports), and each host port is bound.

--disable-ports suppresses publishing of every container’s ports — from both Container.ports and any TaskRun.ports — regardless of what’s configured. See CLI reference.

A real, simpler instance of the object form: examples/full-stack’s app container publishes - local: 8080 / container: 8080 — one port, no range or protocol (that project is written in the native ratect.toml format, where the same field means exactly the same thing — see Field reference). The range and UDP forms above have no real counterpart in examples/.

Dependency readiness

A dependency must be ready before anything that depends on it starts: healthy, then every one of its setup_commands succeeded, in declared order. What each of those two steps waits for, how Docker reaches a health verdict, how several dependencies’ waits combine into one task’s start-up, and a real run of all of it are on Dependency Readiness; the two fields are below. A task’s own container runs the same gate here, concurrently with its main command: a failure while that 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 described in known limitations. Under ratect it has none, even for a task container declared in a YAML file — see The task’s own container.

health_check overrides the image’s health check configuration — each field replaces that one aspect, and any field left out inherits the image’s own value:

FieldTypeDescription
commandstringThe command to run to check the container’s health, via the container’s default shell (a Dockerfile HEALTHCHECK CMD <string>). Exit code 0 means healthy.
intervaldurationTime between health check runs.
retriesintegerConsecutive failures needed before the container is considered unhealthy.
start_perioddurationTime during which failing checks don’t count against retries (a success during it still counts as healthy immediately).
timeoutdurationTime a single check may run before it’s considered failed.

Durations are strings in Batect’s (Go-style) format: one or more <number><unit> components, in any order — ns, us (or µs/μs), ms, s, m, h, numbers optionally fractional — e.g. 2s, 500ms, 1m30s, 1.5h, or a bare 0, quoted or not. Any other number needs its unit: interval: 5 is refused. A negative duration is refused too, except a zero (-0s).

Each setup_commands entry takes:

FieldTypeRequiredDescription
commandstringyesThe command to run. Tokenized into literal argv, and checked when the file loads, the same way a container’s own command/entrypoint is (see Container) — no shell involved. A command relying on shell operators (&&, $VAR expansion, etc.) needs an explicit sh -c '...' wrapper — the FAQ has the worked explanation.
working_directorystringnoDirectory to run it in. Falls back to the container’s effective working_directory when omitted — including a task’s run.working_directory or customise override — and then to the image’s own default when none is set.

Task

tasks:
  test:
    run:
      container: build-env
      command: echo "hello"
    prerequisites:
      - build
FieldTypeRequiredDescription
runTaskRunno*What to actually execute for this task.
prerequisiteslist of stringsno*Names of other tasks to run first, in order. Each prerequisite (and its own prerequisites, transitively) runs at most once per ratect invocation, even if shared by multiple tasks. A circular dependency is detected and reported as an error. A name containing * is a wildcard, expanded against every task name at run time (see Wildcard prerequisites below) rather than looked up literally.
dependencieslist of stringsno**Sidecar containers scoped to this task specifically — see below. Requires run. Each must name a container declared under containers; one that doesn’t is rejected when the file loads.
descriptionstringnoShown next to the task’s name in --list-tasks output — see below. Purely informational.
groupstringnoGroups this task under a heading in --list-tasks output, together with every other task sharing the same group — see below. An empty group is the same as none. Purely a display grouping; has no effect on execution order or prerequisites.
customisemap of string → TaskContainerCustomisationnoPer-task environment/ports/working_directory overrides, keyed by container name — see below.

* At least one of run/prerequisites is required. A task with only prerequisites and no run is valid — its prerequisites still run, then Ratect stops, since there’s no container of the task’s own left to run.

** dependencies here is distinct from a container’s own dependencies field: this one is scoped to this task specifically, rather than to every task that uses the container. It’s unioned with the task’s own container’s dependencies — both start together — and can’t name run.container itself.

Task names

A task’s name contains only letters, digits, colons, dashes, periods and underscores, and starts and ends with a letter or digit — build, lint:go and test.unit are names, -a, a: and a* are not. The rule is Batect’s, and so is the message a name that breaks it fails the load with, for every command, --list-tasks included:

Invalid task name 'a*'. Task names must contain only letters, digits, colons, dashes, periods and underscores, and must start and end with a letter or digit.

Like any error raised while the file is parsed, it gives a line, column and path — tasks.a* — which for this error are the entry’s value’s, not its key’s.

Wildcard prerequisites

A prerequisites entry containing * is expanded against every task name in the project, rather than looked up literally:

tasks:
  lint:go:
    run:
      container: build-env
      command: golangci-lint run
  lint:markdown:
    run:
      container: build-env
      command: markdownlint .
  ci:
    prerequisites:
      - "lint:*"

Running ratect-compat ci here runs both lint:go and lint:markdown (in alphabetical order) before ci itself. A single * matches zero or more characters, and a * can’t be part of a task’s name, so a wildcard never names one task literally. A wildcard matching multiple tasks always runs them in alphabetical order, regardless of the project’s own tasks declaration order. A wildcard matching zero tasks is not an error — it simply contributes nothing. If a task is named both explicitly and by a wildcard in the same prerequisites list, it still only runs once. Quote a wildcard entry ("lint:*", not lint:*) to avoid YAML parsing * as an anchor reference.

TaskContainerCustomisation

Applies to a non-main container used somewhere in this task’s own container graph (a task-level or container-level dependency, at any depth) — keyed by container name under customise:

tasks:
  test:
    run:
      container: build-env
    dependencies:
      - queue
    customise:
      queue:
        environment:
          MODE: test
        working_directory: /custom
FieldTypeRequiredDescription
environmentmap of string → stringnoMerged with the container’s own environment — see Environment precedence for the order. Values support the same expressions as environment does.
portslist of strings/objectsnoAdded to the container’s own ports, not an override — see Port mappings.
working_directorystringnoOverrides the container’s own working_directory. No expression support.

A customise entry can’t target run.container itself — that’s a config error; set the equivalent property on run instead. It also can’t name a container that isn’t actually part of this task’s own container graph (whether because the name doesn’t exist at all, or exists but isn’t reachable from run.container via dependencies — container-level or task-level).

List-tasks output

With no task declaring a non-empty group, --list-tasks prints a single flat, alphabetically sorted list — each task’s name, plus its description unless that is empty or only whitespace. Against ratect-compat/tests/fixtures/smoke.yml, which sets neither:

Tasks in ratect-test:
- list-volume-task
- prereq-task
- prerequisites-only-task
- shared-prereq
- test-task

Once any task in the project declares a non-empty group, every task is listed under a heading instead — one per distinct group value (sorted alphabetically), plus a trailing Ungrouped tasks: heading for any task that doesn’t set group, or sets it to the empty string — Batect treats the two alike. Against examples/jvm/batect.yml (every task there sets a group, so there’s no Ungrouped tasks: heading to show):

Tasks in example-jvm:

Checks:
- lint: Run Checkstyle

Development:
- build: Compile and assemble
- run: Run the application
- test: Run the test suite

Utilities:
- shell: Start a shell in the build environment

With --output quiet, both forms are replaced by a machine-readable listing instead — one task per line, sorted by name, as name alone or name<TAB>description, with no header and no grouping — the same project again:

build	Compile and assemble
lint	Run Checkstyle
run	Run the application
shell	Start a shell in the build environment
test	Run the test suite

TaskRun

For why && and $VAR don’t do what they look like they do in command, and the three different $-syntaxes that resemble each other, see the FAQ.

FieldTypeRequiredDescription
containerstringyesName of a container defined under containers. A name that isn’t one is rejected when the file loads.
commandstringnoOverrides the container’s own command for this task’s run specifically (see Container). Tokenized, and checked when the file loads, the same way. If neither this nor the container’s own command is set, the image’s own default CMD runs instead. Any -- ADDITIONAL_ARGS from the CLI are appended to the command as further literal argv entries — or, when there’s no command, replace the image’s default CMD — see CLI reference.
environmentmap of string → stringnoEnvironment variables to set for this task’s run specifically. Merged with the container’s own environment — see Environment precedence below for the order. Values support the same expressions as environment does.
portslist of strings/objectsnoAdditional port mappings for this task’s run specifically — see Port mappings. Added to the container’s own ports, not an override — there’s no concept of one replacing an entry from the other.
working_directorystringnoOverrides the container’s own working_directory for this task’s run specifically (see Container), including where its setup_commands run. No expression support.
entrypointstringnoOverrides the container’s own entrypoint for this task’s run specifically (see Container). Tokenized, and checked when the file loads, the same way. No expression support.

Environment precedence

A container’s environment is assembled from up to four layers, each overriding the one before it on a key collision:

  1. TERM — Ratect’s own, for every container; or dumb, for every container, under --output all. See TERM propagation.
  2. Proxy variables, when any are set where Ratect runs.
  3. The container’s own environment.
  4. The task’s run.environment, for the task’s own container — or its customise.<container>.environment, for a dependency (see TaskContainerCustomisation).

An image build layers the same way with what applies to a build: proxy variables, then the container’s own build_args. Last, the proxies from Docker’s config.json fill in any proxy argument still unset, overriding nothing — a layer --no-proxy-vars skips.

Interactive mode

Which container is eligible, what it gets, when a real TTY is allocated, and TERM propagation are on Interactive Mode, shared with ratect.

Proxy environment variables

Which variables are propagated, how no_proxy is extended, localhost rewriting and the host-gateway entry, the loopback-bound warning, and --no-proxy-vars are on Proxies, shared with ratect.

ConfigVariable

config_variables:
  environment_name:
    default: dev
FieldTypeRequiredDescription
defaultstringnoThe value used when nothing else provides one — see Expressions for the full precedence order (CLI --config-var > --config-vars-file > this default). Referencing a declared variable that has no default and no override from either CLI source is an error.
descriptionstringnoRecognized but inert — Batect surfaces this in its own generated docs/help output; Ratect has no such output to show one in.

Config variable names

A config variable’s name starts with a letter, contains only letters, digits, dashes, periods and underscores, and doesn’t start with batect, in any mix of case — that prefix is kept for built-ins such as batect.project_directory. The rule is Batect’s, and so is the message a name that breaks it fails the load with, located like a task name’s:

Invalid config variable name '1a'. Config variable names must start with a letter, contain only letters, digits, dashes, periods and underscores, and must not start with 'batect'.

Expressions

environment values (on Container, TaskRun and a task’s customise entries), a volume’s local host path in the object form (not the string form’s — see Volume path resolution), build_directory, build_args, a build_secrets entry’s path (not its environment — that’s a literal host environment variable name, not itself interpolated), and a build_ssh entry’s paths support two kinds of expression, evaluated when you run a task — not when the file loads, so --list-tasks works whatever this machine supplies, and uses no --config-var/--config-vars-file value. Each task is evaluated when the run reaches it — after its prerequisites, before any of its own containers is built or started — with those overrides applied, and only the containers that task uses: a value this machine can’t supply fails only a task that needs it. Everywhere else in the config, a string is used exactly as written, with no substitution — expression support is scoped to fields that can meaningfully take one; it’ll extend to more fields as they themselves get built, not automatically.

ratect.toml differs here. The native format also resolves expressions in image, so a tag can be chosen per run — see Expressions in image. It is rejected in a batect.yml rather than ignored, because Batect resolves nothing there and a file using one would stop working under batect itself. In this format, --override-image is the way to choose an image per run. It also resolves them in a string-form volume’s host path, which a batect.yml uses as written.

Literal text around an expression is kept ("prefix-$VAR-suffix" interpolates just $VAR), apart from escapes. Every other $ and < starts an expression, so write a literal one as \$ or \<.

FormResolves againstExample
$NAMEratect’s own host environment$HOME
${NAME}ratect’s own host environment${HOME}
${NAME:-default}ratect’s own host environment, falling back to default if unset${LOG_LEVEL:-info}
<nameA config_variables entry<environment_name
<{name}A config_variables entry<{environment_name}

A host variable referenced without a :-default fallback, and unset when ratect runs, is a hard error naming the container or task, the field, the expression and the variable — there’s no silent empty-string fallback. A config variable referenced via <name/<{name} must be declared under config_variables; an undeclared name is a hard error, and so is a declared one with no value from any source (see ConfigVariable’s precedence order). Config variable values themselves come from, highest precedence first: --config-var NAME=VALUE (repeatable), --config-vars-file (a flat YAML map), then the variable’s own default — see CLI reference.

Variable names

How far a name runs, as in Batect:

  • Unbraced ($NAME, <name): the longest run of letters, digits and _, so a leading digit or a non-ASCII letter is part of it — $5 is a variable named 5. Anything else ends it: <foo.txt is foo’s value followed by .txt, and $A-B is A’s value followed by -B. A name holding a . or a - — a config variable such as my-var, or the built-in — needs braces.
  • Braced ${…}: everything up to the }, or up to the : that starts a default, which must be :-. ${a b} is a variable named a b.
  • Braced <{…}: everything up to the }, : included, since a config variable has no default.

A malformed expression fails the file’s load, for every command, --list-tasks included, and whether or not a task uses that container. It is malformed when:

  • a $ or < has no name after it: $, $$, a < b, ${}, ${:-x}, <{};
  • a { is never closed: ${, ${HOME, <{name;
  • a : in ${…} isn’t followed by -: ${LOG_LEVEL:info};
  • a default ends in a \ with nothing to escape: ${X:-a\.

The error gives the value’s line and column in the file and its path (containers.app.environment.LOG_LEVEL), quotes the value, and says what is wrong at which column of the value.

Escaping with \

In any of those fields, a \ makes the character after it literal and is itself dropped, as in Batect: \$ and \< start no expression, and \\ is one backslash. Inside a ${NAME:-default}’s default, \} is a } that doesn’t end it. Quote such a value with single quotes, which keep a backslash as written — in a double-quoted YAML string, \ is YAML’s own escape first.

environment:
  PRICE: '\$100'               # $100
  DEFAULTED: '${UNSET:-a\}b}'  # a}b, when UNSET isn't set
  WINDOWS_PATH: 'C:\\Temp'     # C:\Temp

(Illustrative; ratect-core/tests/twins/escapes is a checked-in pair of files using each form.)

A \ at the very end of a value has nothing to escape, so the file fails to load — for every command that loads it, --list-tasks included, and whether or not a task uses that container. The error is located like a malformed expression’s.

A ratect.toml reads \ the same way; write such a value as a literal (single-quoted) TOML string, for the same reason. A field that isn’t an expression, such as a batect.yml’s image, keeps a backslash as written.

Built-in config variable: batect.project_directory

<{batect.project_directory} always resolves to the absolute path of the directory containing the root configuration file, even in an included file — Batect’s one built-in config variable, so Ratect supports it without requiring (or allowing) it to be declared under config_variables. Declaring a config_variables entry named batect.project_directory fails the load, as any name starting batect does, and supplying one via --config-var/--config-vars-file is a hard error — it isn’t overridable.

Only the braced form reaches it, as in Batect: an unbraced name ends at its first ., so <batect.project_directory is a reference to a config variable named batect, followed by the literal .project_directory.

Editor autocompletion and validation

Ratect ships a JSON schema describing what this reference documents: schema/batect-config.schema.json. Pointing an editor at it gives autocompletion for field names, hover documentation, and a warning on a misspelled or unsupported field as you type — including the fields Batect supports and Ratect doesn’t, which is the whole reason this is a schema of Ratect’s own rather than Batect’s published one (that one describes Batect’s full field set, so an editor using it would quietly accept configuration Ratect then rejects at run time).

One gap: the schema lists a text field’s type as string only, so an editor may warn about an unquoted number or boolean there (description: 12.6000, interval: 0) that Ratect accepts as written. Quoting the value silences it.

The simplest way to use it is a comment at the top of your config file, which the YAML extension for VS Code and JetBrains IDEs both honor:

# yaml-language-server: $schema=https://raw.githubusercontent.com/or1can/ratect/main/schema/batect-config.schema.json
project_name: my-project

A local path works the same way ($schema=./schema/batect-config.schema.json), and is worth preferring if you pin a Ratect version — the URL above tracks main, so it describes the development version, which may accept fields your installed Ratect doesn’t yet.

The schema describes a single file, include and all — not the merged result of following those includes — so it applies equally to a root batect.yml and to any file it includes. Its fields are generated from Ratect’s own configuration types, and its patterns for durations and sizes are checked against Ratect’s parser, on Batect’s own cases, by its tests. A shm_size with whitespace Batect refuses, such as " 128m ", loads in Ratect but is flagged by the schema. The checks it can’t express are the cross-field ones (a task needing run or prerequisites, port ranges on both sides of a mapping covering the same number of ports, customise naming a container that’s actually in the task’s graph). Those are still reported by Ratect itself, when it loads the file — for any command that loads it, --list-tasks included.

Not submitted to SchemaStore’s catalog itself, so an editor only picks the schema up via the $schema line above.

Full example

This mirrors the sample config used in the test suite (ratect-compat/tests/fixtures/smoke.yml):

project_name: ratect-test
containers:
  build-env:
    image: alpine:3.18.2
    volumes:
      - .:/code
tasks:
  shared-prereq:
    run:
      container: build-env
      command: echo "I should only run once"
  prereq-task:
    run:
      container: build-env
      command: echo "I am a prerequisite"
    prerequisites:
      - shared-prereq
  list-volume-task:
    run:
      container: build-env
      command: ls /code
    prerequisites:
      - shared-prereq
  test-task:
    run:
      container: build-env
      command: echo "Hello from ratect!"
    prerequisites:
      - prereq-task
      - list-volume-task

Running ratect-compat test-task runs shared-prereq once (even though both prereq-task and list-volume-task depend on it), then prereq-task and list-volume-task, then test-task itself.