@suilway/vm

Docker-backed VM and sandbox runtime for Suilway. The package manages an Ubuntu desktop container, a shared workspace, Docker images/containers/volumes, and the Docker Unix socket used by sandbox and AI agent runtimes.

Requirements

• Node.js 20+
• Docker Engine with access to /var/run/docker.sock
• A host filesystem with enough capacity for the requested 64 GB workspace

The disk: "64GB" value is recorded and validated by the package. Docker bind mounts do not enforce a hard quota by themselves; use a quota-capable storage driver or filesystem if a strict 64 GB limit is required.

Install

npm install @suilway/vm

Quick start

import { SuilwayVM } from "@suilway/vm";

const vm = new SuilwayVM({
  cpu: 4,
  memory: "8GB",
  disk: "64GB",
  image: "ubuntu-24.04-desktop",
});

await vm.create();
await vm.start();

console.log(vm.url);    // http://localhost:6080
console.log(vm.vncUrl); // vnc://localhost:5900

The ubuntu-24.04-desktop alias resolves to the configured image akarita/docker-ubuntu-desktop. The image is started with web VNC on port 6080 and native VNC on port 5900 at 1920x1080.

Docker Compose

mkdir -p volumes/docker volumes/workspace
docker compose up -d

The included compose service applies 4 CPUs, an 8 GB memory limit, the workspace and Docker data mounts, and /var/run/docker.sock. Mounting the Docker socket gives the VM control over the host Docker daemon, so only use this setup in a trusted environment.

Sandbox

import { SandboxRunner, Workspace } from "@suilway/vm";

const sandbox = await new SandboxRunner().run({
  image: "ubuntu:24.04",
  workspace: new Workspace("./volumes/workspace"),
});

const result = await sandbox.terminal.run("pwd && ls -la");
console.log(result.exitCode, result.output);

Package layout

src/
├── vm/         VM lifecycle and configuration
├── docker/     Docker client, containers, images and volumes
├── socket/     Docker socket readiness and event stream
├── sandbox/    Sandbox runner, terminal and workspace filesystem
├── desktop/    Web VNC and native VNC access
└── resources/  CPU, memory and disk validation

Security

/var/run/docker.sock is equivalent to broad control of the Docker host. Do not expose the socket or the VNC ports to an untrusted network. The workspace filesystem helper prevents path traversal outside its configured root, but commands run through Docker still have the permissions of their container.

Development

npm run check
npm run build