Types, units and the engine

Units

import { KiB, MiB, GiB, TiB, type Mebibytes } from "nativesandbox";

Mebibytes is a branded number, so memory: 512 does not compile and the unit has to be written at the call site. The mebibyte is the canonical unit — MiB(512) === 512 at runtime — and the others convert into it.


`KiB(n)`	Kibibytes. Fractional in mebibytes: `KiB(512)` is `0.5`
`MiB(n)`	Mebibytes
`GiB(n)`	Gibibytes
`TiB(n)`	Tebibytes

JavaScript callers get the documentation value without the enforcement — the brand is erased at runtime.

`SandboxError`

import { SandboxError, type SandboxErrorCode } from "nativesandbox";

One error type with a stable code to branch on, deliberately not a subclass hierarchy: callers want to know whether to retry, rebuild or give up, and that is decided by a string.

catch (error) {
  if (error instanceof SandboxError && error.code === "unavailable") { … }
}

See errors for what to do about each code.

Constants


`WORKSPACE`	`"/workspace"` — where the workspace is mounted inside every sandbox
`DEFAULT_IMAGES`	runtime → image for `node`, `python`, `node-python`, `media` and `browser` — listed on Images
`RUNTIME_DEFAULTS`	runtime → what it needs beyond its image: `{ browser: { shmSize: MiB(512) } }`
`WATCHDOG`	`string` — the main process of a self-stopping sandbox

DEFAULT_IMAGES and RUNTIME_DEFAULTS are frozen. Pass images to the constructor to change the mapping; anything unrecognised falls back to node. A spec’s own shmSize overrides RUNTIME_DEFAULTS. WATCHDOG is the shell script a self-stopping sandbox runs as its main process — exported so you can read exactly what runs as PID 1. See the sandbox stops itself.

`SandboxInfo`

What list() returns.

Field	Type
`name`	`string`
`id`	`string`	Container id
`state`	`string`	The engine’s own word — `running`, `exited`, `created`, …
`image`	`string`
`createdAt`	`Date`
`idleTimeoutMs`	`number \| null`	What this sandbox was created with. `null` predates the label
`maxLifetimeMs`	`number \| null`
`stopGraceMs`	`number \| null`

state is passed through from the engine rather than translated, because the vocabulary is the engine’s and inventing a parallel one hides what docker ps would tell you. exited is the ordinary stopped state.

`Engine`

The socket connection. Its constructor takes EngineOptions — a single optional socketPath, which SandboxesOptions also accepts and passes through. The socket connection. You should not need it — Sandboxes wraps everything this package does — but it is exported so you can make a call this package does not, against the same socket.

import { Engine, defaultSocketPath } from "nativesandbox";

const engine = new Engine({ socketPath: defaultSocketPath() });
await engine.version();                    // { Version, ApiVersion }
await engine.pull("docker.io/library/go:1.23-alpine");
await engine.call("GET", "/containers/json?all=true");


`socketPath`	The resolved path, readonly
`call(method, path, body?)`	A raw Docker/Podman REST call. Returns the parsed body, or `null`
`version()`	`{ Version, ApiVersion }`
`pull(image)`	Pulls, and waits for it

defaultSocketPath() is the resolution described in requirements: $DOCKER_HOST, then Podman’s per-user socket, then Docker’s.

Engine is the unwrapped API. Containers you create through it carry none of this package’s labels, so list(), sweep() and removeAll() will not see them — and nothing will reclaim them.

​Units

​SandboxError

​Constants

​SandboxInfo

​Engine

Units

`SandboxError`

Constants

`SandboxInfo`

`Engine`