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.zip

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

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 | decode - issue and inspect API 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 management UI

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)

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.