Skip to main content

​
Overview

The Kernel class manages the core system components: the virtual filesystem (VFS), persistence layer, and virtual port registry for network requests. It’s responsible for booting the system and initializing the standard directory structure.

​
Creating a Kernel

import { Kernel } from '@lifo-sh/core';

const kernel = new Kernel();
await kernel.boot({ persist: true });

​
Constructor

constructor(backend?: PersistenceBackend)
​
backend
PersistenceBackend
Custom persistence backend. Defaults to IndexedDBPersistenceBackend.
Example: 
import { Kernel, IndexedDBPersistenceBackend } from '@lifo-sh/core';

const kernel = new Kernel(new IndexedDBPersistenceBackend());

​
Instance Properties

​
vfs

The virtual filesystem instance. 
vfs: VFS
See VFS for full API documentation. Example: 
const kernel = new Kernel();
await kernel.boot();

kernel.vfs.writeFile('/home/user/test.txt', 'Hello');
const content = kernel.vfs.readFileString('/home/user/test.txt');

​
portRegistry

Registry mapping virtual ports to request handlers for network operations. 
portRegistry: Map<number, VirtualRequestHandler>
Example: 
// Register a virtual HTTP server on port 3000
kernel.portRegistry.set(3000, (req, res) => {
  res.statusCode = 200;
  res.headers['content-type'] = 'application/json';
  res.body = JSON.stringify({ message: 'Hello from virtual server!' });
});

// Now commands like `curl http://localhost:3000` will hit this handler

​
Instance Methods

​
boot()

Boot the kernel. Loads persisted filesystem, initializes standard directories, registers virtual providers, and sets up filesystem watch hooks. 
async boot(options?: { persist?: boolean }): Promise<void>
​
options
object
Example: 
const kernel = new Kernel();

// Boot with persistence (default)
await kernel.boot({ persist: true });

// Boot without persistence (ephemeral filesystem)
await kernel.boot({ persist: false });
Boot sequence:
  1. If persistence is enabled, load saved filesystem from IndexedDB
  2. Initialize standard directory structure (/bin, /etc, /home/user, etc.)
  3. Register virtual providers (/proc, /dev)
  4. If persistence is enabled, set up automatic save on filesystem changes

​
initFilesystem()

Initialize standard Unix-like directory structure and system files. Called automatically by boot(). 
initFilesystem(): void
Creates the following directories:
  • /bin - System binaries
  • /etc - Configuration files
  • /home - User home directories
  • /home/user - Default user home
  • /tmp - Temporary files
  • /var - Variable data
  • /var/log - Log files
  • /usr - User programs
  • /usr/bin - User binaries
  • /usr/share - Shared data
  • /usr/share/pkg - Package data
  • /usr/share/pkg/node_modules - Node.js packages
Writes system files:
  • /etc/motd - Message of the day (shown on shell startup)
  • /etc/hostname - System hostname (lifo)
  • /etc/profile - System-wide environment setup
  • /home/user/.liforc - User shell configuration (aliases, environment)
Example: 
const kernel = new Kernel();
kernel.initFilesystem();

// Standard directories now exist
console.log(kernel.vfs.exists('/home/user')); // true
console.log(kernel.vfs.exists('/tmp')); // true

​
getDefaultEnv()

Get default environment variables for the system. 
getDefaultEnv(): Record<string, string>
​
env
Record<string, string>
Default environment variables
Example: 
const kernel = new Kernel();
const env = kernel.getDefaultEnv();

console.log(env.HOME); // '/home/user'
console.log(env.PATH); // '/usr/bin:/bin'
console.log(env.TERM); // 'xterm-256color'

​
Type Definitions

​
VirtualRequest

interface VirtualRequest {
  method: string;              // HTTP method (GET, POST, etc.)
  url: string;                 // Request URL
  headers: Record<string, string>;
  body: string;                // Request body
}

​
VirtualResponse

interface VirtualResponse {
  statusCode: number;          // HTTP status code
  headers: Record<string, string>;
  body: string;                // Response body
}

​
VirtualRequestHandler

type VirtualRequestHandler = (
  req: VirtualRequest,
  res: VirtualResponse
) => void;

​
Virtual Providers

The kernel automatically registers virtual filesystem providers during boot:

​
/proc

Provides runtime process information (read-only). Available files:
  • /proc/uptime - System uptime in seconds
  • /proc/version - Kernel version information
  • /proc/meminfo - Memory usage statistics
Example: 
const kernel = new Kernel();
await kernel.boot();

const uptime = kernel.vfs.readFileString('/proc/uptime');
console.log('System uptime:', uptime);

​
/dev

Provides device files (read-only). Available files:
  • /dev/null - Null device (always empty)
  • /dev/zero - Zero device (infinite zeros)
  • /dev/random - Random data generator
  • /dev/urandom - Random data generator (same as /dev/random)
Example: 
const random = kernel.vfs.readFile('/dev/random');
console.log('Random bytes:', random.slice(0, 16));

​
Persistence

When persistence is enabled, the kernel automatically:
  1. On boot: Loads the saved filesystem from IndexedDB
  2. On change: Debounces and saves filesystem changes to IndexedDB
Example: 
// Session 1: Create file with persistence enabled
const kernel1 = new Kernel();
await kernel1.boot({ persist: true });
kernel1.vfs.writeFile('/home/user/important.txt', 'My data');

// Session 2: Data persists across page reloads
const kernel2 = new Kernel();
await kernel2.boot({ persist: true });
const data = kernel2.vfs.readFileString('/home/user/important.txt');
console.log(data); // 'My data'

​
Usage with Sandbox

The Kernel is typically created and managed by the Sandbox class. Direct kernel access is provided as a power-user escape hatch: 
const sandbox = await Sandbox.create();

// Access kernel directly
const kernel = sandbox.kernel;

// Register a virtual server
kernel.portRegistry.set(8080, (req, res) => {
  res.statusCode = 200;
  res.body = 'Hello!';
});

// Access VFS directly
kernel.vfs.mkdir('/custom');
kernel.vfs.writeFile('/custom/data.txt', 'Direct access');

​
Source Location

// src/kernel/index.ts
export class Kernel {
  vfs: VFS;
  portRegistry: Map<number, VirtualRequestHandler>;
  
  constructor(backend?: PersistenceBackend);
  async boot(options?: { persist?: boolean }): Promise<void>;
  initFilesystem(): void;
  getDefaultEnv(): Record<string, string>;
}

Build docs developers (and LLMs) love

Get started for freeTalk to us