工程師 Q&A

把工作交給 AI 之前，先搞懂平行沙盒怎麼運作、你的程式碼和資料會去哪裡、什麼會留下來。這頁寫給人看；AI 讀的是 SKILL.md 與工具參考。

平行沙盒是給 AI 操作的：開箱子、設定、刪除，都是你用一句話跟 AI 說要什麼，它去呼叫對應的工具或 REST。下面出現的 sandbox_* 工具與 /v1/... 端點，是讓你知道它實際做了什麼。

平行沙盒能幫我做什麼？

• 你的 AI（Claude Code、Codex、Cursor、Gemini CLI，或任何接得上 MCP 的 client）替每件工作開一個箱子：一台遠端的 Linux 小型虛擬機，裡面有 Docker、git、Node、Go、Chromium 與虛擬螢幕。
• AI 在箱子裡把你改的服務跑起來，開真的瀏覽器或 Android、iPhone 模擬器去測，截圖、錄影，最後交給你在 App 上試（「待驗收」）。你圈出問題、用說的回報，回饋會回到原本的對話。
• 一件工作一個箱子，彼此隔離。好幾件工作可以同時做，不會互搶 port、資料庫或你本機的環境。
• 箱子裡沒有 AI。動手的是你自己的 AI，它透過 MCP 工具操作箱子；平行沙盒本身不會把你的程式碼交給任何 AI 模型。

箱子是什麼規格？

x86_64 的 Linux（Debian 12）。每個大小單位是 2 vCPU、8 GB 記憶體、40 GB 磁碟，開箱時選 1、2、4 或 8 個單位。內建 Docker、git、Node、Go、Python、PHP、Chromium 與虛擬螢幕；需要時再加 Java、Android、.NET、Rust、Flutter 的工具鏈。

從哪裡開始？

1. 先看實際流程：範例 repo 有兩個公開 repo，本機 docker compose up 就能跑，頁面上也列了在箱子裡跑的每一步。
2. 接上：把快速開始的那一句貼給你的 AI。它會安裝 skill，並用 OAuth 登入你的帳號；你不用把任何金鑰交給它。
3. 第一件工作挑小的，例如「在箱子裡把這個 repo 跑起來，開瀏覽器測首頁，交給我驗收」。

架構長怎樣？

一件工作從頭到尾怎麼跑？

1. 開箱：AI 呼叫 sandbox_start，說明這個箱子要做什麼，宣告要跑哪些服務、聽哪些 port，要帶哪些 secrets、接哪個環境。箱子從不含任何帳號資料的乾淨快照開起來。
2. 放程式碼：AI 在箱子裡 git clone，或用 sandbox_sync 把你本機的工作區經平行沙盒的 API 傳進箱子。
3. 跑與測：AI 用 sandbox_exec build、啟動服務、跑測試，用 sandbox_shot 截圖錄影。
4. 交件：AI 用 sandbox_review 把箱子交給你。它出現在 App 的「待驗收」，你打開網頁或模擬器實際操作，有問題就圈起來講。
5. 收掉：驗完 AI 呼叫 sandbox_stop（或你在 App 按「收掉」），箱子的磁碟跟著刪除。要留的東西在那之前 commit、push，或拉回本機。

箱子會留多久？

• 10 分鐘沒有動作 → 凍結：不扣點，記憶體與 /work 都保留，下一次呼叫幾秒內喚醒。
• 最後一次使用後 24 小時 → 自動停掉，磁碟刪除。要留久一點，跟 AI 說「這個箱子留 3 天」，它開箱時會設好，最多 7 天。
• 停掉之後，箱子的網址失效，/work 不會回來；新箱子有新的網址。

前後端拆成好幾個 repo，箱子怎麼跑？

同一個箱子能跑好幾個 repo 嗎？

可以。箱子就是一台 Linux，AI 可以把好幾個 repo clone 到 /work 底下，用 docker compose 或各自的指令一起跑。服務之間用名字互相找（例如 api:3000），跟你在本機用 compose 一樣。

還是每個服務一個箱子？

也可以。服務分在不同箱子時，用 link 把 B 箱子裡的一個名字指到 A 箱子的某個 port：B 裡的程式照原本的主機名呼叫，設定不用改。適合兩個人（或兩個 AI 對話）各改一個服務、又要接起來測的時候。

兩個人各開的箱子接得起來嗎？

接得起來，前提是同一個帳號：一個團隊共用一個平行沙盒帳號（做法見團隊設定），箱子、環境、secrets、發布的版本與點數都在這個帳號裡。link 只連同一個帳號的箱子。帳號目前沒有成員或角色之分。

這次沒改的服務怎麼辦？

看它在哪裡：

環境由你的 AI 用 REST 設定，沒有畫面；你要做的只有在自己的網路裡跑連接器（一行 docker run）。環境改了位址或設定，之後開的箱子才拿得到。

不在我手上的服務（別的團隊、第三方）呢？

你的網路連得到的，箱子就接得到：在連得到它的地方跑連接器，把它的 host:port 列上去。只接受固定 IP 的外部服務也一樣列上去，流量就經連接器從你的網路、用你的對外 IP 出去。你自己都連不到的服務，箱子也連不到。

dev 上的服務能反過來呼叫箱子裡改的那一份嗎？

用內網的方式不行：連接器只讓箱子連出去，你的網路上沒有任何東西能經它連進箱子；dev 上用內網主機名呼叫的服務，照樣呼叫 dev 上的那一份。

箱子的公開網址（https://<id>-<key>.box.parallelsandbox.com）倒是任何連得上網際網路的程式都打得開，所以 webhook 這類回呼可以指到它。

要測「呼叫端 → 改過的服務」，最簡單是把呼叫端也放進同一個箱子，或放進另一個用 link 接過來的箱子。

我的程式碼與資料

箱子裡一定會有我完整的 repo 嗎？

不一定，看 AI 怎麼放進去：

• git clone：箱子自己去拉。私有 repo 要先存一個 token 當 secret（例如 GITHUB_TOKEN），AI 開箱時點名帶進去。
• sandbox_sync：從你的電腦送。只送 git 有追蹤的檔案，加上沒被 .gitignore 排除的新檔；也可以只送某個 commit 的樹。被 ignore 的檔（多數專案的 .env、node_modules）預設不送。

不想被送上去的檔案，放進 .gitignore，或請 AI 只送某個 commit。

程式碼和資料會傳到哪裡？

• 箱子、控制面、儲存、registry、log 服務都在 AWS 上。
• 用 iPhone 模擬器時，你 build 出來的 App 會送到專用的 Mac 主機上安裝執行。
• 箱子會連到你的程式自己會連的地方：npm、GitHub、你的 dev、第三方 API。
• 箱子連你 dev 的流量，經平行沙盒轉給你的連接器；連接器到平行沙盒走 TLS，你的服務自己的 TLS（例如資料庫的 SSL）從箱子到你的服務中間不會被解開。
• 平行沙盒本身不把你的程式碼交給任何 AI 模型。你的 AI 看到的東西（指令輸出、截圖）會經你的 AI client 送到你用的 AI 供應商，跟你在本機用它時一樣。
• App 裡的語音輸入會即時轉成文字，聲音與文字都不保存。

完整的說明在隱私權政策。

箱子停掉之後，磁碟真的會清掉嗎？

會：

• 停箱時，那台小型虛擬機被關掉，它的磁碟檔案隨即刪除。主機的磁碟是加密的，主機收掉時整顆刪除。
• 凍結中的箱子，記憶體與 /work 可能會暫存到加密的儲存空間；箱子恢復或停掉時就刪除。另外設了最長 10 天的保險上限，正常情況下等不到這麼久。
• 要講清楚的是：這是「刪檔＋加密磁碟」，不是逐 block 覆寫。

什麼會留下來、留多久、能不能刪？

要刪什麼，直接跟你的 AI 說（例如「刪掉這個箱子的截圖」「清掉編譯快取」），它會呼叫表裡的 REST。

刪除帳號時，運行中的箱子會停掉，上面這些最晚 30 天內全部刪除。REST 的細節見 REST。

箱子的網址誰打得開？能加登入或限制 IP 嗎？

• 箱子的網址長這樣：https://<id>-<key>.box.parallelsandbox.com。key 是隨機的，不對就跟不存在一樣回 404；拿到完整網址的人就打得開，所以請把它當分享連結看待。
• 要限制來源，替帳號設 IP 白名單：跟你的 AI 說「箱子網址只開給公司的 203.0.113.0/24」，它會呼叫 PUT /v1/box-access。約 3 秒後，帳號所有箱子的網址只接受名單內的 IP，其他來源一律 403、也不會喚醒凍結的箱子。名單整個帳號一份，最多 50 筆，目前只比對 IPv4；要關掉就請它設成空的。
• 適合有公司 VPN 或辦公室固定出口 IP 的團隊。同事打開交件網址、你用手機行動網路測時，都要從名單內的 IP 連（例如先連 VPN）。
• 不另外加登入：交件的網址要能直接給同事試，同事不需要平行沙盒帳號。
• 接手頁與 App 不靠網址裡的 key：接手連結是控制面發的一次性、會過期的 token，App 用你的登入。

資料庫與測試資料

每次開箱都是全新的環境嗎？

是。每個箱子從同一份乾淨快照開起來，箱子裡跑的資料庫只活到箱子停掉。同一個箱子在凍結期間會保留（見箱子會留多久？），但沒有像 Kubernetes PVC 那樣跨箱子共用的持久磁碟。

我服務的環境變數（DATABASE_URL 這類）怎麼進箱子？

存成環境的「服務設定」：從 AWS ECS 匯入（連同它引用的 SSM 參數與 Secrets Manager 值），或上傳一份 .env。開箱時帶這個環境，箱子裡就有 /work/.sbx/env/<服務>.env，改過的服務用它啟動，設定跟在 dev 上一樣。設定加密保存，API 只回變數名稱；改了設定，之後開的箱子才拿得到。

可以直接連 dev 的資料庫嗎？

可以：環境＋連接器，再加上上一題的服務設定。要注意：改過的服務用 dev 的設定啟動時，它的 migration 與寫入都會真的落在 dev 的資料庫。

我有一套測試資料，想每次接著用、不要每次 migration 和 seed？

把那個資料庫放在你自己的網路（例如 dev 環境裡專門給測試用的一台 Postgres），經環境的連接器讓箱子連過去。資料、migration 狀態都在你手上，每個箱子都接著用。這是目前唯一會一直留著的做法：平行沙盒不替你保存箱子裡的資料庫。

想每次都從乾淨的資料庫開始？

在箱子裡執行 psbx-testdb up <名字>，會開一個全新的 Postgres 16（--mysql 則是 MySQL 8.0），把 DATABASE_URL 寫到 /work/.sbx/testdb/<名字>.env；psbx-testdb reset <名字> 把它清回全新，psbx-testdb gotest ./... 讓每個 Go 套件各有一顆資料庫。其他資料庫照你平常的 docker compose 起。

一句話：什麼會留、什麼不會？

• 不會留：箱子裡的一切（程式、容器、資料庫、/work），停箱就沒了。
• 會留：你自己網路裡的東西（經連接器連的資料庫）、registry 裡發布的 image、編譯快取，以及上面表格列的保存檔案，各有各的期限。

Secrets

secrets 存在哪？怎麼進箱子？

• 整個帳號共用一份清單，存在控制面，加密保存。不是每個箱子各一份。
• 預設什麼都不進箱子。AI 開箱時點名要哪幾個，箱子被認領的那一刻才拿到，成為每個指令的環境變數；箱子停掉就跟著消失。
• 值存了就讀不回來：工具回傳、sandbox_status、平台 log 裡都只有名字。
• 進了箱子就是環境變數。指令把它印出來時，回到你的 AI 的內容會把它遮成 ****（8 個字以上的值），環境放進箱子、看起來像密鑰的 dev 設定也一樣；但箱子裡的檔案（例如程式自己寫的 log）仍是真的值，可能含有密鑰的檔案就別拿給你的 AI。
• 不要把平行沙盒自己的 API key 存成 secret，箱子不需要它。

有沒有設定畫面？

有。在 app.parallelsandbox.com 右上角齒輪 → 設定 → Secrets，可以新增、換值、刪除，列出名稱與更新時間，值永遠不會顯示。在 App 填的值不經過你跟 AI 的對話，也就不會送到 AI 供應商；token 在你手上時，建議走這裡。也可以請 AI 用 REST 存（Secrets）。

程式要用 AWS（S3、SQS）的權限怎麼辦？

不要存長期金鑰。在環境上指定一個 AWS 角色，箱子用 OIDC 換一小時到期的暫時憑證，跟 GitHub Actions 連 AWS 是同一套做法（箱子裡的 AWS 權限）。平行沙盒手上沒有任何能進你 AWS 帳號的長期權限。

費用

• 箱子從 ready 起按分鐘扣點，凍結的箱子不扣。10 分鐘沒有動作就會凍結，所以忘了收也不會一直燒錢。
• 往外的流量、log、保存的檔案另外計量；環境與連接器不收費。費率見點數。

範例 repo

每一步的工具呼叫在範例 repo。多個服務、dev 分在 AWS 與辦公室兩個網路、接連接器、從另一個箱子用改過的服務的完整例子，在團隊設定。