The hb CLI covers the sandbox workflows in this section: profile setup, sandbox creation, 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, Sandbox Lifecycle, Sandbox Processes, Sandbox Files, and Sandbox Terminal.
Install
Install hb with curl:
curl -fsSL https://www.hyperup.sh/install.sh | sh
hb version
curl -fsSL https://www.hyperup.sh/install.sh | sh -s -- --version 0.1.0
hb configure --api-key <your_api_key>
hb configure --profile dev --api-key <your_dev_api_key> --base-url http://localhost:3001
hb profile list
hb --profile dev vm list
hb configure --print-path
The CLI uses the default profile unless you pass --profile. hb configure
prompts for an API key if --api-key is omitted and stores profiles in
~/.hb_config/config.
Open The Dashboard
Launch the interactive dashboard:
hb dash requires an interactive terminal. Running hb without a subcommand
shows help; it does not open the dashboard automatically.
Create Sandboxes
Launch from a snapshot:
hb create node
hb create node --port 3000 --port 9222:auth
hb create my_snapshot
hb create snapshot:my_snapshot --snapshot-id <snapshot-id>
hb create --snapshot-name my_snapshot --snapshot-id <snapshot-id>
hb create image:node
hb create --image-name node --region us --timeout-minutes 30
hb create --image-name node --image-id <image-id> --port 3000 --auth
hb create --image-name node --image-id <image-id> --enable-recording
A positional create target without a prefix is treated as a snapshot name.
Choose either a positional target or --snapshot-name / --image-name, not
both.
Launch-time port exposure uses repeated --port flags. Each value can be
<port> or <port>:auth|public. --auth sets the default auth mode for
--port values without an explicit suffix.
--snapshot-id requires --snapshot-name, and --image-id requires
--image-name.
Build And List Images
hb image build packages a local Docker image before uploading it, so image
builds require Docker to be available locally.
hb image build node:22 custom_node
hb image build myorg/app:latest app_prod --env NODE_ENV=production --env PORT=3000
hb image build myorg/app:latest app_prod --entrypoint 'npm run start'
hb image list
hb --json image list
hb 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:
hb vm list
hb vm list --status closed --page 1 --limit 20
hb vm get <sandbox-id>
hb --json vm get <sandbox-id>
hb expose <sandbox-id> --port 3000
hb expose <sandbox-id> --port 3000 --auth
hb expose <sandbox-id> --port 3000:auth
hb unexpose <sandbox-id> --port 3000
hb expose currently accepts exactly one --port value. Use
<port>:auth or <port>:public when you want to override the default auth
mode from --auth.
The CLI uses the vm namespace for sandbox inspection and file reads, but
these commands operate on the same sandbox resource documented in this guide.
Run Commands
Run a one-shot command inside a sandbox:
hb exec <sandbox-id> -- pwd
hb exec <sandbox-id> -- bash -lc 'echo hello'
hb exec --cwd /tmp --env FOO=bar <sandbox-id> -- bash -lc 'echo $FOO'
--use-shell when you want the command executed through a shell:
hb exec --use-shell <sandbox-id> -- 'echo "$HOME"'
Manage Long-Running Processes
Start a background process:
hb process start <sandbox-id> -- bash -lc 'python -m http.server 3000'
hb --json process start <sandbox-id> -- bash -lc 'sleep 30'
hb process get <sandbox-id> <process-id>
hb process list <sandbox-id>
hb process list <sandbox-id> --status running --limit 20
hb process wait <sandbox-id> <process-id>
hb process stream <sandbox-id> <process-id>
hb process stream <sandbox-id> <process-id> --from-seq 120
printf 'hello\n' | hb process stdin <sandbox-id> <process-id> --from-stdin --eof
hb process signal <sandbox-id> <process-id> --signal TERM
hb process kill <sandbox-id> <process-id>
Work With Files
Copy files and directories between your machine and a sandbox:
hb cp ./local.txt <sandbox-id>:/tmp/local.txt
hb cp <sandbox-id>:/tmp/local.txt ./downloaded.txt
hb cp ./dir/. <sandbox-id>:/tmp/dir-contents
hb cp <sandbox-id>:/tmp/a.txt <sandbox-id>:/tmp/b.txt
hb vm read <sandbox-id> /tmp/file.txt
hb vm read --encoding raw <sandbox-id> /tmp/file.bin
hb vm read --encoding base64 <sandbox-id> /tmp/file.bin
hb vm read --offset 0 --length 128 <sandbox-id> /tmp/file.txt
The <sandbox-id>:/path shorthand is only supported by hb cp.
hb vm read expects the sandbox ID and path as separate arguments.
Open An Interactive Terminal
Open a terminal in a selected sandbox:
Open a terminal in a specific sandbox:
Override the default command or set a working directory:
hb connect <sandbox-id> --command python --arg -i
hb connect <sandbox-id> --cwd /tmp
hb connect <sandbox-id> --env FOO=bar
By default, hb connect starts /bin/bash -i -l. Omit [sandbox-id] to
choose from your active sandboxes.
Create And Restore Snapshots
Create a memory snapshot from a running sandbox:
hb snapshot create <sandbox-id> my_snapshot
hb snapshot list
hb snapshot list --limit 20
hb create my_snapshot
hb create --snapshot-name my_snapshot --snapshot-id <snapshot-id>
JSON Output
Most commands support --json for scripting:
hb --json create node --port 3000:auth
hb --json vm get <sandbox-id>
hb --json expose <sandbox-id> --port 3000:public --auth
hb --json process start <sandbox-id> -- bash -lc 'echo hi'
hb --json cp ./file.txt <sandbox-id>:/tmp/file.txt
