ZLayer Documentation

Welcome to the ZLayer documentation. ZLayer is a lightweight container orchestration system designed for simplicity and security.

Getting Started

Installation

ZLayer ships as a single static binary. It runs natively on Linux (kernel 5.4+), macOS 13+ Ventura, and Windows 10 21H2+ / Server 2019+. On Windows, ZLayer uses the Host Compute Service (HCS) native runtime for Windows containers, with optional WSL2 support for Linux workloads.

Linux / macOS

# Quick install
curl -fsSL https://zlayer.dev/install.sh | bash

# Verify
zlayer --version

Windows (PowerShell)

# Quick install
irm https://zlayer.dev/install.ps1 | iex

# Verify
zlayer --version

From GitHub Releases (manual)

Prebuilt artifacts are published on the GitHub Releases page for every tagged version:

  • zlayer-linux-amd64.tar.gz
  • zlayer-linux-arm64.tar.gz
  • zlayer-darwin-arm64.tar.gz
  • zlayer-darwin-amd64.tar.gz
  • zlayer-windows-amd64.tar.gz

Download the archive that matches your platform, extract the zlayer binary, and place it on your PATH.

Your First Container

Create a simple container specification in container.yaml:

apiVersion: zlayer.dev/v1
kind: Container
metadata:
  name: hello-world
spec:
  image: docker.io/library/alpine:latest
  command: ["echo", "Hello from ZLayer!"]

Run the container:

zlayer run container.yaml

Core Concepts

Containers

Containers are the basic unit of execution in ZLayer. Each container runs in an isolated environment with its own filesystem, network namespace, and process tree.

Pods

Pods group containers that need to share resources and communicate via localhost. All containers in a pod share the same network namespace and can access shared volumes.

Overlay Networks

ZLayer provides built-in encrypted overlay networking. This allows containers on different hosts to communicate securely without complex network configuration.

Scheduler

The ZLayer scheduler distributes containers across available nodes based on resource requirements, constraints, and affinity rules. It supports both immediate and queued scheduling modes.

API Reference

Container Spec

The container specification supports the following fields:

  • image - OCI image reference (required)
  • command - Override the image entrypoint
  • args - Arguments to pass to the command
  • env - Environment variables
  • resources - CPU and memory limits
  • network - Network configuration
  • volumes - Volume mounts
  • securityContext - Security settings

Deployment Spec

Beyond raw containers, ZLayer ships a richer deployment spec used by zlayer deploy. A deployment is one of three kinds:

  • kind: Service - long-running workloads (web servers, APIs, workers)
  • kind: Job - run-to-completion tasks
  • kind: Cron - scheduled jobs on a cron expression

Deployments support:

  • scaling: { mode: adaptive | fixed | manual } - automatic scaling driven by load, fixed replica counts, or manual control
  • healthChecks - liveness and readiness probes (HTTP, TCP, exec)
  • initActions - pre-start lifecycle hooks (TCP/HTTP wait, S3 sync, custom commands)
  • storage - persistent volumes backed by local disk or S3
  • tunnel - optional secure tunneling for node-to-node access
  • os: linux | windows - target operating system for the workload

REST API Endpoints

The Manager UI is a client of the ZLayer HTTP API, served under /api/v1. The browser-console and host-power features surfaced in the Manager UI map to these endpoints:

  • POST /api/v1/containers/{id}/exec, then GET /api/v1/exec/{id}/start (WebSocket) - create an exec session inside a running container and attach an interactive PTY. This is the browser console.
  • GET /api/v1/containers/{id}/console/attach (WebSocket) - attach an interactive guest/VM serial console.
  • GET /api/v1/containers/{id}/console - read-only serial console stream (NDJSON by default, or SSE with ?format=sse / an Accept: text/event-stream header).
  • PUT /api/v1/cluster/nodes/{id}/wake - Wake-on-LAN a powered-down node (broadcast from a live same-subnet peer).
  • PUT /api/v1/cluster/nodes/{id}/reboot - reboot a node's host.
  • PUT /api/v1/cluster/nodes/{id}/shutdown - power a node's host off.
  • PUT /api/v1/cluster/nodes/{id}/drain / PUT /api/v1/cluster/nodes/{id}/undrain - cordon a node so the scheduler stops placing new work on it, then return it to service.

CLI Commands

ZLayer is a single binary with a broad command surface. Commands are grouped below by category. Run zlayer --help or zlayer <command> --help for the full reference.

Lifecycle

  • zlayer up / zlayer down - bring a deployment up or tear it down
  • zlayer deploy - apply a deployment spec
  • zlayer join - join an existing cluster
  • zlayer ps / zlayer status - list workloads or inspect cluster state
  • zlayer exec / zlayer logs - exec into a workload or stream its logs
  • zlayer stop / zlayer run / zlayer validate - control or validate a spec

Build & Image

  • zlayer build - build an OCI image from a Dockerfile or ZImagefile
  • zlayer pipeline - run a multi-image ZPipeline build
  • zlayer runtimes - list bundled runtime templates (node, python, rust, go)
  • zlayer pull / zlayer import / zlayer export - move images in and out of the local store
  • zlayer image ls | inspect | rm - manage the local image cache
  • zlayer wasm build | export | push | validate - WebAssembly component workflows

Cluster & Node

  • zlayer node init | join | list | status | remove - manage cluster nodes
  • zlayer network ls | inspect | create | rm - manage overlay networks
  • zlayer volume ls | rm - manage persistent volumes

Server & Daemon

  • zlayer serve - run the API server (add --daemon to background it)
  • zlayer daemon install | start | stop | status - cross-platform service installer (systemd on Linux, launchd on macOS, Windows SCM on Windows)
  • zlayer windows compact - Windows-only: compact the WSL2 VHDX backing file to reclaim disk space

Resources

  • zlayer secret ls | create | get | rm | rotate - secrets management
  • zlayer env / zlayer variable - environment and variable management
  • zlayer task ls | run / zlayer workflow ls | run - tasks and workflows
  • zlayer notifier ls | test - notification channels
  • zlayer job ls | trigger - job scheduling
  • zlayer container ls | logs | stats - low-level container introspection

Auth & RBAC

  • zlayer auth login | whoami - authenticate against the API
  • zlayer token create | ls | revoke - scoped access tokens
  • zlayer user / zlayer group - user and group administration
  • zlayer permission list | grant - role-based access control
  • zlayer audit tail - stream the audit log

Projects & GitOps

  • zlayer project ... - manage projects
  • zlayer credential registry | git - registry and Git credentials
  • zlayer sync ls | create | diff | apply - GitOps-style sync from a Git repo

Tunneling

  • zlayer tunnel create | list | connect - secure node-to-node tunnels

Manager UI

  • zlayer manager init | status | stop - install and control the browser management UI. See the Manager UI section for what it provides.

Docker Compatibility

  • zlayer docker install / zlayer docker uninstall - install or remove the Docker shim
  • zlayer docker run | build | compose | ... - drop-in replacement for the docker CLI when built with the docker-compat feature

Tools

  • zlayer tui - interactive terminal UI for builds and cluster state
  • zlayer completions - generate shell completions (bash, zsh, fish, PowerShell)

Manager UI

The Manager UI is a browser-based control plane for a ZLayer cluster. Launch it with zlayer manager init (check or stop it with zlayer manager status / zlayer manager stop) and open the printed address. Every page is live: node, container, and resource views poll the API and refresh in place, and CPU / memory / GPU readings animate as real-time charts and gauges.

Fleet & Nodes

The /nodes page is a live grid of every node in the cluster - its role and Raft leader status, health, CPU / memory / disk, and any GPUs it advertises - topped by fleet totals (total nodes, healthy nodes, current leader, cluster status). Selecting a node opens its detail page at /nodes/:id, which shows the node's identity, live resource utilization (radial CPU / memory / disk gauges plus a utilization-history chart), advertised GPUs, and the workloads scheduled on it.

Each node detail page also exposes a Power / Lifecycle panel for host control:

  • Drain / Undrain - cordon a node so the scheduler stops placing new work on it, then return it to service
  • Wake-on-LAN - power a shut-down node back on by broadcasting a magic packet from a live peer that shares its subnet
  • Reboot - restart the node's host
  • Shutdown - power the node's host off (it then needs Wake-on-LAN or a manual power-on to return)

Containers & Deployments

The /deployments page lists every deployment with its status, replica count, and per-service detail; each running service shows compact live CPU and memory sparklines and a Console button that opens an interactive shell. The /containers page lists individual containers (with running counts), and /containers/:id is the per-container detail view: inspected metadata, ports, networks, environment and labels, a live stats panel (CPU / memory / PIDs refreshed every couple of seconds), and buttons to open the browser and serial consoles.

Images, Volumes & GPU

Three resource pages round out the fleet view:

  • /images - the local image cache with total count and size. Pull, tag, and delete images, and open an Inspect + History drawer to see an image's configuration and layer history.
  • /volumes - persistent volumes with total count and size; create and delete volumes in place.
  • /gpu - a fleet-wide GPU allocation dashboard: total GPUs and VRAM, reserved GPUs and VRAM, schedulable-capacity gauges (GPUs and VRAM still available to schedule), a per-vendor / model breakdown, and a row for every node that reports or reserves GPU capacity.

Browser Console

The browser console is an in-browser terminal (powered by xterm.js) that opens an interactive shell inside a running container. It is reachable from the Console button on the container detail page and on each running service in the deployments page. Behind the scenes it creates an exec session on the container and streams the PTY over a WebSocket, so you get a fully interactive shell without leaving the browser or configuring SSH.

Serial Console

The serial console attaches directly to a guest's serial line, reachable from the Serial console button on the container detail page. On guests that expose a live serial channel - ZLayer's microVM and VZ runtimes - it is fully interactive, so you can type at the kernel command line or a login prompt; this is the way to reach a guest whose network or in-guest agent is down. On runtimes without a live serial channel (for example Firecracker microVMs or plain OCI containers) the interactive attach is unavailable and the console falls back to a read-only stream that shows serial output without accepting input.

Live Charts

Utilization is shown live throughout the UI. The dashboard renders cluster-aggregate CPU and memory history charts alongside deployment, network, and running-service summaries; the node detail page renders per-node CPU / memory history charts and radial CPU / memory / disk gauges; the GPU dashboard renders schedulable-capacity gauges; and running services render inline CPU / memory sparklines. All of these update continuously from live samples as you watch.

Examples

Web Application

apiVersion: zlayer.dev/v1
kind: Container
metadata:
  name: webapp
spec:
  image: nginx:alpine
  resources:
    cpu: 1
    memory: 256Mi
  network:
    ports:
      - containerPort: 80
        hostPort: 8080
  volumes:
    - name: static-files
      hostPath: /var/www/html
      mountPath: /usr/share/nginx/html

Database with Persistent Storage

apiVersion: zlayer.dev/v1
kind: Container
metadata:
  name: postgres
spec:
  image: postgres:15
  env:
    - name: POSTGRES_PASSWORD
      valueFrom:
        secretRef: db-password
  resources:
    cpu: 2
    memory: 1Gi
  volumes:
    - name: pgdata
      hostPath: /data/postgres
      mountPath: /var/lib/postgresql/data

Pod with Multiple Containers

apiVersion: zlayer.dev/v1
kind: Pod
metadata:
  name: app-with-sidecar
spec:
  containers:
    - name: app
      image: myapp:latest
      ports:
        - containerPort: 8080
    - name: metrics
      image: prometheus/node-exporter:latest
      ports:
        - containerPort: 9100

Windows Service (IIS)

apiVersion: zlayer.dev/v1
kind: Service
metadata:
  name: hello-iis
spec:
  os: windows
  image: mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2022
  ports:
    - containerPort: 80

Configuration

ZLayer is configured via a mix of CLI flags, environment variables, and an optional configuration file. The most common knobs are exposed as both flags on zlayer serve and equivalent environment variables.

Environment Variables

  • ZLAYER_DATA_DIR - root directory for image, volume, and cluster state
  • ZLAYER_STATE_DIR - runtime state (sockets, PID files, scheduler state)
  • ZLAYER_BIND - address the API server binds to (default 0.0.0.0:3669)
  • ZLAYER_API_TOKEN - bearer token for authenticated API access
  • ZLAYER_WEB_ADDR - address the web frontend binds to (default 0.0.0.0:3000)

Service Installation

Pass --service to zlayer serve to install ZLayer as a managed system service. The flag selects the right backend per platform: a systemd unit on Linux, a launchd plist on macOS, or a Windows Service Control Manager (SCM) entry on Windows. zlayer daemon install wraps the same plumbing if you prefer a dedicated subcommand.

Windows-specific Flags

On Windows, zlayer serve --vhd-gb <N> caps the size of the WSL2 VHDX image used for Linux workloads. This is useful in shared CI environments where unbounded growth would exhaust the host disk. Use zlayer windows compact to reclaim free space inside the VHDX after deleting workloads.

Data Directory Layout

  • Linux: ~/.local/share/zlayer/
  • macOS: ~/Library/Application Support/zlayer/
  • Windows: %LOCALAPPDATA%\ZLayer\

When ZLayer runs as a system service, the data directory defaults to a system-wide location appropriate for the platform (e.g. /var/lib/zlayer on Linux, C:\ProgramData\ZLayer on Windows).

For Windows CI test harness setup, see docs/windows-ci-runner.md. For the complete list of configuration options, see the README.

Troubleshooting

Common Issues

  • Permission denied - Ensure you have the necessary privileges to run containers (rootless mode may require additional setup)
  • Image not found - Check that the image reference is correct and the registry is accessible
  • Network unreachable - Verify overlay network configuration and overlay peer connectivity
  • Windows: serve fails to bind - Run as Administrator. The Windows firewall and HCS APIs require elevation. For unattended operation, use zlayer daemon install to register ZLayer as a Service Control Manager (SCM) service.

For more help, please open an issue on GitHub.