crate

Crate is a small container runtime written in Go, built to explore containers work internally. It supports both rootless (without sudo) and rootful (with sudo) execution, with rootless mode being the main focus.

---

Getting started

Install using (Go 1.20+ recommended):

go install github.com/aayushkdev/crate/cmd/crate@latest

(ensure GOBIN is in path)

Verify installation:

crate --help

Usage

Pull an image

Pulls an image from a registry and stores it in the local image store.

crate pull alpine

Crate resolves the tag on each pull and skips blob work when the resolved manifest digest is already present locally.

---

List images

Lists local images from the manifest-backed metadata store.

crate images

---

Create a container

Creates a container from an image and prints the container ID.

crate create alpine

---

Start a container

Starts an existing container by ID.

crate start <CONTAINER_ID> [COMMAND] [ARG...]

Add -d / --detach to start it in the background.

Examples:

crate start c144672a8e04

crate start c144672a8e04 ls -l /

crate start -d c144672a8e04

If no command is provided, the image’s default CMD is used.

In attached mode, Crate allocates a real PTY so interactive shells and terminal programs behave normally.

---

Run (create + start)

run is a convenience command that creates a new container and immediately starts it.

crate run alpine

crate run alpine /bin/sh -c "echo hello world"  

crate run -d alpine

---

Stop a container

Stops one or more running containers by ID.

crate stop <CONTAINER_ID>

---

Remove containers

Removes one or more stopped containers.

crate rm <CONTAINER_ID>

Running containers must be stopped first.

---

List containers

Lists running containers by default.

crate ps

Show all containers:

crate ps -a

---

View logs

Prints a container’s captured stdout/stderr.

crate logs <CONTAINER_ID>

Follow output:

crate logs -f <CONTAINER_ID>

---

Remove images

Removes one or more local image tags.

crate rmi alpine:latest

If removing a tag leaves a manifest untagged, Crate deletes that manifest metadata and prunes any config or layer blobs that are no longer referenced by another local image.

Implemented Concepts

Isolation

• PID namespace
• UTS namespace (hostname)
• Mount namespace
• User namespace (rootless mode)

Filesystem

• Root filesystem setup using pivot_root (or chroot in rootless mode)
• /proc mounted inside the container
• /dev mounted as tmpfs with minimal devices (null, zero, random, urandom, full, shm, pts, ptmx)
• /run mounted as tmpfs
• /sys mounted read-only in rootful mode

Image handling

• Image name parsing (repo:tag)
• Pulling images from registries (docker only for now)
• OCI/Docker manifest resolution
• Manifest-based local image metadata with mutable local tags
• Local blob store (layers and config)
• Local image listing and removal
• Blob pruning when untagged manifests become unreferenced

Process execution

• PID 1 replaced with the container process using execve
• Proper PATH-based command resolution (no shell)
• CMD, Entrypoint and environment variables used from image config
• PTY-backed attached mode for interactive shells and terminal programs
• Container lifecycle commands: start, stop, ps, logs, rm, and detached mode

Far off goals (for now)

• Networking
• Cgroups / resource limits
• Volume mounts
• More configuration options
• Security hardening
• Full OCI spec compliance