Getting Started

This guide walks you through starting the gateway, provisioning your first sandbox, running a command inside it, and using the inspector.

CLI

Use the hiver command to manage a local cluster of sandboxes and agents. See the CLI reference for every command and flag.

hiver

⬢ 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
    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 to OCI image

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

hiver

⬢ 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
    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 to OCI image

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

Start the gateway

hiver up

hiver up

The gateway provides access to the agents. By default, it listens on localhost:10000.

Start a sandbox

hiver start agent-1

hiver start agent-1

By default, this will prompt to start an agent running Claude Code, Codex, Copilot CLI, or Gemini CLI.

Open the Inspector

hiver inspect agent-1

hiver inspect agent-1

First app

Install the client SDK for your language (see Installation), then provision your first sandbox.

Provision a sandbox

getOrCreateSandbox provisions a new sandbox or returns the existing one with the same key. The key allows to establish communication with an existing sandbox in the case the client connection died or reset.

index.ts

import { getOrCreateSandbox } from "@hiver.sh/client";

const sandbox = await getOrCreateSandbox("agent-1", {
  image: "claude",
});

import { getOrCreateSandbox } from "@hiver.sh/client";

const sandbox = await getOrCreateSandbox("agent-1", {
  image: "claude",
});

Config options

Field	Type	Description
`image`	`string`	Image to launch. Select a preconfigured image (`"claude"`, `"codex"`, `"copilot"`, `"openclaw"`, `"antigravity"`, `"browser"`), or the tag of any OCI image (local, Docker Hub, GHCR, or a private registry) bundled with `hiver bundle`. Defaults to the Hiver base image.
`cpu`	`number`	Virtual CPUs allocated to the sandbox (may be fractional, e.g. `0.5`). Defaults to `1`. Cannot be changed after initialization.
`memory`	`number`	Memory in MiB. Defaults to `512`. Cannot be changed after initialization.
`entrypoint`	`string`	Override the image's default entrypoint.
`cwd`	`string`	Working directory for the entrypoint. Cannot be changed after initialization.
`tty`	`boolean`	Launch the entrypoint with a pseudo-TTY. Container isolation only. Cannot be changed after initialization.
`env`	`Record<string, string>`	Additional environment variables injected into the sandbox.
`extra_hosts`	`string[]`	Additional `/etc/hosts` entries in `hostname:ip` form. Cannot be changed after initialization.
`ttl`	`number`	Idle seconds before the sandbox shuts itself down. Defaults to `1800` (30 min). Use `0` to disable.
`fs`	`FileSystem[]`	File systems exposed to the agent. Defaults to a local `/workspace` mount with read/write access.
`egress`	`EgressRule[]`	Ordered egress rules, first match wins. All outbound traffic is allowed by default.
`egress_deny_wait`	`number`	Seconds to hold a would-be-denied request before erroring, giving you a window to widen the policy and let it through. The deny event fires immediately, so you have the full window to react. Defaults to `0` (deny immediately). See Network Access.
`mitm`	`boolean`	Whether outbound TLS is intercepted so egress rules can enforce method/path/headers/body. Defaults to `true`. See Network Access.
`events`	`EventType[]`	Restrict the event stream to these types. Defaults to every type. An empty array observes nothing. See Events.
`snapshot`	`Snapshot`	Automatic snapshot configuration, captured on shutdown, restored on start.

Run a command

exec runs a shell command and returns buffered stdout, stderr, and exit code once the process finishes.

index.ts

const result = await sandbox.exec(["echo", "hello", "world"]);
console.log(result.stdout);    // "hello world\n"
console.log(result.exit_code); // 0

const result = await sandbox.exec(["echo", "hello", "world"]);
console.log(result.stdout);    // "hello world\n"
console.log(result.exit_code); // 0

Keep the sandbox alive

Sandboxes shut down automatically after ttl seconds of inactivity. Call ping on an interval to reset the countdown while your process is running.

index.ts

setInterval(sandbox.ping, 10_000);

setInterval(sandbox.ping, 10_000);

Shut down

When you are done, call shutdown to release the sandbox immediately rather than waiting for the TTL to expire.

index.ts

import { shutdown } from "@hiver.sh/client";

await shutdown(sandbox);

import { shutdown } from "@hiver.sh/client";

await shutdown(sandbox);

Full example

index.ts

import { getOrCreateSandbox, shutdown } from "@hiver.sh/client";

const sandbox = await getOrCreateSandbox("agent-1", {
image: "claude",
});

const keepAlive = setInterval(sandbox.ping, 10_000);

const result = await sandbox.exec(["echo", "hello", "world"]);
console.log(result.stdout);    // "hello world\n"
console.log(result.exit_code); // 0

clearInterval(keepAlive);
await shutdown(sandbox);

import { getOrCreateSandbox, shutdown } from "@hiver.sh/client";

const sandbox = await getOrCreateSandbox("agent-1", {
image: "claude",
});

const keepAlive = setInterval(sandbox.ping, 10_000);

const result = await sandbox.exec(["echo", "hello", "world"]);
console.log(result.stdout);    // "hello world\n"
console.log(result.exit_code); // 0

clearInterval(keepAlive);
await shutdown(sandbox);

Examples

Ready-to-run projects that go further than the snippets above:

hiver-sh/examples — runnable examples in TypeScript and Python: Agent SDK servers that run the agent loop inside the sandbox, CLI and browser drivers, and lower-level client SDK recipes (exec, egress, snapshots, mounts, proxied services).
⭐ Open Work — a complete Next.js app that drives Claude Code or Codex inside a sandbox, with persistent sessions, provider keys kept out of the agent via egress overrides, a driveable remote browser, and live file events. See the walkthrough.

Next: CLI