> ## 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.

# Get a sandbox



## OpenAPI

````yaml /api-reference/openapi.json get /v1/sandboxes/{sandbox_id}
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/{sandbox_id}:
    get:
      tags:
        - Sandboxes
      summary: Get a sandbox
      operationId: get_sandbox
      parameters:
        - name: sandbox_id
          in: path
          description: Sandbox ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Sandbox details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: invalid_api_key
                  message: unauthorized
                  details: null
        '404':
          description: Sandbox not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: sandbox_not_found
                  message: resource not found
                  details: null
      security:
        - api_key: []
components:
  schemas:
    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.
    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
    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
    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
    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.
    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
    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.

````