# Sandbox Handbook

> Frontend integration handbook for the TeamSync Sandbox module (environments, builds, tasks, bindings, runs, secrets, agent confirmation). Bilingual: 繁體中文 (default) and English.

## How to read this as an agent

- Prefer [`/llms-full.txt`](/llms-full.txt) when you need the whole corpus in one request.
- Prefer a per-page `.md` twin (linked below) when you already know the topic.
- Tenant API base: `{TEAMSYNC_API_BASE}/private/module/sandbox` (`module` is singular). Region/profile dropdowns: `GET /public/info/sandbox/{regions,profiles}` (no auth).
- Catalog jobs are `department` or `company` only. `POST /tasks` with `owner_scope=chatroom` is **422**. Unownable department/company create is **403 `owner_scope_forbidden`**. Other unauthorized ids usually **404**.
- Share is not Agent-enablement. Room enable is `.../granted-jobs/{task_id}/enable`. Menu + Agent catalog = granted AND enabled. Manual REST needs share + membership (enable not required). Canonical page: Concepts → Job audience.
- There is no streaming. Poll GET status. Company managers upload build context (`X-Sandbox-Upload-Capability`, 15 min). Artifact download returns a 5-minute `capability_token`, not a URL. Two different tokens.
- Permissions are a ladder (ordinary user / chatroom manager / department manager / company manager / restricted Sandbox API key), not "every mutation needs a company manager". Start at Concepts → Personas, then Job audience.
- Agent submit is five LangGraph tools (not REST). Custom-table `submit_sandbox_job` produces a normal run with `submission_source=custom_table_trigger` and refuses `output_policy` versions.
- `/sandbox-control/*` is system-to-system. `/root/sandbox/*` is operator-only (Concepts → Operators). Pin SHA is Changelog.

## Suggested reading order

1. Get started → Authentication (`Authorization: Bearer` or `X-Api-Key`)
2. Concepts → Personas, then Job audience (share vs enable vs menu)
3. The flow that matches the caller (tenant-user, environment/task, agent confirm, or custom-table trigger)
4. API reference → schemas / endpoints / agent-tools / enums / errors
5. Operators and root only if the caller is a root operator

## zh-TW — 總覽

- [Sandbox 前端整合手冊](https://sandbox-docs.pages.dev/zh-TW/index.md) — TeamSync Sandbox 模組的前端串接指南 — 環境、建置、執行、結果與 Agent 確認流程。

## zh-TW — 快速開始

- [認證與 Base URL](https://sandbox-docs.pages.dev/zh-TW/get-started/auth.md) — Base URL、principal、JWT 與 API key、Sandbox scope 限制、404/503 語意與 Idempotency-Key。
- [快速開始](https://sandbox-docs.pages.dev/zh-TW/get-started/index.md) — 前置條件、認證方式，以及一次跑通整條路徑的最短步驟。
- [五分鐘跑一次](https://sandbox-docs.pages.dev/zh-TW/get-started/quickstart.md) — 從建立環境到取回執行結果的實際呼叫序列（附範例）。

## zh-TW — 概念

- [架構：控制面與資料面](https://sandbox-docs.pages.dev/zh-TW/concepts/architecture.md) — 前端呼叫 /private/module/sandbox 加上兩個公開確認目錄；建置、執行與多數位元組搬運仍在控制面。
- [內容、Digest 與下載](https://sandbox-docs.pages.dev/zh-TW/concepts/content-and-downloads.md) — 用租戶 capability 上傳建置 context 封存、提交 canonical 執行 input，以及用短效 token 下載產出物。
- [概念總覽](https://sandbox-docs.pages.dev/zh-TW/concepts/index.md) — 串接 Sandbox 前必讀的核心模型 — 資源關係、狀態機、內容定址與 Secret。
- [任務受眾 — 分享、啟用、選單](https://sandbox-docs.pages.dev/zh-TW/concepts/job-audience.md) — 部門／公司擁有的目錄任務、分享對象、房間啟用與 Agent 選單、以及誰可以提交。
- [限制與配額](https://sandbox-docs.pages.dev/zh-TW/concepts/limits.md) — 前端實際會碰到的限制 — 分頁、輸入/腳本大小、逾時、環境變數、每公司政策上限。
- [通知](https://sandbox-docs.pages.dev/zh-TW/concepts/notifications.md) — TeamSync 通知中心上的 SandboxNotificationEvent。它們只是提示；GET 狀態仍是權威。
- [營運與 Root](https://sandbox-docs.pages.dev/zh-TW/concepts/operators.md) — /root/sandbox 是營運／root 表面，不是產品前端。區域、策展環境、digest 封鎖與離場圍欄由 root 擁有。
- [角色與權限](https://sandbox-docs.pages.dev/zh-TW/concepts/personas.md) — 租戶使用者、聊天室管理員、部門管理員、公司管理員與受限 API key 的階梯，以及誰能做什麼。
- [資源模型](https://sandbox-docs.pages.dev/zh-TW/concepts/resources.md) — 環境、context 上傳、任務、分享、房間啟用、執行與建置 attempt — 以及部門擁有目錄任務之後它們怎麼連。
- [保留期](https://sandbox-docs.pages.dev/zh-TW/concepts/retention.md) — 執行內容、映像、失敗情境日誌各有不同過期時鐘；前端別把 id 當永久連結。
- [Secret 與授權](https://sandbox-docs.pages.dev/zh-TW/concepts/secrets.md) — secret binding、slot、rotate/revoke，以及借用他人任務時的 secret 授權。
- [狀態機與輪詢](https://sandbox-docs.pages.dev/zh-TW/concepts/states.md) — 版本、建置、執行、任務版本、提案的所有狀態值與轉換；前端一律用輪詢。

## zh-TW — 操作流程

- [Agent 確認流程](https://sandbox-docs.pages.dev/zh-TW/flows/agent-confirm.md) — sandbox 提交是 Agent 工具（不是 REST 端點）；前端如何觀察提案與確認。
- [從自訂表格 trigger 提交執行](https://sandbox-docs.pages.dev/zh-TW/flows/custom-table-trigger.md) — submit_sandbox_job trigger action — 欄位、觸發時授權、$row 插值，以及前端如何觀察這次 run。
- [建立環境並建置](https://sandbox-docs.pages.dev/zh-TW/flows/environment-and-build.md) — 建立環境 → 上傳 context 封存 → 釘版本 → 排隊建置 → 輪詢到 ready。
- [操作流程總覽](https://sandbox-docs.pages.dev/zh-TW/flows/index.md) — 任務導向的流程，每條一頁，含實際端點與狀態轉換。
- [執行與取回結果](https://sandbox-docs.pages.dev/zh-TW/flows/run-and-results.md) — menu → 提交（Idempotency-Key）→ 輪詢 → 內容旗標 → 產出物 → 下載 capability → 取消/重試。
- [任務、分享與啟用](https://sandbox-docs.pages.dev/zh-TW/flows/tasks-and-bindings.md) — 建立部門或公司任務 → 草稿版本 → 發布 → 分享 → 房間啟用給 Agent 選單。
- [一般使用者執行任務](https://sandbox-docs.pages.dev/zh-TW/flows/tenant-user.md) — 一般租戶使用者的執行路徑：menu → 提交（Idempotency-Key）→ 輪詢 → 內容旗標 → 產出物 → 下載 capability → 取消自己進行中的 run。

## zh-TW — API 參考

- [Agent toolkit](https://sandbox-docs.pages.dev/zh-TW/reference/agent-tools.md) — 五個綁定行為主體的 Sandbox 工具、ChatroomJobType.sandbox、確認收據，以及有界的 job-status 預覽。
- [API 端點目錄](https://sandbox-docs.pages.dev/zh-TW/reference/endpoints.md) — 所有前端 sandbox 端點，依資源分組，含認證、請求與回應。
- [狀態列舉值](https://sandbox-docs.pages.dev/zh-TW/reference/enums.md) — 前端會渲染或判斷的所有 sandbox 列舉字串值，取自 src/schemas/enums.py。
- [錯誤碼對照表](https://sandbox-docs.pages.dev/zh-TW/reference/errors.md) — sandbox 前端端點的 HTTP 狀態碼與錯誤語意。
- [API 參考總覽](https://sandbox-docs.pages.dev/zh-TW/reference/index.md) — 端點目錄、狀態列舉值、錯誤碼對照表。
- [請求與回應欄位](https://sandbox-docs.pages.dev/zh-TW/reference/schemas.md) — origin/master 上每個租戶請求／回應模型的完整欄位。多餘欄位一律拒絕。

## zh-TW — 變更紀錄

- [變更紀錄](https://sandbox-docs.pages.dev/zh-TW/changelog/index.md) — 手冊釘在 teamsync-backend origin/master 的哪個 commit，以及這次稽核補了什麼。

## en — Overview

- [Sandbox Frontend Handbook](https://sandbox-docs.pages.dev/en/index.md) — Frontend integration guide for the TeamSync Sandbox module — environments, builds, runs, results, and the agent-confirmation flow.

## en — Get started

- [Authentication and base URL](https://sandbox-docs.pages.dev/en/get-started/auth.md) — Base URL, principal, JWT and API key, Sandbox scope restrictions, the meaning of 404/503, and Idempotency-Key.
- [Get started](https://sandbox-docs.pages.dev/en/get-started/index.md) — Prerequisites, authentication, and the shortest steps to run the whole path end to end.
- [Run it in five minutes](https://sandbox-docs.pages.dev/en/get-started/quickstart.md) — The actual call sequence from creating an environment to fetching run results (with examples).

## en — Concepts

- [Architecture: control vs data plane](https://sandbox-docs.pages.dev/en/concepts/architecture.md) — The frontend talks to /private/module/sandbox plus two public confirmation catalogs; building, running, and most byte movement stay in the control plane.
- [Content, digests, and downloads](https://sandbox-docs.pages.dev/en/concepts/content-and-downloads.md) — Upload a build-context archive through a tenant capability, submit canonical run input, and download artifacts with a short-lived token.
- [Concepts overview](https://sandbox-docs.pages.dev/en/concepts/index.md) — The core models to read before integrating Sandbox — resource relationships, state machines, content addressing, and secrets.
- [Job audience — share, enable, menu](https://sandbox-docs.pages.dev/en/concepts/job-audience.md) — Department- and company-owned catalog jobs, share targets, room enable vs Agent menu, and who may submit.
- [Limits and quotas](https://sandbox-docs.pages.dev/en/concepts/limits.md) — The limits the frontend actually hits — pagination, input/script sizes, timeouts, environment variables, and per-company policy caps.
- [Notifications](https://sandbox-docs.pages.dev/en/concepts/notifications.md) — SandboxNotificationEvent payloads on the TeamSync notification center. They hint; GET status remains authoritative.
- [Operators and root](https://sandbox-docs.pages.dev/en/concepts/operators.md) — /root/sandbox is the operator/root surface, not the product frontend. Regions, curated environments, digest blocks, and offboarding fences are owned by root.
- [Personas and permissions](https://sandbox-docs.pages.dev/en/concepts/personas.md) — The ladder for tenant users, chatroom managers, department managers, company managers, and restricted API keys — who can do what.
- [Resource model](https://sandbox-docs.pages.dev/en/concepts/resources.md) — Environment, context upload, job, share, room enable, run, and build attempt — and how they relate after department-owned catalog jobs.
- [Retention](https://sandbox-docs.pages.dev/en/concepts/retention.md) — Run content, images, and failure-scenario logs each have their own expiry clock; the frontend must not treat an id as a permanent link.
- [Secrets and approvals](https://sandbox-docs.pages.dev/en/concepts/secrets.md) — Secret bindings, slots, rotate/revoke, and secret approvals when borrowing someone else's task.
- [State machines and polling](https://sandbox-docs.pages.dev/en/concepts/states.md) — Every status value and transition for versions, builds, runs, task versions, and proposals; the frontend always polls.

## en — Flows

- [Agent-confirmation flow](https://sandbox-docs.pages.dev/en/flows/agent-confirm.md) — A sandbox submission is an agent tool (not a REST endpoint); how the frontend observes proposals and confirmations.
- [Submit a run from a custom-table trigger](https://sandbox-docs.pages.dev/en/flows/custom-table-trigger.md) — The submit_sandbox_job trigger action — action fields, fire-time authority, $row interpolation, and how the frontend observes the run.
- [Create an environment and build](https://sandbox-docs.pages.dev/en/flows/environment-and-build.md) — Create environment → upload context archive → pin version → queue build → poll to ready.
- [Flows overview](https://sandbox-docs.pages.dev/en/flows/index.md) — Task-oriented flows, one page each, with the actual endpoints and state transitions.
- [Run and fetch results](https://sandbox-docs.pages.dev/en/flows/run-and-results.md) — menu → submit (Idempotency-Key) → poll → content flags → artifacts → download capability → cancel/retry.
- [Jobs, share, and enable](https://sandbox-docs.pages.dev/en/flows/tasks-and-bindings.md) — Create a department or company job → draft version → publish → share → room-enable for the Agent menu.
- [Run a task as a tenant user](https://sandbox-docs.pages.dev/en/flows/tenant-user.md) — The ordinary tenant-user path — menu, submit (Idempotency-Key), poll, content flags, artifacts, download capability, cancel your own in-flight run.

## en — API reference

- [Agent toolkit](https://sandbox-docs.pages.dev/en/reference/agent-tools.md) — The five principal-bound Sandbox tools, ChatroomJobType.sandbox, confirmation receipts, and bounded job-status previews.
- [API endpoint catalog](https://sandbox-docs.pages.dev/en/reference/endpoints.md) — Every frontend sandbox endpoint, grouped by resource, with auth, request, and response.
- [Status enum values](https://sandbox-docs.pages.dev/en/reference/enums.md) — Every sandbox enum string value the frontend renders or checks, taken from src/schemas/enums.py.
- [Error-code table](https://sandbox-docs.pages.dev/en/reference/errors.md) — HTTP status codes and error semantics for the sandbox frontend endpoints.
- [API reference overview](https://sandbox-docs.pages.dev/en/reference/index.md) — Endpoint catalog, status enum values, error-code table.
- [Request and response schemas](https://sandbox-docs.pages.dev/en/reference/schemas.md) — Field-complete tenant request and response models as they appear on origin/master. Extra fields are forbidden.

## en — Changelog

- [Changelog](https://sandbox-docs.pages.dev/en/changelog/index.md) — Handbook pin against teamsync-backend origin/master, and what this audit filled.