Xila

Appearance

Headless Xila runtime ​

The xila-runtime binary runs a Xila command-line shell or a VFS executable without a graphical desktop. It can be built as a native binary or used in a Linux/amd64 OCI image. This is not the development image that contains Rust and build tools.

Image and executable ​

Core's container workflow builds and smoke-tests the image from Dockerfile.runtime and publishes to ghcr.io/xila-project/xila-runtime on eligible pushes. latest follows the default branch; releases receive matching v* tags, and published builds receive a commit-SHA tag.

The image runs as UID/GID 10001, retains its mutable disk in /var/lib/xila, and carries an immutable reference image at /usr/share/xila/base.img. Its entrypoint is /usr/bin/xila-runtime, and its default command is shell --network=none. The container currently supports linux/amd64, not embedded hardware.

Command syntax ​

text
xila-runtime shell [OPTIONS]
xila-runtime run [OPTIONS] -- <Xila executable> [arguments...]

Options available in either mode:

text
[--disk PATH] [--seed PATH] [--network=none]
[--mount host=PATH,xila=PATH,ro|rw[,uid=N,gid=N,file_mode=OCTAL,directory_mode=OCTAL]]
[--env KEY=VALUE]...
  • shell starts Xila's built-in /applications/executables/command_line_shell and needs stdin to log in. A fresh seeded installation accepts administrator with an empty password. It forbids overriding User with --env.
  • run starts an absolute executable path in Xila's VFS after --. For a WASI guest, use /applications/executables/wasm followed by the guest module's Xila VFS path and any arguments.
  • --disk PATH selects the mutable LittleFS disk (default: /var/lib/xila/drive.img).
  • --seed PATH selects the image used only when no disk exists (default: /usr/share/xila/base.img).
  • --network=none is the only accepted Xila network mode. Docker's separate --network none disables container networking.
  • --mount host=...,xila=...,ro|rw grants an explicitly selected runtime-host directory to Xila's VFS. Optional uid, gid, file_mode, and directory_mode control ownership and permissions.
  • --env KEY=VALUE adds an explicit guest environment setting; repeat it for multiple settings.
  • --help and --version display CLI information.

Isolation and durability ​

Host directories must first be mounted into Docker and then separately exposed through Xila's --mount; a Docker bind mount alone grants no Xila VFS access. Ambient host environment variables are not passed to guests. Use read-only mounts unless writes are necessary.

A writable volume at /var/lib/xila retains the LittleFS disk across container runs. An existing disk is never overwritten by a newer seed. SIGINT/SIGTERM attempts to flush/unmount before exiting; abrupt termination may lose recent writes. The image is non-root and supports a read-only container root filesystem with writable state and a temporary /tmp.

This runner does not provide a graphical desktop, host sockets, an enabled Xila network stack, hardware acceleration, embedded-board support, or sandbox guarantees beyond Docker's own isolation. Guest compatibility remains limited to the WASI API subset Xila implements.

See also ​