boxy

boxy

A tiny container CLI powered by containerd and runc.

🔥 No Docker daemon needed — just containerd (system service) + Linux namespaces.

🚀 Quick start

# Install containerd + runc (Ubuntu/Debian example)
sudo apt update && sudo apt install -y containerd runc

# Clone & build boxy
git clone https://github.com/arnab2001/boxy.git
cd boxy && go build -o boxy ./cmd/boxy

# Pull an image
sudo ./boxy pull nginx

# Run a container with port forwarding
sudo ./boxy run --name web -p 8080:80 nginx

# Access your container
curl http://localhost:8080

# List containers
sudo ./boxy ps

# Stop and remove
sudo ./boxy stop web
sudo ./boxy rm web

📑 Command reference

boxy pull nginx:1.27

# Basic container
boxy run --name api alpine        # /bin/sh

# Background container
boxy run -d --name redis redis:7  # background

# Port forwarding examples
boxy run --name web -p 8080:80 nginx                    # TCP (default)
boxy run --name app -p 3000:3000/tcp -p 5353:53/udp app # Multiple ports
boxy run --name db -p 127.0.0.1:5432:5432 postgres     # Bind to specific IP

NAME   STATE     PID   IMAGE
web    RUNNING   2419  docker.io/library/nginx:latest
redis  STOPPED   -     docker.io/library/redis:7

boxy stop redis 5s

boxy rm web
boxy rm -f redis  # force kill first

🌐 Networking & Port Publishing

Boxy uses CNI (Container Network Interface) for networking with automatic port forwarding via iptables.

Requirements

• CNI plugins installed at /opt/cni/bin/ (bridge, portmap)
• iptables for port forwarding rules

Install CNI Plugins

# Download and install CNI plugins
wget https://github.com/containernetworking/plugins/releases/download/v1.4.1/cni-plugins-linux-amd64-v1.4.1.tgz
sudo mkdir -p /opt/cni/bin
sudo tar -xzf cni-plugins-linux-amd64-v1.4.1.tgz -C /opt/cni/bin

Network Configuration

Boxy automatically creates a bridge network (boxy0) with:

• Root mode: 172.18.0.0/16 subnet
• Rootless mode: 10.88.0.0/16 subnet

Rootless Support

Run boxy without root privileges:

# Rootless mode (experimental)
./boxy run --name app -p 8080:80 nginx

Rootless Limitations:

• Privileged ports (<1024) require bypass4netns plugin
• Some network features may be limited
• User namespace restrictions apply

🔍 Architecture snapshot

boxy CLI
   │ gRPC
   ▼
containerd (system daemon)
   │ fork/exec
   ▼
runc  →  Linux namespaces, cgroups
   │
   ▼
CNI plugins → bridge + iptables (port forwarding)

🌱 Roadmap ideas

Legend: ✅ Complete | 🔄 In Progress | 📋 Planned

🤝 Contributing

1. Fork the repo & create a feature branch.
2. Follow golangci-lint run (no warnings).
3. Make PRs small and focused.
4. Add tests for new functionality in the test/ directory.

🧪 Testing

# Run all tests
cd test && go test -v .

# Run benchmarks
go test -bench=.

# Run with coverage
go test -cover .

📝 License

MIT License - see LICENSE for details.