# Toast: containerized task graphs with Docker image caching

> Toast is a Rust build tool that runs YAML-defined development and CI tasks in Docker containers. It caches each task as an image and can share those cached images through a Docker registry, but its usefulness depends on how precisely a project defines task inputs and dependencies.

**stepchowfun/toast** — Containerize your development and continuous integration environments. 🥂

- Repository: https://github.com/stepchowfun/toast
- Stars: 1,633 · Forks: 38
- Language: Rust
- License: NOASSERTION
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/stepchowfun-toast

## Toast's YAML task graph for Docker-based builds

Toast addresses a specific gap between shell scripts and general-purpose container platforms. A team defines one container image and describes activities such as installing packages, compiling code, running tests, or serving pages in a YAML file called a toastfile. This is useful for developers who want the same task definitions locally and in continuous integration without installing every dependency on the host.

 Each task has a command and can declare dependencies, copied host files, exported files, environment variables, and caching behavior. Those fields create a dependency graph. In the README's C example, `build` depends on `install_gcc`, while `run` depends on `build`. Toast therefore operates as a high-level containerized build system rather than only as a wrapper for Docker commands.

This model suits repositories with repeatable commands such as compilation, linting, packaging, and testing. It also suits CI pipelines that benefit from cached preparation tasks. It is less suitable when the required unit is a network of services, because the README compares Toast with Docker Compose but distinguishes Toast through task definitions and remote caching. The repository topics also reflect that build-tool focus: `build-system`, `build-tool`, `ci`, `containers`, and `continuous-integration` are all represented.

## Docker commits, input hashes, and cache reuse

Toast does not describe caching as a generic cache directory. It commits the container after a task and stores the result as a Docker image. The image tag contains a cryptographic hash calculated from the task's shell command, copied file contents, and other task inputs. On a later invocation, Toast can identify an unchanged task and skip its command.

Dependency outputs become part of the effective environment for downstream work. If `install_gcc` is reused, a dependent `build` task does not need to repeat package installation merely because the project was invoked again. Changing `main.c` invalidates the `build` input, so the documented workflow reruns `build` and its dependent `run` task. This is a content-sensitive model rather than a timer-based decision.

Caching is not always desirable. A development server can represent external input that Toast does not know how to observe, such as requests or runtime state. The README addresses this directly with the `cache: false` option. Setting that option on a task also disables caching for tasks that depend on it. This prevents a long-running or externally changing operation from being restored as though its previous result were current.

A practical consequence is that task design affects cache quality. Commands should have explicit dependencies, and files that affect results should be listed through `input_paths`. The README does not describe a general ignore-file mechanism, automatic host filesystem watching, or a documented way to model every external service as an input. Those omissions make cache invalidation a project-specific configuration concern.

## Defining and running the first Toast task

The README does not document how to install Toast or how to invoke the repository's `install.sh` file. The repository includes `install.sh`, but no supported installation command appears in the available tutorial, so it would be misleading to invent one. Assuming the Toast executable is already available and Docker can run the selected image, create a file named `toast.yml` with the documented greeting task:

```yaml
image: ubuntu
tasks:
  greet:
    command: echo 'Hello, World!' # Toast will run this in a container.
```

Run Toast from the directory containing that file:

```bash
toast
```

The README says the first run executes `greet` inside a container based on `ubuntu`. Running `toast` again should report that nothing changed and skip the task because its cached image is still valid. That second invocation checks both Docker image caching and task hashing in the reader's local setup.

A cache-free variant is useful when a task should always execute:

```yaml
image: ubuntu
tasks:
  greet:
    cache: false # Don't cache this task.
    command: echo 'Hello, World!'
```

The installation gap matters. Because the README does not say which operating systems are supported or how `install.sh` installs Toast, prospective users must check the repository's installation documentation before assuming that a particular platform or package format works.

## Copying source inputs and extracting build artifacts

Toast separates container work from files on the host through `input_paths` and `output_paths`. The README's C workflow installs `gcc`, copies `main.c` into the container, compiles it, and runs the resulting `a.out`. Host files are copied into `/scratch` by default, and commands execute in that directory.

The following configuration demonstrates a cached compilation step and artifact export:

```yaml
image: ubuntu
tasks:
  install_gcc:
    command: |
      apt-get update
      apt-get install --yes gcc

  build:
    dependencies:
      - install_gcc
    input_paths:
      - main.c
    output_paths:
      - a.out
    command: gcc main.c
```

Here, `main.c` is part of the build input and therefore participates in cache invalidation. The `a.out` file is copied back to the host after compilation. Without `output_paths`, a build product remains inside the cached container unless another task consumes it there.

Using `.` would import the entire directory containing the toastfile, but that broader input has a cost: unrelated file changes may invalidate tasks. The precise-file example is cleaner when the build consumes a small fixed set of sources. The README does not document behavior for host paths outside the project directory, conflicting output destinations, or platform-specific executable permissions, so those cases require verification before teams depend on them.

Tasks may also receive environment values. The README uses `CLUSTER: staging` as the default for a hypothetical deployment task, showing that task configuration can parameterize behavior without changing the command text.

## Sharing cached images through a Docker registry

Beyond caching on one machine, Toast can store task images in a Docker registry. The intended workflow extends beyond personal reuse: a developer, other team members, and a CI system can refer to the same remote cache. A CI job can perform expensive setup and compilation, then make those results available to subsequent local or CI runs.

This approach differs from copying a build directory. Task state is represented by Docker images, and the same Docker infrastructure used to execute tasks can also hold their cached results. It also means the cache boundary is tied to container image lifecycle. Docker images can accumulate locally, so the README specifically points to Docuum for least recently used image eviction.

The README does not give the registry configuration syntax, authentication steps, image naming policy, retention controls, or cache eviction policy. It therefore supports the existence and purpose of remote caching, but not a complete operational procedure. Teams should not assume that two developers will share entries unless their Toast and Docker configuration produce compatible image tags and can reach the same registry.

A registry cache also changes the operational surface. Cached images and registry permissions become part of build infrastructure. The README does not say how registry outages affect execution or how stale images are pruned. It also does not document trust controls beyond the task hash. Those are concrete questions to answer before making the remote cache mandatory in CI.

## Docker Compose and Nix as different approaches

Docker Compose is the closest comparison in the README because it also provides Docker-based development environments. Its focus is convenient service definition, while Toast adds named tasks such as `lint`, `test`, and `run`. Toast also documents local task caching and remote caching through a Docker registry. 

Nix addresses reproducible builds through functional package management and derivations rather than containerized task execution. The README says Nix requires a larger commitment because users must adopt the Nix package manager or write their own derivations. Toast lets a team retain familiar package commands such as `apt-get install...` inside a selected container image.

That convenience is also a boundary. A toastfile does not replace the operating system and package manager inside its base image. Teams must still choose and maintain that image, write container commands, and account for differences between images. Toast coordinates and caches the workflow; it does not turn an arbitrary image into a fully reproducible build independent of image contents and external package state.

## Image storage, release activity, and license records

Toast's cache design has a visible storage cost because each completed task can produce a Docker image. The README acknowledges this and recommends Docuum for LRU eviction. That recommendation is narrower than automatic cleanup within Toast. Projects that already manage many Docker images should account for storage growth and image pruning before enabling caching broadly.

The repository was not archived, and its last push was on 2026-10-11. Documented releases include v0.48.0 dated 2026-04-06, v0.47.7 dated 2025-01-23, and v0.47.6 dated 2024-02-22. These facts show recent repository activity and a recent tagged release, but they do not establish compatibility or operational stability for a particular base image.

Licensing requires direct inspection because the repository records differ. The repository description classifies `LICENSE.md` as a custom license that GitHub could not classify, while `Cargo.toml` declares `license = "MIT"`. The README does not reproduce `LICENSE.md`, so the precise grant and conditions cannot be summarized safely. Organizations that distribute Toast should compare `LICENSE.md` with the Cargo package metadata. This is a repository inconsistency to resolve, not legal advice.

The README excerpt does not document a migration policy for upgrading task files. `CHANGELOG.md` is the first repository file to inspect when moving beyond v0.48.0, particularly for changes involving configuration parsing or cache behavior.

## Conclusion

Developers and CI maintainers should consider Toast when they want a task-oriented container workflow without adopting the Nix package model. Teams that need a general service-definition system should prefer Docker Compose, while projects sensitive to Docker daemon requirements should verify container startup before adoption. Check the selected image, input and output paths, cache sharing, and `LICENSE.md` first.

## FAQ

### What is Toast used for?

Toast runs YAML-defined development and CI tasks in Docker containers. Tasks can install system packages, compile applications, run tests, serve web pages, and depend on other tasks.

### How does Toast cache tasks?

Toast commits each task's container to an image and derives its tag from a cryptographic hash of the command, copied files, and other task inputs. An unchanged task can be skipped, and Docker images can optionally provide a shared remote cache.

### How do I install and run Toast?

The README does not document an installation command, although the repository contains `install.sh`. Once the executable is available, create `toast.yml` with an `image` and a task, then run `toast` from that directory.

### When should a Toast task disable caching?

Caching is unsuitable for tasks such as development servers whose useful result depends on runtime activity rather than stable files and commands. Set `cache: false` on that task, and tasks that depend on it also run without task caching.

### What is the difference between Toast and Docker Compose?

The README describes Docker Compose as a convenient way to define containerized development services, while Toast adds task-oriented operations such as `lint`, `test`, and `run`, plus local and remote task caching.

## Sources

- [Issues](https://github.com/stepchowfun/toast/issues)
- [README](https://github.com/stepchowfun/toast/blob/main/README.md)
- [Releases](https://github.com/stepchowfun/toast/releases)
- [stepchowfun/toast on GitHub](https://github.com/stepchowfun/toast)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/stepchowfun-toast