> ## Documentation Index > Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create a sandbox > By default, the sandbox is created without starting. Use `start=true` to start it immediately and `wait_for=running` to wait until it is ready. ## OpenAPI ````yaml /api-reference/openapi.personal.json post /v1/orgs/{slug}/sandboxes openapi: 3.1.0 info: title: Personal token API description: User-scoped API for account and organization management. version: 0.1.0 servers: - url: https://api.microsandbox.dev security: - bearer: [] paths: /v1/orgs/{slug}/sandboxes: post: tags: - Sandboxes summary: Create a sandbox description: |- By default, the sandbox is created without starting. Use `start=true` to start it immediately and `wait_for=running` to wait until it is ready. operationId: create_sandbox parameters: - name: slug in: path description: Organization slug required: true schema: type: string - name: start in: query description: >- If `true`, durably queue the sandbox for immediate orchestrator dispatch. required: false schema: type: boolean - name: wait_for in: query description: Optional lifecycle state to wait for after durable start admission. required: false schema: oneOf: - type: 'null' - $ref: '#/components/schemas/SandboxWaitFor' - name: wait_timeout in: query description: Server-side wait budget in seconds; valid only with `wait_for`. required: false schema: type: - integer - 'null' format: int64 minimum: 0 requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateSandboxRequest' required: true responses: '200': description: Sandbox created content: application/json: schema: $ref: '#/components/schemas/SandboxResponse' '400': description: Invalid request '401': description: Unauthorized '409': description: Name already exists '429': description: Readiness wait capacity exhausted '502': description: Orchestrator unreachable security: - bearer: [] components: schemas: SandboxWaitFor: type: string enum: - running description: Lifecycle state an opt-in create request may wait to observe. CreateSandboxRequest: allOf: - $ref: '#/components/schemas/CloudCreateSandboxRequest' description: |- The microsandbox create request - source, resources, runtime, env, mounts, network, and lifecycle - flattened onto the request body. - type: object properties: registry: $ref: '#/components/schemas/RegistrySelection' description: >- Registry-credential selection for the image pull. Absent ⇒ `Auto` (infer the credential from the image's registry host). Credential-only: this never changes *where* the image is pulled from - the image string controls that - only *which* stored credential, if any, is presented. slug: type: - string - 'null' description: >- Optional globally-unique slug - the SSH username token. Lowercase letters, digits, and single hyphens; 3-63 chars. Omitted ⇒ a dictionary slug is generated. Must be globally unique (409 on conflict). description: >- What the user sends in `POST /v1/sandboxes`. The body carries the shared microsandbox [`CloudCreateSandboxRequest`] union. Its source-specific and common [`CloudSandboxSpec`] fields stay flat on the wire beside the cloud-only SSH `slug` and registry-credential selection. SandboxResponse: type: object description: Sandbox details and resolved configuration. required: - id - org_id - name - slug - status - ephemeral - created_at properties: automatic_recovery_ends_at: type: - string - 'null' format: date-time description: When an explicit recovery choice becomes necessary. created_at: type: string format: date-time ephemeral: type: boolean id: type: string format: uuid last_failure_message: type: - string - 'null' description: Human-readable reason for the last failure. name: type: string org_id: type: string format: uuid slug: type: string spec: oneOf: - type: 'null' - $ref: '#/components/schemas/SandboxSpecResponse' description: Curated projection of the resolved spec; absent until resolved. started_at: type: - string - 'null' format: date-time description: Latest run's start time; `null` if the sandbox has never run. status: $ref: '#/components/schemas/SandboxStatus' status_reason: oneOf: - type: 'null' - $ref: '#/components/schemas/SandboxStatusReason' description: Scheduler condition while `status` is `starting`. stopped_at: type: - string - 'null' format: date-time description: Latest run's stop time; `null` while open or never run. temporarily_unavailable_since: type: - string - 'null' format: date-time description: When the current worker outage became user-visible. CloudCreateSandboxRequest: oneOf: - allOf: - $ref: '#/components/schemas/CloudSandboxSpec' description: Settings shared by every sandbox source. - type: object required: - reference properties: patches: type: array items: $ref: '#/components/schemas/CloudPatch' description: Rootfs patches applied before VM start. pull_policy: $ref: '#/components/schemas/CloudPullPolicy' description: OCI image pull policy. reference: type: string description: OCI image reference. resources: $ref: '#/components/schemas/CloudSandboxResources' description: CPU, memory, and writable-disk resources. - type: object description: Create a sandbox from an OCI image. required: - source properties: source: type: string enum: - oci description: Create a sandbox from an OCI image. - allOf: - $ref: '#/components/schemas/CloudSandboxSpec' description: Settings shared by every sandbox source. - type: object required: - path properties: patches: type: array items: $ref: '#/components/schemas/CloudPatch' description: Rootfs patches applied before VM start. path: type: string description: Host directory used as the root filesystem. resources: $ref: '#/components/schemas/CloudSandboxComputeResources' description: CPU and memory resources. - type: object description: Create a sandbox from a host directory. required: - source properties: source: type: string enum: - bind description: Create a sandbox from a host directory. - allOf: - $ref: '#/components/schemas/CloudSandboxSpec' description: Settings shared by every sandbox source. - type: object required: - path - format properties: format: $ref: '#/components/schemas/CloudDiskImageFormat' description: Disk image format. fstype: type: - string - 'null' description: >- Inner filesystem type, when it cannot be detected automatically. patches: type: array items: $ref: '#/components/schemas/CloudPatch' description: Rootfs patches applied before VM start. path: type: string description: Host path to the disk image. resources: $ref: '#/components/schemas/CloudSandboxComputeResources' description: CPU and memory resources. - type: object description: Create a sandbox from a disk image file. required: - source properties: source: type: string enum: - disk_image description: Create a sandbox from a disk image file. - allOf: - $ref: '#/components/schemas/CloudSandboxSpec' description: Settings shared by every sandbox source. - type: object required: - disk_snapshot_ref properties: disk_snapshot_ref: $ref: '#/components/schemas/CloudSnapshotLocation' description: Disk snapshot to restore. pull_policy: $ref: '#/components/schemas/CloudPullPolicy' description: >- Pull policy used if the snapshot's pinned base image must be fetched. resources: $ref: '#/components/schemas/CloudSandboxComputeResources' description: CPU and memory resources. - type: object description: Create a fresh-booted sandbox from a disk snapshot. required: - source properties: source: type: string enum: - disk_snapshot description: Create a fresh-booted sandbox from a disk snapshot. description: |- Wire shape of a cloud sandbox create request body. Each root filesystem origin is a distinct source variant. The common sandbox settings remain flat beside the source-specific fields. Legacy requests carrying an `image` object are accepted during migration. RegistrySelection: oneOf: - type: object description: Infer a stored credential from the image registry host. required: - mode properties: mode: type: string enum: - auto - type: object description: Force an anonymous pull. required: - mode properties: mode: type: string enum: - anonymous - type: object description: Use an already-stored organization credential. required: - credential_id - mode properties: credential_id: type: string format: uuid description: Id of a configured `OrgRegistryCredential` belonging to the org. mode: type: string enum: - specific - type: object description: Use plaintext credentials for this create-and-start operation only. required: - username - password - mode properties: mode: type: string enum: - inline password: type: string format: password description: Registry password or access token. Always redacted from `Debug`. username: type: string description: Registry username. description: >- Registry credential selection accepted on sandbox-create requests. `Inline` is deliberately request-only: its plaintext fields must be vaulted before persistence and must never enter the sandbox row, a worker launch definition, a log, or an API response. SandboxSpecResponse: type: object description: Resolved sandbox configuration. Secret values are omitted. required: - resources - runtime - env - labels - rlimits - lifecycle - mounts - network properties: env: type: array items: $ref: '#/components/schemas/EnvVar' description: Environment variables. image: type: - string - 'null' description: OCI image reference the sandbox boots; `null` for a non-OCI rootfs. labels: type: object description: User-defined labels. additionalProperties: type: string propertyNames: type: string lifecycle: $ref: '#/components/schemas/SandboxPolicy' description: Lifecycle policy. mounts: type: array items: $ref: '#/components/schemas/SandboxMountResponse' description: Volume mounts - guest path + options only; volume ids omitted. network: $ref: '#/components/schemas/SandboxNetworkResponse' description: Network config - secret values/vault paths omitted. resources: $ref: '#/components/schemas/CloudSandboxResources' description: CPU, memory, and writable-disk sizing. rlimits: type: array items: $ref: '#/components/schemas/Rlimit' description: Resource limits. runtime: $ref: '#/components/schemas/SandboxRuntimeOptions' description: Guest runtime options. SandboxStatus: type: string description: Sandbox lifecycle status. enum: - created - starting - running - temporarily_unavailable - recovery_decision_required - stopping - stopped - failed SandboxStatusReason: type: string description: |- Why a submitted sandbox is still waiting for placement on a worker. Only meaningful while `status` is `starting`. enum: - scheduling - insufficient_capacity CloudSandboxSpec: type: object description: Settings shared by every cloud sandbox creation source. required: - name properties: env: type: array items: $ref: '#/components/schemas/EnvVar' description: Environment variables visible to commands in the sandbox. default: [] init: oneOf: - type: 'null' - $ref: '#/components/schemas/HandoffInit' description: Hand off PID 1 to a guest init binary after agentd setup. default: null labels: type: object description: User-defined labels attached to the sandbox. default: {} additionalProperties: type: string propertyNames: type: string lifecycle: oneOf: - $ref: '#/components/schemas/SandboxPolicy' description: Sandbox lifecycle policy. default: ephemeral: false idle_timeout_secs: null max_duration_secs: null mounts: type: array items: $ref: '#/components/schemas/CloudVolumeMount' description: Volume mounts. default: [] name: type: string description: Unique sandbox name. default: '' network: oneOf: - $ref: '#/components/schemas/CloudNetworkSpec' description: Network specification. default: enabled: true strict: false rlimits: type: array items: $ref: '#/components/schemas/CloudRlimit' description: Sandbox-wide resource limits inherited by guest processes. default: [] runtime: oneOf: - $ref: '#/components/schemas/CloudSandboxRuntimeOptions' description: Guest runtime options. default: cmd: null entrypoint: null log_level: null scripts: {} shell: null user: null workdir: null security_profile: oneOf: - $ref: '#/components/schemas/SecurityProfile' description: In-guest security profile. default: default CloudPatch: oneOf: - type: object description: Write text content to a file. required: - path - content - replace - type properties: content: type: string description: Text content to write. mode: type: - integer - 'null' format: int32 description: File permissions, such as `0o644`. `None` uses the default. minimum: 0 path: type: string description: Absolute guest path, such as `/etc/app.conf`. replace: type: boolean description: Allow replacing a file that already exists in the rootfs. type: type: string enum: - text - type: object description: Write raw bytes to a file. required: - path - content - replace - type properties: content: type: array items: type: integer format: int32 minimum: 0 description: Raw byte content to write. mode: type: - integer - 'null' format: int32 description: File permissions, such as `0o644`. `None` uses the default. minimum: 0 path: type: string description: Absolute guest path. replace: type: boolean description: Allow replacing a file that already exists in the rootfs. type: type: string enum: - file - type: object description: Copy a file from the host into the rootfs. required: - src - dst - replace - type properties: dst: type: string description: Absolute guest destination path. mode: type: - integer - 'null' format: int32 description: File permissions. `None` preserves source permissions. minimum: 0 replace: type: boolean description: Allow replacing a file that already exists in the rootfs. src: type: string description: Host path to copy from. type: type: string enum: - copy_file - type: object description: Copy a directory from the host into the rootfs. required: - src - dst - replace - type properties: dst: type: string description: Absolute guest destination path. replace: type: boolean description: Allow replacing files that already exist in the rootfs. src: type: string description: Host directory to copy from. type: type: string enum: - copy_dir - type: object description: Create a symlink. required: - target - link - replace - type properties: link: type: string description: Absolute guest path where the symlink is created. replace: type: boolean description: Allow replacing a path that already exists in the rootfs. target: type: string description: Symlink target path. type: type: string enum: - symlink - type: object description: Create a directory. required: - path - type properties: mode: type: - integer - 'null' format: int32 description: Directory permissions, such as `0o755`. `None` uses the default. minimum: 0 path: type: string description: Absolute guest path. type: type: string enum: - mkdir - type: object description: Remove a file or directory. required: - path - type properties: path: type: string description: Absolute guest path to remove. type: type: string enum: - remove - type: object description: Append content to an existing file. required: - path - content - type properties: content: type: string description: Content to append. path: type: string description: Absolute guest path of the file to append to. type: type: string enum: - append description: >- Filesystem change applied before the sandbox starts. The type field selects the operation. CloudPullPolicy: type: string description: Cloud pull policy. Twin of domain [`PullPolicy`] with a snake_case wire. enum: - if_missing - always - never CloudSandboxResources: type: object description: Cloud resource request. properties: disk_size_mib: type: - integer - 'null' format: int32 description: Writable disk size in MiB. Applies only to OCI root filesystems. default: null minimum: 0 memory_mib: type: integer format: int32 description: Guest memory in MiB. default: 512 minimum: 0 vcpus: type: integer format: int32 description: Number of virtual CPUs. default: 1 minimum: 0 CloudSandboxComputeResources: type: object description: >- CPU and memory request shared by sources without a managed writable disk. properties: memory_mib: type: integer format: int32 description: Guest memory in MiB. default: 512 minimum: 0 vcpus: type: integer format: int32 description: Number of virtual CPUs. default: 1 minimum: 0 CloudDiskImageFormat: type: string description: >- Disk image format for cloud disk-image sources. Twin of [`DiskImageFormat`] with a snake_case wire. enum: - qcow2 - raw - vmdk CloudSnapshotLocation: oneOf: - type: object description: Held in managed snapshot storage. required: - id - type properties: id: type: string description: Identifier of the stored artifact. type: type: string enum: - managed - type: object description: Stored in a directory on a mounted host volume. required: - path - type properties: path: type: string description: Artifact directory path on the host volume. type: type: string enum: - host_volume description: Public locator for a managed or host-volume cloud snapshot. EnvVar: type: object description: Environment variable entry. required: - key - value properties: key: type: string description: Environment variable name. value: type: string description: Environment variable value. SandboxPolicy: type: object description: Sandbox lifecycle policy. properties: ephemeral: type: boolean description: >- 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. idle_timeout_secs: type: - integer - 'null' format: int64 description: Idle timeout in seconds. `None` = no idle detection. minimum: 0 max_duration_secs: type: - integer - 'null' format: int64 description: Hard cap on total sandbox lifetime in seconds. `None` = run forever. minimum: 0 SandboxMountResponse: oneOf: - type: object description: Host-subpath bind mount. required: - guest - options - stat_virtualization - host_permissions - type properties: guest: type: string host_permissions: $ref: '#/components/schemas/HostPermissions' options: $ref: '#/components/schemas/MountOptions' quota_mib: type: - integer - 'null' format: int32 minimum: 0 stat_virtualization: $ref: '#/components/schemas/StatVirtualization' type: type: string enum: - Bind - type: object description: Named-volume mount. required: - guest - options - stat_virtualization - host_permissions - type properties: guest: type: string host_permissions: $ref: '#/components/schemas/HostPermissions' options: $ref: '#/components/schemas/MountOptions' stat_virtualization: $ref: '#/components/schemas/StatVirtualization' type: type: string enum: - Named - type: object description: Guest-memory tmpfs. required: - guest - options - type properties: guest: type: string options: $ref: '#/components/schemas/MountOptions' size_mib: type: - integer - 'null' format: int32 minimum: 0 type: type: string enum: - Tmpfs - type: object description: Disk-image mount. required: - guest - format - options - type properties: format: $ref: '#/components/schemas/DiskImageFormat' fstype: type: - string - 'null' guest: type: string options: $ref: '#/components/schemas/MountOptions' type: type: string enum: - DiskImage description: >- A mount, projected for the user: guest path + options, never the resolved volume id / source. SandboxNetworkResponse: type: object description: Network config, projected for the user. Secrets drop their vault path. required: - enabled - ports - trust_host_cas properties: dns: oneOf: - type: 'null' - $ref: '#/components/schemas/DnsConfig' enabled: type: boolean interface: oneOf: - type: 'null' - $ref: '#/components/schemas/InterfaceOverrides' max_connections: type: - integer - 'null' minimum: 0 policy: oneOf: - type: 'null' - $ref: '#/components/schemas/NetworkPolicy' ports: type: array items: $ref: '#/components/schemas/PublishedPortSpec' secrets: type: array items: $ref: '#/components/schemas/SandboxSecretResponse' tls: oneOf: - type: 'null' - $ref: '#/components/schemas/TlsConfig' trust_host_cas: type: boolean Rlimit: type: object description: A POSIX resource limit. required: - resource - soft - hard properties: hard: type: integer format: int64 description: Hard limit (ceiling, requires privileges to raise). minimum: 0 resource: $ref: '#/components/schemas/RlimitResource' description: Resource type. soft: type: integer format: int64 description: Soft limit (can be raised up to hard limit by the process). minimum: 0 SandboxRuntimeOptions: type: object description: Guest runtime options for a sandbox. properties: cmd: type: - array - 'null' items: type: string description: Image command override. default: null disable_metrics_sample: type: boolean description: >- Force-disable metrics sampling regardless of `metrics_sample_interval_ms`. default: false entrypoint: type: - array - 'null' items: type: string description: Image entrypoint override. default: null hostname: type: - string - 'null' description: Guest hostname override. default: null log_level: oneOf: - type: 'null' - $ref: '#/components/schemas/SandboxLogLevel' description: Runtime log verbosity. default: null metrics_sample_interval_ms: type: - integer - 'null' format: int64 description: Metrics sampling interval in milliseconds. `None` disables sampling. default: 1000 minimum: 0 scripts: type: object description: Named scripts available inside the guest. default: {} additionalProperties: type: string propertyNames: type: string shell: type: - string - 'null' description: Default shell for scripts and interactive sessions. default: null user: type: - string - 'null' description: Guest user identity override. default: null workdir: type: - string - 'null' description: Working directory inside the guest. default: null HandoffInit: type: object description: Fully-assembled handoff-init specification. required: - cmd properties: args: type: array items: type: string description: Supplemental argv. `argv[0]` is implicitly `cmd`. cmd: type: string description: >- Init binary: absolute path inside the guest rootfs, or the literal `auto`. Always a Linux-style `/`-separated path - never build it with host OS path APIs, whose semantics diverge on Windows (`\` separators, `/sbin/init` treated as relative). env: type: array items: type: array items: false prefixItems: - type: string - type: string description: Extra env vars merged on top of the inherited env. CloudVolumeMount: oneOf: - type: object description: Bind mount a host directory into the guest. required: - host - guest - type properties: guest: type: string description: Guest path to mount at. host: type: string description: Host directory to bind into the guest. host_permissions: $ref: '#/components/schemas/HostPermissions' description: Host permission policy applied to the mount. options: $ref: '#/components/schemas/MountOptions' description: Mount options (read-only, no-exec, …). quota_mib: type: - integer - 'null' format: int32 description: Optional guest-write quota in MiB. minimum: 0 stat_virtualization: $ref: '#/components/schemas/StatVirtualization' description: How guest `stat()` results are virtualized. type: type: string enum: - bind - type: object description: Mount a named volume into the guest. required: - name - guest - type properties: guest: type: string description: Guest path to mount at. host_permissions: $ref: '#/components/schemas/HostPermissions' description: Host permission policy applied to the mount. name: type: string description: Named volume to mount. options: $ref: '#/components/schemas/MountOptions' description: Mount options (read-only, no-exec, …). stat_virtualization: $ref: '#/components/schemas/StatVirtualization' description: How guest `stat()` results are virtualized. type: type: string enum: - named - type: object description: Temporary filesystem backed by guest memory. required: - guest - type properties: guest: type: string description: Guest path to mount at. options: $ref: '#/components/schemas/MountOptions' description: Mount options (read-only, no-exec, …). size_mib: type: - integer - 'null' format: int32 description: Optional size cap in MiB. minimum: 0 type: type: string enum: - tmpfs - type: object description: Mount a disk image file as a virtio-blk device at a guest path. required: - host - guest - format - type properties: format: $ref: '#/components/schemas/CloudDiskImageFormat' description: Disk image format. fstype: type: - string - 'null' description: Inner filesystem type (auto-detected if absent). guest: type: string description: Guest path to mount at. host: type: string description: Host path to the disk image file. options: $ref: '#/components/schemas/MountOptions' description: Mount options (read-only, no-exec, …). type: type: string enum: - disk_image description: Persistent volume mounted at a path inside the sandbox. CloudNetworkSpec: type: object description: >- Cloud network specification: a subset of the domain [`crate::domain::NetworkSpec`]. Interface overrides, host port mapping, DNS, TLS interception, rate limits, and host-CA trust are not part of this type. Unknown fields are ignored for compatibility with newer clients; accepting them does not enable their behavior. properties: enabled: type: boolean description: Whether networking is enabled for this sandbox. default: true max_connections: type: - integer - 'null' description: Max concurrent guest connections. default: null minimum: 0 policy: oneOf: - type: 'null' - $ref: '#/components/schemas/NetworkPolicy' description: Egress/ingress policy. default: null secrets: oneOf: - type: 'null' - $ref: '#/components/schemas/CloudSecretsConfig' description: Secret-injection config. default: null strict: type: boolean description: >- Require hostname-based policy allows to use inspectable application authority. default: false CloudRlimit: type: object description: >- A POSIX resource limit. Twin of [`Rlimit`] using [`CloudRlimitResource`]. required: - resource - soft - hard properties: hard: type: integer format: int64 description: Hard limit (ceiling, requires privileges to raise). minimum: 0 resource: $ref: '#/components/schemas/CloudRlimitResource' description: Resource type. soft: type: integer format: int64 description: Soft limit (can be raised up to the hard limit by the process). minimum: 0 CloudSandboxRuntimeOptions: type: object description: >- Cloud guest runtime options: a subset of [`crate::domain::SandboxRuntimeOptions`]. The hostname and the metrics-sampling knobs are not part of this type. Unknown fields are ignored for compatibility with newer clients. properties: cmd: type: - array - 'null' items: type: string description: Command override. default: null entrypoint: type: - array - 'null' items: type: string description: Entrypoint override. default: null log_level: oneOf: - type: 'null' - $ref: '#/components/schemas/SandboxLogLevel' description: Runtime log level. default: null scripts: type: object description: Named in-guest scripts. default: {} additionalProperties: type: string propertyNames: type: string shell: type: - string - 'null' description: Default shell. default: null user: type: - string - 'null' description: Guest user. default: null workdir: type: - string - 'null' description: Working directory for guest commands. default: null SecurityProfile: type: string description: Sandbox-level in-guest security profile. enum: - default - restricted HostPermissions: type: string description: >- Host permission propagation policy for a virtiofs-backed volume mount. Serializes/deserializes as the lowercase variant name (`"private"`, `"mirror"`) to align with the CLI and NAPI spellings. enum: - private - mirror MountOptions: type: object description: Guest mount behavior shared by every volume mount kind. properties: nodev: type: boolean description: Whether device files on the mount are ignored. default: false noexec: type: boolean description: >- 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. default: false nosuid: type: boolean description: >- Whether setuid and setgid privilege elevation from files on the mount is ignored. default: false override_gid: type: - integer - 'null' format: int32 description: >- Guest gid presented for host files under this mount that carry no per-file stat override. See [`override_uid`](Self::override_uid); the two must be set together. default: null minimum: 0 override_uid: type: - integer - 'null' format: int32 description: >- Guest uid presented for host files under this mount that carry no per-file stat override. Host-created files (written outside the guest) have no override, so without this they surface with the runtime's fallback owner. When set, such files are presented as this uid instead. Must be set together with [`override_gid`](Self::override_gid). `None` keeps the fallback. default: null minimum: 0 readonly: type: boolean description: >- 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. default: false StatVirtualization: type: string description: >- Stat virtualization policy for a virtiofs-backed volume mount. Serializes/deserializes as the lowercase variant name (`"strict"`, `"relaxed"`, `"off"`) so persisted JSON aligns with the CLI grammar (`stat-virt=strict|relaxed|off`) and the NAPI string contract. enum: - strict - relaxed - 'off' DiskImageFormat: type: string description: Disk image format for virtio-blk root filesystems and volume mounts. enum: - Qcow2 - Raw - Vmdk DnsConfig: type: object description: >- DNS interception and filtering settings. Carried in [`NetworkSpec::dns`]. properties: nameservers: type: array items: type: string description: |- Upstream nameservers as `IP`, `IP:PORT`, `HOST`, or `HOST:PORT` strings. Empty falls back to the host's `/etc/resolv.conf`. default: [] query_timeout_ms: type: integer format: int64 description: 'Per-query timeout in milliseconds. Default: 5000.' default: 5000 minimum: 0 rebind_protection: type: boolean description: 'Whether DNS-rebinding protection is enabled. Default: true.' default: true InterfaceOverrides: type: object description: |- Optional guest interface overrides. Unset fields are derived from the sandbox slot by the local network engine. Carried in [`NetworkSpec::interface`]. properties: ipv4_address: type: - string - 'null' description: 'Guest IPv4 address (e.g. `172.16.0.2`). Default: derived from slot.' default: null ipv4_pool: type: - string - 'null' description: >- Guest IPv4 pool CIDR (e.g. `"172.16.0.0/12"`). Default: derived from slot. default: null ipv6_address: type: - string - 'null' description: 'Guest IPv6 address. Default: derived from slot.' default: null ipv6_pool: type: - string - 'null' description: 'Guest IPv6 pool CIDR. Default: derived from slot.' default: null mac: type: - array - 'null' items: type: integer format: int32 minimum: 0 description: 'Guest MAC address as six octets. Default: derived from slot.' default: null mtu: type: - integer - 'null' format: int32 description: 'Interface MTU. Default: 1500.' default: null minimum: 0 NetworkPolicy: type: object description: |- Egress/ingress network policy: an ordered [`Rule`] list plus a per-direction default [`Action`]. Carried in [`NetworkSpec::policy`]. properties: default_egress: $ref: '#/components/schemas/Action' description: 'Default action for egress traffic matching no rule. Default: `Deny`.' default_ingress: $ref: '#/components/schemas/Action' description: >- Default action for ingress traffic matching no rule. Default: `Deny`. rules: type: array items: $ref: '#/components/schemas/Rule' description: Ordered rules, evaluated first-match-wins per direction. PublishedPortSpec: type: object description: A published port mapping between host and guest. required: - host_port - guest_port - host_bind properties: guest_port: type: integer format: int32 description: Guest-side port to forward to. minimum: 0 host_bind: type: string description: Host address to bind. Defaults to loopback. host_port: type: integer format: int32 description: Host-side port to bind. minimum: 0 protocol: $ref: '#/components/schemas/PortProtocol' description: Transport protocol. SandboxSecretResponse: type: object description: >- A network secret, projected for the user: the env var, placeholder, and its allow-list / injection policy. The value isn't in the resolved spec at all, and the OpenBao vault path is never exposed. required: - env_var - placeholder - allowed_hosts - injection properties: allowed_hosts: type: array items: type: object env_var: type: string injection: type: object on_violation: type: object placeholder: type: string TlsConfig: type: object description: >- TLS interception configuration. Carried in [`NetworkSpec::tls`](NetworkSpec). The local network engine terminates TCP at its in-process stack, so TLS MITM is handled by proxy tasks - these fields configure which ports/domains are intercepted and how the interception CA is sourced. properties: block_quic_on_intercept: type: boolean description: >- Drop UDP to intercepted ports when TLS interception is active, forcing QUIC traffic to fall back to TCP/TLS. bypass: type: array items: type: string description: >- Domains to bypass (no MITM). Supports exact match and `*.suffix` wildcards. cache: $ref: '#/components/schemas/CertCacheConfig' description: Per-domain certificate cache configuration. enabled: type: boolean description: Whether TLS interception is enabled. intercept_ca: $ref: '#/components/schemas/InterceptCaConfig' description: |- Interception CA configuration. The TLS proxy uses this CA to sign per-domain certs it presents to the guest during interception. intercepted_ports: type: array items: type: integer format: int32 minimum: 0 description: 'TCP ports subject to TLS interception (default: `[443]`).' scoped_upstream_ca_cert: type: array items: $ref: '#/components/schemas/ScopedUpstreamCaCert' description: >- Host-scoped CA certificate PEM files to trust for upstream server verification. scoped_verify_upstream: type: array items: $ref: '#/components/schemas/ScopedVerifyUpstream' description: Host-scoped upstream verification overrides. upstream_ca_cert: type: array items: type: string description: CA certificate PEM files to trust for upstream server verification. verify_upstream: type: boolean description: Whether to verify the upstream server's TLS certificate. RlimitResource: type: string description: POSIX resource limit identifiers. enum: - Cpu - Fsize - Data - Stack - Core - Rss - Nproc - Nofile - Memlock - As - Locks - Sigpending - Msgqueue - Nice - Rtprio - Rttime SandboxLogLevel: type: string description: Runtime log verbosity for sandbox specs. enum: - error - warn - info - debug - trace CloudSecretsConfig: type: object description: >- Secret-injection config for the cloud API. Twin of domain [`SecretsConfig`]. properties: entries: type: array items: $ref: '#/components/schemas/CloudSecretEntry' description: Secrets to inject. on_violation: $ref: '#/components/schemas/CloudViolationAction' description: Default action when a placeholder leaks to a disallowed host. CloudRlimitResource: type: string description: |- POSIX resource-limit identifiers. Twin of [`RlimitResource`] with a snake_case wire. enum: - cpu - fsize - data - stack - core - rss - nproc - nofile - memlock - as - locks - sigpending - msgqueue - nice - rtprio - rttime Action: type: string description: Action to take on traffic matched by a [`Rule`] (or a policy default). enum: - allow - deny Rule: type: object description: |- A single egress/ingress policy rule. Evaluated first-match-wins per direction. required: - direction - destination - action properties: action: $ref: '#/components/schemas/Action' description: Action to take on a match. destination: $ref: '#/components/schemas/Destination' description: Destination filter (direction-dependent interpretation). direction: $ref: '#/components/schemas/Direction' description: Direction this rule applies to. ports: type: array items: $ref: '#/components/schemas/PortRange' description: Guest-side port-range set; empty matches any port. protocols: type: array items: $ref: '#/components/schemas/Protocol' description: Protocol set; empty matches any protocol. PortProtocol: type: string description: Transport protocol for a published port. enum: - tcp - udp CertCacheConfig: type: object description: Per-domain certificate cache configuration. properties: capacity: type: integer description: 'Maximum number of cached certificates. Default: 1000.' minimum: 0 validity_hours: type: integer format: int64 description: 'Certificate validity duration in hours. Default: 24.' minimum: 0 InterceptCaConfig: type: object description: Certificate authority configuration for TLS interception. properties: cert_path: type: - string - 'null' description: |- Path to an existing CA certificate PEM file. If `None`, a CA is auto-generated and persisted. key_path: type: - string - 'null' description: |- Path to an existing CA private key PEM file. If `None`, a key is auto-generated and persisted. ScopedUpstreamCaCert: type: object description: A CA certificate PEM file trusted only for matching upstream hosts. required: - pattern - path properties: path: type: string description: Path to the CA certificate PEM file. pattern: type: string description: >- Host pattern this CA applies to. Supports exact hosts and `*.suffix` wildcards. ScopedVerifyUpstream: type: object description: An upstream certificate verification override for matching hosts. required: - pattern - verify properties: pattern: type: string description: >- Host pattern this override applies to. Supports exact hosts and `*.suffix` wildcards. verify: type: boolean description: Whether to verify matching upstream server certificates. CloudSecretEntry: type: object description: A single cloud secret entry. Twin of domain [`SecretEntry`]. required: - env_var - placeholder properties: allowed_hosts: type: array items: $ref: '#/components/schemas/CloudHostPattern' description: Hosts allowed to receive this secret. env_var: type: string description: Environment variable name exposed to the sandbox. injection: $ref: '#/components/schemas/SecretInjection' description: Where the secret may be injected. on_violation: oneOf: - type: 'null' - $ref: '#/components/schemas/CloudViolationAction' description: Per-secret violation action overriding the config default. placeholder: type: string description: Placeholder the sandbox sees instead of the real value. require_tls_identity: type: boolean description: 'Require verified TLS identity before substituting (default: true).' source: oneOf: - type: 'null' - $ref: '#/components/schemas/CloudSecretSource' description: Host-side source resolved into `value` at spawn time. value: type: string description: The secret value (empty when `source` carries a reference instead). CloudViolationAction: oneOf: - type: object description: Block the request silently. required: - type properties: type: type: string enum: - block - type: object description: Block and log (default). required: - type properties: type: type: string enum: - block_and_log - type: object description: Block and terminate the sandbox. required: - type properties: type: type: string enum: - block_and_terminate - type: object description: >- Forward the request with the placeholder unchanged for matching hosts. required: - hosts - type properties: hosts: type: array items: $ref: '#/components/schemas/CloudHostPattern' description: Hosts for which the placeholder passes through unchanged. type: type: string enum: - passthrough description: |- Action on a cloud secret violation. Twin of [`ViolationAction`], with `Passthrough`'s host list normalized to a `hosts` field. Destination: oneOf: - type: string description: Match any destination. enum: - any - type: object description: IP address or CIDR block (e.g. `"1.2.3.4"`, `"10.0.0.0/8"`). required: - cidr properties: cidr: type: string description: IP address or CIDR block (e.g. `"1.2.3.4"`, `"10.0.0.0/8"`). - type: object description: Exact domain name (e.g. `"example.com"`). required: - domain properties: domain: type: string description: Exact domain name (e.g. `"example.com"`). - type: object description: Domain suffix - the apex and any subdomain of it. required: - domain_suffix properties: domain_suffix: type: string description: Domain suffix - the apex and any subdomain of it. - type: object description: A pre-defined destination group. required: - group properties: group: $ref: '#/components/schemas/DestinationGroup' description: A pre-defined destination group. description: >- Traffic destination matched by a network rule, such as an IP range or domain name. Direction: type: string description: Direction a [`Rule`] applies to. enum: - egress - ingress - any PortRange: type: object description: Inclusive guest-side port range for a [`Rule`] match. required: - start - end properties: end: type: integer format: int32 description: End port (inclusive). minimum: 0 start: type: integer format: int32 description: Start port (inclusive). minimum: 0 Protocol: type: string description: Protocol filter for a [`Rule`]. enum: - tcp - udp - icmpv4 - icmpv6 CloudHostPattern: oneOf: - type: object description: Exact hostname match. required: - value - type properties: type: type: string enum: - exact value: type: string description: Hostname to match exactly. - type: object description: Wildcard match (e.g. `*.openai.com`). required: - value - type properties: type: type: string enum: - wildcard value: type: string description: Wildcard pattern. - type: object description: Any host (dangerous - the secret can be exfiltrated). required: - type properties: type: type: string enum: - any description: >- Host allowlist pattern for cloud secrets. Twin of [`HostPattern`], with the domain's scalar variants normalized to `{ value }` for a uniform union. SecretInjection: type: object description: Where in the HTTP request a secret can be injected. properties: basic_auth: type: boolean description: 'Substitute in HTTP Basic Auth (default: true).' body: type: boolean description: |- Substitute in request body (default: false). Fixed-length HTTP/1 bodies up to 16 MiB update `Content-Length`; larger fixed-length bodies are blocked. Chunked HTTP/1 bodies are decoded and re-encoded with fresh chunk sizes. Encoded bodies pass through unchanged. HTTP/2 DATA-frame body substitution is not supported; matching body placeholders are blocked. headers: type: boolean description: 'Substitute in HTTP headers (default: true).' query_params: type: boolean description: 'Substitute in URL query parameters (default: false).' CloudSecretSource: oneOf: - type: object description: Read from a host environment variable at apply time. required: - var - type properties: type: type: string enum: - env var: type: string description: Host environment variable name. - type: object description: Read from a host-side secret store reference. required: - reference - type properties: reference: type: string description: Store-specific secret reference. type: type: string enum: - store description: Host-side source for a cloud secret. Twin of [`SecretSource`]. DestinationGroup: type: string description: Pre-defined destination category for a [`Destination::Group`] match. enum: - public - loopback - private - link_local - metadata - multicast - host securitySchemes: bearer: type: http scheme: bearer description: >- Personal access token (msb_pat_…) or session JWT - the credential an agent acts with on a user's behalf. ````