Skip to main content
Fermion Sandbox lets you safely execute untrusted or user-generated code inside secure, containerized Linux environments. This guide walks you through installation, setup, and creating your first sandbox: from installing the SDK to running your first command inside an isolated container.

​
Prerequisites

Before you begin, ensure that your environment meets the following requirements.
  • You’ll need Node.js 18 or higher | Python runtime installed on your system, along with a package manager such as npm, yarn, pnpm, bun for Javascript runtimes or pip or uv for python runtimes.
  • A valid Fermion API key is required for authentication, which you can obtain from your Fermion Dashboard.
  • Familiarity with basic JavaScript or TypeScript will also be helpful as you follow along with the examples in this guide.

​
Installation

1

Install the Package

Install the package with the help of a package manager of your choice
# Using npm
npm install @fermion-app/sandbox

# Using yarn
yarn add @fermion-app/sandbox

# Using bun 
bun install @fermion-app/sandbox

# Using pnpm
pnpm add @fermion-app/sandbox
2

Get Your API Key

Login to your Fermion instructor dashboard and head over to School Setting -> API Access to get your FERMION_API_KEY. Learn more on how to get your Fermion API key
3

Set Up Environment Variables

Create a .env file in your project root and add your API key:
FERMION_API_KEY=your_api_key_here
Never commit API keys to version control. Always load them via environment variables or secure secret management systems.

​
Creating your first Sandbox

Let’s walk through a complete example of creating, running, and cleaning up a sandbox. This example shows how to execute a Node.js script securely in the cloud. 
import { Sandbox } from '@fermion-app/sandbox'

async function main() {
  // Initialize the sandbox with your API key
  const sandbox = new Sandbox({
    apiKey: process.env.FERMION_API_KEY
  })

  try {
    // Create a new container
    console.log('Creating sandbox...')
    const snippetId = await sandbox.create({
      shouldBackupFilesystem: false // Files won't persist after disconnect
    })
    console.log('Sandbox created! Snippet ID:', snippetId)

    // Run a simple command
    console.log('\nRunning node --version...')
    const nodeVersion = await sandbox.runCommand({
      cmd: 'node',
      args: ['--version']
    })
    console.log('Node version:', nodeVersion.stdout.trim())

    // Write a file
    console.log('\nWriting hello.js...')
    await sandbox.writeFile({
      path: '/home/damner/hello.js',
      content: 'console.log("Hello from Fermion Sandbox!")'
    })
    console.log('File written')

    // Execute the file (~/ works in commands, shell expands it)
    console.log('\nExecuting hello.js...')
    const output = await sandbox.runCommand({
      cmd: 'node',
      args: ['~/hello.js']
    })
    console.log('Output:', output.stdout.trim())

    // Read the file back
    console.log('\nReading hello.js...')
    const fileResponse = await sandbox.getFile('/home/damner/hello.js')
    const fileContent = await fileResponse.text()
    console.log('File contents:', fileContent)

  } catch (error) {
    console.error('Error:', error.message)
  } finally {
    // Always clean up
    console.log('\nDisconnecting...')
    await sandbox.disconnect()
    console.log('Disconnected')
  }
}

main()

​
Expected Output

The following code snippet will create a sandbox that executes a simple node.js program. Following is the expected output: 
Creating sandbox...
Sandbox created! Snippet ID: abc123xyz

Running node --version...
Node version: v20.11.0

Writing hello.js...
File written

Executing hello.js...
Output: Hello from Fermion Sandbox!

Reading hello.js...
File contents: console.log("Hello from Fermion Sandbox!")

Disconnecting...
Disconnected

​
Next Steps

Now that you’ve successfully run your first sandbox, you’re ready to explore more advanced concepts and integrations.

Typescript SDK

Explore all available methods for Typescript SDK

Python SDK

Explore all available methods for Python SDK