Sandbox CLI

The hx CLI covers the sandbox workflows in this section: profile setup, sandbox creation, network policies, 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, Network Policies, Volumes, Sandbox Lifecycle, Sandbox Processes, Local Filesystem, Base Images, Build And Upload A Custom Image, and Sandbox Terminal.

Install

See Install for macOS, Linux, Windows, and direct-download instructions.

Configure Profiles

hx auth login

hx auth login --profile dev

List saved profiles and run a command with a specific profile:

hx profile list
hx --profile dev vm list

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>

Manage Outbound Network Access

Set a network policy when creating a sandbox:

hx vm create node --allow-internet=false
hx vm create node \
  --allow-internet=false \
  --allow-out api.example.com \
  --allow-out 1.1.1.1

Update a running sandbox or restore the default outbound policy:

hx vm network set <sandbox-id> --deny-out 203.0.113.0/24
hx vm network set <sandbox-id> --allow-internet=false --allow-out api.example.com
hx vm network clear <sandbox-id>

Each --allow-out or --deny-out flag may be repeated. Network updates apply to new connections; established connections may continue until they close. See Network Policies for rule precedence, target formats, and domain behavior.

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

Get Started

Sandbox

Base Images

Custom Images

Volumes

Local Filesystem

Install

Configure Profiles

Open The Dashboard

Manage Volumes

Create Sandboxes

Manage Outbound Network Access

Build And List Images

Inspect, Stop, And Expose Sandboxes

Run Commands

Manage Long-Running Processes

Work With Files

Open An Interactive Terminal

Create And Restore Snapshots

JSON Output

​Install

​Configure Profiles

​Open The Dashboard

​Manage Volumes

​Create Sandboxes

​Manage Outbound Network Access

​Build And List Images

​Inspect, Stop, And Expose Sandboxes

​Run Commands

​Manage Long-Running Processes

​Work With Files

​Open An Interactive Terminal

​Create And Restore Snapshots

​JSON Output

Install

Configure Profiles

Open The Dashboard

Manage Volumes

Create Sandboxes

Manage Outbound Network Access

Build And List Images

Inspect, Stop, And Expose Sandboxes

Run Commands

Manage Long-Running Processes

Work With Files

Open An Interactive Terminal

Create And Restore Snapshots

JSON Output