Package Overview Lifo is distributed as a collection of npm packages. Choose the packages that fit your use case:
@lifo-sh/core Required - Kernel, shell, VFS, commands, and sandbox API
@lifo-sh/ui Optional - Terminal UI component based on xterm.js
lifo-sh Optional - CLI tool to run Lifo in your system terminal
Installing the Core Package The @lifo-sh/core package is the foundation of Lifo. It includes everything needed to create sandboxes and run commands programmatically.
npm install @lifo-sh/core
Package Details Installing the UI Package Add the terminal UI component to create interactive terminal experiences in your web application:
The UI package includes xterm.js and addons. Only install this if you need visual terminal rendering.
Installing the CLI Run Lifo directly in your system terminal:
After installation, launch Lifo:
Quick Start Examples Headless / Programmatic Usage For server-side or programmatic usage without a visual terminal:
import { Sandbox } from '@lifo-sh/core' ; const sandbox = await Sandbox . create (); // Run commands const result = await sandbox . commands . run ( 'ls -la /home/user' ); console . log ( result . stdout ); // Work with files await sandbox . fs . writeFile ( '/tmp/test.txt' , 'Hello, Lifo!' ); const content = await sandbox . fs . readFile ( '/tmp/test.txt' );
Browser with Terminal UI For web applications with interactive terminal:
import { Terminal } from '@lifo-sh/ui' ; import { Sandbox } from '@lifo-sh/core' ; // Create terminal in a DOM element const terminal = new Terminal ( document . getElementById ( 'terminal' )); // Create sandbox with terminal attached const sandbox = await Sandbox . create ({ terminal , persist: true , // Enable IndexedDB persistence }); // Terminal is now interactive!
Node.js Environment Lifo works in Node.js environments too:
import { Sandbox } from '@lifo-sh/core' ; const sandbox = await Sandbox . create (); // Mount a real directory into the virtual filesystem sandbox . mountNative ( '/mnt/project' , '/path/to/project' , { readOnly: false , fsModule: require ( 'node:fs' ), }); // Now you can work with real files await sandbox . commands . run ( 'ls /mnt/project' );
TypeScript Support Lifo is written in TypeScript and includes full type definitions:
import type { Sandbox , SandboxOptions , CommandResult , RunOptions , SandboxFs , SandboxCommands , } from '@lifo-sh/core' ; const options : SandboxOptions = { persist: true , cwd: '/home/user' , env: { DEBUG: '1' }, }; const sandbox = await Sandbox . create ( options );
TypeScript 5.0+ is recommended for the best development experience.
Browser Requirements Lifo requires a modern browser with support for:
ES2020+ features (async/await, dynamic import, etc.)
Web APIs: fetch, ReadableStream, TextEncoder/TextDecoder
IndexedDB (for persistence)
Supported Browsers Edge and other Chromium-based browsers are also supported.
Vite No special configuration needed! Lifo works out of the box with Vite:
import { defineConfig } from 'vite' ; export default defineConfig ({ // Lifo works without any special config }) ;
Webpack For Webpack, you may need to configure fallbacks for Node.js modules:
module . exports = { resolve: { fallback: { "fs" : false , "path" : false , "crypto" : false , } } };
Next.js Configure Next.js to handle Lifo as a client-side module:
/** @type {import('next').NextConfig} */ const nextConfig = { webpack : ( config ) => { config . resolve . fallback = { ... config . resolve . fallback , fs: false , path: false , }; return config ; }, }; module . exports = nextConfig ;
Then use dynamic imports with ssr: false:
import dynamic from 'next/dynamic' ; const LifoTerminal = dynamic ( () => import ( '../components/LifoTerminal' ), { ssr: false } );
Environment Variables Configure Lifo behavior through sandbox options:
const sandbox = await Sandbox . create ({ env: { HOME: '/home/user' , USER: 'developer' , HOSTNAME: 'lifo' , PATH: '/bin:/usr/bin' , SHELL: '/bin/sh' , // Add custom variables DEBUG: '1' , API_KEY: 'your-key' , } });
Package Extensions Lifo supports installable packages for additional functionality:
lifo-pkg-git Git version control using isomorphic-git
lifo-pkg-ffmpeg FFmpeg for video/audio processing (WebAssembly)
Install packages at runtime:
# Inside Lifo shell lifo install https://example.com/package.tgz # Or programmatically await sandbox.commands.run ( 'lifo install https://example.com/package.tgz' );
Troubleshooting Module Not Found If you get module resolution errors:
// Use the full package path import { Sandbox } from '@lifo-sh/core' ; // Not: import { Sandbox } from '@lifo-sh/core/dist/index.js' ;
IndexedDB Quota Exceeded If you hit storage limits:
// Clear persisted data await sandbox . kernel . persistence . clear (); // Or start fresh without persistence const sandbox = await Sandbox . create ({ persist: false });
TypeScript Errors Ensure your tsconfig.json includes:
{ "compilerOptions" : { "target" : "ES2020" , "module" : "ESNext" , "moduleResolution" : "bundler" , "esModuleInterop" : true , "skipLibCheck" : true } }
Verifying Installation Test your installation with this simple script:
import { Sandbox } from '@lifo-sh/core' ; async function test () { console . log ( 'Creating sandbox...' ); const sandbox = await Sandbox . create (); console . log ( 'Running command...' ); const result = await sandbox . commands . run ( 'echo "Installation successful!"' ); console . log ( result . stdout ); // "Installation successful!\n" console . log ( 'Exit code:' , result . exitCode ); // 0 console . log ( '✓ Lifo is working correctly!' ); } test (). catch ( console . error );
Run it:
Next Steps
Quickstart Guide Build your first Lifo application
Core Concepts Learn about Lifo’s architecture
API Reference Explore the complete API
Examples See real-world usage examples
Getting Help
GitHub Issues Report bugs or request features
Discussions Ask questions and share ideas