Hopx Cloud Sandboxes

Hopx provides public templates like code-interpreter (data science focused) and base (minimal Ubuntu). You can build custom reusable templates using the Template class to define images, file copies, commands, and working directories.

import { Template, waitForPort } from '@hopx-ai/sdk';

const template = new Template()
  .fromNodeImage('20')
  .copy('package.json', '/app/package.json')
  .copy('src/', '/app/src/')
  .runCmd('cd /app && npm install')
  .setWorkdir('/app')
  .setStartCmd('node src/index.js', waitForPort(3000));

const result = await Template.build(template, {
  name: 'my-app',
  apiKey: 'your-api-key'
});

const sandbox = await Sandbox.create({ templateId: result.templateID });

Install the official Python SDK for Hopx.ai using pip to access secure, isolated cloud sandboxes for code execution.

pip install hopx-ai

Methods for authenticating with private registries have been renamed to clarify their purpose. Use fromPrivateImage instead of fromImage when providing credentials, and use the updated GCP/AWS specific methods.

```typescript
// ✅ After
template.fromPrivateImage('registry.example.com/myimage:tag', {
  username: 'user',
  password: 'pass'
});

# ✅ After
template.from_private_image('registry.example.com/myimage:tag', RegistryAuth(
    username='user',
    password='pass'
))

Renamed Cloud Registry Methods:

• fromGCPRegistry() → fromGCPPrivateImage()
• fromAWSRegistry() → fromAWSPrivateImage()
• from_gcp_registry() → from_gcp_private_image()
• from_aws_registry() → from_aws_private_image()

The FROM step type has been removed. You must now specify base images using either the Template constructor or specific helper methods like fromPythonImage() (JS/TS) or from_python_image() (Python).

// ✅ After - Base image in constructor
const template = new Template('python:3.11')
  .runCmd('pip install numpy');

// Or using helper methods
const template = new Template()
  .fromPythonImage('3.11')
  .runCmd('pip install numpy');

# ✅ After - Base image in constructor
template = Template(from_image='python:3.11').run_cmd('pip install numpy')

# Or using helper methods
template = Template().from_python_image('3.11').run_cmd('pip install numpy')

Install the @hopx-ai/sdk package using npm to access the JavaScript/TypeScript SDK.

npm install @hopx-ai/sdk

To run the template building tests for the JavaScript/TypeScript SDK, you must first install the dependencies and build the SDK from the javascript/ directory.

Prerequisites

1. Navigate to the javascript/ directory.
2. Install npm dependencies.
3. Build the SDK.

cd javascript/

# Install dependencies
npm install

# Build the SDK
npm run build

To verify that WebSocket authentication and error handling are working correctly in your environment, you can run the comprehensive test suite provided in the examples directory. This requires a valid Hopx API key.

Prerequisites:

• Python 3.8+
• websockets library >= 12.0
• A valid HOPX_API_KEY environment variable.

Execution:

export HOPX_API_KEY="your_api_key"
python examples/test_websocket_auth.py

Install the hopx-ai package using pip to access the Python SDK for managing cloud sandboxes.

pip install hopx-ai

You can install the Hopx CLI using a one-line installer that automatically detects your OS and Python version.

Quick Install

curl -fsSL https://get.hopx.ai/install.sh | bash

Installation Modes

If you are running the script locally or want to specify a method, use the --mode flag:

• pip (Default): Standard installation via pip.
• pipx: Installs the CLI in an isolated environment.
• git: Installs the development version directly from GitHub.

Environment Variables

• HOPX_INSTALL_MODE: Set to pip, pipx, or git to control the installation method.
• HOPX_DRY_RUN: Set to true to perform a dry run without making any changes.

Post-Installation Verification

After installation, verify it works by running:

hopx --version
hopx --help
hopx run "print('Hello from Hopx!')"

To get started, import Sandbox from @hopx-ai/sdk and use Sandbox.create() to initialize a new environment. You can specify a template (like code-interpreter) and provide an apiKey. You can also use the HOPX_API_KEY environment variable instead of passing it explicitly. Once created, use runCode() to execute scripts and kill() to destroy the sandbox and stop billing.

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

const sandbox = await Sandbox.create({
  template: 'code-interpreter',
  apiKey: 'your-api-key'  // or set HOPX_API_KEY environment variable
});

const result = await sandbox.runCode(`
console.log('Node.js', process.version);
console.log('Hello from Hopx!');
`);

console.log(result.stdout);
await sandbox.kill();