API 端點目錄

除非另註，路徑省略前綴 {BASE}/private/module/sandbox。租戶路由經 get_sandbox_principal；未授權回 404（例外：不能擁有的 department／company 建立是 403 owner_scope_forbidden；owner_scope=chatroom 是 422）。完整欄位：請求與回應欄位。OpenAPI 雙 tag：總 tag Module: Sandbox 加上 Module: Sandbox - Settings／Environments／Tasks／Bindings／Secrets／Runs。

公開確認目錄（沒有 /private 前綴，不必登入）

xlarge 的 tenant_selectable=false。Region 再與 GET /settings.allowed_regions 取交集。營運端 live 集合是 /root/sandbox/regions。

用來加密 secret 寫入的 encrypted_value——見 Secret 與授權。跟 model-catalog 的 encrypted_api_key 流程共用（不是 sandbox 專屬）。503 代表伺服器沒設定金鑰對（加密寫入會回 422 sandbox_transit_keypair_missing，絕不會退回明文）。

永久公開產出物連結（沒有 /private 前綴，不必登入）

沒有 TTL。撤銷後，或底層物件離開 deletion_state=active 後，一律 404。見 內容、Digest 與下載。

單次 run 的 Command 輸出端點（沒有 /private 前綴，Bearer 憑證）

掛在自訂表格 callback 路由底下，不是 Sandbox 的路由。見任務輸出交給自訂表格 Command。

公司設定

SandboxCompanySettingsUpdate（可寫）：run_content_retention_days(1..365)、unreferenced_image_retention_days(1..90)、allowed_regions(≥1)、policy_version(樂觀鎖 CAS)。CAS 不符 → 409。GET 與 PUT 皆需 COMPANY_MANAGER。

SandboxCompanySettingsResponse 另外回傳（唯讀／衍生）：timeout_ceiling_seconds、active_environment_limit、capacity_retained_version_limit、placement_scope（固定 "runtime_execution_only"）、does_not_govern[]（build／validator／registry／r2／log／control_plane）、residency_guaranteed（固定 false）、regional_job_capacity_grace_days_fixed。allowed_regions 只管執行期 Job／Execution 放置，不管建置／validator／registry／R2／log／控制面駐留。

環境 / 版本 / 建置（前綴 /environments）

**環境權限：**公司擁有環境由公司管理員管理；部門擁有環境可由該部門管理員或公司管理員建立／管理。部門管理員建立時須傳 owner_scope: "department" 與該部門的 owner_id。Context 上傳、版本、build、重試與 archive 都套用相同 owner-scope 閘門；curated 環境沒有租戶寫入路徑。Metadata 仍可由同公司身分讀取，上傳 session 則要求 owner 管理權。未授權租戶在 router 回 404，受限 key 會先被 auth 拒絕。

請求欄位

• SandboxEnvironmentCreateRequest：name(1–256)、description(≤2048)。
• Context 上傳：company manager；策展環境 404。declared_bytes 1..1 GiB；archive_format zip/tar/tar.gz。PUT 要 X-Sandbox-Upload-Capability + Content-Type: application/octet-stream。上限：20 slots、20 GiB 宣告、每分鐘 5 次 init。Abort 未完成 session — 漏掉的 slot 會 429 staging_slot_exhausted，連 scan report 也卡住。
• Dockerfile FROM（compose）：任何公開映像都可以，包含 scratch——2026-08-25 起沒有固定允許清單（合成後的 layer 仍會檢查平台保留路徑，error_code=context_invalid）。compose 仍拒絕：動態 FROM、任何 # syntax= 指示行（檔案中任何一行都算）、來自網路來源的 ADD、RUN --network=host、type=secret／type=ssh 的 RUN --mount 或 from= 指到未審查 stage 的 --mount、指到未審查 stage 的 COPY --from，以及超過 1 MiB 的 Dockerfile。
• SandboxEnvironmentVersionCreateRequest：首選 owned_object_id（來自 complete）。source_digest 可選（^sha256:[0-9a-f]{64}$），但單獨送時後端只驗格式，不會確認它對應任何已完成的 context 物件——會建出一個沒有綁定封存的版本，後續建置仍會被受理並保留預算，直到建置時才失敗；請一律送 owned_object_id。兩個都送必須相符。source_ref(≤1024)、resource_profile（僅租戶可選；不是 xlarge）。
• SandboxBuildAttemptCreateRequest：build_region（SandboxRegionCode 列舉，可省略；託管雲端預設 asia-east1，地端部署預設 onprem；集合見 GET /public/info/sandbox/regions）、build_profile（SandboxBuildProfile 列舉，可省略，預設 standard）。沒有 ≤64／≤32 的長度限制——送不在列舉內的字串是 422 enum 錯誤。列舉內但該部署目錄沒公開的值（雲端的 onprem、地端的任何雲端代碼）是 422 build_region_unavailable；地端在已有 active 區域列、但指定的不在其中時也回同一個 422。

回應重點欄位

• SandboxEnvironmentVersionResponse：id、environment_id、version_number、state、security_state、resource_profile、capacity_retained、ready_at?…；擁有者專屬：source_digest?、source_ref?（借用視圖省略）。
• SandboxBuildAttemptResponse：id、environment_version_id、attempt_number、status、phase、terminal_class、stage_code、error_code、error_detail（≤128 字元，error_code 底下具體是哪條規則，例如 reserved_path_or_hostile_entry）、build_region、build_profile、report_total_bytes（無任何憑證/金鑰）。常見 error_code：context_invalid、dockerfile_exit、policy_reject、identity_config、tenant_cancel（CVE 掃描結果自 2026-08-25 起只是參考——vulnerability_reject 已經不會再出現）。

任務 / 版本 / 分享（前綴 /tasks）

請求欄位

• SandboxTaskCreateRequest：name(1–256)、description(≤2048)、owner_scope（只有 department/company；chatroom → 422）、owner_id(pattern)、agent_enabled(預設 false，舊旗標)。
• SandboxTaskVersionCreateRequest／UpdateRequest（僅 PATCH draft）：environment_version_id、startup_script(≤1MiB)、work_script(≤1MiB)、ordinary_env?、input_instructions?(≤64KiB)、input_example?(≤64KiB，若設了 input_schema 必須符合它——不符合是這次草稿建立／更新呼叫的 422 job_contract_invalid，發布時絕不會出現)、input_schema?(≤64KiB，JSON Schema draft 2020-12；每次 run 提交都會強制檢查，不符合是 422 input_schema_violation)、work_command?(≤4096 UTF-8 位元組——寫進 /workspace/driver.sh 的 driver 指令列，在 startup.sh 之後 source；空白 → . /workspace/work.sh；含 NUL 或超長 → 422 job_contract_invalid)、timeout_seconds(預設1800，最大 604680)、secret_slot_declarations?（{name} 或字串的 list）、requires_confirmation(預設 false)、output_policy?（以 kind 區分的聯集：{ kind: "custom_table_writeback", table_id, allowed_ops }，或自 v5.21.0 起的 { kind: "custom_table_command", command_id, chatroom_id, input_schema }；只有部門擁有）。
• 分享 vs 啟用 vs 選單：任務受眾。歷史篩選：status、method、executor_kind、source_kind、department_id、chatroom_id。limit 預設 10，最大 100。
• SandboxShareCreateRequest：target_kind、target_id、secret_slot_policies?（{slot_name: "borrower"|"owner"|"owner_overridable"}，≤100 筆，只能在建立時設定——見 Secrets）。SandboxShareRevokeRequest：reason(≤512)。
• SandboxInputPreviewRequest：{ input: <任意 JSON> }。

回應重點：SandboxTaskVersionResponse 含必填的 source_visible、state、content_state（active／scrubbed）、requires_confirmation、secret_slot_names[]、canonical_digest、content_hash、update_available；擁有者專屬：startup_script?、work_script?、work_command?、ordinary_env?、secret_slot_declarations?、output_policy?（借用視圖省略；借用者的 work_command 是 null）。GET /tasks 會過濾隱藏的 quick-run 父任務。SandboxShareGrantResponse 也帶 secret_slot_policies?（owner 與 borrower 視圖都看得到——政策名稱不是機密）。SandboxInputPreviewResponse：input_file_content（$TEAMSYNC_INPUTS_FILE 的精確位元組）、input_digest、runtime_contract（見下）、schema_valid、schema_errors[]。

綁定（前綴 /bindings）

SandboxBindingCreateRequest：chatroom_id、task_id、task_version_id。與 granted-jobs 啟用同一釘選。首選 POST /chatrooms/{id}/granted-jobs/{task_id}/enable。沒有 GET /bindings 列表。 房間管理者用 GET /chatrooms/{id}/granted-jobs 列 grant。Agent／UI 目錄是 GET /chatrooms/{id}/menu（已授予 且 已啟用）。

Secret / 授權（路徑 /secrets*、/secret-approvals*、/shared-task-secret-approvals*）

需 consumer-scope manager；建立/輪替/撤銷要帶 Idempotency-Key；值永不回顯。

SandboxSecretWriteRequest：consumer_scope、consumer_id、task_id、slot_name（^[A-Za-z_][A-Za-z0-9_]{0,127}$）、encrypted_value（必填；SandboxEncryptedValue { encrypted_key, iv, ciphertext }，全都 base64——混合 AES-256-GCM + RSA-OAEP-SHA256 傳輸信封；解密後的值 1..64KiB，不記錄）。明文 value 欄位一律拒絕——加密流程與四種可分辨的 422 slug 見 Secrets。SandboxSecretApprovalCreateRequest：consumer_scope、consumer_id、task_id、task_version_id、task_version_digest(sha256:)、slot_names(1..100——理論上在共享 secret slot 政策下必須剛好等於 borrower 解析出的 slot 子集，但這條路由本身不檢查；不符只會在之後認領時才被抓到，讓 run 被 secret_approval_required 拒絕——見 Secrets)、risk_accepted: true(必為 true)。digest 不符 → 409。binding／approval 沒有列表端點。

執行（路徑帶 /chatrooms/{chatroom_id}/...）

受限金鑰欄的 ❌ 405 來自 scope allowlist（路由不在受限金鑰的允許清單），quick-run 的 ❌ 403 來自 denied-path 規則——沒有任何一條會回 404。這些是金鑰已涵蓋該聊天室時的結果；金鑰 allowed_chatrooms 不含 {cid} 時，任何路由都先回 403。

請求欄位

• SandboxManualRunSubmitRequest：task_version_id、input(canonical JSON——若版本宣告了 input_schema 且不符合，會在派工前回 422 input_schema_violation)、timeout_seconds?。手動 REST 需要 live share + 成員資格；不要求啟用。Agent／選單需要 granted+enabled。
• Retry 保留精確的任務版本 pin，並建立新的 run 身分。省略 body、送 {} 或 {"input": null} 會逐位元重放保留的來源 input；非 null 的 input 會覆寫參數，並依一般 input 限制驗證與暫存。來源 input 不存在、已退役、無法讀取或 digest 不符時，重放回 409 retry_input_unavailable；請改傳明確 input。必須帶 Idempotency-Key；來源尚未終態時回 409 retry_not_eligible。受限 Sandbox key 不能 retry：允許房間的請求由 route allowlist 回 405，超出 scope 的房間可能更早回 403。
• SandboxQuickRunRequest：name、environment_version_id、startup_script、work_script、ordinary_env、input、timeout_seconds(必填)。input 跟手動提交一樣會暫存（v5.10.11），所以 Quick Run 也可能回 422 input_not_stageable／503 input_staging_unavailable。
• 提交、重試與 Quick Run 把 429 宣告為 SandboxQueuedRunLimitErrorResponse（sandbox_queued_run_limit）或 SandboxQueueFullErrorResponse（queue_full，僅地端，帶 Retry-After）。什麼都沒排入佇列。見執行與取回結果。
• 選單 page_size 預設 50；後端 ≥ #1149 起 next_page_token 是真的游標（用 page_token 帶回）。items 還含 task_id、task_name、task_version_digest、input_schema?、secret_slots[]（逐 slot 的 {name, policy, borrower_bound, owner_bound, effective_source}）、runtime_contract?、secret_use_risk_warning?。Granted-jobs items 也帶 secret_slots[]。
• run 上的 submission_source：rest／agent／quick_run／custom_table_trigger。

回應重點

• SandboxRunDetailResponse：id、company_id、chatroom_id、status、resource_profile、principal_type、principal_id、auth_method、task_id、task_version_id、timeout_seconds、submission_source、input_digest、retry_of_run_id、error_code、queue_position?、eta_seconds?（v5.10.11；託管雲端一律 null）、queued_at?、terminal_at?、secret_slot_provenance?（{slot_name: {resolved_via, consumer_scope}}，已遮蔽——run 沒有快照時是 null）。（cancel_requested_at 有持久化，不回傳。share_grant_id 在提交時內部凍結，但不在這個回應上。）
• SandboxRunContentResponse：state、has_input、has_output、has_log、has_artifact_bundle、input_digest（只有旗標 — REST 沒有 log／output 位元組）。
• SandboxArtifactDownloadCapabilityResponse：artifact_id、run_id、company_id、capability_token、expires_at（5 分鐘）、content_type、content_disposition、x_content_type_options: nosniff（無原始 key/URL，也沒有租戶兌換路由 — 見 下載）。
• SandboxPublicLinkResponse：run_id、object_kind（log／output）、url（永久，沒有 TTL）、token、revoked、created_at?。見 下載。

不對前端開放（僅供理解）

• /sandbox-control/*：系統對系統 OIDC + capability，include_in_schema=False。人不要呼叫。地端部署另外掛載 executor 的 work-lease 路由 /sandbox-control/onprem/work/*（以 executor token 驗證；託管雲端沒有）。
• /root/sandbox/*：營運／root，不是前端——包括工作佇列檢視 GET /root/sandbox/queue。見 營運與 Root。

欄位或路徑若與後端不符，以 src/routers/private/modules/sandbox/ 與 src/schemas/sandbox.py 為準。

能力與管理清單（v5.10.0）

下列路徑共用 private Sandbox base。授權、回應欄位與 UI 串接請見能力與管理查詢。