@fermion-app/sandbox

Secure isolated code execution SDK. Run untrusted code, build projects, or host services in ephemeral containers.

Installation

npm install @fermion-app/sandbox

Quick Start

import { Sandbox } from '@fermion-app/sandbox'

// Create sandbox
const sandbox = new Sandbox({ apiKey: 'your-api-key' })
await sandbox.create({ shouldBackupFilesystem: false })

// Execute commands
const result = await sandbox.runCommand({
	cmd: 'node',
	args: ['--version']
})
console.log(result.stdout)

// Write and read files
await sandbox.writeFile({
	path: '~/script.js',
	content: 'console.log("Hello World")'
})

const response = await sandbox.getFile('~/script.js')
const content = await response.text()

// Clean up
await sandbox.disconnect()

Key Features

• Isolated containers - Secure Linux environments for code execution
• Real-time streaming - WebSocket-based command output streaming
• File operations - Read/write files with binary support
• Public URLs - Expose ports 3000, 1337, 1338 for web services
• Git support - Clone repositories on container startup
• TypeScript - Full type safety and IntelliSense

Core API

Creating a Sandbox

const sandbox = new Sandbox({ apiKey: 'your-api-key' })

// New container
await sandbox.create({
	shouldBackupFilesystem: false, // Persist filesystem after shutdown
	gitRepoUrl: 'https://github.com/user/repo.git' // Optional
})

// Or connect to existing
await sandbox.fromSnippet('snippet-id')

Running Commands

// Quick commands (< 5 seconds)
const { stdout, stderr } = await sandbox.runCommand({
	cmd: 'ls',
	args: ['-la']
})

// Long-running with streaming
const { stdout, stderr, exitCode } = await sandbox.runStreamingCommand({
	cmd: 'npm',
	args: ['install'],
	onStdout: data => console.log(data),
	onStderr: data => console.error(data)
})

File Operations

// Write file
await sandbox.writeFile({
	path: '~/app.js',
	content: 'console.log("Hello")'
})

// Read file
const response = await sandbox.getFile('~/app.js')
const text = await response.text()
const buffer = await response.arrayBuffer()

Web Services

// Start a server
await sandbox.runStreamingCommand({
	cmd: 'node',
	args: ['server.js']
})

// Get public URL
const url = await sandbox.exposePort(3000)
console.log(`Live at: ${url}`)
// https://abc123-3000.run-code.com

Examples

Run a Node.js Project

const sandbox = new Sandbox({ apiKey: process.env.API_KEY })
await sandbox.create({
	gitRepoUrl: 'https://github.com/user/node-app.git'
})

// Install and build
await sandbox.runStreamingCommand({
	cmd: 'npm',
	args: ['install'],
	onStdout: data => process.stdout.write(data)
})

await sandbox.runCommand({
	cmd: 'npm',
	args: ['run', 'build']
})

// Start server
sandbox.runStreamingCommand({
	cmd: 'npm',
	args: ['start']
})

const url = await sandbox.exposePort(3000)
console.log(`App running at: ${url}`)

API Reference

Constructor

• new Sandbox({ apiKey }) - Initialize client

Methods

• create(options) - Create new container
• fromSnippet(id) - Connect to existing container
• runCommand(options) - Execute command (< 5s)
• runStreamingCommand(options) - Execute with streaming
• writeFile(options) - Write file to container
• getFile(path) - Read file from container
• exposePort(port) - Get public URL for port
• disconnect() - Clean up resources
• isConnected() - Check connection status

File Paths

All paths must start with ~ (home) or /home/damner:

• ~/file.js → /home/damner/file.js
• /home/damner/app/index.js → absolute path
• /home/damner/code/app/index.js → also supported (nested under home)

Supported Ports

Public URLs available for:

• Port 3000
• Port 1337
• Port 1338

Development

npm install    # Install dependencies
npm run build  # Build the package

License

MIT

Support

For issues and questions, visit GitHub Issues.