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

# Overview

> Official JavaScript/TypeScript SDK for HopX - Create and manage cloud sandboxes in Node.js and browsers. Install the SDK, authenticate with your API key, and start creating sandboxes, executing code, managing files, and automating desktop interactions. Complete reference with async/await examples for all SDK methods and classes.

**Version:** 0.1.21+\
**Last Verified:** 2025-01-27\
**Package:** `@hopx-ai/sdk` on [npm](https://www.npmjs.com/package/@hopx-ai/sdk)

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

<Note>
  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.
</Note>

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

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

* **[Installation Guide](/sdk/javascript/installation)** - Install the SDK and set up your environment
* **[Quickstart](/sdk/javascript/quickstart)** - Get your first sandbox running in minutes
* **[API Reference](/sdk/javascript/sandbox)** - Complete class and method documentation

## Related

* [Python SDK](/sdk/python/introduction) - Official Python SDK
* [CLI Reference](/cli/introduction) - Command-line interface for HopX
* [API Reference](/api/introduction) - Raw REST API documentation
* [Core Concepts](/core-concepts/sandboxes/creating) - Learn about sandboxes, execution, and more