rules.json

{
  "": "Single source of truth for Docker -> wslc translation. Consumed by the Python package, the npm CLI, the MCP server and the VS Code extension. Do not fork this logic per language. Every claim here is verified against a real wslc on a windows-2025 runner; see .",
  "schemaVersion": 2,
  "wslcPreview": "2.9.4.0",
  "identical": [
    "run",
    "build",
    "pull",
    "push",
    "stop",
    "start",
    "exec",
    "logs",
    "inspect",
    "stats",
    "tag",
    "login",
    "logout",
    "kill",
    "save",
    "load",
    "attach",
    "version",
    "ps",
    "images",
    "rmi",
    "rm",
    "create"
  ],
  "renamed": {
    "cp": "container cp"
  },
  "unsupported": {
    "swarm": "Swarm orchestration has no wslc equivalent. Use Kubernetes or keep Docker for this workload.",
    "service": "Swarm services are not supported by wslc.",
    "stack": "Swarm stacks are not supported by wslc.",
    "node": "Swarm node management is not supported by wslc.",
    "secret": "Swarm secrets are not supported. Pass values with -e or mount a file.",
    "config": "Swarm configs are not supported by wslc.",
    "plugin": "Docker plugins are not supported by wslc.",
    "context": "wslc has a single local runtime, so there are no contexts to switch.",
    "buildx": "buildx / bake is not available. Use wslc build for single-platform images.",
    "manifest": "Manifest lists cannot be created with wslc in the preview.",
    "trust": "Docker Content Trust is Docker-specific and has no wslc equivalent.",
    "checkpoint": "Checkpoint/restore is not implemented in wslc.",
    "restart": "No restart command in wslc 2.9.4. Run  then .",
    "pause": "Pause/unpause (SIGSTOP freezing) is not implemented in wslc 2.9.4.",
    "unpause": "Pause/unpause is not implemented in wslc 2.9.4.",
    "info": "No .  only exposes . Use  for build info.",
    "top": "No . Use  inside the container.",
    "wait": "No . Poll  or run the container in the foreground without --detach.",
    "port": "No  command. Published ports are shown in the PORTS column of .",
    "rename": "Containers cannot be renamed in wslc 2.9.4. Recreate with the desired --name.",
    "diff": "No filesystem diff.  writes the container filesystem to a tar for inspection.",
    "commit": "No commit. Use  then , or build from a Dockerfile.",
    "history": "wslc 2.9.4 has no image history.  shows config but not per-layer history.",
    "search": "wslc 2.9.4 cannot search a registry. Browse Docker Hub / the registry web UI instead."
  },
  "flags": {
    "--platform": {
      "action": "drop",
      "takesValue": true,
      "severity": "warn",
      "note": " is dropped: wslc builds and runs for the host architecture only in the preview."
    },
    "--restart": {
      "action": "drop",
      "takesValue": true,
      "severity": "warn",
      "note": "Restart policies are not implemented in the wslc preview. Flag dropped — use a Windows scheduled task or a wrapper script for auto-restart."
    },
    "--gpus": {
      "action": "keep",
      "takesValue": true,
      "severity": "info",
      "note": " is native in wslc 2.9.4 (). Do NOT rewrite it to : wslc has no --device flag. On a host without an NVIDIA GPU the run fails at container init with an ldconfig error.",
      "noteAlways": " is native in wslc 2.9.4, but the host must actually have the GPU: on a machine without one,  fails at container init with an ldconfig error."
    },
    "--network": {
      "action": "conditional",
      "takesValue": true,
      "whenValue": {
        "host": {
          "action": "error",
          "severity": "error",
          "note": "wslc rejects host networking outright:  (exit 1). It is not implicit and cannot be dropped silently.  works."
        }
      },
      "severity": "info",
      "note": "Custom networks are supported: create with , then .  is valid;  is rejected."
    },
    "--volume": {
      "action": "keep",
      "takesValue": true,
      "aliases": [
        "-v",
        "--mount"
      ],
      "severity": "info",
      "noteWhenWindowsPath": "Windows host paths are shared over VirtioFS. Use forward slashes () and expect Linux-style permissions on the container side."
    },
    "--memory": {
      "action": "keep",
      "takesValue": true,
      "severity": "info",
      "note": "Supported (). Unit suffix must be UPPERCASE:  works,  is rejected with . Plain byte counts also work. Expect a kernel warning that swap limits are unavailable.",
      "requireValuePattern": "^[0-9]+([KMGT]|[KMGT]B)?$",
      "noteWhenValueRejected": "wslc rejects lowercase size units:  fails with . Use an UPPERCASE suffix (512M, 1G) or a plain byte count.",
      "aliases": [
        "-m"
      ],
      "fixValueCase": "upperSizeSuffix",
      "noteWhenValueFixed": "Rewrote the size to use an UPPERCASE unit suffix: wslc rejects lowercase units () while Docker accepts both."
    },
    "--shm-size": {
      "action": "keep",
      "takesValue": true,
      "severity": "info",
      "note": "Supported. Same uppercase-unit rule as --memory:  works,  is rejected.",
      "requireValuePattern": "^[0-9]+([KMGT]|[KMGT]B)?$",
      "noteWhenValueRejected": "wslc rejects lowercase size units:  fails with . Use an UPPERCASE suffix (64M, 1G).",
      "fixValueCase": "upperSizeSuffix",
      "noteWhenValueFixed": "Rewrote the size to use an UPPERCASE unit suffix: wslc rejects lowercase units () while Docker accepts both."
    },
    "--cpus": {
      "action": "keep",
      "takesValue": true,
      "severity": "info",
      "note": "Supported, accepts fractional values (0.5, 1, 2.5)."
    },
    "--ulimit": {
      "action": "keep",
      "takesValue": true,
      "severity": "info",
      "note": "Supported, e.g. ."
    },
    "--stop-timeout": {
      "action": "keep",
      "takesValue": true,
      "severity": "info",
      "note": "Supported, seconds; -1 means no timeout."
    },
    "--health-cmd": {
      "action": "keep",
      "takesValue": true,
      "severity": "info",
      "note": "Supported. wslc has the full health-check family: --health-cmd, --health-interval, --health-retries, --health-start-period, --health-timeout, --no-healthcheck."
    },
    "--device": {
      "action": "drop",
      "takesValue": true,
      "severity": "warn",
      "note": "wslc 2.9.4 has no --device flag (). For GPUs use --gpus."
    },
    "--publish": {
      "action": "keep",
      "takesValue": true,
      "aliases": [
        "-p"
      ],
      "severity": "info",
      "note": "Supported ().  publishes all exposed ports."
    },
    "--cap-add": {
      "action": "drop",
      "takesValue": true,
      "severity": "warn",
      "note": "wslc 2.9.4 has no --cap-add (). There is no way to grant extra capabilities; --privileged and --security-opt are missing too."
    },
    "--cap-drop": {
      "action": "drop",
      "takesValue": true,
      "severity": "warn",
      "note": "wslc 2.9.4 has no --cap-drop ()."
    },
    "--privileged": {
      "action": "drop",
      "takesValue": false,
      "severity": "warn",
      "note": "wslc 2.9.4 has no --privileged ()."
    },
    "--security-opt": {
      "action": "drop",
      "takesValue": true,
      "severity": "warn",
      "note": "wslc 2.9.4 has no --security-opt ()."
    },
    "--expose": {
      "action": "drop",
      "takesValue": true,
      "severity": "warn",
      "note": "wslc 2.9.4 has no --expose. Publish the port with -p, or use -P/--publish-all to publish every port the image exposes."
    }
  },
  "compose": {
    "supported": false,
    "note": "wslc has no built-in Compose runtime. Translate each service into a wslc run call, or drive them from a PowerShell/bash script.",
    "docsUrl": "https://wslcontainers.com/guides/compose/",
    "keys": {
      "image": {
        "status": "ok",
        "maps": "positional image argument"
      },
      "build": {
        "status": "ok",
        "maps": "wslc build -t <name>"
      },
      "command": {
        "status": "ok",
        "maps": "trailing command args"
      },
      "entrypoint": {
        "status": "ok",
        "maps": "--entrypoint"
      },
      "environment": {
        "status": "ok",
        "maps": "-e KEY=VALUE"
      },
      "env_file": {
        "status": "ok",
        "maps": "--env-file"
      },
      "ports": {
        "status": "ok",
        "maps": "-p HOST:CONTAINER"
      },
      "volumes": {
        "status": "partial",
        "maps": "-v",
        "note": "Named volumes must be created first with wslc volume create. Windows paths go over VirtioFS."
      },
      "networks": {
        "status": "partial",
        "maps": "--network",
        "note": "Bridge-only. Create with wslc network create before running."
      },
      "working_dir": {
        "status": "ok",
        "maps": "-w"
      },
      "user": {
        "status": "ok",
        "maps": "-u"
      },
      "hostname": {
        "status": "ok",
        "maps": "--hostname"
      },
      "container_name": {
        "status": "ok",
        "maps": "--name"
      },
      "labels": {
        "status": "ok",
        "maps": "--label"
      },
      "cap_add": {
        "status": "missing",
        "note": "wslc 2.9.4 has no --cap-add (), and no --privileged or --security-opt either."
      },
      "devices": {
        "status": "missing",
        "note": "wslc 2.9.4 has no --device. GPUs go through --gpus; there is no generic device passthrough."
      },
      "tmpfs": {
        "status": "ok",
        "maps": "--tmpfs"
      },
      "stdin_open": {
        "status": "ok",
        "maps": "-i"
      },
      "tty": {
        "status": "ok",
        "maps": "-t"
      },
      "restart": {
        "status": "missing",
        "note": "No restart policies in the wslc preview."
      },
      "healthcheck": {
        "status": "ok",
        "maps": "--health-cmd / --health-interval / --health-retries / --health-timeout / --health-start-period",
        "emit": "health",
        "note": "wslc run implements all five health flags plus --no-healthcheck. Nothing reads the compose file, so the flags are emitted onto the run command for you. What is still missing is depends_on gating on health state."
      },
      "depends_on": {
        "status": "missing",
        "note": "No dependency ordering. Start services in order yourself and add readiness waits."
      },
      "deploy": {
        "status": "missing",
        "note": "Swarm-only section, ignored entirely."
      },
      "profiles": {
        "status": "missing",
        "note": "Compose-only concept."
      },
      "extends": {
        "status": "missing",
        "note": "Compose-only concept."
      },
      "configs": {
        "status": "missing",
        "note": "Swarm configs are unsupported; mount a file instead."
      },
      "secrets": {
        "status": "missing",
        "note": "Swarm secrets are unsupported; use -e or a mounted file."
      },
      "cap_drop": {
        "status": "missing",
        "note": "wslc 2.9.4 has no --cap-drop."
      },
      "expose": {
        "status": "missing",
        "note": "No --expose on wslc run. Publish with ports: (-p), or use -P to publish everything the image exposes."
      },
      "network_mode": {
        "status": "missing",
        "note": "network_mode: host is refused with . Use a user-defined network plus published ports."
      },
      "privileged": {
        "status": "missing",
        "note": "No --privileged on wslc run."
      },
      "security_opt": {
        "status": "missing",
        "note": "No --security-opt on wslc run."
      },
      "shm_size": {
        "status": "ok",
        "maps": "--shm-size",
        "note": "Unit suffix must be UPPERCASE (64M, not 64m)."
      },
      "mem_limit": {
        "status": "ok",
        "maps": "-m",
        "note": "Unit suffix must be UPPERCASE (512M, not 512m)."
      },
      "dns": {
        "status": "ok",
        "maps": "--dns"
      },
      "ulimits": {
        "status": "ok",
        "maps": "--ulimit"
      },
      "domainname": {
        "status": "ok",
        "maps": "--domainname"
      },
      "stop_signal": {
        "status": "ok",
        "maps": "--stop-signal"
      },
      "stop_grace_period": {
        "status": "ok",
        "maps": "--stop-timeout",
        "note": "Converted to whole seconds."
      }
    }
  },
  "devcontainer": {
    "keys": {
      "image": {
        "status": "ok"
      },
      "build.dockerfile": {
        "status": "ok"
      },
      "build.args": {
        "status": "ok",
        "maps": "--build-arg"
      },
      "build.platform": {
        "status": "missing",
        "note": "Host architecture only."
      },
      "workspaceMount": {
        "status": "partial",
        "note": "VirtioFS; use forward slashes for Windows paths."
      },
      "workspaceFolder": {
        "status": "ok"
      },
      "containerEnv": {
        "status": "ok",
        "maps": "-e"
      },
      "remoteEnv": {
        "status": "ok"
      },
      "forwardPorts": {
        "status": "ok",
        "maps": "-p"
      },
      "postCreateCommand": {
        "status": "ok",
        "maps": "wslc exec"
      },
      "postStartCommand": {
        "status": "ok"
      },
      "postAttachCommand": {
        "status": "ok"
      },
      "remoteUser": {
        "status": "ok",
        "maps": "-u"
      },
      "containerUser": {
        "status": "ok"
      },
      "mounts": {
        "status": "partial",
        "note": "VirtioFS path rules apply."
      },
      "runArgs": {
        "status": "partial",
        "note": "Passed through verbatim; unsupported flags will fail at runtime."
      },
      "dockerComposeFile": {
        "status": "missing",
        "note": "No Compose runtime. Replace with a single image or build entry."
      },
      "features": {
        "status": "missing",
        "note": "Requires BuildKit metadata that wslc build does not emit."
      },
      "runServices": {
        "status": "missing",
        "note": "Compose-only key."
      },
      "shutdownAction": {
        "status": "partial",
        "note": "stopCompose is meaningless without Compose."
      }
    },
    "requiredSetting": {
      "key": "dev.containers.dockerPath",
      "value": "wslc",
      "note": "Point the Dev Containers extension at wslc. Prefer workspace scope over global."
    }
  },
  "apiIncompatible": {
    "note": "CLI-driven tooling ports to wslc. API-driven tooling cannot, because wslc is daemonless and exposes no Docker Engine API or socket.",
    "tools": [
      {
        "name": "Testcontainers",
        "via": "Engine API",
        "works": false
      },
      {
        "name": "Docker-in-Docker sidecars",
        "via": "mounted socket",
        "works": false
      },
      {
        "name": "Portainer",
        "via": "Engine API",
        "works": false
      },
      {
        "name": "Lazydocker",
        "via": "Engine API",
        "works": false
      },
      {
        "name": "LocalStack (docker mode)",
        "via": "Engine API",
        "works": false
      },
      {
        "name": "act",
        "via": "Engine API",
        "works": false
      },
      {
        "name": "VS Code Dev Containers",
        "via": "CLI binary",
        "works": true
      },
      {
        "name": "shell scripts calling docker",
        "via": "CLI binary",
        "works": true
      }
    ]
  },
  "links": {
    "site": "https://wslcontainers.com",
    "converter": "https://wslcontainers.com/",
    "cheatsheet": "https://wslcontainers.com/reference/cheatsheet/",
    "compose": "https://wslcontainers.com/guides/compose/",
    "install": "https://wslcontainers.com/guides/install/",
    "vsDocker": "https://wslcontainers.com/guides/vs-docker-desktop/",
    "devcontainers": "https://wslcontainers.com/guides/vscode-dev-containers/",
    "testcontainers": "https://wslcontainers.com/guides/testcontainers/"
  },
  "renamedOptional": {
    "": "wslc accepts BOTH the docker-style short command and the noun-verb form (verified:  and  both exit 0). These rewrites are cosmetic; converters should not treat the short form as an error.",
    "commands": {
      "ps": "container list",
      "images": "image list",
      "rmi": "image remove",
      "rm": "container remove",
      "create": "container create"
    }
  },
  "verification": {
    "wslcVersion": "2.9.4.0",
    "verifiedAt": "2026-07-29",
    "method": "GitHub Actions windows-2025 runner, real wslc invocations",
    "runs": [
      "30417819781",
      "30417964880",
      "30418758451"
    ]
  },
  "twoWord": {
    "system prune": {
      "status": "unsupported",
      "note": " only exposes  in 2.9.4 — there is no . Run the per-noun prunes instead: , , , ."
    },
    "system info": {
      "status": "unsupported",
      "note": "No  in wslc 2.9.4. Use ."
    },
    "system df": {
      "status": "unsupported",
      "note": "No  in wslc 2.9.4. Inspect per-noun listings instead."
    },
    "container prune": {
      "status": "supported",
      "note": "Removes all stopped containers."
    },
    "image prune": {
      "status": "supported",
      "note": "Removes dangling images; --all removes all unused images."
    },
    "volume prune": {
      "status": "supported",
      "note": "Removes unused anonymous volumes; --all includes named ones."
    },
    "network prune": {
      "status": "supported",
      "note": "Removes all unused networks."
    }
  },
  "passthrough": {
    "": "These commands work in BOTH short form (docker-like) and long form (noun verb). Both are native in wslc 2.9.4.",
    "cp": "Only long form container cp works in wslc 2.9.4; top-level cp is not recognized",
    "create": "short 'create' and long 'container create' both work",
    "images": "short 'images' and long 'image list' both work",
    "ps": "short 'ps' and long 'container list' both work",
    "rm": "short 'rm' and long 'container remove' both work",
    "rmi": "short 'rmi' and long 'image remove' both work"
  }
}