Skip to main content
SDK Version: 0.1.21+
Last Verified: 2025-01-27

​
Prerequisites

Before installing the HopX JavaScript SDK, ensure you have:
  • Node.js 18+ (20+ recommended for LTS support)
  • npm, yarn, or pnpm (package manager)
  • HopX API key - Get yours at console.hopx.dev

​
Install with npm

The recommended way to install the HopX JavaScript SDK: 
npm install @hopx-ai/sdk

​
Install with yarn

yarn add @hopx-ai/sdk

​
Install with pnpm

pnpm add @hopx-ai/sdk

​
Install Specific Version

Install a specific version: 
npm install @hopx-ai/sdk@0.1.21

​
Install from Source

For development or to use the latest unreleased version: 
git clone https://github.com/hopx-ai/hopx.git
cd HopX/javascript
npm install
npm run build
Building from source requires Node.js 18+, TypeScript 5.3+, and build tools. See the GitHub repository for detailed development setup instructions.

​
TypeScript Support

TypeScript definitions are included automatically. No additional @types package needed. 
import { Sandbox, ExecutionResult } from '@hopx-ai/sdk';

const sandbox: Sandbox = await Sandbox.create({ template: 'code-interpreter' });
const result: ExecutionResult = await sandbox.runCode('print("Hello")');

​
Verify Installation

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

​
Set Up Authentication

The SDK requires an API key for authentication. You have three options: 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"

# Windows (CMD)
set HOPX_API_KEY=your-API key-here

​
Option 2: Pass API key Directly

Pass the API key when creating a sandbox: 
import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({
  template: 'code-interpreter',
  apiKey: 'your-API key-here'
});

​
Option 3: Configuration File

Create a .env file in your project root: 
# .env
HOPX_API_KEY=your-API key-here
Then load it in your code (requires dotenv package): 
npm install dotenv

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

const sandbox = await Sandbox.create({ template: 'code-interpreter' });
Never commit your API key to version control. Always use environment variables or secure secret management for production applications.

​
Get Your API key

  1. Sign up at console.hopx.dev
  2. Navigate to Settings → API Keys
  3. Create a new API key
  4. Copy the key (you’ll only see it once)
API keys are scoped to your account and have full access to create, manage, and delete sandboxes. Keep them secure.

​
Supported Node.js Versions

The SDK is tested and supported on:
  • Node.js 18.x - Minimum supported version
  • Node.js 20.x - LTS, recommended for production
  • Node.js 22.x - Latest LTS, fully supported

​
Module Systems

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

const sandbox = await Sandbox.create({ template: 'code-interpreter' });
Ensure your package.json has: 
{
  "type": "module"
}

​
CommonJS

const { Sandbox } = require('@hopx-ai/sdk');

(async () => {
  const sandbox = await Sandbox.create({ template: 'code-interpreter' });
})();

​
Dependencies

The SDK has minimal dependencies:
  • node-fetch - HTTP client for API calls (Node.js 18+ has native fetch)
  • ws - WebSocket client for streaming
  • Type definitions included
All dependencies are automatically installed with npm install @hopx-ai/sdk.

​
Browser Support

The SDK can be used in browsers with:
  1. CORS Configuration - Configure your HopX account to allow browser origins
  2. Build Tool - Use a bundler (webpack, Vite, esbuild) to bundle the SDK
  3. API key Security - Never expose API keys in client-side code (use a backend proxy)
Using the SDK directly in browsers requires CORS configuration and exposes your API key. For production browser applications, use a backend proxy instead.

​
Troubleshooting

​
Import Errors

If you get Cannot find module '@hopx-ai/sdk':
  1. Verify Node.js version: node --version (should be 18+)
  2. Check installation: npm list @hopx-ai/sdk
  3. Reinstall: npm install --save @hopx-ai/sdk

​
TypeScript Errors

If TypeScript can’t find types:
  1. Ensure @hopx-ai/sdk is in dependencies (not devDependencies)
  2. Restart your TypeScript server/IDE
  3. Check tsconfig.json includes node_modules in type resolution

​
Authentication Errors

If you get authentication errors:
  1. Verify API key is set: echo $HOPX_API_KEY (Linux/macOS) or echo %HOPX_API_KEY% (Windows)
  2. Check API key is valid at console.hopx.dev
  3. Ensure no extra spaces or quotes in the API key

​
Network Errors

If you encounter network errors:
  1. Check internet connection
  2. Verify firewall allows outbound HTTPS (port 443)
  3. Check if you’re behind a corporate proxy (may need proxy configuration)
For more troubleshooting help, see the Troubleshooting Guide.

​
Next Steps

Once you’ve successfully installed the SDK: