Container Runtime

# Container Runtime PRD

## Overview
Build a minimal container runtime that uses Linux namespaces for process isolation, cgroups v2 for resource limits, chroot for filesystem isolation, overlay filesystems for layered images, and basic networking with port forwarding.

## Requirements
- Create isolated processes using Linux namespaces: PID, UTS, mount, and network
- chroot into a provided root filesystem for filesystem isolation
- Mount the proc filesystem inside the container for process visibility
- Set a custom hostname for the container using UTS namespace
- cgroups v2 resource limits: memory limit and CPU shares
- Create a container from a root filesystem tarball
- Container networking: veth pair, bridge interface, and NAT for internet access
- Port forwarding: map host ports to container ports
- Container lifecycle management: create, start, stop, and remove containers
- List all running containers with status information
- exec into a running container to run additional commands inside it
- Container stdout/stderr capture with a logs command
- Environment variable passing from host to container
- Overlay filesystem: writable layer on top of a read-only base image
- Image pulling from a tar archive for distributing container images
- Resource usage reporting: memory and CPU usage from cgroup stats
- CLI with subcommands: run, exec, ps, logs, stop, rm

## Tech Stack
- TypeScript / Node.js (or C/Go if preferred — must run on Linux)
- Linux kernel APIs: clone, unshare, chroot, mount, cgroups v2 filesystem
- No external container runtime libraries — raw syscall-level implementation required

## Scoring Criteria
- **Functional (40%)**: Containers start in isolation, namespaces separate correctly, cgroups limit resources
- **Quality (20%)**: Proper namespace teardown, clean lifecycle management, safe error handling
- **Fidelity (25%)**: All features including networking, overlay FS, exec, logs, and resource reporting
- **Speed (15%)**: Time bonus