// @generated by microsandbox-types. Do not edit by hand.

export type JsonValue = number | string | boolean | Array<JsonValue> | { [key in string]: JsonValue } | null;

export type DiskImageFormat = "Qcow2" | "Raw" | "Vmdk";

export type OciRootfsSource = {
/**
 * OCI image reference (e.g. `python`).
 */
reference: string,
/**
 * Writable overlay upper size in MiB.
 */
upper_size_mib?: number | null, };

export type RootfsSource = { "Bind": string } | { "Oci": OciRootfsSource } | { "DiskImage": {
/**
 * Path to the disk image file on the host.
 */
path: string,
/**
 * Disk image format.
 */
format: DiskImageFormat,
/**
 * Inner filesystem type (optional; auto-detected if absent).
 */
fstype: string | null, } };

export type PullPolicy = "IfMissing" | "Always" | "Never";

export type StatVirtualization = "strict" | "relaxed" | "off";

export type HostPermissions = "private" | "mirror";

export type SecurityProfile = "default" | "restricted";

export type MountOptions = {
/**
 * Whether the mount is read-only.
 *
 * Guest writes fail with the kernel's read-only filesystem behavior. Virtiofs-backed mounts also reject writes on the host-side filesystem server as defense in depth.
 */
readonly: boolean,
/**
 * Whether direct execution from the mount is disabled.
 *
 * This prevents `execve` of binaries or scripts located on the mount. Interpreters can still read files from the mount, for example `sh /mnt/script.sh`, because the interpreter itself executes from a different filesystem.
 */
noexec: boolean,
/**
 * Whether setuid and setgid privilege elevation from files on the mount is ignored.
 */
nosuid: boolean,
/**
 * Whether device files on the mount are ignored.
 */
nodev: boolean, };

export type VolumeKind = "Directory" | "Disk";

export type VolumeSpec = {
/**
 * Volume name.
 */
name: string,
/**
 * Storage kind.
 */
kind: VolumeKind,
/**
 * Size quota in MiB. `None` means unlimited.
 */
quota_mib: number | null,
/**
 * Disk capacity in MiB. Required for disk volumes.
 */
capacity_mib: number | null,
/**
 * Labels for organization.
 */
labels: Array<[string, string]>, };

export type NamedVolumeMode = "Existing" | "Create" | "EnsureExists";

export type NamedVolumeCreate = {
/**
 * Creation behavior for this named volume mount.
 */
mode: NamedVolumeMode,
/**
 * Volume name to create or ensure exists.
 */
name: string,
/**
 * Storage kind to create or ensure exists.
 */
kind: VolumeKind,
/**
 * Directory quota in MiB, if configured.
 */
quota_mib: number | null,
/**
 * Disk capacity in MiB, if configured.
 */
capacity_mib: number | null,
/**
 * Labels to attach to newly-created volumes.
 */
labels: Array<[string, string]>, };

export type VolumeMount = { "type": "Bind",
/**
 * Host path to bind mount.
 */
host: string,
/**
 * Guest mount path.
 */
guest: string,
/**
 * Guest mount behavior.
 */
options: MountOptions,
/**
 * Guest-visible stat virtualization policy.
 */
stat_virtualization: StatVirtualization,
/**
 * Host permission propagation policy.
 */
host_permissions: HostPermissions,
/**
 * Guest-write byte budget in MiB.
 *
 * Bounds how much the guest may add beyond the directory's existing
 * contents. `None` applies the protective default at spawn time; set a
 * value to override it.
 */
quota_mib: number | null, } | { "type": "Named",
/**
 * Volume name.
 */
name: string,
/**
 * Guest mount path.
 */
guest: string,
/**
 * Creation metadata for sandbox-time named volume provisioning.
 *
 * This is transient and intentionally skipped when sandbox configs are persisted; restarting a sandbox mounts the already-created volume.
 */
create: NamedVolumeCreate | null,
/**
 * Guest mount behavior.
 */
options: MountOptions,
/**
 * Guest-visible stat virtualization policy.
 */
stat_virtualization: StatVirtualization,
/**
 * Host permission propagation policy.
 */
host_permissions: HostPermissions, } | { "type": "Tmpfs",
/**
 * Guest mount path.
 */
guest: string,
/**
 * Size limit in MiB.
 */
size_mib: number | null,
/**
 * Guest mount behavior.
 */
options: MountOptions, } | { "type": "DiskImage",
/**
 * Host path to the disk image file.
 */
host: string,
/**
 * Guest mount path.
 */
guest: string,
/**
 * Disk image format.
 */
format: DiskImageFormat,
/**
 * Inner filesystem type. When `None`, agentd probes `/proc/filesystems`.
 */
fstype: string | null,
/**
 * Guest mount behavior.
 */
options: MountOptions, };

export type Patch = { "Text": {
/**
 * Absolute guest path, such as `/etc/app.conf`.
 */
path: string,
/**
 * Text content to write.
 */
content: string,
/**
 * File permissions, such as `0o644`. `None` uses the default.
 */
mode: number | null,
/**
 * Allow replacing a file that already exists in the rootfs.
 */
replace: boolean, } } | { "File": {
/**
 * Absolute guest path.
 */
path: string,
/**
 * Raw byte content to write.
 */
content: Array<number>,
/**
 * File permissions, such as `0o644`. `None` uses the default.
 */
mode: number | null,
/**
 * Allow replacing a file that already exists in the rootfs.
 */
replace: boolean, } } | { "CopyFile": {
/**
 * Host path to copy from.
 */
src: string,
/**
 * Absolute guest destination path.
 */
dst: string,
/**
 * File permissions. `None` preserves source permissions.
 */
mode: number | null,
/**
 * Allow replacing a file that already exists in the rootfs.
 */
replace: boolean, } } | { "CopyDir": {
/**
 * Host directory to copy from.
 */
src: string,
/**
 * Absolute guest destination path.
 */
dst: string,
/**
 * Allow replacing files that already exist in the rootfs.
 */
replace: boolean, } } | { "Symlink": {
/**
 * Symlink target path.
 */
target: string,
/**
 * Absolute guest path where the symlink is created.
 */
link: string,
/**
 * Allow replacing a path that already exists in the rootfs.
 */
replace: boolean, } } | { "Mkdir": {
/**
 * Absolute guest path.
 */
path: string,
/**
 * Directory permissions, such as `0o755`. `None` uses the default.
 */
mode: number | null, } } | { "Remove": {
/**
 * Absolute guest path to remove.
 */
path: string, } } | { "Append": {
/**
 * Absolute guest path of the file to append to.
 */
path: string,
/**
 * Content to append.
 */
content: string, } };

export type NetworkSpec = {
/**
 * Whether networking is enabled for this sandbox.
 */
enabled: boolean,
/**
 * Guest interface overrides for the local network engine.
 */
interface: JsonValue | null,
/**
 * Host-to-guest port mappings.
 */
ports: Array<PublishedPortSpec>,
/**
 * Egress and ingress policy subdocument.
 */
policy: JsonValue | null,
/**
 * DNS interception and filtering subdocument.
 */
dns: JsonValue | null,
/**
 * TLS interception subdocument.
 */
tls: JsonValue | null,
/**
 * Secret injection subdocument.
 */
secrets: JsonValue | null,
/**
 * Max concurrent guest connections.
 */
max_connections: number | null,
/**
 * Whether to copy trusted host CAs into the guest at boot.
 */
trust_host_cas: boolean, };

export type PublishedPortSpec = {
/**
 * Host-side port to bind.
 */
host_port: number,
/**
 * Guest-side port to forward to.
 */
guest_port: number,
/**
 * Transport protocol.
 */
protocol: PortProtocol,
/**
 * Host address to bind. Defaults to loopback.
 */
host_bind: string, };

export type PortProtocol = "tcp" | "udp";

export type HandoffInit = {
/**
 * Init binary: absolute path inside the guest rootfs, or the literal `auto`.
 */
cmd: string,
/**
 * Supplemental argv. `argv[0]` is implicitly `cmd`.
 */
args: Array<string>,
/**
 * Extra env vars merged on top of the inherited env.
 */
env: Array<[string, string]>, };

export type SandboxPolicy = {
/**
 * Whether the sandbox is ephemeral.
 *
 * Ephemeral sandboxes are one-off: the host runtime that owns the
 * process removes the persisted DB row and on-disk state when the VM
 * reaches a terminal status, and other host runtimes opportunistically
 * clean up ephemeral leftovers from runtimes that died before they
 * could self-clean. Defaults to `false` (persistent); named and created
 * sandboxes stay inspectable and restartable after they stop.
 */
ephemeral: boolean,
/**
 * Hard cap on total sandbox lifetime in seconds. `None` = run forever.
 */
max_duration_secs: number | null,
/**
 * Idle timeout in seconds. `None` = no idle detection.
 */
idle_timeout_secs: number | null, };

export type SnapshotDestination = { "Name": string } | { "Path": string };

export type SnapshotSpec = {
/**
 * Name of the source sandbox. Must be stopped.
 */
source_sandbox: string,
/**
 * Where to write the artifact.
 */
destination: SnapshotDestination,
/**
 * User-supplied labels.
 */
labels: Array<[string, string]>,
/**
 * Overwrite an existing artifact at the destination.
 */
force: boolean,
/**
 * Compute and record upper-layer content integrity at creation time.
 */
record_integrity: boolean, };

export type SandboxSpec = {
/**
 * Unique sandbox name.
 */
name: string,
/**
 * Root filesystem source.
 */
image: RootfsSource,
/**
 * CPU and memory resources.
 */
resources: SandboxResources,
/**
 * Guest runtime options.
 */
runtime: SandboxRuntimeOptions,
/**
 * Environment variables visible to commands in the sandbox.
 */
env: Array<EnvVar>,
/**
 * User-defined labels attached to the sandbox.
 */
labels: { [key in string]: string },
/**
 * Sandbox-wide resource limits inherited by guest processes.
 */
rlimits: Array<Rlimit>,
/**
 * Volume mounts.
 */
mounts: Array<VolumeMount>,
/**
 * Rootfs patches applied before VM start.
 */
patches: Array<Patch>,
/**
 * Network specification.
 */
network: NetworkSpec,
/**
 * Hand off PID 1 to a guest init binary after agentd setup.
 */
init: HandoffInit | null,
/**
 * Pull policy for OCI images.
 */
pull_policy: PullPolicy,
/**
 * In-guest security profile.
 */
security_profile: SecurityProfile,
/**
 * Sandbox lifecycle policy.
 */
lifecycle: SandboxPolicy, };

export type SandboxResources = {
/**
 * Number of virtual CPUs.
 */
cpus: number,
/**
 * Guest memory in MiB.
 */
memory_mib: number, };

export type SandboxRuntimeOptions = {
/**
 * Working directory inside the guest.
 */
workdir: string | null,
/**
 * Default shell for scripts and interactive sessions.
 */
shell: string | null,
/**
 * Named scripts available inside the guest.
 */
scripts: { [key in string]: string },
/**
 * Image entrypoint override.
 */
entrypoint: Array<string> | null,
/**
 * Image command override.
 */
cmd: Array<string> | null,
/**
 * Guest hostname override.
 */
hostname: string | null,
/**
 * Guest user identity override.
 */
user: string | null,
/**
 * Runtime log verbosity.
 */
log_level: SandboxLogLevel | null,
/**
 * Metrics sampling interval in milliseconds. `None` disables sampling.
 */
metrics_sample_interval_ms: number | null,
/**
 * Force-disable metrics sampling regardless of `metrics_sample_interval_ms`.
 */
disable_metrics_sample: boolean, };

export type EnvVar = {
/**
 * Environment variable name.
 */
key: string,
/**
 * Environment variable value.
 */
value: string, };

export type SandboxLogLevel = "error" | "warn" | "info" | "debug" | "trace";

export type RlimitResource = "Cpu" | "Fsize" | "Data" | "Stack" | "Core" | "Rss" | "Nproc" | "Nofile" | "Memlock" | "As" | "Locks" | "Sigpending" | "Msgqueue" | "Nice" | "Rtprio" | "Rttime";

export type Rlimit = {
/**
 * Resource type.
 */
resource: RlimitResource,
/**
 * Soft limit (can be raised up to hard limit by the process).
 */
soft: number,
/**
 * Hard limit (ceiling, requires privileges to raise).
 */
hard: number, };

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

export type CloudCreateSandboxRequest = {
/**
 * User-facing sandbox name.
 */
name: string,
/**
 * OCI image reference to run.
 */
image: string,
/**
 * Virtual CPU count.
 */
vcpus: number,
/**
 * Guest memory in MiB.
 */
memory_mib: number,
/**
 * Environment variables injected into the sandbox.
 */
env: { [key in string]: string },
/**
 * Whether the sandbox should be removed when its allocation terminates.
 */
ephemeral: boolean,
/**
 * Working directory inside the guest.
 */
workdir?: string | null,
/**
 * Default shell inside the guest.
 */
shell?: string | null,
/**
 * OCI entrypoint override.
 */
entrypoint?: Array<string> | null,
/**
 * Guest hostname override.
 */
hostname?: string | null,
/**
 * Guest user identity.
 */
user?: string | null,
/**
 * Runtime log verbosity.
 */
log_level?: string | null,
/**
 * Named scripts mounted into the guest.
 */
scripts?: { [key in string]: string },
/**
 * Hard sandbox lifetime cap in seconds.
 */
max_duration_secs?: number | null,
/**
 * Idle timeout in seconds.
 */
idle_timeout_secs?: number | null, };

export type CloudSandbox = {
/**
 * Server-side UUID.
 */
id: string,
/**
 * Owning org's UUID.
 */
org_id: string,
/**
 * User-facing sandbox name.
 */
name: string,
/**
 * Current lifecycle status.
 */
status: CloudSandboxStatus,
/**
 * Create request stored by the cloud control plane.
 */
config: CloudCreateSandboxRequest,
/**
 * Whether the sandbox should be removed when its allocation terminates.
 */
ephemeral: boolean,
/**
 * Creation timestamp.
 */
created_at: string,
/**
 * Last start timestamp, when known.
 */
started_at?: string | null,
/**
 * Last stop timestamp, when known.
 */
stopped_at?: string | null,
/**
 * Last failure reason, when any.
 */
last_error?: string | null, };

export type CloudSandboxStatus = "created" | "starting" | "running" | "stopping" | "stopped" | "failed";

export type CloudPaginated<T> = {
/**
 * Page of response items.
 */
data: Array<T>,
/**
 * Cursor for the next page, when one exists.
 */
next_cursor?: string | null, };

export type CloudMessageResponse = {
/**
 * Human-readable response message.
 */
message: string, };

export type CloudErrorBody = {
/**
 * Flat machine-readable error code, when returned in this shape.
 */
code?: string | null,
/**
 * Flat human-readable error message, when returned in this shape.
 */
message?: string | null,
/**
 * Nested error object returned by the API error responder.
 */
error?: CloudErrorDetails | null, };

export type CloudErrorDetails = {
/**
 * Machine-readable error code.
 */
code?: string | null,
/**
 * Human-readable error message.
 */
message?: string | null, };