> ## 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 ## OpenAPI ````yaml /api-reference/openapi.json post /v1/sandboxes openapi: 3.1.0 info: title: microsandbox cloud API description: >- REST API for microsandbox cloud: sandbox and volume lifecycle, organization context, quotas, usage, and audit events, authenticated with an organization API key. version: 0.1.0 servers: - url: https://api.microsandbox.dev security: - api_key: [] paths: /v1/sandboxes: post: tags: - Sandboxes summary: Create a sandbox operationId: create_sandbox parameters: - 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 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: invalid_request message: invalid request details: null '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: invalid_api_key message: unauthorized details: null '409': description: Name already exists content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: name_already_exists message: '''name'' already exists' details: null '429': description: Readiness wait capacity exhausted content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: rate_limited message: too many requests details: null '502': description: Orchestrator unreachable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: orchestrator_unreachable message: orchestrator unreachable details: null security: - api_key: [] 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 sandbox specification - image, resources, runtime, env, mounts, network, 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 *is* a microsandbox [`CloudSandboxSpec`] - carried verbatim through the shared [`CloudCreateSandboxRequest`] envelope (flattened onto the wire) so it can never drift from the cross-repo contract - plus the cloud-only fields that have no place in the shared spec: the globally-unique SSH `slug` and the registry-credential selection. (Writable-disk size now lives in the spec's `resources.disk_size_mib`.) SandboxResponse: type: object description: >- The API view of a [`Sandbox`]: an explicit allowlist of user-facing fields. Internal columns (registry selection, sync bookkeeping, resolved refs) never appear; the resolved spec surfaces only as the curated [`SandboxSpecResponse`]. required: - id - org_id - name - slug - status - ephemeral - created_at properties: 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. ErrorResponse: type: object description: Error envelope returned by every non-2xx response. required: - error properties: error: type: object required: - code - message properties: code: type: string description: Stable machine-readable error code, e.g. `invalid_api_key`. message: type: string description: Human-readable description of the error. details: type: - object - 'null' description: Optional structured context for the error. CloudCreateSandboxRequest: allOf: - $ref: '#/components/schemas/CloudSandboxSpec' description: The cloud sandbox specification, flattened onto the request body. description: >- Wire shape of a cloud sandbox create request body. Flattens [`CloudSandboxSpec`] onto the request body, so on the wire this is byte-identical to `CloudSandboxSpec`. The generated bindings surface the flattened shape as `CloudSandboxSpec` directly. 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: >- A curated, user-facing projection of a sandbox's resolved spec. Built from [`ResolvedSandboxSpec`]; omits every internal resolution (secret values/vault paths, volume ids). 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 - 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: Cloud sandbox specification carried on create routes. properties: env: type: array items: $ref: '#/components/schemas/EnvVar' description: Environment variables visible to commands in the sandbox. default: [] image: $ref: '#/components/schemas/CloudRootfsSource' 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 patches: type: array items: $ref: '#/components/schemas/CloudPatch' description: Rootfs patches applied before VM start. default: [] pull_policy: oneOf: - $ref: '#/components/schemas/CloudPullPolicy' description: Pull policy for OCI images. default: if_missing resources: oneOf: - $ref: '#/components/schemas/CloudSandboxResources' description: CPU, memory, and user-facing disk resources. default: memory_mib: 512 vcpus: 1 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 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 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 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 CloudRootfsSource: type: object description: Root filesystem source. The hosted cloud accepts OCI images only. required: - type - reference properties: type: type: string enum: - oci reference: type: string description: OCI image reference, e.g. `python:3.12`. 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: >- Cloud volume mount. Internal-tagged mirror of the domain [`VolumeMount`]; the transient `create` field is not carried on the wire. CloudNetworkSpec: type: object description: >- Cloud network specification: a subset of the domain [`NetworkSpec`]. Interface overrides, host port mapping, DNS, TLS interception, and host-CA trust are not part of this type. `deny_unknown_fields` - posting an omitted field is an error, not a silent drop. 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 additionalProperties: false 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: >- Rootfs patch applied before VM start. Twin of [`Patch`], internally tagged with a snake_case `type` instead of the domain's external PascalCase tag. CloudPullPolicy: type: string description: Cloud pull policy. Twin of domain [`PullPolicy`] with a snake_case wire. enum: - if_missing - always - never 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 [`SandboxRuntimeOptions`]. The hostname and the metrics-sampling knobs are not part of this type. `deny_unknown_fields`. 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 additionalProperties: false 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 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 CloudDiskImageFormat: type: string description: >- Disk image format for cloud disk-image sources. Twin of [`DiskImageFormat`] with a snake_case wire. enum: - qcow2 - raw - vmdk 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 filter for a [`Rule`]. The `Cidr`, `Domain`, and `DomainSuffix` leaves carry their canonical string form (e.g. `"10.0.0.0/8"`, `"example.com"`); the local network engine re-parses and validates them into its richer internal types at load time. 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: api_key: type: http scheme: bearer description: Organization API key (msb_…) - org-scoped programmatic access. ````