gontainer

Lightweight container runtime and tooling written in Go — includes the runtime daemon gontainerd and the CLI gontainer for managing containers and images.

---

Table of Contents

• gontainer
  • Table of Contents
  • Overview
  • Quick Start
  • CLI Commands
  • Image Format
    • Directory layout (example)
    • Minimal metadata.json fields (current example in images/alpine/metadata.json)
  • TODO
  • Examples & Common Tasks
  • Contributing

---

Overview

Gontainer is a minimal Docker like container runtime implemented in Go. It provides a small daemon (gontainerd) and a CLI (gontainer) to manage images and containers via a Unix socket (/var/run/gontainer.sock). The project is intentionally small and designed to be a learning-friendly runtime that can be extended.

Quick Start

Build the binaries using the Makefile:

make build

Start the daemon (require root):

sudo ./bin/gontainerd &

Run a container from a local image (example):

./bin/gontainer run --rm -d alpine

CLI Commands

Implemented commands (see cmd/gontainer):

• gontainer run [image] — Run a container from an image

  • Flags:
    • --name, -n <name> : set container name

• gontainer ps — List running containers

  • Flags:
    • --all, -a : show all containers

• gontainer rm [container...] — Remove one or more containers by id or name

  • Flags:
    • --force, -f : force remove running containers

• gontainer rmi [image...] — Remove one or more images

• gontainer images — List local images

• gontainer image ls (alias: image list) — List local images (same as images)

• gontainer image rm [image...] — Remove image(s) (alias for rmi)

• gontainer attach [container] — Attach to a running container

These commands communicate with the gontainerd daemon via the Unix socket at /var/run/gontainer.sock.

Image Format

The repository ships simple images under images/<name>/ with a small metadata.json. Below is a suggested, minimal image layout and fields to use when implementing pull/push and tag handling:

Directory layout (example)

images/
	alpine/
		metadata.json
		rootfs.tar  

Minimal metadata.json fields (current example in images/alpine/metadata.json)

• name (string): repository name (e.g., alpine).

• cmd (string): default command to run (e.g., /bin/sh).
• env (object): environment variables map (e.g., { "PATH": "/usr/bin:..." }).

TODO

• Registry support (mostly done) — finish and document registry features
• Networking — handle network namespaces and port mapping (e.g. bridge, port forwarding)
• pull command — pull images from registry (not implemented)
• push command — push images to registry (not implemented)
• stop command — stop a running container (not implemented)
• start command — start a stopped container (not implemented)
• Recovery system for daemon — implement restart/recovery of running containers on daemon restart (not-started)
• Persistent store for daemon — persist container and image state to disk (not-started)
• Tags system for images — support repository:tag semantics and tag operations (not-started)

Examples & Common Tasks

• List running containers:

./bin/gontainer ps

• Remove a container:

./bin/gontainer rm <container-id>

Contributing

Thanks for considering a contribution! All contributions are welcome. If you'd like to contribute:

• Open an issue first for larger changes to discuss the approach.
• Fork the repo and create a topic branch for your work.
• Send a pull request with a clear description and, where appropriate, tests.