create

Create a CheerpX application instance

namespace CheerpX {
  class Linux {
    static async create(options?: {
      mounts?: MountPointConfiguration[];
      networkInterface?: NetworkInterface;
    }): Promise<CheerpX.Linux>;
  }
}

Parameters

• options (object, optional) - Used to configure different settings of the CheerpX Linux environment. This object may include settings for mounts, network interfaces, and other features, structured as { option: "value" }.

Returns

CheerpX.Linux.create returns a Promise which is resolved once the CheerpX Linux environment is fully initialized and ready to use. The resolved value is a CheerpX.Linux instance that provides methods for interacting with the CheerpX environment.

Additionally, this instance allows you to register and monitor system events, such as CPU and disk activity. For more details, see the event callbacks page.

Options

A description of each CheerpX.Linux.create option with brief examples are given below.

mounts

mounts?: MountPointConfiguration[];

This option configures the filesystems that will be available in the CheerpX environment. Each mount point configures a device and specifies where it should be accessible within the virtual filesystem.

Each mount configuration must follow this structure:

interface MountPointConfiguration {
  // Specifies the filesystem type
  // 'ext2' for Linux ext2
  // 'dir' for a hierarchical file system
  // 'devs' for device files (no device required)
  // 'proc' for process info files. (no device required)
  type: "ext2" | "dir" | "devs" | "proc";

  // First mount must be "/" (root). Every other mount's path must
  // point to a directory that already exists inside the filesystem
  // mounted at an ancestor path, following standard Linux mount conventions.
  path: string;
  // Required for 'ext2' and 'dir' types, but optional for 'devs' and 'proc'
  dev?: CheerpX.Device;
}

Example:

const cx = await CheerpX.Linux.create({
  mounts: [
    { type: "ext2", path: "/", dev: overlayDevice },
    { type: "dir", path: "/app", dev: webDevice },
    { type: "devs", path: "/dev" }, // No dev required
    { type: "proc", path: "/proc" }, // No dev required
  ],
});

Mount order matters

Because each mount’s path must point to an existing directory inside an already-mounted filesystem, mounting /app/bin before /app exists will fail. Mount /app first.

// Fails: nothing has created "/app" yet, so "/app/bin" has no parent to mount onto
const cx = await CheerpX.Linux.create({
  mounts: [
    { type: "dir", path: "/", dev: dataDevice },
    { type: "dir", path: "/app/bin", dev: webDevice },
  ],
});

Note

CheerpX supports a variety of backends, designed to provide access to HTTP resources, IndexedDB-based persistent storage and data from JavaScript. Complete Ext2 filesystems are also supported on top of block devices. For detailed information, including usage examples and full APIs, please refer to the Files and filesystems guide.

networkInterface

networkInterface?: NetworkInterface;

This option configures network settings, which allows CheerpX to communicate over networks.

Each Configuration must follow this structure:

interface NetworkInterface {
  authKey?: string;
  controlUrl?: string;
  loginUrlCb?: (url: string) => void;
  stateUpdateCb?: (state: number) => void;
  netmapUpdateCb?: (map: any) => void;
}

The following sections provide details on each available option within NetworkInterface, along with example usages.

authKey

authKey?: string;

The authKey is a string containing an authentication key for registering pre-authenticated users or devices. You can generate one here.

Example:

const cx = await CheerpX.Linux.create({
  mounts: mountPoints,
  networkInterface: { authKey: "YOUR KEY" },
});

controlUrl

controlUrl?: string;

The controlUrl is an optional string used to specify the URL of a self-hosted Headscale server.

Example:

const cx = await CheerpX.Linux.create({
  mounts: mountPoints,
  networkInterface: { controlUrl: "YOUR URL" },
});

loginUrlCb

loginUrlCb?: (url: string) => void;

The loginUrlCb is a callback function that handles login URLs during the authentication process. It receives the URL that should be visited to continue the login process. This is necessary when authenticating with Tailscale.

Example:

const cx = await CheerpX.Linux.create({
  mounts: mountPoints,
  networkInterface: { loginUrlCb },
});

function loginUrlCb(url) {
  console.log("Login URL is ready:", url);
  // Open the login URL in a new tab or window
  window.open(url, "_blank");
}

stateUpdateCb

stateUpdateCb?: (state: number) => void;

The stateUpdateCb is a callback that runs when the connection state changes. The state parameter represents the connection status.

Example:

const cx = await CheerpX.Linux.create({
  mounts: mountPoints,
  networkInterface: { stateUpdateCb },
});

function stateUpdateCb(state) {
  if (state === 6) {
    console.log("Connected");
  }
}

netmapUpdateCb

netmapUpdateCb?: (map: any) => void;

The netmapUpdateCb is a callback that runs whenever the network configuration updates. It provides details about the current network configuration.

Example:

const cx = await CheerpX.Linux.create({
  mounts: mountPoints,
  networkInterface: { netmapUpdateCb },
});

function netmapUpdateCb(map) {
  const currentIp = map.self.addresses[0];
  console.log(`Current IP: ${currentIp}`);
}

For more detailed information about how CheerpX handles networking, including the use of Tailscale and overcoming browser limitations, see the Networking guide.