@microsandbox/types

Shared task and wire contract types for microsandbox, as TypeScript.

This package is the type-only mirror of the microsandbox-types Rust crate. It gives TypeScript consumers (the Node SDK, the cloud front end, and anything talking to the cloud API) the exact sandbox spec and cloud wire shapes the rest of microsandbox uses, so a SandboxSpec or CloudCreateSandboxRequest means the same thing on both sides of the wire.

It contains no runtime code. Every export is a type or interface; importing it adds nothing to your bundle.

Generated, Not Hand-Written

src/index.ts is generated from the Rust crate with ts-rs and carries a // @generated header. Do not edit it. To change a shape, edit the Rust type and regenerate from the repo root:

cargo run -p microsandbox-types --features ts --bin microsandbox-types-generate

Install

npm install @microsandbox/types

Usage

Import the shapes you need with import type:

import type {
  SandboxSpec,
  RootfsSource,
  CloudCreateSandboxRequest,
} from "@microsandbox/types";

const image: RootfsSource = { Oci: { reference: "python", upper_size_mib: null } };

const req: CloudCreateSandboxRequest = {
  name: "worker",
  image: "python",
  vcpus: 2,
  memory_mib: 1024,
  env: {},
  ephemeral: true,
};

Generated Shape Notes

The bindings follow ts-rs conventions, which mirror the Rust serde representation:

• Rust enums become tagged unions or string literals. RootfsSource is { "Bind": string } | { "Oci": OciRootfsSource } | { "DiskImage": {...} }; lowercase enums like StatVirtualization are "strict" | "relaxed" | "off".
• VolumeMount is internally tagged with a type field ("Bind" | "Named" | "Tmpfs" | "DiskImage").
• Optional Rust fields are T | null; fields skipped when absent are ?: optional.
• serde_json::Value is rendered as the JsonValue alias for the network subdocuments (policy, dns, tls, secrets, interface).

Build And Typecheck

npm run build       # tsc -> dist/
npm run typecheck   # tsc --noEmit