---
title: "测试沙箱连通性"
method: POST
path: "/system/sandbox-check"
tags: ["系统"]
---

# 测试沙箱连通性

`POST /system/sandbox-check`

使用当前填写的参数测试沙箱后端，不保存配置；deep=true 会执行临时脚本，远端后端还会创建并销毁一个沙箱

## Request body

- InternalHandlerSandboxCheckRequest
  - `config` GithubComTencentWeKnoraInternalTypesTenantSandboxConfig
    - `allow_private_endpoints` boolean — AllowPrivateEndpoints permits this workspace config to reach RFC1918 or loopback cluster endpoints. Link-local/cloud-metadata addresses remain blocked. It is explicit in the UI instead of hidden in process env.
    - `cube` GithubComTencentWeKnoraInternalTypesCubeSandboxConfig
      - `api_key` string — 加密
      - `api_url` string
      - `cube_sandbox_ttl_seconds` integer
      - `http_timeout_sec` integer — HTTPTimeoutSec bounds each HTTP call to the sandbox control plane. 0 means use the built-in default (30s), never the deployment's value.
      - `proxy_url` string
      - `sandbox_domain` string
      - `template_id` string
    - `default_timeout_sec` integer — DefaultTimeoutSec is the per-execution timeout in seconds. 0 uses the program's built-in default.
    - `docker` GithubComTencentWeKnoraInternalTypesDockerSandboxConfig
      - `image` string
    - `e2b` GithubComTencentWeKnoraInternalTypesE2BSandboxConfig
      - `api_key` string — 加密
      - `api_url` string
      - `e2b_sandbox_ttl_seconds` integer
      - `http_timeout_sec` integer — HTTPTimeoutSec bounds each HTTP call to the sandbox control plane. 0 means use the built-in default (30s), never the deployment's value.
      - `proxy_url` string — ProxyURL is the data-plane gateway that fronts envd. E2B Cloud resolves "<port>-<sandboxID>.<sandbox_domain>" through public DNS and TLS, so it needs no value here. Self-hosted E2B-compatible control planes usually serve every sandbox from one gateway address and expect the sandbox authority in the Host header; setting this makes WeKnora dial the gateway directly instead of requiring wildcard DNS and a certificate for the sandbox domain. An "http://" gateway also downgrades the data-plane scheme, which the E2B SDK otherwise pins to https.
      - `sandbox_domain` string
      - `template_id` string
    - `env_vars` object — EnvVars are additional environment variables injected into every sandbox created for this tenant. 🔒 Values are encrypted at rest. These become visible to all scripts running in the tenant's sandboxes — do not place secrets here that scripts must not access.
    - `sandbox_type` string — SandboxType selects the sandbox backend. Named configs may use "cube", "e2b", "docker", or "local". "disabled" is reserved for the hidden workspace policy row.
    - `volume_mount` GithubComTencentWeKnoraInternalTypesVolumeMountConfig
      - `enabled` boolean — Enabled toggles the volume mount for this tenant.
      - `mount_path` string — MountPath is the sandbox-internal path where the volume is mounted. Default: /weknora/tenant/skills (customizable per use case).
      - `provider` string — Provider identifies the volume backend. Currently "e2b" or "cube".
      - `volume_id` string — VolumeID is the provider-specific volume identifier, populated after EnsureVolume / CreateVolume succeeds.
      - `volume_name` string — VolumeName is the human-readable volume name, e.g. "weknora-tenant-<id>-skills".
      - `volume_owner_fingerprint` string — VolumeOwnerFingerprint = sha256(provider + APIKey + APIURL). Used to detect when the tenant switched to a different backend or API key, at which point the volume is no longer reachable and must be recreated.
  - `config_id` string — ConfigID lets an edit form test stored credentials while overriding only the fields the admin changed in the drawer.
  - `deep` boolean — Deep additionally runs a throwaway script. For remote backends this also creates and destroys one sandbox, which is the only way to validate the template ID, data plane, in-sandbox execution, and outbound egress. It may consume real sandbox time, so it is opt-in.

## Response `200`

OK

- InternalHandlerSandboxCheckResponse
  - `capabilities` object
  - `checks` InternalHandlerSandboxCheckItem[]
    - `latency_ms` integer
    - `message` string — Message carries free-form provider detail for an executed probe.
    - `name` string
    - `ok` boolean
    - `reason` string — Reason is a stable code explaining why a probe was skipped. It exists so the UI can phrase the skip in the operator's language instead of echoing a server-side sentence.
  - `ok` boolean
  - `provider` string

---

[API](https://skmtc.net/tencentblueking/apis/weknora-api.md) · [All operations](https://skmtc.net/tencentblueking/apis/weknora-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tencentblueking/weknora-api/revisions/6e297e21afca/schema)