> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the HopX JavaScript SDK and set up your development environment. Get started with the official JavaScript/TypeScript SDK for HopX, install via npm, configure API keys, and verify installation. Learn system requirements, installation methods, and troubleshooting tips. Includes installation examples for Node.js and browser environments.

**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](https://console.hopx.dev)

## Install with npm

The recommended way to install the HopX JavaScript SDK:

```bash theme={null}
npm install @hopx-ai/sdk
```

## Install with yarn

```bash theme={null}
yarn add @hopx-ai/sdk
```

## Install with pnpm

```bash theme={null}
pnpm add @hopx-ai/sdk
```

## Install Specific Version

Install a specific version:

```bash theme={null}
npm install @hopx-ai/sdk@0.1.21
```

## Install from Source

For development or to use the latest unreleased version:

```bash theme={null}
git clone https://github.com/hopx-ai/hopx.git
cd HopX/javascript
npm install
npm run build
```

<Note>
  Building from source requires Node.js 18+, TypeScript 5.3+, and build tools. See the [GitHub repository](https://github.com/hopx-ai/HopX) for detailed development setup instructions.
</Note>

## TypeScript Support

TypeScript definitions are included automatically. No additional `@types` package needed.

```typescript theme={null}
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:

```bash theme={null}
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:

### Option 1: Environment Variable (Recommended)

Set the `HOPX_API_KEY` environment variable:

```bash theme={null}
# 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:

```typescript theme={null}
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:

```bash theme={null}
# .env
HOPX_API_KEY=your-API key-here
```

Then load it in your code (requires `dotenv` package):

```bash theme={null}
npm install dotenv
```

```typescript theme={null}
import 'dotenv/config';
import { Sandbox } from '@hopx-ai/sdk';

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

<Warning>
  Never commit your API key to version control. Always use environment variables or secure secret management for production applications.
</Warning>

## Get Your API key

1. Sign up at [console.hopx.dev](https://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)

<Note>
  API keys are scoped to your account and have full access to create, manage, and delete sandboxes. Keep them secure.
</Note>

## 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

### ES Modules (Recommended)

```typescript theme={null}
import { Sandbox } from '@hopx-ai/sdk';

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

Ensure your `package.json` has:

```json theme={null}
{
  "type": "module"
}
```

### CommonJS

```javascript theme={null}
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)

<Warning>
  Using the SDK directly in browsers requires CORS configuration and exposes your API key. For production browser applications, use a backend proxy instead.
</Warning>

## 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](https://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](/sdk/javascript/troubleshooting).

## Related

* **[JavaScript SDK Quickstart](/sdk/javascript/quickstart)** - Get started with the SDK
* **\[API key Management]\(/API key)** - Learn about API key security
* **[Sandbox Class Reference](/sdk/javascript/sandbox)** - Complete SDK reference

## Next Steps

Once you've successfully installed the SDK:

* **[Quickstart Guide](/sdk/javascript/quickstart)** - Create your first sandbox and run code
* **[API Reference](/sdk/javascript/sandbox)** - Explore the full SDK API
* **[CLI Installation](/cli/installation)** - Install the HopX CLI