composefs-run

NOTE: This is currently a proof of concept, and not intended for production use

A minimal container runner that runs OCI containers directly from composefs-rs repositories using crun, without requiring podman's full runtime infrastructure or persistent state tracking.

Use --pull to check the registry and download a missing or updated image (requires skopeo in PATH):

target/debug/cfsrun --pull registry.fedoraproject.org/fedora:40

Without --pull, images must already be in the repository. With --pull, a registry error is reported even if an older image is available locally.

Features

• Mostly CLI-compatible with podman run
• Rootful mode: kernel erofs + overlayfs, bridge networking via netavark
• Rootless mode: FUSE-based composefs + unprivileged overlayfs (userxattr), user namespace with subuid/subgid mapping, pasta networking
• Minimal host state, containers are just child processes. There is no equivalent of podman ps/rm etc.
• No detached mode, always assumes -i.
• By default, writable overlays are transient, stored in /var/tmp. This can be overridden with --overlay-dir
• By default runs catatonit in the container to forward signals

Quick start

# Build (requires composefs-rs as a dependency)
cargo build

# Pull an image into a composefs repository
cfsctl init --insecure /tmp/repo
cfsctl --repo /tmp/repo oci pull docker://quay.io/centos/centos:stream10 cs10

# Run a container (rootless — automatic)
target/debug/cfsrun --repo /tmp/repo -t cs10 -- bash

# Run as root (uses kernel erofs + bridge networking)
sudo target/debug/cfsrun --repo /tmp/repo -t cs10 -- bash

Common options

cfsrun [OPTIONS] <IMAGE> [-- <CMD>...]

Options:
  --repo <PATH>           Path to composefs repository
  --pull                  Check the registry and pull a missing or updated image
  -t, --tty               Allocate a pseudo-TTY
  -e, --env <KEY=VALUE>   Set environment variables
  -u, --user <UID[:GID]>  Override user
  -w, --workdir <PATH>    Override working directory
  -v, --volume <H:C[:ro]> Bind mount
  --device <PATH[:PATH[:PERMS]]>  Add host device
  --read-only             Read-only rootfs
  --overlay-dir <PATH>    Persistent overlay directory
  --commit <REF>          Save the run's changes as a new image
  --network <MODE>        host|pasta|bridge|private
  --hostname <NAME>       Container hostname
  --privileged            Full capabilities, no seccomp/SELinux
  --cap-add/--cap-drop    Modify capabilities
  --security-opt <OPT>    seccomp, label, no-new-privileges
  --dns/--dns-search      DNS configuration
  -p, --publish <H:C>     Port forwarding
  --add-host <HOST:IP>    Extra /etc/hosts entries

Committing a run

cfsrun --repo /tmp/repo --commit updated cs10 -- sh -c 'echo hello > /hello'
cfsrun --repo /tmp/repo updated -- cat /hello

Use --commit <REF> to save the container's changes as a new image in the same repository. The new image is based on the image used to start the container and keeps its default configuration.

Changes are saved after the container exits, including when its command fails. cfsrun preserves the container's exit status even if saving the image fails. In that case, it reports an error and keeps the writable directory for recovery. Detailed diagnostics may be saved to a log at the reported path.

--commit cannot be combined with --read-only or --rootfs. Changes to bind mounts and temporary filesystems are excluded.

Testing

# Unit tests (no container image needed)
just test-unit

# Integration tests (requires cfsctl in PATH, pulls test image)
just cfsctl=/path/to/cfsctl test-integration

# All tests
just cfsctl=/path/to/cfsctl test

License

Apache-2.0 OR MIT