> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fermion.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Getting Started with the Fermion Sandbox
> Set up Fermion Sandbox and run your first secure containerized code session.
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](/api-guide/introduction#how-to-get-your-api-key).
* Familiarity with basic **JavaScript or TypeScript** will also be helpful as you follow along with the examples in this guide.
***
## Installation
Install the package with the help of a package manager of your choice
```bash Typescript/Javascript theme={null}
# 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
```
```bash Python theme={null}
# Using pip
pip install fermion_sandbox
# Using pipenv
pipenv install fermion_sandbox
# Using uv
uv add fermion_sandbox
```
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](/api-guide/introduction#how-to-get-your-api-key)
Create a .env file in your project root and add your API key:
```bash theme={null}
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.
```javaScript hello.js theme={null}
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()
```
```python hello.py theme={null}
from fermion_sandbox import Sandbox
import os
def main():
# Initialize the sandbox with your API key
sandbox = Sandbox(api_key=os.getenv("FERMION_API_KEY"))
# Create a new container
print("Creating sandbox...")
snippet_id = sandbox.create(should_backup_filesystem=False) # Files won't persist after disconnect
print(f"Sandbox created! Snippet ID: {snippet_id}")
# Run a simple command
print("\nRunning python3 --version...")
python_version = sandbox.run_command(cmd="python3", args=["--version"])
print("Python version:", python_version.stdout.strip())
# Write a file
print("\nWriting hello.py...")
sandbox.write_file(path="~/hello.py", content='print("Hello from Fermion Sandbox!")')
print("File written")
# Execute the file
print("\nExecuting hello.py...")
output = sandbox.run_command(cmd="python3", args=["hello.py"])
print("Output:", output.stdout.strip())
# Read the file back
print("\nReading hello.py...")
file_response = sandbox.get_file("~/hello.py")
file_content = file_response.text()
print("File contents:", file_content)
# Always clean up
print("\nDisconnecting...")
sandbox.disconnect()
print("Disconnected")
if __name__ == "__main__":
main()
```
## Expected Output
The following code snippet will create a sandbox that executes a simple node.js program. Following is the expected output:
```bash Typescript output theme={null}
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
```
```bash Python output theme={null}
Creating sandbox...
Sandbox created! Snippet ID: abcd-python-1234k
Running python3 --version...
Python version: Python 3.11.6
Writing hello.py...
File written
Executing hello.py...
Output: Hello from Fermion Sandbox!
Reading hello.py...
File contents: print("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.
Explore all available methods for Typescript SDK
Explore all available methods for Python SDK