Getting Started with HopX: Your First Sandbox in 5 Minutes

Q: 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

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

from hopx_ai import Sandbox
 
# Create a sandbox using the code-interpreter template
sandbox = Sandbox.create(template="code-interpreter")
 
print(f"Sandbox created: {sandbox.id}")
print(f"Status: {sandbox.status}")
 

JavaScript Example

javascript

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

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

from hopx_ai import Sandbox
 
with Sandbox.create(template="code-interpreter") as sandbox:
    # Execute Python code
    result = sandbox.run_code("""
import sys
print(f"Python version: {sys.version}")
print("Hello from HopX!")
 
# Do some computation
numbers = [1, 2, 3, 4, 5]
total = sum(numbers)
print(f"Sum of {numbers} = {total}")
""")
    
    print("Output:", result.stdout)
 

JavaScript

javascript

import { Sandbox } from '@hopx-ai/sdk';
 
const sandbox = await Sandbox.create({ template: 'code-interpreter' });
 
try {
    const result = await sandbox.runCode(`
import sys
print(f"Python version: {sys.version}")
print("Hello from HopX!")
 
numbers = [1, 2, 3, 4, 5]
total = sum(numbers)
print(f"Sum of {numbers} = {total}")
`);
    
    console.log('Output:', result.stdout);
} finally {
    await sandbox.kill();
}
 

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

from hopx_ai import Sandbox
 
with Sandbox.create(template="code-interpreter") as sandbox:
    # Write a file
    sandbox.files.write("/app/data.txt", "Hello, HopX!")
    
    # Read it back
    content = sandbox.files.read("/app/data.txt")
    print(f"File content: {content}")
    
    # List directory contents
    files = sandbox.files.list("/app")
    print(f"Files in /app: {files}")
 

JavaScript

javascript

import { Sandbox } from '@hopx-ai/sdk';
 
const sandbox = await Sandbox.create({ template: 'code-interpreter' });
 
// Write a file
await sandbox.files.write('/app/data.txt', 'Hello, HopX!');
 
// Read it back
const content = await sandbox.files.read('/app/data.txt');
console.log('File content:', content);
 
// List directory
const files = await sandbox.files.list('/app');
console.log('Files:', files);
 
await sandbox.kill();
 

Step 6: Run Shell Commands

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

Python

python

from hopx_ai import Sandbox
 
with Sandbox.create(template="code-interpreter") as sandbox:
    # Install a package
    result = sandbox.commands.run("pip install requests")
    print(result.stdout)
    
    # Run any shell command
    result = sandbox.commands.run("ls -la /")
    print(result.stdout)
 

JavaScript

javascript

import { Sandbox } from '@hopx-ai/sdk';
 
const sandbox = await Sandbox.create({ template: 'code-interpreter' });
 
// Install a package
const pipResult = await sandbox.commands.run('pip install requests');
console.log(pipResult.stdout);
 
// Run any shell command
const lsResult = await sandbox.commands.run('ls -la /');
console.log(lsResult.stdout);
 
await sandbox.kill();
 

Available Templates

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

Template	Description	Pre-installed
`code-interpreter`	Recommended - Full Python data science environment	Python 3.11, pandas, numpy, matplotlib, scikit-learn, requests
`nodejs`	Node.js environment	Node.js 20, npm
`go`	Go development	Go 1.21 toolchain
`rust`	Rust development	cargo, rustc
`java`	Java development	Java 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:

Build an AI Agent - Connect your sandbox to OpenAI or Claude to create coding assistants
Create Custom Templates - Pre-bake your dependencies for faster startups
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.

Getting Started with HopX: Your First Sandbox in 5 Minutes

Getting Started with HopX: Your First Sandbox in 5 Minutes

Prerequisites

Step 1: Install the SDK

Python

JavaScript/TypeScript

Step 2: Set Up Authentication

Step 3: Create Your First Sandbox

Python Example

JavaScript Example

Step 4: Execute Code

Python

JavaScript

Step 5: Work with Files

Python

JavaScript

Step 6: Run Shell Commands

Python

JavaScript

Available Templates

What's Next?

Common Questions

How fast do sandboxes start?

How long can a sandbox run?

Is my code isolated from other users?

How much does it cost?

Conclusion

Related articles

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

Microsoft AutoGen with Isolated Code Execution Using HopX

CrewAI Multi-Agent Pipelines with Secure Code Execution

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

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

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

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

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

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

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

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