Currunt

This project is a container runtime, written primarily as a learning exercise, by referencing only the OCI spec, Kernel documentation, blog posts, and educational resources. No source code/documentation of existing container runtimes or AI has been used. External dependencies are minimized to the greatest degree possible.

It is being written in two phases:

1. a cli tool that can start, stop, and attach to container processes, with full support for typical commands passed to a container (env var values, override commands, exposed ports, etc). The result of this phase will be OCI Runtime compliant.

2. a rewrite into a system daemon that will aim to implement the CRI API specification

• Getting Started
  • Usage
• Roadmap
  • Phase 1a:
  • Phase 1b
  • Phase 2
• Known Issues and Limitations
• Resources

Getting Started

Binaries can be found on the releases page, only Linux is supported.

Usage

currunt has a similar interface to other container tools like docker:

sudo ./currunt run -image busybox -interactive -tty

You can override the entrypoint, cmd, env, working directory, etc:

sudo ./currunt run -image ghcr.io/holysoles/ginrcon:latest -interactive -tty -entrypoint "/bin/sh" -cmd "-c ls" -workdir "/proc"

Or provide volume mounts:

sudo ./currunt run -image busybox -interactive -tty -entrypoint "/bin/sh" -volume ".:/app"

You can also let the container detach, but there is not presently a re-attach method

sudo ./currunt run -image nginx

Roadmap

Phase 1a:

Goal: "feel like a container runtime"

• run an isolated (chrooted) process
• support env variables
• pull images from distribution v2 image registries (Docker Hub, GitHub, GitLab, GCR, Forgejo)
• run processes in unpacked image environment
• run the command/arguments/env specified in the image config
• support attaching a tty to the process
• support attaching interactively to the process
• support volume mounts
• have a overlay for the container to persist changes separately from from image
• use pivotroot instead of chroot for isolation
• support namespaces
• track running containers in an index file
• support networking to host

Phase 1b

Goal: support more nuanced container features that make the magic happen

• network bridge with host and expose ports
• support cgroups
• support adding/dropping capabilities
• use a system location for image storage
• image+layer caching
• re-attach to previously detached container (enterns)
• invoke container entrypoint with pid 1 (currently spawn command is pid 1)
• support user namespaces

Phase 2

• rewrite to daemon with socket (and likely drop the CLI)
  • If keeping the CLI, will look into improvements (kong?)
• full support for CRI API spec

Known Issues and Limitations

• General
  • Only running 1 container at a time is currently supported due to hardcoded IP assignment for the network devices
  • Passing user/groups at the command line is ignored
• Registry Support
  • haven't been able to test successful image pulls with quay.io. It's possible there's additional work needed.
  • no backwards compatibility with distribution v2 schema 1
• Networking
  • the container does not have access to any of the host's networks

Resources

• Containers in general
  • Liz Rice's "Containers From Scratch"
  • DePaul University lecture notes
  • container in c
• Namespaces
  • namespaces in go
  • Scott Lowe's Weblog: Network Namespaces
• Distribution Specification
  • OCI Distribution Spec
    • Spec whitepaper
    • converting image manifest config to OCI runtime blob
  • Distribution API auth
  • Distribution API requests via curl
• PivotRoot and Chroot
  • Why Pivot Root is Used for Containers
  • chroot vulnerabilities
• OverlayFS
  • overlay fs docs