> ## Documentation Index > Fetch the complete documentation index at: https://hyperbrowser.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Sandbox CLI > Use the Hyperbrowser CLI to create and manage sandboxes 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](/sandboxes/create), [Volumes](/sandboxes/volumes), [Sandbox Lifecycle](/sandboxes/lifecycle), [Sandbox Processes](/sandboxes/processes), [Local Filesystem](/sandboxes/filesystem/overview), [Base Images](/sandboxes/base-images), [Build And Upload A Custom Image](/sandboxes/custom-images), and [Sandbox Terminal](/sandboxes/terminal). ## Install See [Install](/sandboxes/install) for macOS, Linux, Windows, and direct-download instructions. ## Configure Profiles Login with your account ```bash theme={null} hx auth login ``` Login with and save credentials to a profile: ```bash theme={null} hx auth login --profile dev ``` List saved profiles and run a command with a specific profile: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} hx vm volumes create my-workspace hx vm volumes ls hx vm volumes get ``` Attach a volume at sandbox launch: ```bash theme={null} hx vm create node --mount :/mnt/workspace hx vm create node --mount :/mnt/cache:ro hx vm create node --mount source=,target=/mnt/workspace hx vm create node --mount source=,target=/mnt/cache,readonly ``` See [Managing Volumes](/sandboxes/volumes/managing) and [Mounting Volumes](/sandboxes/volumes/mounting) for API-level rules. ## Create Sandboxes Launch from an image: ```bash theme={null} 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 --port 3000 --auth hx vm create --image-name node --image-id --enable-recording ``` Launch from a snapshot: ```bash theme={null} hx vm create my_snapshot --snapshot hx vm create snapshot:my_snapshot --snapshot-id hx vm create --snapshot-name my_snapshot --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: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} hx vm list hx vm list --status closed --page 1 --limit 20 hx vm get hx --json vm get ``` Stop a sandbox: ```bash theme={null} hx vm stop ``` Expose or remove an exposed sandbox port: ```bash theme={null} hx vm expose --port 3000 hx vm expose --port 3000 --auth hx vm expose --port 3000:auth hx vm unexpose --port 3000 ``` `hx vm expose` currently accepts exactly one `--port` value. Use `:auth` or `: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: ```bash theme={null} hx vm exec 'pwd' hx vm exec 'echo hello' hx vm exec --cwd /tmp --env FOO=bar 'echo $FOO' ``` ## Manage Long-Running Processes Start a background process: ```bash theme={null} hx vm process start 'python3 -m http.server 3000' hx --json vm process start 'sleep 30' ``` Inspect, wait for, and stream a process: ```bash theme={null} hx vm process get

hx vm process list hx vm process list --status running --limit 20 hx vm process wait

hx vm process stream

--from-seq 120 ``` Send input or terminate a process: ```bash theme={null} printf 'hello\n' | hx vm process stdin

--from-stdin --eof hx vm process signal

--signal TERM hx vm process kill

``` ## Work With Files Copy files and directories between your machine and a sandbox: ```bash theme={null} hx vm cp ./local.txt :/tmp/local.txt hx vm cp :/tmp/local.txt ./downloaded.txt hx vm cp ./dir/. :/tmp/dir-contents hx vm cp :/tmp/a.txt :/tmp/b.txt ``` Read a file directly from a sandbox: ```bash theme={null} hx vm read /tmp/file.txt hx vm read --encoding raw /tmp/file.bin hx vm read --encoding base64 /tmp/file.bin hx vm read --offset 0 --length 128 /tmp/file.txt ``` The `:/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: ```bash theme={null} hx vm connect ``` Open a terminal in a specific sandbox: ```bash theme={null} hx vm connect ``` Override the default command or set a working directory: ```bash theme={null} hx vm connect --command python3 --arg -i hx vm connect --cwd /tmp hx vm connect --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: ```bash theme={null} hx vm snapshot create my_snapshot ``` List snapshots: ```bash theme={null} hx vm snapshot list hx vm snapshot list --limit 20 ``` Restore from a snapshot: ```bash theme={null} hx vm create my_snapshot --snapshot hx vm create --snapshot-name my_snapshot --snapshot-id ``` ## JSON Output Most commands support `--json` for scripting: ```bash theme={null} hx --json vm create node --port 3000:auth hx --json vm get hx --json vm expose --port 3000:public --auth hx --json vm process start 'echo hi' hx --json vm cp ./file.txt :/tmp/file.txt ```