Your first 10 minutes with boxr: pull, run, ps, logs, stop, done

This is the companion post to the boxr usage walkthrough video, the same commands in text form so you can copy them. It assumes Article 1's install is done: one static binary on your PATH, state in ~/.boxr.

One honest note up front, carried over from the video: this was recorded as root in a throwaway test VM, so boxr info in the video shows Rootless Mode: false. On your machine as a normal user the whole flow below runs fully rootless. Nothing in this walkthrough needs sudo.

Look at the empty shelves

boxr images

Empty table, just the header row. You have not pulled anything yet.

Pull an image

boxr pull library/alpine:latest

One spelling note: use library/alpine:latest, not docker.io/library/alpine:latest. boxr currently does not normalize the docker.io/ prefix, so that spelling misses the image cache and re-pulls on every run. Same image bytes, but the short spelling is the one the cache recognizes. It is a known bug, filed and waiting on the maintainer.

Run boxr images again and alpine is there.

Run something trivial

boxr run --rm library/alpine:latest echo hello

You should see hello. The --rm flag removes the container when it exits, which is the right default for one-shot commands. If you know Docker, this flag and everything about this command line will feel familiar. That is deliberate: boxr's CLI is Docker-shaped on purpose.

Run something that stays up

boxr run -d --name web -p 8080:80 nginx:latest

-d detaches, --name web names it, -p 8080:80 publishes the container's port 80 on host port 8080. boxr pulls nginx on first use, exactly like you would expect.

boxr ps
boxr logs web

boxr ps lists running containers (boxr ls is an alias). boxr logs web streams the container's stdout, which for nginx is its startup lines. Confirm it is serving:

curl -s http://localhost:8080 | head -3

Peek inside

boxr exec web cat /etc/os-release

boxr exec runs a command in a running container, same shape as docker exec. boxr top web lists the container's processes if you want to see what is actually running in there.

The full lifecycle, spelled out

run is really create plus start in one step. If you want the pieces separated:

boxr create --name sleeper library/alpine:latest sleep 3600
boxr start sleeper
boxr ps
boxr stop sleeper
boxr rm sleeper

create builds the container without starting it, start launches it, stop halts it, rm removes it. Nothing about this sequence touches root.

Clean up the images too

boxr rmi library/alpine:latest
boxr images

rmi removes the image. Containers and images are separate inventories: removing a container does not remove its image, and rmi will refuse while a container still references the image.

The flags you already know

Almost everything Docker-shaped works the way you expect:

• -d detach, --name name the container
• -p host:container publish ports (a user-space TCP proxy forwards them, so low ports need no privileges)
• -v host-dir:/container-dir bind mounts

One practical consequence of rootless bind mounts that is worth knowing: files the container writes as root show up on the host owned by your user, not by root. No sudo chown dance afterwards:

mkdir -p ~/boxr-data
boxr run -d --name files -v ~/boxr-data:/data:rw library/alpine:latest sleep 3600
boxr exec files sh -c "echo hello > /data/greeting.txt"
cat ~/boxr-data/greeting.txt
boxr stop files && boxr rm files

What rootless looks like from the outside

After any of the commands above, run this on the host:

ps aux | grep -v grep | grep boxr

Nothing. No daemon, no agent, no background process. Each boxr invocation does its work and exits completely. All state lives in ~/.boxr in your home directory, so uninstalling is deleting the binary and that folder.

boxr info shows the engine's view of itself: version, storage, network mode, and whether it is running rootless. (Remember the recording caveat: it says false in the video because that VM ran as root. On your account it says true.)

And boxr --help lists the full command surface: build for Dockerfile-compatible image builds, compose for multi-container apps, volume and network for persistent state and custom networks. This series stays with the daily loop; the rest is in the repo's CLI reference.

Next up

Article 3 compares the Docker, Podman, and boxr architectures and shares our startup benchmark with every caveat on the table: 134 ms vs 217 ms median, 20 warm runs each, and yes, both engines ran as root in the test VM. Full disclosure there too.

If rootless-first resonates, try the binary and open an issue when something breaks: https://github.com/kchaitanya863/boxr. That feedback is the fastest way to make the engine better.