Skip to main content

Sysbox

Sysbox is a container runtime that lets customers run Docker-in-Docker securely inside pods — without --privileged mode. Many workloads (custom image builds, CI/CD pipelines, system-level tooling) require it.

Sysbox is required

Every validator probes every node for the sysbox-runc runtime. Nodes missing it are rejected — they earn no emission and cannot be rented. Sysbox is a hard requirement for every Lium node, not an optional optimization. Setup takes ~5 minutes.

Install​

The lium-io repo ships an installer that takes care of NVIDIA Container Toolkit + Sysbox in one go. From any Ubuntu host:

curl -fsSL https://raw.githubusercontent.com/Datura-ai/lium-io/main/neurons/executor/nvidia_docker_sysbox_setup.sh | sudo bash

Or, if you already have the lium-io repo cloned locally:

cd lium-io/neurons/executor
chmod +x nvidia_docker_sysbox_setup.sh
sudo ./nvidia_docker_sysbox_setup.sh

Confirm /etc/docker/daemon.json includes the sysbox runtime:

{
  "runtimes": {
    "sysbox-runc": {
      "path": "/usr/bin/sysbox-runc"
    }
  }
}

Restart Docker:

sudo systemctl restart docker

Verify​

Run the same command our validator uses:

docker run --rm --runtime=sysbox-runc --gpus all daturaai/compute-subnet-executor:latest nvidia-smi

If you see nvidia-smi output — you're good.

Docker ≥ 29.2.0: CDI compatibility fix​

Running Docker 29.2.0 or later? Sysbox + GPU will fail with a permission denied error:

OCI runtime create failed: ... failed to open OCI spec file: ... permission denied

This is because Docker 29.2.x enables CDI (Container Device Interface) by default, routing --gpus through CDI — incompatible with sysbox's user namespace.

Disable CDI by adding "features": {"cdi": false} to /etc/docker/daemon.json:

{
  "features": {
    "cdi": false
  }
}

Restart Docker and re-run the verify command:

sudo systemctl restart docker

This change is safe and reversible — remove the features block and restart Docker to re-enable CDI.

Troubleshooting​

  • sysbox-runc not found — the installer didn't finish. Re-run nvidia_docker_sysbox_setup.sh and check its output.
  • GPU not visible inside the container — confirm NVIDIA Container Toolkit is installed (nvidia-container-cli --version) and the Docker daemon was restarted after the install.
  • Validator still reports Sysbox missing — wait one validation cycle (~15 min) and re-check from the Provider Portal.