Skip to main content
Goal: Create a sandbox, execute code, and see the output in under 5 minutes.
Prerequisites: Node.js 18+, npm, HopX API key
Time: ~5 minutes This quickstart gets you from zero to your first successful code execution. Follow these steps in order.

​
What You’ll Learn

In this quickstart, you’ll learn how to:
  • Install and verify the JavaScript SDK
  • Set up API key authentication
  • Create a sandbox from a template
  • Execute code in the sandbox using async/await
  • Access execution results and output
  • Clean up sandboxes properly

​
Step 1: Install the SDK

npm install @hopx-ai/sdk

​
Step 1.5: Verify Installation

Verify the SDK is installed correctly: 
node -e "const { Sandbox } = require('@hopx-ai/sdk'); console.log('HopX SDK installed successfully')"
Expected output: HopX SDK installed successfully

​
Step 2: Set Your API key

Set the HOPX_API_KEY environment variable: 
# Linux/macOS
export HOPX_API_KEY="your-API key-here"

# Windows (PowerShell)
$env:HOPX_API_KEY="your-API key-here"
Get your API key from console.hopx.dev → Settings → API Keys

​
Step 3: Create and Run Your First Sandbox

Create a file hello-HopX.js: 
import { Sandbox } from '@hopx-ai/sdk';

async function main() {
  // Create a sandbox (~100ms)
  const sandbox = await Sandbox.create({ template: 'code-interpreter' });

  // Execute code in the sandbox
  const result = await sandbox.runCode('print("Hello from HopX!")');

  // Print the output
  console.log(result.stdout);

  // Cleanup - delete the sandbox
  await sandbox.kill();
}

main().catch(console.error);

​
Step 4: Run It

node hello-HopX.js
If using ES modules, ensure your package.json has "type": "module", or use .mjs extension.

​
Expected Output

Hello from HopX!

​
What Just Happened?

  1. Sandbox.create() - Created a new sandbox from the code-interpreter template (Python environment)
  2. sandbox.runCode() - Executed Python code in the sandbox
  3. result.stdout - Retrieved the standard output from code execution
  4. sandbox.kill() - Deleted the sandbox to free resources

​
Next Steps

Now that you have a working setup, explore more:

​
Quickstart Variations

For more advanced quickstart examples including error handling, environment variables, and TypeScript patterns, see the Advanced Quickstart Guide (coming soon).

​
Troubleshooting

“API key required” error?
  • Verify HOPX_API_KEY is set: echo $HOPX_API_KEY
  • Get your key at console.hopx.dev
“Template not found” error?
  • Use template: 'code-interpreter' (default Python template)
  • See Available Templates for options
“Cannot find module” error?
  • Run npm install @hopx-ai/sdk
  • Check Node.js version: node --version (should be 18+)
Network timeout?
  • Check internet connection
  • Verify firewall allows HTTPS (port 443)
For more help, see the Troubleshooting Guide.