Back to Blog

Getting Started with HopX: Your First Sandbox in 5 Minutes

Tutorials•Amin Al Ali Al Darwish••5 min read

Getting Started with HopX: Your First Sandbox in 5 Minutes

HopX gives you secure, isolated cloud sandboxes that start in under 100 milliseconds. Each sandbox is a fully-functional Linux VM with root access—perfect for running untrusted code, AI agent workflows, or data processing tasks.

In this guide, you'll create your first sandbox and execute code in it. Let's get started.

Prerequisites

Before you begin, you'll need:

  • A HopX account (sign up at console.hopx.ai)
  • Your API key from the HopX dashboard
  • Python 3.8+ or Node.js 18+

Step 1: Install the SDK

Choose your preferred language:

Python

bash
1
pip install hopx-ai
2
 

JavaScript/TypeScript

bash
1
npm install @hopx-ai/sdk
2
 

Step 2: Set Up Authentication

Export your API key as an environment variable:

bash
1
export HOPX_API_KEY="your-api-key-here"
2
 

Or pass it directly when creating sandboxes (we'll show both methods).

Step 3: Create Your First Sandbox

Python Example

python
1
from hopx_ai import Sandbox
2
 
3
# Create a sandbox using the code-interpreter template
4
sandbox = Sandbox.create(template="code-interpreter")
5
 
6
print(f"Sandbox created: {sandbox.id}")
7
print(f"Status: {sandbox.status}")
8
 

JavaScript Example

javascript
1
import { Sandbox } from '@hopx-ai/sdk';
2
 
3
const sandbox = await Sandbox.create({ template: 'code-interpreter' });
4
 
5
console.log(`Sandbox created: ${sandbox.id}`);
6
console.log(`Status: ${sandbox.status}`);
7
 

That's it! Your sandbox is now running in the cloud.

Step 4: Execute Code

Now let's run some Python code in your sandbox:

Python

python
1
from hopx_ai import Sandbox
2
 
3
with Sandbox.create(template="code-interpreter") as sandbox:
4
    # Execute Python code
5
    result = sandbox.run_code("""
6
import sys
7
print(f"Python version: {sys.version}")
8
print("Hello from HopX!")
9
 
10
# Do some computation
11
numbers = [1, 2, 3, 4, 5]
12
total = sum(numbers)
13
print(f"Sum of {numbers} = {total}")
14
""")
15
16
    print("Output:", result.stdout)
17
 

JavaScript

javascript
1
import { Sandbox } from '@hopx-ai/sdk';
2
 
3
const sandbox = await Sandbox.create({ template: 'code-interpreter' });
4
 
5
try {
6
    const result = await sandbox.runCode(`
7
import sys
8
print(f"Python version: {sys.version}")
9
print("Hello from HopX!")
10
 
11
numbers = [1, 2, 3, 4, 5]
12
total = sum(numbers)
13
print(f"Sum of {numbers} = {total}")
14
`);
15
16
    console.log('Output:', result.stdout);
17
} finally {
18
    await sandbox.kill();
19
}
20
 

Output:

text
1
Python version: 3.11.0
2
Hello from HopX!
3
Sum of [1, 2, 3, 4, 5] = 15
4
 

Step 5: Work with Files

Sandboxes have a full filesystem. You can read and write files:

Python

python
1
from hopx_ai import Sandbox
2
 
3
with Sandbox.create(template="code-interpreter") as sandbox:
4
    # Write a file
5
    sandbox.files.write("/app/data.txt", "Hello, HopX!")
6
7
    # Read it back
8
    content = sandbox.files.read("/app/data.txt")
9
    print(f"File content: {content}")
10
11
    # List directory contents
12
    files = sandbox.files.list("/app")
13
    print(f"Files in /app: {files}")
14
 

JavaScript

javascript
1
import { Sandbox } from '@hopx-ai/sdk';
2
 
3
const sandbox = await Sandbox.create({ template: 'code-interpreter' });
4
 
5
// Write a file
6
await sandbox.files.write('/app/data.txt', 'Hello, HopX!');
7
 
8
// Read it back
9
const content = await sandbox.files.read('/app/data.txt');
10
console.log('File content:', content);
11
 
12
// List directory
13
const files = await sandbox.files.list('/app');
14
console.log('Files:', files);
15
 
16
await sandbox.kill();
17
 

Step 6: Run Shell Commands

Need to install packages or run system commands? Use the commands interface:

Python

python
1
from hopx_ai import Sandbox
2
 
3
with Sandbox.create(template="code-interpreter") as sandbox:
4
    # Install a package
5
    result = sandbox.commands.run("pip install requests")
6
    print(result.stdout)
7
8
    # Run any shell command
9
    result = sandbox.commands.run("ls -la /")
10
    print(result.stdout)
11
 

JavaScript

javascript
1
import { Sandbox } from '@hopx-ai/sdk';
2
 
3
const sandbox = await Sandbox.create({ template: 'code-interpreter' });
4
 
5
// Install a package
6
const pipResult = await sandbox.commands.run('pip install requests');
7
console.log(pipResult.stdout);
8
 
9
// Run any shell command
10
const lsResult = await sandbox.commands.run('ls -la /');
11
console.log(lsResult.stdout);
12
 
13
await sandbox.kill();
14
 

Available Templates

HopX provides pre-built templates for common use cases. The code-interpreter template is recommended for most Python workloads:

TemplateDescriptionPre-installed
code-interpreterRecommended - Full Python data science environmentPython 3.11, pandas, numpy, matplotlib, scikit-learn, requests
nodejsNode.js environmentNode.js 20, npm
goGo developmentGo 1.21 toolchain
rustRust developmentcargo, rustc
javaJava developmentJava 17, Maven

Tip: Use code-interpreter for AI agents and data analysis. It includes the most common packages pre-installed.

What's Next?

You've just created your first HopX sandbox and executed code in it. Here are some next steps:

  1. Build an AI Agent - Connect your sandbox to OpenAI or Claude to create coding assistants
  2. Create Custom Templates - Pre-bake your dependencies for faster startups
  3. Explore Desktop Automation - Use VNC for browser testing and GUI automation

Common Questions

How fast do sandboxes start?

Sandboxes start in approximately 100 milliseconds when using pre-built templates. Custom templates with cached dependencies are similarly fast.

How long can a sandbox run?

By default, sandboxes have a 1-hour timeout. You can extend this or keep them running indefinitely by adjusting the timeout settings.

Is my code isolated from other users?

Yes. Each sandbox runs in its own micro-VM with dedicated kernel, filesystem, and network stack. There's no shared infrastructure between sandboxes.

How much does it cost?

HopX uses pay-per-second billing:

  • Compute: $0.000014/vCPU-second
  • Memory: $0.0000045/GiB-second
  • Free tier: $200 in credits when you sign up

Conclusion

You've learned the basics of HopX:

  • ✅ Installing the SDK
  • ✅ Creating sandboxes
  • ✅ Executing code
  • ✅ Working with files
  • ✅ Running shell commands

Ready to build something amazing? Sign up for free and get $200 in credits to start.

For more details, check out the full documentation.

Related articles

Microsoft Agent Framework with HopX: Secure Code Execution for AI Agents

Build AI agents with Microsoft's new Agent Framework and HopX sandboxes. The unified successor to AutoGen and Semantic Kernel, now with isolated code execution.

Nov 27, 2025•11 min read

Microsoft AutoGen with Isolated Code Execution Using HopX

Build production-ready AutoGen agents with secure code execution. Replace Docker with HopX sandboxes for faster, safer multi-agent conversations that can run Python.

Nov 26, 2025•12 min read

CrewAI Multi-Agent Pipelines with Secure Code Execution

Build production-ready CrewAI agents that execute code safely. Learn how to create multi-agent workflows where each agent can run code in isolated HopX sandboxes.

Nov 26, 2025•13 min read