Skip to main content
Version: 0.1.21+
Last Verified: 2025-01-27
Package: @hopx-ai/sdk on npm

​
What is the JavaScript SDK?

The HopX JavaScript SDK provides a modern, type-safe interface for creating and managing cloud sandboxes from Node.js applications, TypeScript projects, or browser environments. Build AI agents, run untrusted code securely, execute tests in isolation, or process data with rich output capture—all with async/await and full TypeScript support. The SDK is a thin wrapper around the HopX REST API that handles authentication, request formatting, error translation, and response parsing automatically, giving you a better developer experience than working with the raw API.

​
Target Audience

This SDK is designed for:
  • Backend Node.js developers using Node.js 18+ or 20+
  • TypeScript developers who want full type safety and IDE autocomplete
  • Frontend developers building browser-based tools (with CORS configuration)
  • Full-stack engineers working with JavaScript/TypeScript ecosystems
  • Automation engineers building Node.js-based workflows

​
Supported Runtimes

  • Node.js: 18.x, 20.x, 22.x (LTS versions recommended)
  • TypeScript: 4.5+ (full type definitions included)
  • Browsers: Modern browsers with ES2020+ support (with CORS setup)
  • Package Managers: npm, yarn, pnpm

​
When to Use the SDK vs CLI vs Raw API

​
Use the JavaScript SDK when:

  • ✅ You’re building Node.js or TypeScript applications
  • ✅ You want TypeScript type definitions and IDE autocomplete
  • ✅ You prefer Promise-based async/await patterns
  • ✅ You need automatic error handling and retries
  • ✅ You’re working with JavaScript objects and JSON
  • ✅ You want tree-shakeable imports

​
Use the CLI when:

  • ✅ You prefer command-line workflows
  • ✅ You’re scripting or automating from shell
  • ✅ You want quick one-off operations
  • ✅ You’re working in CI/CD pipelines
  • ✅ You need interactive terminal sessions

​
Use the Raw API when:

  • ⚠️ You’re building in a non-JavaScript language
  • ⚠️ You need fine-grained control over HTTP requests
  • ⚠️ You’re integrating with existing HTTP client libraries (axios, fetch wrappers)
  • ⚠️ You need custom retry logic or connection pooling
The SDK is a thin wrapper around the HopX REST API. It handles authentication, request formatting, error translation, and response parsing automatically. For most JavaScript/TypeScript use cases, the SDK provides a better developer experience.

​
Architecture

The SDK is built with:
  • TypeScript - Full type definitions for all APIs
  • ES Modules - Modern import/export syntax
  • CommonJS - Also supports require() for compatibility
  • Promise-based - All operations return Promises (async/await friendly)

​
Core Capabilities

The JavaScript SDK provides:
  • Sandbox Management - Create, connect, list, and delete sandboxes
  • Code Execution - Run Python, JavaScript, Bash, Go, and more
  • Rich Outputs - Capture matplotlib plots, pandas DataFrames, images
  • File Operations - Read, write, list, upload, download files
  • Command Execution - Run shell commands synchronously or in background
  • Environment Variables - Set, get, update, and clear environment variables
  • Process Management - List and manage running processes
  • Cache Management - Monitor and clear execution result cache
  • Desktop Automation - VNC access, mouse/keyboard control (Premium)
  • Template Building - Create custom sandbox environments
  • WebSocket Streaming - Real-time terminal and code execution streaming

​
Quick Example

import { Sandbox } from '@hopx-ai/sdk';

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

// Execute code
const result = await sandbox.runCode('print("Hello from HopX!")');
console.log(result.stdout);  // "Hello from HopX!\n"

// Cleanup
await sandbox.kill();

​
Next Steps