---
title: "Create sandbox config"
method: POST
path: "/sandbox-configs"
tags: ["SandboxConfig"]
---

# Create sandbox config

`POST /sandbox-configs`

Create a named workspace sandbox backend config. Credentials are masked in the response.

## Request body

- InternalHandlerSandboxConfigRequest
  - `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
      - `dns_servers` string[] — DNSServers are Cube template nameserver IPs. Empty uses Cubelet's default.
      - `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
      - `cpu_limit` number — CPULimit is the number of CPU cores one sandbox may use. 0 uses the built-in default.
      - `host` string — Host is the daemon endpoint in DOCKER_HOST form. Empty means the local unix socket.
      - `http_timeout_sec` integer — HTTPTimeoutSec bounds each Engine API call. 0 uses the built-in default.
      - `idle_ttl_seconds` integer — IdleTTLSeconds is how long a session container may go unused before it is reclaimed. The daemon has no idle timeout of its own, so this is what stops an abandoned session from pinning host memory indefinitely.
      - `image` string
      - `memory_limit_mb` integer — MemoryLimitMB caps one sandbox's memory. 0 uses the built-in default.
      - `network_mode` string — NetworkMode is the Docker network sandboxes join: "bridge" (default) or "none" for no egress. Nothing else is accepted — host and container: modes share another namespace outright, and a named network is usually the deployment's own compose network, which would put the sandbox next to Postgres and Redis.
      - `pids_limit` integer — PidsLimit caps how many processes one sandbox may run. 0 uses the built-in default.
      - `runtime` string — Runtime selects an alternative OCI runtime such as "runsc" (gVisor). Empty uses the daemon default.
      - `tls_cert_path` string — TLSCertPath is a directory on the WeKnora host containing ca.pem, cert.pem and key.pem. Required when Host is a TCP endpoint.
    - `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 is cube, e2b, or docker; disabled is the hidden policy row.
    - `skill_image` GithubComTencentWeKnoraInternalTypesSkillImageConfig
      - `base_template_id` string — BaseTemplateID is the template this chain was originally built from; the rebuild path starts over from it.
      - `built_at` string — BuiltAt records when this generation was produced.
      - `generation` integer — Generation increments on every successful install/remove, for naming and troubleshooting.
      - `owner_fingerprint` string — OwnerFingerprint identifies the provider account that owns the snapshot. Snapshots are invisible across accounts, so a mismatch means "fall back to the base template" rather than "fail".
      - `snapshot_id` string — SnapshotID is the currently effective snapshot; empty = base template.
    - `skill_rollout` string — SkillRollout decides whether sessions that already hold a sandbox of this config rebuild after a skill install or removal. Empty and SkillRolloutNextTurn rebuild on the next chat turn. SkillRolloutNewSession leaves those sandboxes on the previous image; only sessions that start afterwards boot the new snapshot.
    - `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.
  - `description` string
  - `name` string, required

## Response `201`

Created sandbox config

- object

## Other responses

- `400` — Invalid request or validation failure
- `401` — Unauthorized

## Changes

- **2026-08-13** `6e297e21afca` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/tencentblueking/apis/weknora-api/changes/sandbox-configs/post.md)

---

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