Skip to content

v2 Containers

Jump to bottom Edit New page
Eric Trenkel edited this page Oct 1, 2026 · 2 revisions

Containers

Docker, Podman and WSL's own containers on this machine, in one list. The engine owns them; WSL Manager shows them and drives their lifecycle.

Containers are deliberately not instances. A WSL distro or a macOS VM is a machine the app owns for its whole life; a container is one process tree spawned from an image that someone else's engine owns. They keep their own screen, and "delete" means something much cheaper here than it does on the home screen.

Turning it on

Containers is an experimental destination, so it is off until you ask for it:

Settings → Experimental features → Containers

The entry then appears in the navigation pane. Experimental means the screen works but is still settling — please report anything odd.

Engines

The app drives an engine's command-line tool, so anything that speaks Docker's grammar fits. Three are probed, in this order:

Engine Command Where Notes
Docker docker Windows, macOS Docker Engine or Docker Desktop
Podman podman Windows, macOS Including podman machine
WSL container wslc Windows only Built into WSL itself — nothing to install, no daemon to start

Settings → Container engine picks which one the screen and the AI tools drive. Automatic takes Docker if it is installed, otherwise Podman, otherwise WSL's own engine.

WSL's engine ships inside WSL from version 2.9.3 and is generally available in 3.0.1. If wslc is missing, update WSL itself:

wsl --update
wslc version

It is only probed on a Windows host (or a Windows machine reached through Remote WSL) — on a Mac it cannot exist, so the app does not spend a process launch looking for it.

Creating a container

WSL Manager does not create containers, and that is on purpose. It is a front end for an engine's lifecycle commands — the same reason there is no "create container" button for Docker either. Containers you create with any of the three engines show up on the screen by themselves; hit Refresh if you made one while the screen was open.

Create them with the engine's own CLI. For WSL's built-in engine that is wslc run, which takes Docker's flags:

# Pull nothing by hand — run fetches the image if it is missing
wslc run -d --name web -p 127.0.0.1:8080:80 nginx

# A throwaway shell, removed again when you leave it
wslc run --rm -it alpine sh

# Build from a Dockerfile in the current directory, then run it
wslc build -t myapp .
wslc run -d --name myapp -e DEBUG=1 -v mydata:/data myapp

wslc run [options] <image> [command] [arguments...], with the flags you would expect:

Flag Meaning
-d, --detach Run in the background — what you want for anything long-lived
--name Name the container, so the list shows something readable
-p, --publish Publish a container port to the host ([host-ip:]host-port:container-port)
-P, --publish-all Publish every exposed port to random host ports
-v, --volume Bind a volume into the container
--mount, --tmpfs Attach a filesystem mount, or a tmpfs at a path
-e, --env, --env-file Environment variables, inline or from a file
-it Interactive, with a TTY — for a shell rather than a service
--rm Remove the container once it exits
-u, --user, -w, --workdir User and working directory for the process
-m, --memory, --cpus, --gpus Resource limits, and GPU passthrough (--gpus all)
--network, --ip, --dns Networking
--health-cmd and friends Health check command, interval, retries, timeouts
--pull always / missing / never (default missing)

Other verbs wslc has that the app does not wrap: create (make a container without starting it), pull, push, build, import, load, export, rmi, kill, attach, events, info, registry / login / logout for registry credentials, and settings, which opens the engine's own config file in your editor. Run wslc <command> --help for any of them.

For Docker and Podman the commands are the same with the binary swapped — docker run -d --name web -p 8080:80 nginx.

What the screen does

Once a container exists, everything on the screen works the same whichever engine owns it:

Action What it does
Refresh Re-read the list from the engine
Start / Stop Toggle on the row, depending on the current state
Restart Stop and start again
Logs The container's output, in a dialog
Delete Removes the container and everything written inside it that is not in a volume. The image is kept

Each row shows the name, the image it came from, its state and status, and any published ports.

Delete is the one destructive action here — and it is much narrower than deleting an instance. A container is cheap to recreate from the same run command; anything you need to survive it belongs in a volume.

WSL's engine in detail

wslc accepts Docker's spellings as aliases (ps, logs, inspect, stop, volume ls, network ls, rm --force, --version), so almost nothing about the screen changes when it is the active engine. A few differences are worth knowing if you also use the CLI directly:

  • --format is a vocabulary, not a template language. It takes json or table — a Go template like {{.ID}} is not accepted. The app asks for --format json, whose keys and State values stay English whatever your Windows display language.
  • The table output is localised. On a German Windows, wslc list prints CONTAINER-ID BILD BEFEHL ERSTELLT STATUS PORTS NAMEN. That is why the app parses the JSON and only ever shows the table as text.
  • --since wants an instant, not a duration. --since 15m is read as epoch 15 — "since 1970" — with no error. Use an epoch or an RFC 3339 timestamp; the app converts durations against the clock before passing them on.
  • stats takes a single sample and rejects --no-stream.
  • top and system df do not exist. The app says so by name rather than running a command that answers with a usage dump.

From the AI assistant and MCP

With the Containers switch on, the AI assistant and the MCP server gain the container tools, against whichever engine is active (or one named per call):

container_engines, container_list, container_start, container_stop, container_restart, container_remove, container_logs, container_exec, container_inspect, container_images, container_volumes, container_networks, container_stats, container_processes, container_disk_usage.

Reads an engine genuinely lacks are refused by name — container_processes and container_disk_usage on wslc, for instance. As on the screen, none of these creates a container; container_exec runs a command inside one that is already running.

Troubleshooting

"No container engine found." On Windows, WSL 2.9.3 and later include the wslc engine — run wsl --update to get it. Otherwise install Docker or Podman, make sure its command is on your PATH, and hit Refresh. The app resolves each engine through PATH, so a tool installed only inside a WSL distro will not be found.

"The container engine did not answer." The command was found but failed. With Docker that is usually the daemon not running; start Docker Desktop or the service and refresh. wslc has no daemon, so here it more often means WSL itself needs wsl --update.

The list is empty but containers are running. Check Settings → Container engine — a container created with Docker is invisible to wslc and the other way round. Each engine keeps its own containers. Switch the engine, or set it back to Automatic.

A container is missing after a reboot. Nothing here sets a restart policy; wslc run has no --restart flag. Start it again from the screen.

Add a custom footer
Add a custom sidebar

Clone this wiki locally