@fermion-app/sandbox

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

Installation

``bash
npm install @fermion-app/sandbox
`

Quick Start

`typescript
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

$3

`typescript
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')
`

$3

`typescript
// 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)
})
`

$3

`typescript
// 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()
`

$3

`typescript
// 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

$3

`typescript
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

$3

- new Sandbox({ apiKey }) - Initialize client

$3

- 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

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

License

MIT

Support

For issues and questions, visit GitHub Issues.