Commands

wctr

The client. It finds the daemon at -H unix:///path, else $WCTR_HOST, else unix:///var/run/wctr.sock.

wctr run pulls an image it does not have.

A WebAssembly guest has no signals, so wctr stop kills the container at once: -t is accepted for compatibility and ignored. In the API, /attach is a plain streamed response, not a hijacked connection.

Terminals and input (v0.30.0)

wctr run -i/-t, wctr attach and wctr start -ai give a container’s first process its own stdin and terminal. They use Docker’s fields Config.Tty, Config.OpenStdin, Config.StdinOnce and HostConfig.ConsoleSize.

• A container’s first process can get a stdin that attached clients write into. With -t it also gets a terminal: the engine handles line editing, echo and CR LF, and keeps keys typed ahead when a program switches to raw mode (the hand-over of the typed line is engine v0.29.2).
• POST /containers/{id}/attach accepts stdin=1 and detachKeys. Like exec start, it does not hijack the connection: the request body carries stdin and the response streams the output. POST /containers/{id}/resize is new.
• Ctrl-P Ctrl-Q detaches; detach keys use Docker’s format.
• It works in both executors, the native one and the browser’s. No host call blocks on stdin (v0.29.1).
• These commands are in engine v0.30.0’s cli package. cmd/wctr v0.2.0 required engine v0.22.0 and does not have them; cmd/wctr v0.3.0 requires engine v0.30.0 and does. The daemon (wctrd v0.31.0) serves the API.

For builders (v0.12.0, API only for now)

• POST /images/load takes an OCI image layout as a tar; each index.json entry is named by io.containerd.image.name or org.opencontainers.image.ref.name, else <none>. It is checked as a pull is, and nothing is read from the host.
• PUT /containers/{id}/archive?path=DIR extracts a tar into a container (relative clean names only, no devices, paths resolved inside the container, its quota applies), and GET returns a tar of a path. These two routes accept uploads up to 1 GiB by default; every other request is limited to 1 MiB.
• GET /images/{name}/json shows the full image config, the history, and RootFS.Layers as diff_ids. Dangling images appear as <none>.
• HEAD on the archive route returns only the path’s stat, without building a tar (v0.14.0).
• The Go client filters lists through ContainersFiltered, NetworksFiltered and VolumesFiltered, which take an api.Filters. v0.18.0 had changed the signatures of Containers, Networks and Volumes to take filters, which broke the dashboard; v0.21.0 restored them, and a new CI job compiles downstream modules against the engine.
• A start refused before the process exists (a port, a network, a volume) is recorded as an exit with code 128 and the reason, as Docker records it: a run --rm returns at once and its container is removed (v0.22.0). Since v0.23.0, wctr run exits 125 when the daemon refuses the start.
• Other modules add commands to wctr through an extension hook, cli.Options.Extra; wctr build and wctr compose use it. wctr build needs a wctrd of v0.12.0 or later (v0.17.0 for shell-form RUN).

Events (v0.6.0)

wctr events and GET /events stream NDJSON. --since and --until bound the range, and the filters are type, event, container, image, volume, network and label. The last 1024 events are kept, and a reader that is too slow is cut off.

Stats (v0.7.0)

wctr stats and the stats endpoint report memory against its limit, bytes written, layer and log size, and pids. CPU is not measured: a WebAssembly guest gives no CPU accounting, so it is shown as --.

Volumes (v0.8.0)

wctr volume create|ls|inspect|rm|prune, and wctr run -v NAME:/path[:ro]. Only named volumes exist: a host path is refused. A volume is shared between containers, :ro is enforced, and volumes survive a restart and a page reload. They appear in system df and in inspect.

Persistence (v0.4.0)

Containers survive a wctrd restart: they are kept under --data-root in containers/ (state, exit code, logs and written files). A container that was running comes back exited with code 137, and a --rm container is removed. An entry that is corrupted is dropped and reported.

Exit status of wctr run

The container’s own, or:

A guest’s own proc_exit code is a Docker status (engine v0.30.1): 0 to 255 is kept, so a guest that exits 126, 127 or 130 reports exactly that. A code outside that range (os.Exit(-1) arrives as 4294967295, or 256 and above) is reported as 1, which is also what wasmtime reports for it. wasmtime additionally turns 126 to 255 into 1; the engine does not, because Docker is the target.

Standard input, output and error are reported to the guest as a character device only under run -t or exec -t (a pipe is no longer reported as one since engine v0.30.1); otherwise (a pipe) they are of type unknown, as in wasmtime, so isatty() and Go’s terminal checks answer false for piped input.

Restart policies

run --restart and HostConfig.RestartPolicy (engine v0.25.0), as Docker’s:

• always restarts a container whenever it exits, and starts it with the engine;
• unless-stopped does the same, except that the engine leaves it stopped if a user stopped it;
• on-failure[:N] restarts it when it exits with a code other than 0, at most N times (0: no bound);
• no is the default.

A user’s stop or kill ends the policy until the next start, which counts from zero. Each restart waits first: 100 ms, doubled after every run shorter than 10 s, at most a minute. Meanwhile the container is restarting: ps lists it as Restarting (code) … ago, and rm needs -f. A start the engine refuses (a volume, a network, a port) is not retried. inspect shows HostConfig.RestartPolicy, RestartCount and State.Restarting. A policy cannot be combined with --rm.

Health checks

run --health-cmd CMD, --health-interval, --health-timeout, --health-start-period, --health-start-interval, --health-retries and --no-healthcheck (engine v0.28.0), as well as an image’s HEALTHCHECK and Config.Healthcheck. The test (CMD argv, CMD-SHELL through /bin/sh -c, or NONE) runs inside the running container through the exec machinery, every interval (default 30 s; 5 s during the start period), and is killed after the timeout (default 30 s, exit code −1). A pass makes the container healthy; retries consecutive failures (default 3) make it unhealthy; failures in the start period do not count. Fields left empty are taken from the image’s check. inspect shows State.Health (Status, FailingStreak, and the last 5 results with at most 4 KiB of output each), ps shows Up … (healthy), and each change of status is a health_status event (healthy or unhealthy; --filter event=health_status). Probes stop with the container and are not exec events. Unlike Docker, an interval or timeout below 100 ms is refused. A CMD-SHELL probe needs a /bin/sh in the image (the shell image has one).

For embedders. An in-process engine must register wasi.WASIX in its HostModules, as wctrd does, to run the shell image or health checks.

wctrd

Bounds on untrusted content