Hiverv0.1.45
GitHub

CLI

The hiver CLI runs the local stack, launches sandboxes, streams their events, opens the Inspector, and bundles your Docker images into runnable Hiver images. It's the fastest way to try Hiver and to develop against it locally.

Commands

⬢ Hiver · Agent Runtime

  Usage: hiver <command> [options]

  Commands
    up             Bring up local stack
    down           Bring down local stack
    connect        Connect to stack
    start          Start a sandbox
    run            Build and launch a project directory as a sandbox
    stop           Stop a sandbox
    shell          Open an interactive shell in a sandbox
    list           List the sandboxes
    events         Stream a sandbox's events live as they happen
    inspect        Launch the inspector
    bundle         Prepare OCI image

  Run hiver <command> --help for command details.

Local stack

up starts the gateway and runtime as local containers; down tears them down. The gateway listens on localhost:10000 by default, that's the URL the clients target out of the box.

hiver up
hiver down

Connect to a remote stack

Point the CLI at a gateway you're running elsewhere (e.g. a Kubernetes deployment) so list, events, inspect, and shell operate against it:

hiver connect https://gateway.example.com

Manage sandboxes

start provisions a sandbox. With no arguments it prompts you to pick an agent CLI (Claude Code, Codex, Copilot CLI, or Gemini CLI); pass a key and flags to script it.

hiver start                       # interactive: pick an agent image
hiver start agent-1               # start under a specific key
hiver start agent-1 --image python --entrypoint "tail -f /dev/null" --ttl 3600
FlagDescription
--image <image>Image to launch. Defaults to the base image, or the picker's choice.
--entrypoint <cmd>Override the image entrypoint.
--ttl <seconds>Idle seconds before shutdown. 0 disables the timeout.
--ttyAttach a pseudo-TTY to the entrypoint.
i
Language runtime images (like python) whose default command exits immediately will stop as soon as they start. Keep one alive with --entrypoint "tail -f /dev/null".

For anything the flags don't cover, most notably env, pipe a JSON SandboxConfig to stdin instead:

hiver start claude <<EOF
{
  "image": "claude",
  "env": { "ANTHROPIC_API_KEY": "$ANTHROPIC_API_KEY" }
}
EOF

Flags and stdin can combine; flags win where both set the same field.

Run a project directory

run bundles a directory's Dockerfile and launches it in one step, using the directory name as the image tag and, by default, the sandbox key. With no argument it uses the current directory; pass a second argument to override the key.

hiver run                  # build and launch the current directory
hiver run ./my-app         # build and launch a specific directory
hiver run ./my-app agent-1 # launch under a specific key

If the directory has no Dockerfile, run offers to scaffold a minimal one whose entrypoint is tail -f /dev/null, keeping the sandbox alive until you stop it. It also writes a .hiver.json holding the SandboxConfig the sandbox is launched with; a later hiver run reuses that config and re-bundles the image from the directory. Edit .hiver.json to set env, ttl, entrypoint, and anything else the sandbox is launched with — including image, which becomes the tag the directory is bundled to (defaulting to the directory name).

Stop, list, and open a shell:

hiver stop agent-1
hiver list
hiver shell agent-1                       # interactive shell inside the sandbox
hiver shell agent-1 --command /bin/bash   # choose the shell

Stream events

Tail a sandbox's live event stream, every command, file access, and outbound request, in your terminal:

hiver events agent-1
hiver events agent-1 --gateway-url https://gateway.example.com

Pass --jq <filter> to run each event through a jq expression before it's printed. The filter is applied to one event at a time, so select(...) drops events, .field projects, and a filter that yields multiple values prints one line each:

# only log events
hiver events agent-1 --jq 'select(.type == "log")'
# just the command of each exec event
hiver events agent-1 --jq 'select(.type == "exec") | .cmd'

Inspector

Launch the Inspector in your browser. Add --record to capture a session for later replay.

hiver inspect
hiver inspect --record

Bundle an image

bundle wraps any Docker image with the Hiver runtime so it can run as a sandbox. Pass an image reference (from a registry or built locally) or a path to a build context.

hiver bundle python:3.13-alpine --tag python
hiver bundle ./my-agent --tag my-agent
hiver bundle ./my-agent                    # tag comes from ./my-agent/.hiver.json
hiver bundle ./my-agent --tag my-agent --platform linux/amd64,linux/arm64

When bundling a directory that has a .hiver.json, --tag defaults to its image field — the same tag hiver run bundles to — so hiver bundle ./my-agent and hiver run ./my-agent stay in sync without repeating the tag.

FlagDescription
--tag <tag>Tag for the produced Hiver runtime image (used as image when provisioning). Defaults to the image in the directory's .hiver.json, else <image>-bundled.
--platform <list>Comma-separated target platforms, e.g. linux/amd64,linux/arm64.
--microvmBuild a microVM-isolation image (bakes a guest kernel + rootfs).

The resulting tag is what you pass as image in SandboxConfig. See OCI Image for a full walkthrough.

Install the skill

The Hiver Agent Skill — the full documentation as an on-disk skill — ships bundled with the CLI. install-skill detects the coding agents on your machine (Claude Code, Codex, Antigravity, and GitHub Copilot CLI) and symlinks the skill into each one's skills directory, so they can pull the pages they need into context. The first run of hiver also offers to do this.

hiver install-skill                # all detected agents
hiver install-skill claude codex   # only specific agents
hiver install-skill --project      # into ./<agent>/skills in the current dir
FlagDescription
--projectLink into ./<agent>/skills in the current directory instead of $HOME.
--forceReplace a non-symlink file or directory already sitting at the skill path.

Next: Inspector