Installation

​

Prerequisites

• 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

npm install @hopx-ai/sdk

​

Install with yarn

yarn add @hopx-ai/sdk

​

Install with pnpm

pnpm add @hopx-ai/sdk

​

Install Specific Version

npm install @hopx-ai/sdk@0.1.21

​

Install from Source

git clone https://github.com/hopx-ai/hopx.git
cd HopX/javascript
npm install
npm run build

​

TypeScript Support

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

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

​

Set Up Authentication

​

Option 1: Environment Variable (Recommended)

# 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

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

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

​

Option 3: Configuration File

# .env
HOPX_API_KEY=your-API key-here

npm install dotenv

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

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

​

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)

​

Supported Node.js Versions

• 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

​

ES Modules (Recommended)

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

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

{
  "type": "module"
}

​

CommonJS

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

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

​

Dependencies

• node-fetch - HTTP client for API calls (Node.js 18+ has native fetch)
• ws - WebSocket client for streaming
• Type definitions included

​

Browser Support

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)

​

Troubleshooting

​

Import Errors

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

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

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

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)

​

Related

• JavaScript SDK Quickstart - Get started with the SDK
• [API key Management](/API key) - Learn about API key security
• Sandbox Class Reference - Complete SDK reference

​

Next Steps

• Quickstart Guide - Create your first sandbox and run code
• API Reference - Explore the full SDK API
• CLI Installation - Install the HopX CLI