---
title: "GET /v1/sandboxes/by-name/:name — get a sandbox by name (API key, org inferred from key)."
method: GET
path: "/v1/sandboxes/by-name/{name}"
tags: ["sandboxes"]
---

# GET /v1/sandboxes/by-name/:name — get a sandbox by name (API key, org inferred from key).

`GET /v1/sandboxes/by-name/{name}`

Retrieve one sandbox by its organization-scoped name.

## Path parameters

- `name` string, required

## Response `200`

Sandbox details

- SandboxResponse — 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`].
  - `automatic_recovery_ends_at` string, date-time, nullable — When an explicit recovery choice becomes necessary.
  - `created_at` string, date-time, required
  - `ephemeral` boolean, required
  - `id` string, uuid, required
  - `last_failure_message` string, nullable — Human-readable reason for the last failure.
  - `name` string, required
  - `org_id` string, uuid, required
  - `slug` string, required
  - `spec` SandboxSpecResponse — A curated, user-facing projection of a sandbox's resolved spec. Built from [`ResolvedSandboxSpec`]; omits every internal resolution (secret values/vault paths, volume ids).
    - `env` EnvVar[], required — Environment variables.
      - `key` string, required — Environment variable name.
      - `value` string, required — Environment variable value.
    - `image` string, nullable — OCI image reference the sandbox boots; `null` for a non-OCI rootfs.
    - `labels` object, required — User-defined labels.
    - `lifecycle` SandboxPolicy, required — Sandbox lifecycle policy.
      - `ephemeral` boolean — 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` integer, nullable — Idle timeout in seconds. `None` = no idle detection.
      - `max_duration_secs` integer, nullable — Hard cap on total sandbox lifetime in seconds. `None` = run forever.
    - `mounts` SandboxMountResponse[], required — Volume mounts — guest path + options only; volume ids omitted.
      - union — A mount, projected for the user: guest path + options, never the resolved volume id / source.
        - object — Host-subpath bind mount.
          - `guest` string, required
          - `host_permissions` 'private' | 'mirror', required — 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.
          - `options` MountOptions, required — Guest mount behavior shared by every volume mount kind.
            - `nodev` boolean — Whether device files on the mount are ignored.
            - `noexec` boolean — Whether direct execution from the mount is disabled. This prevents `execve` of binaries or scripts located on the mount. Interpreters can still read files from the mount, for example `sh /mnt/script.sh`, because the interpreter itself executes from a different filesystem.
            - `nosuid` boolean — Whether setuid and setgid privilege elevation from files on the mount is ignored.
            - `readonly` boolean — 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.
          - `quota_mib` integer, nullable
          - `stat_virtualization` 'strict' | 'relaxed' | 'off', required — 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.
          - `type` 'Bind', required
        - object — Named-volume mount.
          - `guest` string, required
          - `host_permissions` 'private' | 'mirror', required — 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.
          - `options` MountOptions, required — Guest mount behavior shared by every volume mount kind.
            - `nodev` boolean — Whether device files on the mount are ignored.
            - `noexec` boolean — Whether direct execution from the mount is disabled. This prevents `execve` of binaries or scripts located on the mount. Interpreters can still read files from the mount, for example `sh /mnt/script.sh`, because the interpreter itself executes from a different filesystem.
            - `nosuid` boolean — Whether setuid and setgid privilege elevation from files on the mount is ignored.
            - `readonly` boolean — 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.
          - `stat_virtualization` 'strict' | 'relaxed' | 'off', required — 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.
          - `type` 'Named', required
        - object — Guest-memory tmpfs.
          - `guest` string, required
          - `options` MountOptions, required — Guest mount behavior shared by every volume mount kind.
            - `nodev` boolean — Whether device files on the mount are ignored.
            - `noexec` boolean — Whether direct execution from the mount is disabled. This prevents `execve` of binaries or scripts located on the mount. Interpreters can still read files from the mount, for example `sh /mnt/script.sh`, because the interpreter itself executes from a different filesystem.
            - `nosuid` boolean — Whether setuid and setgid privilege elevation from files on the mount is ignored.
            - `readonly` boolean — 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.
          - `size_mib` integer, nullable
          - `type` 'Tmpfs', required
        - object — Disk-image mount.
          - `format` 'Qcow2' | 'Raw' | 'Vmdk', required — Disk image format for virtio-blk root filesystems and volume mounts.
          - `fstype` string, nullable
          - `guest` string, required
          - `options` MountOptions, required — Guest mount behavior shared by every volume mount kind.
            - `nodev` boolean — Whether device files on the mount are ignored.
            - `noexec` boolean — Whether direct execution from the mount is disabled. This prevents `execve` of binaries or scripts located on the mount. Interpreters can still read files from the mount, for example `sh /mnt/script.sh`, because the interpreter itself executes from a different filesystem.
            - `nosuid` boolean — Whether setuid and setgid privilege elevation from files on the mount is ignored.
            - `readonly` boolean — 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.
          - `type` 'DiskImage', required
    - `network` SandboxNetworkResponse, required — Network config, projected for the user. Secrets drop their vault path.
      - `dns` DnsConfig — DNS interception and filtering settings. Carried in [`NetworkSpec::dns`].
        - `nameservers` string[] — Upstream nameservers as `IP`, `IP:PORT`, `HOST`, or `HOST:PORT` strings. Empty falls back to the host's `/etc/resolv.conf`.
        - `query_timeout_ms` integer — Per-query timeout in milliseconds. Default: 5000.
        - `rebind_protection` boolean — Whether DNS-rebinding protection is enabled. Default: true.
      - `enabled` boolean, required
      - `interface` InterfaceOverrides — Optional guest interface overrides. Unset fields are derived from the sandbox slot by the local network engine. Carried in [`NetworkSpec::interface`].
        - `ipv4_address` string, nullable — Guest IPv4 address (e.g. `172.16.0.2`). Default: derived from slot.
        - `ipv4_pool` string, nullable — Guest IPv4 pool CIDR (e.g. `"172.16.0.0/12"`). Default: derived from slot.
        - `ipv6_address` string, nullable — Guest IPv6 address. Default: derived from slot.
        - `ipv6_pool` string, nullable — Guest IPv6 pool CIDR. Default: derived from slot.
        - `mac` integer[], nullable — Guest MAC address as six octets. Default: derived from slot.
        - `mtu` integer, nullable — Interface MTU. Default: 1500.
      - `max_connections` integer, nullable
      - `policy` NetworkPolicy — Egress/ingress network policy: an ordered [`Rule`] list plus a per-direction default [`Action`]. Carried in [`NetworkSpec::policy`].
        - `default_egress` 'allow' | 'deny' — Action to take on traffic matched by a [`Rule`] (or a policy default).
        - `default_ingress` 'allow' | 'deny' — Action to take on traffic matched by a [`Rule`] (or a policy default).
        - `rules` Rule[] — Ordered rules, evaluated first-match-wins per direction.
          - `action` 'allow' | 'deny', required — Action to take on traffic matched by a [`Rule`] (or a policy default).
          - `destination` union, required — 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.
            - 'any' — Match any destination.
            - object — IP address or CIDR block (e.g. `"1.2.3.4"`, `"10.0.0.0/8"`).
              - …
            - object — Exact domain name (e.g. `"example.com"`).
              - …
            - object — Domain suffix — the apex and any subdomain of it.
              - …
            - object — A pre-defined destination group.
              - …
          - `direction` 'egress' | 'ingress' | 'any', required — Direction a [`Rule`] applies to.
          - `ports` PortRange[] — Guest-side port-range set; empty matches any port.
            - `end` integer, required — End port (inclusive).
            - `start` integer, required — Start port (inclusive).
          - `protocols` Protocol[] — Protocol set; empty matches any protocol.
      - `ports` PublishedPortSpec[], required
        - `guest_port` integer, required — Guest-side port to forward to.
        - `host_bind` string, required — Host address to bind. Defaults to loopback.
        - `host_port` integer, required — Host-side port to bind.
        - `protocol` 'tcp' | 'udp' — Transport protocol for a published port.
      - `secrets` SandboxSecretResponse[]
        - `allowed_hosts` object[], required
        - `env_var` string, required
        - `injection` object, required
        - `on_violation` object
        - `placeholder` string, required
      - `tls` TlsConfig — 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.
        - `block_quic_on_intercept` boolean — Drop UDP to intercepted ports when TLS interception is active, forcing QUIC traffic to fall back to TCP/TLS.
        - `bypass` string[] — Domains to bypass (no MITM). Supports exact match and `*.suffix` wildcards.
        - `cache` CertCacheConfig — Per-domain certificate cache configuration.
          - `capacity` integer — Maximum number of cached certificates. Default: 1000.
          - `validity_hours` integer — Certificate validity duration in hours. Default: 24.
        - `enabled` boolean — Whether TLS interception is enabled.
        - `intercept_ca` InterceptCaConfig — Certificate authority configuration for TLS interception.
          - `cert_path` string, nullable — Path to an existing CA certificate PEM file. If `None`, a CA is auto-generated and persisted.
          - `key_path` string, nullable — Path to an existing CA private key PEM file. If `None`, a key is auto-generated and persisted.
        - `intercepted_ports` integer[] — TCP ports subject to TLS interception (default: `[443]`).
        - `scoped_upstream_ca_cert` ScopedUpstreamCaCert[] — Host-scoped CA certificate PEM files to trust for upstream server verification.
          - `path` string, required — Path to the CA certificate PEM file.
          - `pattern` string, required — Host pattern this CA applies to. Supports exact hosts and `*.suffix` wildcards.
        - `scoped_verify_upstream` ScopedVerifyUpstream[] — Host-scoped upstream verification overrides.
          - `pattern` string, required — Host pattern this override applies to. Supports exact hosts and `*.suffix` wildcards.
          - `verify` boolean, required — Whether to verify matching upstream server certificates.
        - `upstream_ca_cert` string[] — CA certificate PEM files to trust for upstream server verification.
        - `verify_upstream` boolean — Whether to verify the upstream server's TLS certificate.
      - `trust_host_cas` boolean, required
    - `resources` CloudSandboxResources, required — Cloud resource request.
      - `disk_size_mib` integer, nullable — Writable disk size in MiB. Applies only to OCI root filesystems.
      - `memory_mib` integer — Guest memory in MiB.
      - `vcpus` integer — Number of virtual CPUs.
    - `rlimits` Rlimit[], required — Resource limits.
      - `hard` integer, required — Hard limit (ceiling, requires privileges to raise).
      - `resource` 'Cpu' | 'Fsize' | 'Data' | 'Stack' | 'Core' | 'Rss' | 'Nproc' | 'Nofile' | 'Memlock' | 'As' | 'Locks' | 'Sigpending' | 'Msgqueue' | 'Nice' | 'Rtprio' | 'Rttime', required — POSIX resource limit identifiers.
      - `soft` integer, required — Soft limit (can be raised up to hard limit by the process).
    - `runtime` SandboxRuntimeOptions, required — Guest runtime options for a sandbox.
      - `cmd` string[], nullable — Image command override.
      - `disable_metrics_sample` boolean — Force-disable metrics sampling regardless of `metrics_sample_interval_ms`.
      - `entrypoint` string[], nullable — Image entrypoint override.
      - `hostname` string, nullable — Guest hostname override.
      - `log_level` 'error' | 'warn' | 'info' | 'debug' | 'trace' — Runtime log verbosity for sandbox specs.
      - `metrics_sample_interval_ms` integer, nullable — Metrics sampling interval in milliseconds. `None` disables sampling.
      - `scripts` object — Named scripts available inside the guest.
      - `shell` string, nullable — Default shell for scripts and interactive sessions.
      - `user` string, nullable — Guest user identity override.
      - `workdir` string, nullable — Working directory inside the guest.
  - `started_at` string, date-time, nullable — Latest run's start time; `null` if the sandbox has never run.
  - `status` 'created' | 'starting' | 'running' | 'temporarily_unavailable' | 'recovery_decision_required' | 'stopping' | 'stopped' | 'failed', required — Sandbox lifecycle status.
  - `status_reason` 'scheduling' | 'insufficient_capacity' — Why a submitted sandbox is still waiting for placement on a worker. Only meaningful while `status` is `starting`.
  - `stopped_at` string, date-time, nullable — Latest run's stop time; `null` while open or never run.
  - `temporarily_unavailable_since` string, date-time, nullable — When the current worker outage became user-visible.

## Other responses

- `401` — Unauthorized
- `404` — Sandbox not found

---

[API](https://skmtc.dev/microsandbox/apis/microsandbox-api.md) · [All operations](https://skmtc.dev/microsandbox/apis/microsandbox-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/microsandbox/microsandbox-api/revisions/23f2a45cb09b/schema)