Skip to main content

​
Get Started in 3 Steps

This guide will walk you through creating your first Lifo sandbox and running commands both programmatically and in a visual terminal.
1

Install Lifo

Install the core package via npm, yarn, or pnpm:
npm install @lifo-sh/core
2

Create Your First Sandbox

Create a simple script to interact with Lifo programmatically:
import { Sandbox } from '@lifo-sh/core';

// Create a sandbox instance
const sandbox = await Sandbox.create();

// Run a command
const result = await sandbox.commands.run('echo "Hello, Lifo!"');
console.log(result.stdout); // "Hello, Lifo!\n"
console.log(result.exitCode); // 0
The Sandbox.create() method handles all initialization: kernel boot, VFS setup, command registry, and shell creation.
3

Work with the Filesystem

Use the filesystem API to read and write files:
// Write a file
await sandbox.fs.writeFile('/tmp/greeting.txt', 'Hello from Lifo!');

// Read it back
const content = await sandbox.fs.readFile('/tmp/greeting.txt');
console.log(content); // "Hello from Lifo!"

// Create a directory
await sandbox.fs.mkdir('/tmp/mydir', { recursive: true });

// List directory contents
const files = await sandbox.fs.readdir('/tmp');
console.log(files); // [{ name: 'greeting.txt', type: 'file' }, ...]

​
Running Commands

Lifo supports all the Unix shell features you’re familiar with:

​
Basic Commands

// List files
await sandbox.commands.run('ls -la /home/user');

// Search with grep
await sandbox.commands.run('grep "pattern" /etc/profile');

// Text processing
await sandbox.commands.run('cat /etc/passwd | wc -l');

​
Pipes and Redirects

// Pipe commands together
await sandbox.commands.run('ls /etc | grep profile | sort');

// Redirect output to a file
await sandbox.commands.run('echo "hello" > /tmp/output.txt');

// Append to a file
await sandbox.commands.run('date >> /tmp/log.txt');

​
Command Options

// Capture output
const result = await sandbox.commands.run('ls /etc', {
  cwd: '/home/user',  // Working directory
  env: { DEBUG: '1' }, // Environment variables
  timeout: 5000,       // Timeout in milliseconds
  onStdout: (data) => console.log('stdout:', data),
  onStderr: (data) => console.log('stderr:', data),
});

console.log(result.stdout);
console.log(result.stderr);
console.log(result.exitCode);

​
Visual Terminal Mode

To embed an interactive terminal in your web application:
1

Install UI Package

npm
npm install @lifo-sh/ui
2

Create Terminal Element

Add a container element to your HTML:
<div id="terminal" style="width: 800px; height: 600px;"></div>
3

Initialize Terminal

import { Terminal } from '@lifo-sh/ui';
import { Sandbox } from '@lifo-sh/core';

// Create terminal UI
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!
// Users can type commands directly
With persist: true, the filesystem state is automatically saved to IndexedDB and restored on reload.

​
Node.js Compatibility

Run JavaScript files using the built-in Node.js compatibility layer: 
// Write a Node.js script
await sandbox.fs.writeFile('/tmp/script.js', `
  const fs = require('fs');
  const path = require('path');
  
  // Write a file
  fs.writeFileSync('/tmp/data.txt', 'Hello from Node!');
  
  // Read it back
  const content = fs.readFileSync('/tmp/data.txt', 'utf-8');
  console.log(content);
  
  // Use path utilities
  console.log(path.join('/tmp', 'data.txt'));
`);

// Execute the script
const result = await sandbox.commands.run('node /tmp/script.js');
console.log(result.stdout);
// Output:
// Hello from Node!
// /tmp/data.txt
Lifo supports 15 Node.js standard library modules: fs, path, buffer, events, util, os, process, http, child_process, stream, url, timers, crypto, console, and more.

​
Example: File Processing Pipeline

Here’s a practical example that combines multiple features: 
import { Sandbox } from '@lifo-sh/core';

const sandbox = await Sandbox.create();

// Create sample data
const data = ['apple', 'banana', 'cherry', 'date', 'elderberry'];
await sandbox.fs.writeFile('/tmp/fruits.txt', data.join('\n'));

// Process with Unix commands
const result = await sandbox.commands.run(`
  cat /tmp/fruits.txt | 
  grep -v "banana" | 
  sort -r | 
  head -n 3 > /tmp/result.txt
`);

// Read the result
const output = await sandbox.fs.readFile('/tmp/result.txt');
console.log(output);
// Output:
// date
// cherry
// apple

​
Next Steps

Installation Guide

Learn about different installation options and environment setup

Core Concepts

Understand Lifo’s architecture and design principles

Filesystem Operations

Deep dive into VFS operations and file handling

API Reference

Explore the complete API documentation

​
Common Patterns

​
Working with Binary Files

// Write binary data
const binaryData = new Uint8Array([0x89, 0x50, 0x4E, 0x47]);
await sandbox.fs.writeFile('/tmp/image.png', binaryData);

// Read binary data
const data = await sandbox.fs.readFile('/tmp/image.png', null);
console.log(data); // Uint8Array

​
Environment Variables

// Access environment variables
const home = sandbox.env.HOME;
const user = sandbox.env.USER;

// Set environment for a command
await sandbox.commands.run('echo $MY_VAR', {
  env: { MY_VAR: 'custom value' }
});

​
Working Directory

// Get current working directory
console.log(sandbox.cwd); // "/home/user"

// Change working directory
sandbox.cwd = '/tmp';

// Or use cwd option for specific commands
await sandbox.commands.run('pwd', { cwd: '/etc' });
Need help? Check out our GitHub repository or open an issue.

Build docs developers (and LLMs) love

Get started for freeTalk to us