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, Custom images, and Sandbox terminal. For Mac creation, desktop sharing, and persistent disk commands, see macOS sandboxes (Beta). macOS is enabled for teams on request. For GPU image builds and creation, use hx 0.1.25 or later and follow GPU sandboxes. Contact us to enable GPU access for your team.

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, inspect, and delete persistent volumes:

hx vm volumes create my-workspace
hx vm volumes ls
hx vm volumes get <volume-id>
hx vm volumes delete my-workspace --force

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.

Manage Secrets

Store encrypted values and pass them to sandbox processes as environment variables. Values are read from a file or stdin, encrypted locally, and never shown again:

hx secrets create provider-key --from-file ./provider-key.txt
hx secrets create ci-otp --type totp --from-file ./otp-seed.txt
printf '%s' "$NEW_KEY" | hx secrets set provider-key --stdin
hx secrets ls
hx secrets ls --type totp
hx secrets get provider-key
hx secrets delete-version provider-key 1

hx vm exec <sandbox-id> --secret API_KEY=provider-key -- node app.js
hx vm process start <sandbox-id> --secret API_KEY=provider-key --secret-version API_KEY=2 'node worker.js'
hx vm create my-image --secret API_KEY=provider-key

Group secrets in a vault and pass them all by name. --secret is merged over the vault and wins on a clash. --entry sets or replaces a variable and --remove drops one. A secret a vault uses can’t be deleted until the vault stops using it:

hx vaults create app-env --entry DB_URL=app-db-url --entry API_KEY=provider-key@2
hx vaults ls
hx vaults get app-env

hx vm exec <sandbox-id> --vault app-env -- node app.js
hx vm process start <sandbox-id> --vault app-env 'node worker.js'
hx vm create my-image --vault app-env --secret API_KEY=provider-key-staging

hx vaults update app-env --entry API_KEY=provider-key --remove DB_URL
hx vaults delete app-env --force
hx secrets delete provider-key --force

Read fields from 1Password when a process starts, signing in with a service account token stored as an op_token secret. --1password-field is repeatable and takes ENV=item/[section/]field:

printf '%s' "$OP_SERVICE_ACCOUNT_TOKEN" | hx secrets create op-token --type op_token --stdin

hx vm exec <sandbox-id> --1password-token op-token --1password-vault "Dev Vault for Testing" \
  --1password-field SC_USER="scrapingcourse login/username" -- node app.js
hx vm process start <sandbox-id> --1password-token op-token --1password-vault "Dev Vault for Testing" \
  --1password-field SC_USER="scrapingcourse login/username" 'node worker.js'
hx vm create my-image --1password-token op-token --1password-vault "Dev Vault for Testing" \
  --1password-field SC_USER="scrapingcourse login/username"

See Secrets for delivery rules and limits, and 1Password for references and errors.

Fill Credentials Into Browser Sessions

Store each part of a website login as a secret with allowed origins, group them in a vault, and fill them into a browser session’s login form:

hx secrets create github-username --allowed-origin https://github.com --from-file ./username.txt
hx secrets create github-password --allowed-origin https://github.com --from-file ./password.txt
hx secrets update github-password --allowed-origin https://github.com --allowed-origin https://*.github.com
hx vaults create github-login --entry USERNAME=github-username --entry PASSWORD=github-password

hx browser create --vault github-login
hx browser fill <session-id> --vault github-login \
  --field USERNAME=#login_field --field PASSWORD=#password

hx browser create --credential github-password
hx browser fill <session-id> --credential github-password --selector '#password' \
  --page-url https://github.com/login

To fill from 1Password, attach the op_token secret and name the allowed origins with the fill. The nth --1password-ref (item/[section/]field) fills the nth --selector:

hx browser create --1password-token op-token
hx browser fill <session-id> --1password-token op-token --1password-vault "Dev Vault for Testing" \
  --allowed-origin https://www.scrapingcourse.com \
  --1password-ref "scrapingcourse login/username" --selector '#email' \
  --1password-ref "scrapingcourse login/password" --selector '#password'

See Credential fill for outcomes, allowed origins, one-time codes and tab choice.

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

Building from a local Docker image requires local Docker. With --remote, the CLI uploads a Dockerfile build context and builds it remotely without local Docker.

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 wait supports --wait-timeout and --poll-interval when you want to control how long the CLI waits and how often it polls build status.

GPU images require --remote --enable-gpu-builds. Use hx vm image wait to wait for GPU publication as well as build completion. See Custom images for build methods and readiness.

Create GPU sandboxes

Flag	Use
`--gpu`	Select a GPU type from the rate table.
`--gpu-count`	Request 1–8 whole GPUs of that type on one host; defaults to 1. Available counts depend on the type and host capacity.
`--wait-for-provisioning`	Wait until the sandbox is active before returning. Stopping the wait does not stop the sandbox.

Use --region us and a GPU-ready image built by your team. --memory sets system RAM; GPU memory is determined by the GPU type. --disk defaults to 12 GiB for GPU sandboxes and must be at least 12 GiB. Follow the GPU guide for the complete build, create, run, and stop sequence.

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

Manage Secrets

Fill Credentials Into Browser Sessions

Create Sandboxes

Manage Outbound Network Access

Build and list images

Create GPU sandboxes

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

​Manage Secrets

​Fill Credentials Into Browser Sessions

​Create Sandboxes

​Manage Outbound Network Access

​Build and list images

​Create GPU sandboxes

​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

Manage Secrets

Fill Credentials Into Browser Sessions

Create Sandboxes

Manage Outbound Network Access

Build and list images

Create GPU sandboxes

Inspect, Stop, And Expose Sandboxes

Run Commands

Manage Long-Running Processes

Work With Files

Open An Interactive Terminal

Create And Restore Snapshots

JSON Output