microsandbox 0.1.1 → 0.3.7

package/index.d.cts

@@ -0,0 +1,751 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/**
+ * Handle for a streaming command execution.
+ *
+ * Use `recv()` to get events one at a time, or iterate with a loop:
+ * ```js
+ * const handle = await sandbox.execStream("tail", ["-f", "/var/log/app.log"]);
+ * let event;
+ * while ((event = await handle.recv()) !== null) {
+ *   if (event.eventType === "stdout") process.stdout.write(event.data);
+ * }
+ * ```
+ */
+export declare class ExecHandle {
+  /** Get the correlation ID for this execution. */
+  get id(): Promise<string>
+  /** Receive the next event. Returns `null` when the stream ends. */
+  recv(): Promise<ExecEvent | null>
+  /** Take the stdin writer. Can only be called once; returns `null` on subsequent calls. */
+  takeStdin(): Promise<ExecSink | null>
+  /** Wait for the process to exit and return the exit status. */
+  wait(): Promise<ExitStatus>
+  /** Wait for completion and collect all output. */
+  collect(): Promise<ExecOutput>
+  /** Send a signal to the running process. */
+  signal(signal: number): Promise<void>
+  /** Kill the running process (SIGKILL). */
+  kill(): Promise<void>
+}
+export type JsExecHandle = ExecHandle
+
+/**
+ * Output of a completed command execution.
+ *
+ * Provides both string and raw byte access to stdout/stderr:
+ * ```js
+ * const output = await sandbox.shell("echo hello");
+ * console.log(output.stdout());       // "hello
+"
+ * console.log(output.stdoutBytes());   // <Buffer 68 65 6c 6c 6f 0a>
+ * console.log(output.code);            // 0
+ * console.log(output.success);         // true
+ * ```
+ */
+export declare class ExecOutput {
+  /** Exit code of the process. */
+  get code(): number
+  /** Whether the process exited successfully (code == 0). */
+  get success(): boolean
+  /** Get stdout as a UTF-8 string. */
+  stdout(): string
+  /** Get stderr as a UTF-8 string. */
+  stderr(): string
+  /** Get stdout as raw bytes. */
+  stdoutBytes(): Buffer
+  /** Get stderr as raw bytes. */
+  stderrBytes(): Buffer
+  /** Get the exit status. */
+  status(): ExitStatus
+}
+
+/** Stdin writer for a running process. */
+export declare class ExecSink {
+  /** Write data to the process stdin. */
+  write(data: Buffer): Promise<void>
+  /** Close stdin (sends EOF to the process). */
+  close(): Promise<void>
+}
+export type JsExecSink = ExecSink
+
+/**
+ * Factory for creating volume mount configurations.
+ *
+ * ```js
+ * import { Mount, Sandbox } from 'microsandbox'
+ *
+ * const sb = await Sandbox.create({
+ *     name: "worker",
+ *     image: "python:3.12",
+ *     volumes: {
+ *         "/app/src": Mount.bind("./src", { readonly: true }),
+ *         "/data": Mount.named("my-data"),
+ *         "/tmp": Mount.tmpfs({ sizeMib: 100 }),
+ *     },
+ * })
+ * ```
+ */
+export declare class Mount {
+  /** Create a bind mount (host directory → guest path). */
+  static bind(path: string, opts?: MountOptions | undefined | null): MountConfig
+  /** Create a named volume mount. */
+  static named(name: string, opts?: MountOptions | undefined | null): MountConfig
+  /** Create a tmpfs (in-memory) mount. */
+  static tmpfs(opts?: TmpfsOptions | undefined | null): MountConfig
+}
+
+/**
+ * Factory for creating network policy configurations.
+ *
+ * ```js
+ * import { NetworkPolicy, Sandbox } from 'microsandbox'
+ *
+ * const sb = await Sandbox.create({
+ *     name: "worker",
+ *     image: "python:3.12",
+ *     network: NetworkPolicy.publicOnly(),
+ * })
+ * ```
+ */
+export declare class NetworkPolicy {
+  /** No network access at all. */
+  static none(): NetworkConfig
+  /** Public internet only — blocks private ranges (default). */
+  static publicOnly(): NetworkConfig
+  /** Unrestricted network access. */
+  static allowAll(): NetworkConfig
+}
+export type JsNetworkPolicy = NetworkPolicy
+
+/**
+ * Factory for creating rootfs patch configurations.
+ *
+ * ```js
+ * import { Patch, Sandbox } from 'microsandbox'
+ *
+ * const sb = await Sandbox.create({
+ *     name: "worker",
+ *     image: "alpine",
+ *     patches: [
+ *         Patch.text("/etc/greeting.txt", "Hello!
+"),
+ *         Patch.mkdir("/app", { mode: 0o755 }),
+ *         Patch.append("/etc/hosts", "127.0.0.1 myapp.local
+"),
+ *         Patch.copyFile("./config.json", "/app/config.json"),
+ *         Patch.copyDir("./scripts", "/app/scripts"),
+ *         Patch.symlink("/usr/bin/python3", "/usr/bin/python"),
+ *         Patch.remove("/etc/motd"),
+ *     ],
+ * })
+ * ```
+ */
+export declare class Patch {
+  /** Write text content to a file in the guest filesystem. */
+  static text(path: string, content: string, opts?: PatchOptions | undefined | null): PatchConfig
+  /** Create a directory in the guest filesystem (idempotent). */
+  static mkdir(path: string, opts?: PatchOptions | undefined | null): PatchConfig
+  /** Append content to an existing file in the guest filesystem. */
+  static append(path: string, content: string): PatchConfig
+  /** Copy a file from the host into the guest filesystem. */
+  static copyFile(src: string, dst: string, opts?: PatchOptions | undefined | null): PatchConfig
+  /** Copy a directory from the host into the guest filesystem. */
+  static copyDir(src: string, dst: string, opts?: PatchReplaceOptions | undefined | null): PatchConfig
+  /** Create a symlink in the guest filesystem. */
+  static symlink(target: string, link: string, opts?: PatchReplaceOptions | undefined | null): PatchConfig
+  /** Remove a file or directory from the guest filesystem (idempotent). */
+  static remove(path: string): PatchConfig
+}
+
+/**
+ * A running sandbox instance.
+ *
+ * Created via `Sandbox.create()` or `Sandbox.start()`. Holds a live connection
+ * to the guest VM and can execute commands, access the filesystem, and query metrics.
+ */
+export declare class Sandbox {
+  /** Create a sandbox from configuration (attached mode — stops on GC/process exit). */
+  static create(config: SandboxConfig): Promise<Sandbox>
+  /** Create a sandbox that survives the parent process (detached mode). */
+  static createDetached(config: SandboxConfig): Promise<Sandbox>
+  /** Start an existing stopped sandbox (attached mode). */
+  static start(name: string): Promise<Sandbox>
+  /** Start an existing stopped sandbox (detached mode). */
+  static startDetached(name: string): Promise<Sandbox>
+  /** Get a lightweight handle to an existing sandbox. */
+  static get(name: string): Promise<JsSandboxHandle>
+  /** List all sandboxes. */
+  static list(): Promise<Array<SandboxInfo>>
+  /** Remove a stopped sandbox from the database. */
+  static remove(name: string): Promise<void>
+  /** Sandbox name. */
+  get name(): Promise<string>
+  /** Whether this handle owns the sandbox lifecycle (attached mode). */
+  get ownsLifecycle(): Promise<boolean>
+  /** Execute a command and wait for completion. */
+  exec(cmd: string, args?: Array<string> | undefined | null): Promise<ExecOutput>
+  /** Execute a command with full configuration and wait for completion. */
+  execWithConfig(config: ExecConfig): Promise<ExecOutput>
+  /** Execute a command with streaming I/O. */
+  execStream(cmd: string, args?: Array<string> | undefined | null): Promise<ExecHandle>
+  /** Execute a shell command using the sandbox's configured shell. */
+  shell(script: string): Promise<ExecOutput>
+  /** Execute a shell command with streaming I/O. */
+  shellStream(script: string): Promise<ExecHandle>
+  /** Get a filesystem handle for operations on the running sandbox. */
+  fs(): SandboxFs
+  /** Get point-in-time resource metrics. */
+  metrics(): Promise<SandboxMetrics>
+  /** Stop the sandbox gracefully (SIGTERM). */
+  stop(): Promise<void>
+  /** Stop and wait for exit, returning the exit status. */
+  stopAndWait(): Promise<ExitStatus>
+  /** Kill the sandbox immediately (SIGKILL). */
+  kill(): Promise<void>
+  /** Graceful drain (SIGUSR1 — for load balancing). */
+  drain(): Promise<void>
+  /** Wait for the sandbox process to exit. */
+  wait(): Promise<ExitStatus>
+  /** Detach from the sandbox — it will continue running after this handle is dropped. */
+  detach(): Promise<void>
+  /** Remove the persisted database record after stopping. */
+  removePersisted(): Promise<void>
+}
+
+/** Filesystem operations on a running sandbox (via agent protocol). */
+export declare class SandboxFs {
+  /** Read a file as a Buffer. */
+  read(path: string): Promise<Buffer>
+  /** Read a file as a UTF-8 string. */
+  readString(path: string): Promise<string>
+  /** Write data to a file (accepts Buffer or string). */
+  write(path: string, data: Buffer): Promise<void>
+  /** List directory contents. */
+  list(path: string): Promise<Array<FsEntry>>
+  /** Create a directory. */
+  mkdir(path: string): Promise<void>
+  /** Remove a directory. */
+  removeDir(path: string): Promise<void>
+  /** Remove a file. */
+  remove(path: string): Promise<void>
+  /** Copy a file within the sandbox. */
+  copy(from: string, to: string): Promise<void>
+  /** Rename a file within the sandbox. */
+  rename(from: string, to: string): Promise<void>
+  /** Get file or directory metadata. */
+  stat(path: string): Promise<FsMetadata>
+  /** Check if a path exists. */
+  exists(path: string): Promise<boolean>
+  /** Copy a file from the host into the sandbox. */
+  copyFromHost(hostPath: string, guestPath: string): Promise<void>
+  /** Copy a file from the sandbox to the host. */
+  copyToHost(guestPath: string, hostPath: string): Promise<void>
+}
+export type JsSandboxFs = SandboxFs
+
+/**
+ * A lightweight handle to a sandbox from the database.
+ *
+ * Does NOT hold a live connection — use `connect()` or `start()` to get a live `Sandbox`.
+ */
+export declare class SandboxHandle {
+  /** Sandbox name. */
+  get name(): string
+  /** Status at time of query: "running", "stopped", "crashed", or "draining". */
+  get status(): string
+  /** Raw config JSON string from the database. */
+  get configJson(): string
+  /** Creation timestamp as ms since Unix epoch. */
+  get createdAt(): number | null
+  /** Last update timestamp as ms since Unix epoch. */
+  get updatedAt(): number | null
+  /** Get point-in-time metrics from the database. */
+  metrics(): Promise<SandboxMetrics>
+  /** Start the sandbox (attached mode) — returns a live Sandbox handle. */
+  start(): Promise<Sandbox>
+  /** Start the sandbox (detached mode). */
+  startDetached(): Promise<Sandbox>
+  /** Connect to an already-running sandbox (no lifecycle ownership). */
+  connect(): Promise<Sandbox>
+  /** Stop the sandbox (SIGTERM). */
+  stop(): Promise<void>
+  /** Kill the sandbox (SIGKILL). */
+  kill(): Promise<void>
+  /** Remove the sandbox from the database. */
+  remove(): Promise<void>
+}
+export type JsSandboxHandle = SandboxHandle
+
+/**
+ * Factory for creating secret entries.
+ *
+ * ```js
+ * import { Secret, Sandbox } from 'microsandbox'
+ *
+ * const sb = await Sandbox.create({
+ *     name: "agent",
+ *     image: "python:3.12",
+ *     secrets: [
+ *         Secret.env("OPENAI_API_KEY", {
+ *             value: process.env.OPENAI_API_KEY,
+ *             allowHosts: ["api.openai.com"],
+ *         }),
+ *     ],
+ * })
+ * ```
+ */
+export declare class Secret {
+  /** Create a secret bound to an environment variable. */
+  static env(envVar: string, opts: SecretEnvOptions): SecretEntry
+}
+
+/** A named persistent volume. */
+export declare class Volume {
+  /** Create a new named volume. */
+  static create(config: VolumeConfig): Promise<Volume>
+  /** Get a lightweight handle to an existing volume. */
+  static get(name: string): Promise<VolumeHandle>
+  /** List all volumes. */
+  static list(): Promise<Array<VolumeInfo>>
+  /** Remove a volume. */
+  static remove(name: string): Promise<void>
+  /** Volume name. */
+  get name(): string
+  /** Host path of the volume. */
+  get path(): string
+}
+export type JsVolume = Volume
+
+/** A lightweight handle to a volume from the database. */
+export declare class VolumeHandle {
+  /** Volume name. */
+  get name(): string
+  /** Size quota in MiB, if set. */
+  get quotaMib(): number | null
+  /** Used bytes on disk. */
+  get usedBytes(): number
+  /** Key-value labels. */
+  get labels(): Record<string, string>
+  /** Creation timestamp as ms since epoch. */
+  get createdAt(): number | null
+  /** Remove this volume. */
+  remove(): Promise<void>
+}
+export type JsVolumeHandle = VolumeHandle
+
+/** Get metrics for all running sandboxes. */
+export declare function allSandboxMetrics(): Promise<Record<string, SandboxMetrics>>
+
+/** Configuration for command execution. */
+export interface ExecConfig {
+  /** Command to execute. */
+  cmd: string
+  /** Command arguments. */
+  args?: Array<string>
+  /** Working directory inside the sandbox. */
+  cwd?: string
+  /** User to run as. */
+  user?: string
+  /** Environment variables. */
+  env?: Record<string, string>
+  /** Timeout in milliseconds. */
+  timeoutMs?: number
+  /** Stdin mode: "null" (default), "pipe", or a string to send as stdin bytes. */
+  stdin?: string
+  /** Enable pseudo-TTY. */
+  tty?: boolean
+}
+
+/** Execution event emitted by `ExecHandle.recv()`. */
+export interface ExecEvent {
+  /** "started", "stdout", "stderr", or "exited". */
+  eventType: string
+  /** Process ID (only for "started" events). */
+  pid?: number
+  /** Output data (only for "stdout" and "stderr" events). */
+  data?: Buffer
+  /** Exit code (only for "exited" events). */
+  code?: number
+}
+
+/** Execution event type. */
+export declare const enum ExecEventType {
+  Started = 'started',
+  Stdout = 'stdout',
+  Stderr = 'stderr',
+  Exited = 'exited'
+}
+
+/** Process exit status. */
+export interface ExitStatus {
+  code: number
+  success: boolean
+}
+
+/** Filesystem entry metadata returned by `fs.list()`. */
+export interface FsEntry {
+  path: string
+  /** "file", "directory", "symlink", or "other". */
+  kind: string
+  size: number
+  mode: number
+  modified?: number
+}
+
+/** Filesystem entry kind. */
+export declare const enum FsEntryKind {
+  File = 'file',
+  Directory = 'directory',
+  Symlink = 'symlink',
+  Other = 'other'
+}
+
+/** Filesystem metadata returned by `fs.stat()`. */
+export interface FsMetadata {
+  /** "file", "directory", "symlink", or "other". */
+  kind: string
+  size: number
+  mode: number
+  readonly: boolean
+  modified?: number
+  created?: number
+}
+
+/** Download and install msb + libkrunfw to ~/.microsandbox/. */
+export declare function install(): Promise<void>
+
+/** Check if msb and libkrunfw are installed and available. */
+export declare function isInstalled(): boolean
+
+/** Log level for sandbox process output. */
+export declare const enum LogLevel {
+  Trace = 'trace',
+  Debug = 'debug',
+  Info = 'info',
+  Warn = 'warn',
+  Error = 'error'
+}
+
+/** Volume mount configuration. */
+export interface MountConfig {
+  /** Mount a host directory. Mutually exclusive with `named` and `tmpfs`. */
+  bind?: string
+  /** Mount a named volume. Mutually exclusive with `bind` and `tmpfs`. */
+  named?: string
+  /** Use tmpfs (memory-backed). Mutually exclusive with `bind` and `named`. */
+  tmpfs?: boolean
+  /** Read-only mount. */
+  readonly?: boolean
+  /** Size limit in MiB (for tmpfs). */
+  sizeMib?: number
+}
+
+/** Options for bind and named volume mounts. */
+export interface MountOptions {
+  /** Read-only mount. */
+  readonly?: boolean
+}
+
+/** Network configuration. */
+export interface NetworkConfig {
+  /**
+   * Preset policy: "public-only" (default), "allow-all", or "none".
+   * Ignored if `rules` is provided.
+   */
+  policy?: string
+  /** Custom policy rules (first match wins). Overrides `policy` preset. */
+  rules?: Array<PolicyRule>
+  /** Default action when no rule matches: "allow" or "deny". */
+  defaultAction?: string
+  /** Block specific domains via DNS interception. */
+  blockDomains?: Array<string>
+  /** Block domain suffixes via DNS interception. */
+  blockDomainSuffixes?: Array<string>
+  /** Enable DNS rebinding protection (default: true). */
+  dnsRebindProtection?: boolean
+  /** TLS interception configuration. */
+  tls?: TlsConfig
+  /** Max concurrent connections (default: 256). */
+  maxConnections?: number
+}
+
+/** Rootfs patch applied before VM startup. */
+export interface PatchConfig {
+  /** Patch kind: "text", "file", "copyFile", "copyDir", "symlink", "mkdir", "remove", "append". */
+  kind: string
+  /** Guest path (all kinds except symlink where it's `link`). */
+  path?: string
+  /** Text content (for "text" and "append" kinds). */
+  content?: string
+  /** Source host path (for "copyFile" and "copyDir" kinds). */
+  src?: string
+  /** Destination guest path (for "copyFile" and "copyDir" kinds). */
+  dst?: string
+  /** Symlink target path (for "symlink" kind). */
+  target?: string
+  /** Symlink link path (for "symlink" kind). */
+  link?: string
+  /** File permissions (e.g. 0o644). */
+  mode?: number
+  /** Allow replacing existing files. */
+  replace?: boolean
+}
+
+/** Options for `Patch.text()` and `Patch.copyFile()`. */
+export interface PatchOptions {
+  /** File permissions (e.g. 0o644). */
+  mode?: number
+  /** Allow replacing existing files. */
+  replace?: boolean
+}
+
+/** Options for `Patch.copyDir()` and `Patch.symlink()`. */
+export interface PatchReplaceOptions {
+  /** Allow replacing existing files/directories. */
+  replace?: boolean
+}
+
+/** Network policy rule action. */
+export declare const enum PolicyAction {
+  Allow = 'allow',
+  Deny = 'deny'
+}
+
+/** Network policy rule direction. */
+export declare const enum PolicyDirection {
+  Outbound = 'outbound',
+  Inbound = 'inbound'
+}
+
+/** Network policy rule protocol. */
+export declare const enum PolicyProtocol {
+  Tcp = 'tcp',
+  Udp = 'udp',
+  Icmpv4 = 'icmpv4',
+  Icmpv6 = 'icmpv6'
+}
+
+/** A network policy rule. */
+export interface PolicyRule {
+  /** "allow" or "deny". */
+  action: string
+  /** "outbound" or "inbound". */
+  direction?: string
+  /**
+   * Destination filter. One of:
+   * - "*" — any destination
+   * - "1.2.3.4/24" — CIDR notation
+   * - "example.com" — exact domain
+   * - ".example.com" — domain suffix
+   * - "loopback", "private", "link-local", "metadata", "multicast" — destination group
+   */
+  destination?: string
+  /** Protocol filter: "tcp", "udp", "icmpv4", "icmpv6". */
+  protocol?: string
+  /** Port or port range (e.g. 443 or "8000-9000"). */
+  port?: string
+}
+
+/** Image pull policy. */
+export declare const enum PullPolicy {
+  Always = 'always',
+  IfMissing = 'if-missing',
+  Never = 'never'
+}
+
+/** Registry credentials for pulling private images. */
+export interface RegistryCredentials {
+  username: string
+  password: string
+}
+
+/** Configuration for creating a sandbox. */
+export interface SandboxConfig {
+  /** Unique sandbox name. */
+  name: string
+  /** OCI image ref (e.g. "python:3.12"), host path, or disk image path. */
+  image: string
+  /** Guest memory in MiB (default: 512). */
+  memoryMib?: number
+  /** Virtual CPU count (default: 1). */
+  cpus?: number
+  /** Working directory inside the guest. */
+  workdir?: string
+  /** Default shell binary path. */
+  shell?: string
+  /** Override image entrypoint. */
+  entrypoint?: Array<string>
+  /** Override image cmd. */
+  cmd?: Array<string>
+  /** Guest hostname. */
+  hostname?: string
+  /** User to run as (UID or name). */
+  user?: string
+  /** Environment variables. */
+  env?: Record<string, string>
+  /** Named scripts that can be run via `sandbox.run(name)`. */
+  scripts?: Record<string, string>
+  /** Volume mounts keyed by guest path. */
+  volumes?: Record<string, MountConfig>
+  /** Rootfs patches applied before boot. */
+  patches?: Array<PatchConfig>
+  /** Image pull policy: "always", "if-missing", or "never". */
+  pullPolicy?: string
+  /** Log level: "trace", "debug", "info", "warn", "error". */
+  logLevel?: string
+  /** Kill any existing sandbox with the same name before creating. */
+  replace?: boolean
+  /** Suppress log output. */
+  quietLogs?: boolean
+  /** Arbitrary key-value labels. */
+  labels?: Record<string, string>
+  /** Signal to send on stop (default: SIGTERM). */
+  stopSignal?: string
+  /** Maximum run duration in seconds. */
+  maxDurationSecs?: number
+  /** Registry credentials for pulling private images. */
+  registryAuth?: RegistryCredentials
+  /** Port mappings: host_port → guest_port (TCP). */
+  ports?: Record<string, number>
+  /** Network configuration. */
+  network?: NetworkConfig
+  /**
+   * Secret entries. Created with `Secret.env()`.
+   *
+   * ```js
+   * import { Secret } from 'microsandbox'
+   * secrets: [
+   *     Secret.env("OPENAI_API_KEY", { value: "sk-...", allowHosts: ["api.openai.com"] }),
+   * ]
+   * ```
+   */
+  secrets?: Array<SecretEntry>
+}
+
+/** Lightweight handle info for a sandbox from the database. */
+export interface SandboxInfo {
+  name: string
+  /** "running", "stopped", "crashed", or "draining". */
+  status: string
+  configJson: string
+  createdAt?: number
+  updatedAt?: number
+}
+
+/** Point-in-time resource metrics for a sandbox. */
+export interface SandboxMetrics {
+  cpuPercent: number
+  memoryBytes: number
+  memoryLimitBytes: number
+  diskReadBytes: number
+  diskWriteBytes: number
+  netRxBytes: number
+  netTxBytes: number
+  /** Uptime in milliseconds. */
+  uptimeMs: number
+  /** Timestamp as milliseconds since Unix epoch. */
+  timestampMs: number
+}
+
+/** Sandbox status. */
+export declare const enum SandboxStatus {
+  Running = 'running',
+  Stopped = 'stopped',
+  Crashed = 'crashed',
+  Draining = 'draining'
+}
+
+/**
+ * A secret entry for the `secrets` array on `SandboxConfig`.
+ *
+ * Created via `Secret.env()`:
+ * ```js
+ * import { Secret } from 'microsandbox'
+ * Secret.env("OPENAI_API_KEY", { value: "sk-...", allowHosts: ["api.openai.com"] })
+ * ```
+ */
+export interface SecretEntry {
+  /** Environment variable name. */
+  envVar: string
+  /** The secret value (never enters the sandbox). */
+  value: string
+  /** Allowed hosts (exact match, e.g. `["api.openai.com"]`). */
+  allowHosts?: Array<string>
+  /** Allowed host patterns (wildcard, e.g. `["*.openai.com"]`). */
+  allowHostPatterns?: Array<string>
+  /** Custom placeholder (auto-generated as `$MSB_<ENV_VAR>` if omitted). */
+  placeholder?: string
+  /** Require verified TLS identity before substitution (default: true). */
+  requireTls?: boolean
+  /** Violation action: "block", "block-and-log" (default), "block-and-terminate". */
+  onViolation?: string
+}
+
+/** Options for `Secret.env()`. */
+export interface SecretEnvOptions {
+  /** The secret value (never enters the sandbox). */
+  value: string
+  /** Allowed hosts (exact match, e.g. `["api.openai.com"]`). */
+  allowHosts?: Array<string>
+  /** Allowed host patterns (wildcard, e.g. `["*.openai.com"]`). */
+  allowHostPatterns?: Array<string>
+  /** Custom placeholder (auto-generated as `$MSB_<ENV_VAR>` if omitted). */
+  placeholder?: string
+  /** Require verified TLS identity before substitution (default: true). */
+  requireTls?: boolean
+  /** Violation action: "block", "block-and-log" (default), "block-and-terminate". */
+  onViolation?: string
+}
+
+/** TLS interception configuration. */
+export interface TlsConfig {
+  /** Domains to bypass (no interception). Supports "*.suffix" wildcards. */
+  bypass?: Array<string>
+  /** Verify upstream server certificates (default: true). */
+  verifyUpstream?: boolean
+  /** Ports to intercept (default: [443]). */
+  interceptedPorts?: Array<number>
+  /** Block QUIC on intercepted ports (default: false). */
+  blockQuic?: boolean
+  /** Path to custom CA certificate PEM file. */
+  caCert?: string
+  /** Path to custom CA private key PEM file. */
+  caKey?: string
+}
+
+/** Options for tmpfs mounts. */
+export interface TmpfsOptions {
+  /** Size limit in MiB. */
+  sizeMib?: number
+  /** Read-only mount. */
+  readonly?: boolean
+}
+
+/** Action to take when a secret is sent to a disallowed host. */
+export declare const enum ViolationAction {
+  /** Silently block the request. */
+  Block = 'block',
+  /** Block the request and log the violation. */
+  BlockAndLog = 'block-and-log',
+  /** Block the request and terminate the sandbox. */
+  BlockAndTerminate = 'block-and-terminate'
+}
+
+/** Volume configuration for creation. */
+export interface VolumeConfig {
+  name: string
+  /** Size quota in MiB. */
+  quotaMib?: number
+  /** Arbitrary key-value labels. */
+  labels?: Record<string, string>
+}
+
+/** Volume handle info from the database. */
+export interface VolumeInfo {
+  name: string
+  quotaMib?: number
+  usedBytes: number
+  labels: Record<string, string>
+  createdAt?: number
+}