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

# Quickstart

> Get your first sandbox running with the HopX API in minutes. Complete quickstart guide for using the HopX REST API to create sandboxes, execute code, manage files, and clean up resources. Learn authentication, make your first API call, and understand API response formats. Includes curl examples and response handling.

Get up and running with the HopX API in minutes. This quickstart walks you through creating your first sandbox, executing code, and cleaning up.

## What You'll Learn

In this quickstart, you'll learn how to:

* Authenticate with the HopX API using API keys
* Create sandboxes using the Control Plane API
* Execute code using the VM Agent API
* Handle API responses and extract results
* Delete sandboxes to free resources
* Use common API patterns and variations

## Prerequisites

Before you begin, you'll need:

* An API key from [console.hopx.dev](https://console.hopx.dev)
* `curl` installed (or any HTTP client)
* Basic familiarity with REST APIs

## Step 1: Set Your API key

Set your API key as an environment variable:

```bash theme={null}
export HOPX_API_KEY="hopx_live_YOUR_KEY_ID.YOUR_SECRET"
```

<Note>
  Replace `YOUR_KEY_ID` and `YOUR_SECRET` with your actual API key from the dashboard.
</Note>

## Step 2: Create a Sandbox

Create a sandbox from a pre-built template:

```bash theme={null}
curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "73",
    "timeout_seconds": 3600
  }'
```

**Response:**

```json theme={null}
{
  "id": "sandbox_abc123xyz",
  "object": "sandbox",
  "status": "running",
  "public_host": "https://sandbox_abc123xyz.hopx.dev",
  "direct_url": "https://sandbox_abc123xyz.hopx.dev",
  "template_id": "73",
  "template_name": "code-interpreter",
  "organization_id": 123,
  "region": "us-east",
  "resources": {
    "vcpu": 2,
    "memory_mb": 4096,
    "disk_mb": 10240
  },
  "internet_access": true,
  "timeout_seconds": 3600,
  "created_at": "2025-01-28T00:00:00Z",
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_expires_at": "2025-01-28T01:00:00Z",
  "request_id": "req_abc123"
}
```

Save the `id` and `auth_token` from the response. You'll need them for the next steps.

## Step 3: Execute Code

Execute Python code in your sandbox using the VM Agent API:

```bash theme={null}
curl -X POST https://sandbox_abc123xyz.hopx.dev/execute \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "print(\"Hello from HopX!\")",
    "language": "python"
  }'
```

**Response:**

```json theme={null}
{
  "success": true,
  "stdout": "Hello from HopX!\n",
  "stderr": "",
  "exit_code": 0,
  "execution_time": 0.15
}
```

<Success>
  🎉 **Success!** You've executed your first code in a HopX sandbox. The output shows "Hello from HopX!" was printed successfully.
</Success>

## Step 4: Clean Up

Delete the sandbox when you're done:

```bash theme={null}
curl -X DELETE https://api.hopx.dev/v1/sandboxes/sandbox_abc123xyz \
  -H "Authorization: Bearer $HOPX_API_KEY"
```

**Response:**

```json theme={null}
{
  "status": "deleted",
  "id": "sandbox_abc123xyz",
  "request_id": "req_abc123"
}
```

## What Just Happened?

1. **Created a sandbox** - You spun up an isolated cloud environment from the `code-interpreter` template
2. **Executed code** - You ran Python code in the sandbox and received the output
3. **Cleaned up** - You deleted the sandbox to free resources

The sandbox was completely isolated - any code you run can't access your local system or other sandboxes.

## Related

* **[Python SDK Quickstart](/sdk/python/quickstart)** - Get started with the Python SDK
* **[JavaScript SDK Quickstart](/sdk/javascript/quickstart)** - Get started with the JavaScript SDK
* **[Creating Sandboxes](/core-concepts/sandboxes/creating)** - Learn more about sandbox creation
* **[Code Execution](/core-concepts/code-execution/synchronous)** - Understand code execution concepts
* [CLI Reference](/cli/introduction) - Command-line interface

## Next Steps

* **[Control Plane API](/api/control-plane/overview)** - Learn about all sandbox management endpoints
* **[VM Agent API](/api/vm-agent/overview)** - Explore code execution, file operations, and more
* **[Authentication](/api/authentication)** - Deep dive into API key management and security
* **[SDK Quickstart](/sdk/python/quickstart)** - Use the Python or JavaScript SDK for easier integration

## Common Variations

### Create Sandbox with Environment Variables

```bash theme={null}
curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "73",
    "env_vars": {
      "MY_VAR": "my_value",
      "API_KEY": "secret123"
    }
  }'
```

### Execute JavaScript Code

```bash theme={null}
curl -X POST https://sandbox_abc123xyz.hopx.dev/execute \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "console.log(\"Hello from JavaScript!\");",
    "language": "javascript"
  }'
```

### List All Sandboxes

```bash theme={null}
curl https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer $HOPX_API_KEY"
```

## Troubleshooting

### Error: 401 Unauthorized

Your API key is missing or invalid. Verify:

* The `HOPX_API_KEY` environment variable is set correctly
* You're using the `Authorization: Bearer` header format
* Your API key hasn't been revoked in the dashboard

### Error: 404 Template Not Found

The template ID doesn't exist. Try:

* Listing available templates: `GET /v1/templates`
* Using a template name instead: `"template_name": "code-interpreter"`

### Error: 503 Service Unavailable

No sandboxes are available at the moment. This is usually temporary. Try again in a few moments.

For more help, see the [Errors & Troubleshooting](/api/errors) guide.