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 installed on your system, along with a package manager such as npm, yarn, or pnpm.
  • 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 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() {
  // Step 1: Initialize the sandbox with your API key
  const sandbox = new Sandbox({
    apiKey: process.env.FERMION_API_KEY
  })

  try {
    // Step 2: 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)

    // Step 3: 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())

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

    // Step 5: Execute the file
    console.log('\nExecuting hello.js...')
    const output = await sandbox.runCommand({
      cmd: 'node',
      args: ['hello.js']
    })
    console.log('Output:', output.stdout.trim())

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

  } catch (error) {
    console.error('Error:', error.message)
  } finally {
    // Step 7: 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

​
Common Issues

This error occurs when your sandbox initialization is missing the FERMION_API_KEY value.How to fix:
  • Ensure your .env file contains FERMION_API_KEY=your_api_key_here
  • Verify that your .env file is located in your project root
  • If using dotenv, import it before creating the sandbox:
require('dotenv').config()
This typically means the container took too long to start.Possible fixes:
  • Retry after a short delay: the issue may be temporary
  • Check the system status page for ongoing service disruptions
  • If this persists, contact support with your snippetId for analysis
This indicates a network or firewall issue blocking WebSocket traffic.How to fix:
  • Ensure wss:// connections are allowed on your network
  • Check your firewall or proxy configuration
  • If using a corporate VPN, try disabling it temporarily

​
Next Steps

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

Core Concepts

Understand how Fermion Sandboxes are provisioned, managed, and destroyed.

Available Methods

Explore all available methods and advanced configuration options.