Sandbox

import { Sandbox } from "microsandbox";

await using sandbox = await Sandbox.builder("demo")
  .image("alpine")
  .cpus(1)
  .memory(512)
  .create();

static builder(name: string): SandboxBuilder

static get(name: string): Promise<SandboxHandle>

static list(): Promise<SandboxHandle[]>

static remove(name: string): Promise<void>

static start(name: string): Promise<Sandbox>

static startDetached(name: string): Promise<Sandbox>

readonly name: string

readonly config: Readonly<SandboxConfig>

readonly ownsLifecycle: boolean

detach(): Promise<void>

drain(): Promise<void>

fs(): SandboxFs

kill(): Promise<void>

metrics(): Promise<SandboxMetrics>

metricsStream(intervalMs: number): Promise<MetricsStream>

logs(opts?: LogReadOptions): Promise<LogEntry[]>

import { Sandbox } from "microsandbox";

const handle = await Sandbox.get("web");

// Default — all user-program output, regardless of pipe/pty mode
const entries = await handle.logs();

for (const e of entries) {
  const source =
    e.source === "stdout" ? "OUT" :
    e.source === "stderr" ? "ERR" :
    e.source === "output" ? "PTY" :
    "SYS";

  console.log(
    `[${e.timestamp.toISOString()}] ${source} ${e.sessionId}: ${e.text().trimEnd()}`
  );
}

// Filtered: last 50 entries from the past hour, including system lines
const recent = await handle.logs({
  tail: 50,
  since: new Date(Date.now() - 60 * 60 * 1000),
  sources: ["stdout", "stderr", "output", "system"],
});

removePersisted(): Promise<void>

stop(): Promise<void>

stopAndWait(): Promise<ExitStatus>

wait(): Promise<ExitStatus>

[Symbol.asyncDispose](): Promise<void>

append(path: string, content: string): this

copyDir(src: string, dst: string, opts?: { replace?: boolean }): this

copyFile(
  src: string,
  dst: string,
  opts?: { mode?: number; replace?: boolean },
): this

file(
  path: string,
  content: Buffer,
  opts?: { mode?: number; replace?: boolean },
): this

mkdir(path: string, opts?: { mode?: number }): this

remove(path: string): this

symlink(target: string, link: string, opts?: { replace?: boolean }): this

text(
  path: string,
  content: string,
  opts?: { mode?: number; replace?: boolean },
): this

type LogSource = "stdout" | "stderr" | "output" | "system";

const creation = await Sandbox.builder("demo")
  .image("alpine")
  .createWithPullProgress();

for await (const ev of creation) {
  if (ev.kind === "layerDownloadProgress") {
    console.log(`${ev.layerIndex}: ${ev.downloadedBytes}/${ev.totalBytes}`);
  }
}

const sandbox = await creation.awaitSandbox();