Quickstart - Hopx Documentation

Get up and running with the HopX CLI in 5 minutes. This guide walks you through installation, authentication, creating your first sandbox, executing code, and managing files.

What You’ll Learn

In this quickstart, you’ll learn how to:

Install the HopX CLI
Authenticate with your API key
Create your first sandbox
Execute code in multiple languages
Manage files in sandboxes
Clean up sandboxes

Prerequisites

HopX API key (get one here if you don’t have it)
Python 3.12+ installed
Terminal access

Step 1: Install the CLI

Install the CLI using the quick install script:

curl -fsSL https://raw.githubusercontent.com/hopx-ai/hopx/main/cli/scripts/install.sh | bash

Expected Output:

✓ HopX CLI installed successfully
✓ Version: 0.1.2
✓ Run 'hopx init' to get started

Verify installation:

hopx --version

Expected Output:

hopx-cli 0.1.2

Step 2: Authenticate

Option 1: Interactive Setup (Recommended)

Run the interactive setup wizard:

hopx init

The wizard will:

Guide you through browser-based OAuth login
Help you create an API key
Configure default settings
Test your connection

Option 2: Manual Authentication

Authenticate manually:

# Browser login
hopx auth login

# Create API key
hopx auth keys create --name "my-key"

# Verify authentication
hopx auth status

Expected Output:

✓ Authenticated
✓ API key: hopx_live_... (configured)

Option 3: Environment Variable

Set your API key as an environment variable:

export HOPX_API_KEY="hopx_live_..."

Get your API key at console.hopx.dev.

Step 3: Create Your First Sandbox

Create a sandbox from a pre-built template:

hopx sandbox create --template python

Expected Output:

✓ Sandbox created: sb_abc123
✓ Status: running
✓ Template: python

List your sandboxes:

hopx sandbox list

Expected Output:

┌──────────────────┬─────────┬────────────┐
│ ID               │ Status  │ Template   │
├──────────────────┼─────────┼────────────┤
│ sb_abc123        │ running │ python     │
└──────────────────┴─────────┴────────────┘

Step 4: Execute Code

Execute Python code in your sandbox:

hopx run "print('Hello, World!')"

Expected Output:

Hello, World!

Execute code from a file:

# Create a local file
echo "print('Hello from file!')" > script.py

# Execute from file
hopx run -f script.py

Expected Output:

Hello from file!

Execute JavaScript:

hopx run "console.log('Hello from JavaScript!')" -l javascript

Expected Output:

Hello from JavaScript!

Execute Bash:

hopx run "echo 'Hello from Bash!'" -l bash

Expected Output:

Hello from Bash!

Step 5: Manage Files

Write a file to your sandbox:

hopx files write sb_abc123 /app/data.txt "Hello, World!"

Expected Output:

✓ File written: /app/data.txt

Read the file:

hopx files read sb_abc123 /app/data.txt

Expected Output:

Hello, World!

List files in a directory:

hopx files list sb_abc123 /app/

Expected Output:

┌──────────────┬──────┬─────────────────────┐
│ Name         │ Size │ Modified            │
├──────────────┼──────┼─────────────────────┤
│ data.txt     │ 13   │ 2025-01-27 10:00:00 │
└──────────────┴──────┴─────────────────────┘

Upload a local file:

# Create local file
echo "Local content" > local.txt

# Upload to sandbox
hopx files upload sb_abc123 ./local.txt /app/uploaded.txt

Expected Output:

✓ File uploaded: /app/uploaded.txt

Download a file:

hopx files download sb_abc123 /app/data.txt ./downloaded.txt

Expected Output:

✓ File downloaded: ./downloaded.txt

Step 6: Run Shell Commands

Run shell commands in your sandbox:

hopx cmd run sb_abc123 "ls -la /app"

Expected Output:

total 16
drwxr-xr-x 2 user user 4096 Jan 27 10:00 .
drwxr-xr-x 3 user user 4096 Jan 27 10:00 ..
-rw-r--r-- 1 user user   13 Jan 27 10:00 data.txt
-rw-r--r-- 1 user user   14 Jan 27 10:00 uploaded.txt

Install packages:

hopx cmd run sb_abc123 "pip install requests"

Expected Output:

Collecting requests
  Downloading requests-2.31.0-py3-none-any.whl (62 kB)
...
Successfully installed requests-2.31.0

Step 7: Manage Environment Variables

Set environment variables:

hopx env set sb_abc123 API_KEY=secret123 DEBUG=true

Expected Output:

✓ Environment variables set

List environment variables:

hopx env list sb_abc123

Expected Output:

┌───────────┬─────────────┐
│ Variable  │ Value       │
├───────────┼─────────────┤
│ API_KEY   │ secret123   │
│ DEBUG     │ true        │
└───────────┴─────────────┘

Get a specific variable:

hopx env get sb_abc123 API_KEY

Expected Output:

secret123

Step 8: Clean Up

Kill your sandbox when done:

hopx sandbox kill sb_abc123

Expected Output:

✓ Sandbox killed: sb_abc123

Or pause it to preserve state:

hopx sandbox pause sb_abc123

Expected Output:

✓ Sandbox paused: sb_abc123

Resume later:

hopx sandbox resume sb_abc123

Expected Output:

✓ Sandbox resumed: sb_abc123

Next Steps

Now that you’ve completed the quickstart, explore more CLI features:

Sandbox Management - Complete sandbox lifecycle management
Code Execution - Execute code in multiple languages
File Operations - Advanced file management
Shell Commands - Run system commands
Environment Variables - Manage environment configuration
Templates - List and build custom templates
Configuration - Configure CLI settings and profiles

CLI Overview - Learn about CLI features
CLI Installation - Detailed installation guide
Python SDK Quickstart - Get started with Python SDK
JavaScript SDK Quickstart - Get started with JavaScript SDK

​What You’ll Learn

​Prerequisites

​Step 1: Install the CLI

​Step 2: Authenticate

​Option 1: Interactive Setup (Recommended)

​Option 2: Manual Authentication

​Option 3: Environment Variable

​Step 3: Create Your First Sandbox

​Step 4: Execute Code

​Step 5: Manage Files

​Step 6: Run Shell Commands

​Step 7: Manage Environment Variables

​Step 8: Clean Up

​Next Steps

​Related

What You’ll Learn

Prerequisites

Step 1: Install the CLI

Step 2: Authenticate

Option 1: Interactive Setup (Recommended)

Option 2: Manual Authentication

Option 3: Environment Variable

Step 3: Create Your First Sandbox

Step 4: Execute Code

Step 5: Manage Files

Step 6: Run Shell Commands

Step 7: Manage Environment Variables

Step 8: Clean Up

Next Steps

Related