Getting Started

This guide walks you through installing the Hive client, provisioning your first sandbox, and running a command inside it.

Install

npm install hive

npm install hive

Provision a sandbox

getOrCreateSandbox provisions a new sandbox or returns the existing one with the same id — so it is safe to call on every startup without creating duplicates.

index.ts

import { getOrCreateSandbox, shutdown } from "hive";

const sandbox = await getOrCreateSandbox("my-sandbox", {
  image: "ubuntu:24.04",
});

import { getOrCreateSandbox, shutdown } from "hive";

const sandbox = await getOrCreateSandbox("my-sandbox", {
  image: "ubuntu:24.04",
});

Config options

Field	Type	Description
`image`	`string`	Container image to use (e.g. `"ubuntu:24.04"`). Defaults to the Hive base image.
`env`	`Record<string, string>`	Environment variables injected into every exec call.
`ttl`	`number`	Idle seconds before the sandbox shuts itself down. Defaults to `1800` (30 min).
`fs`	`FileSystem[]`	One or more filesystem mounts. Defaults to a local `/workspace` mount with read/write access.
`egress`	`EgressRule[]`	Outbound network rules. All outbound traffic is allowed by default.

Run a command

sandbox.exec runs a shell command and returns when it exits.

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

The return value has three fields: stdout, stderr, and exit_code.

Keep the sandbox alive

Sandboxes shut down automatically after ttl seconds of inactivity. Call sandbox.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

await shutdown(sandbox);

await shutdown(sandbox);

Full example

index.ts

import { getOrCreateSandbox, shutdown } from "hive";

const sandbox = await getOrCreateSandbox("my-sandbox", {
  image: "ubuntu:24.04",
});

// Keep the sandbox alive every 10 seconds
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 "hive";

const sandbox = await getOrCreateSandbox("my-sandbox", {
  image: "ubuntu:24.04",
});

// Keep the sandbox alive every 10 seconds
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);

Next: Execution