pocket-docker

A minimal container runtime in Go. Single binary, no daemon, stores state in ~/.pocket-docker/state.db.

Demo

Requirements

• Linux with cgroup v2 (most modern distros)
• Go 1.22+ (for building)
• ip (iproute2) and iptables for networking

Runs rootless unless using --network or --publish (requires root/CAP_NET_ADMIN).

Installation

go build ./cmd/pocket-docker

Quick Start

Get a rootfs.
Any .tar that expands to a Linux filesystem will do. For example Docker is a convenient image source:

docker export $(docker create busybox) > busybox.tar

Run interactive shell

sudo ./pocket-docker run \
  --rootfs busybox.tar \
  --cmd "/bin/sh" \
  -it --network --publish 8080:80 --memory 104857600

Or run detached

sudo ./pocket-docker run \
  --rootfs busybox.tar \
  --cmd "/bin/sh -c 'while true; do sleep 3600; done'" \
  --detach

Commands

Command	Description
run	Create and start a container
ps	List containers
exec	Run command in a running container
logs	View container logs
inspect	Display detailed container info
stop	Stop a container
rm	Remove a container

Run Flags

Flag	Description
-v, --volume	Bind mount volume (host:container[:ro])
-e, --env	Set environment variable (KEY=VALUE)
-w, --workdir	Working directory inside container
-it	Interactive mode with TTY
-d, --detach	Run in background
-p, --publish	Publish port (host:container[/udp])
-m, --memory	Memory limit in bytes

Examples

Run with volume and environment

./pocket-docker run --rootfs busybox.tar \
  -v /tmp/data:/data \
  -e MY_VAR=hello \
  -w /data \
  --cmd '/bin/sh'

List and inspect

./pocket-docker ps
./pocket-docker inspect <ID>

Logs and exec

./pocket-docker logs -f --tail 50 <ID>
./pocket-docker exec -it <ID> /bin/sh

Cleanup

./pocket-docker stop --all
./pocket-docker rm --all

Testing

Run e2e tests in Docker (requires Docker):

make test

Interactive shell for manual testing:

make test-shell