Skip to main content
The hx CLI covers the sandbox workflows in this section: profile setup, sandbox creation, volume management, process execution, file transfer, terminals, snapshots, image builds, and port exposure. Use the CLI when you want a shell-first workflow or need to script sandbox operations outside the SDKs. For the underlying API concepts, see Creating Sandboxes, Volumes, Sandbox Lifecycle, Sandbox Processes, Local Filesystem, Base Images, Build And Upload A Custom Image, and Sandbox Terminal.

​
Install

Install hx with curl: 
curl -fsSL https://www.hyperup.sh/install.sh | sh
hx version
Install a specific version: 
curl -fsSL https://www.hyperup.sh/install.sh | sh -s -- --version 0.1.0

​
Configure Profiles

Save your default profile: 
hx configure --api-key <your_api_key>
Create a named profile for a different control plane: 
hx configure --profile dev --api-key <your_dev_api_key> --base-url http://localhost:3001
List saved profiles and run a command with a specific profile: 
hx profile list
hx --profile dev vm list
Print the config path: 
hx configure --print-path
The CLI uses the default profile unless you pass --profile. hx configure prompts for an API key if --api-key is omitted and stores profiles in ~/.hx_config/config.

​
Open The Dashboard

Launch the interactive dashboard: 
hx dash
hx dash requires an interactive terminal. Running hx without a subcommand shows help; it does not open the dashboard automatically.

​
Manage Volumes

Create, list, and inspect persistent volumes: 
hx vm volumes create my-workspace
hx vm volumes ls
hx vm volumes get <volume-id>
Attach a volume at sandbox launch: 
hx vm create node --mount <volume-id>:/mnt/workspace
hx vm create node --mount <volume-id>:/mnt/cache:ro
hx vm create node --mount source=<volume-id>,target=/mnt/workspace
hx vm create node --mount source=<volume-id>,target=/mnt/cache,readonly
See Managing Volumes and Mounting Volumes for API-level rules.

​
Create Sandboxes

Launch from an image: 
hx vm create node
hx vm create node --port 3000 --port 9222:auth
hx vm create image:node
hx vm create --image-name node --region us --timeout-minutes 30
hx vm create --image-name node --image-id <image-id> --port 3000 --auth
hx vm create --image-name node --image-id <image-id> --enable-recording
Launch from a snapshot: 
hx vm create my_snapshot --snapshot
hx vm create snapshot:my_snapshot --snapshot-id <snapshot-id>
hx vm create --snapshot-name my_snapshot --snapshot-id <snapshot-id>

​
Build And List Images

hx vm image build packages a local Docker image before uploading it, so image builds require Docker to be available locally.
Build a Firecracker image from a local Docker image: 
hx vm image build node:22 custom_node
hx vm image build myorg/app:latest app_prod --env NODE_ENV=production --env PORT=3000
hx vm image build myorg/app:latest app_prod --entrypoint 'npm run start'
List available images: 
hx vm image list
hx --json vm image list
hx vm image build also supports --wait-timeout and --poll-interval when you want to control how long the CLI waits and how often it polls build status.

​
Inspect, Stop, And Expose Sandboxes

List and inspect sandboxes: 
hx vm list
hx vm list --status closed --page 1 --limit 20
hx vm get <sandbox-id>
hx --json vm get <sandbox-id>
Stop a sandbox: 
hx vm stop <sandbox-id>
Expose or remove an exposed sandbox port: 
hx vm expose <sandbox-id> --port 3000
hx vm expose <sandbox-id> --port 3000 --auth
hx vm expose <sandbox-id> --port 3000:auth
hx vm unexpose <sandbox-id> --port 3000
hx vm expose currently accepts exactly one --port value. Use <port>:auth or <port>:public when you want to override the default auth mode from --auth.
Sandbox workflows are grouped under the hx vm namespace (for example hx vm create, hx vm process, hx vm connect, and hx vm volumes).

​
Run Commands

Run a one-shot command inside a sandbox: 
hx vm exec <sandbox-id> 'pwd'
hx vm exec <sandbox-id> 'echo hello'
hx vm exec --cwd /tmp --env FOO=bar <sandbox-id> 'echo $FOO'

​
Manage Long-Running Processes

Start a background process: 
hx vm process start <sandbox-id> 'python3 -m http.server 3000'
hx --json vm process start <sandbox-id> 'sleep 30'
Inspect, wait for, and stream a process: 
hx vm process get <sandbox-id> <process-id>
hx vm process list <sandbox-id>
hx vm process list <sandbox-id> --status running --limit 20
hx vm process wait <sandbox-id> <process-id>
hx vm process stream <sandbox-id> <process-id>
hx vm process stream <sandbox-id> <process-id> --from-seq 120
Send input or terminate a process: 
printf 'hello\n' | hx vm process stdin <sandbox-id> <process-id> --from-stdin --eof
hx vm process signal <sandbox-id> <process-id> --signal TERM
hx vm process kill <sandbox-id> <process-id>

​
Work With Files

Copy files and directories between your machine and a sandbox: 
hx vm cp ./local.txt <sandbox-id>:/tmp/local.txt
hx vm cp <sandbox-id>:/tmp/local.txt ./downloaded.txt
hx vm cp ./dir/. <sandbox-id>:/tmp/dir-contents
hx vm cp <sandbox-id>:/tmp/a.txt <sandbox-id>:/tmp/b.txt
Read a file directly from a sandbox: 
hx vm read <sandbox-id> /tmp/file.txt
hx vm read --encoding raw <sandbox-id> /tmp/file.bin
hx vm read --encoding base64 <sandbox-id> /tmp/file.bin
hx vm read --offset 0 --length 128 <sandbox-id> /tmp/file.txt
The <sandbox-id>:/path shorthand is only supported by hx vm cp. hx vm read expects the sandbox ID and path as separate arguments.

​
Open An Interactive Terminal

Open a terminal in a selected sandbox: 
hx vm connect
Open a terminal in a specific sandbox: 
hx vm connect <sandbox-id>
Override the default command or set a working directory: 
hx vm connect <sandbox-id> --command python3 --arg -i
hx vm connect <sandbox-id> --cwd /tmp
hx vm connect <sandbox-id> --env FOO=bar
By default, hx vm connect starts /bin/bash -i -l.

​
Create And Restore Snapshots

Create a memory snapshot from a running sandbox: 
hx vm snapshot create <sandbox-id> my_snapshot
List snapshots: 
hx vm snapshot list
hx vm snapshot list --limit 20
Restore from a snapshot: 
hx vm create my_snapshot --snapshot
hx vm create --snapshot-name my_snapshot --snapshot-id <snapshot-id>

​
JSON Output

Most commands support --json for scripting: 
hx --json vm create node --port 3000:auth
hx --json vm get <sandbox-id>
hx --json vm expose <sandbox-id> --port 3000:public --auth
hx --json vm process start <sandbox-id> 'echo hi'
hx --json vm cp ./file.txt <sandbox-id>:/tmp/file.txt