Skip to main content
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

Run the interactive setup wizard: 
hopx init
The wizard will:
  1. Guide you through browser-based OAuth login
  2. Help you create an API key
  3. Configure default settings
  4. 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: