在將要執行工作的電腦上設定一個 Oysterun Host、開啟其 dashboard，再從各自擁有該值的畫面讀取每個可見 identity。Host、Session、AgentFolder、Agent ID 與 shared Website link 即使含有相似文字，也不能互換。

1. 準備電腦與執行權限

請在一般終端機中，以之後要執行 Oysterun 的同一位作業系統使用者操作。安裝前，準備：

2. 安裝 Oysterun 並進入 setup

安裝公開的 Oysterun command，再執行它：

npm install -g oysterun
oysterun

必要 Host settings 缺少或不完整時，oysterun 會自動進入 setup。之後要重新開啟 setup 問題時，使用：

oysterun setup

步驟 1 前，Oysterun 會檢查 Claude 或 Codex 是否可用。兩者都找不到時，會顯示 Continue setup without an agent provider?

3. 完成畫面實際顯示的 setup 步驟

task-owned 終端機的完整 setup checkpoint，同框顯示 oysterun setup 命令、編號 Host name 與 Project folders context、provider preflight，以及 Start Oysterun Host now 問題，沒有 password input 或 shell history。
Setup checkpoint：真實的 oysterun setup 流程顯示從 Host name、Project folders、provider detection 到步驟 7 Start Host 的編號 context；畫面沒有 password input 或不相關 shell history。

1. Host name

在 Name this Host 輸入容易辨認這台電腦的 display name。它在產品清單中識別 Host；不是 Session Name 或 Agent ID。

2. Project folders

選擇一個已存在的 Default Browse Root。這是 Host 的 project-discovery boundary，本身不會啟動 Session。新的 Session 沒有明確指定資料夾時，它會預先填入 Start Folder；因此啟動該 Session 前，請在 Session Setup 確認或變更畫面上的 Start Folder。

3. Host password

建立並確認 password。輸入內容會隱藏。Dashboard 登入表單只要求這組 Host password，不會顯示 username 欄位。

4. Managed connectivity

Oysterun 會註冊或繼續使用這個 Host，並配置或重用穩定的 Managed Endpoint。一般 setup 不會要求 public IP、router port、domain、第三方 tunnel 或 Cloud token。

5. Help improve Oysterun?

閱讀每日 aggregate report 說明，再決定是否傳送。這項 consent 不會改變 Host、Session 或資料夾 identity。

6. Phone app

一般互動式 setup 會詢問 Show phone app download link and QR code? 採用預設的 No，即可不顯示兩者並繼續步驟 7。只有需要 download link 與 QR 時才選擇 Yes。即使不進行 phone pairing，也能完成 Host 與 web dashboard 設定。

7. Start Host

新的 managed service 會詢問是否立刻啟動 Host。已有 managed Host 執行時，問題會改為 Restart Oysterun Host now?；沒有本次確切 restart 許可就停止。成功啟動後，setup 可能會自動開啟 dashboard。

4. 確認預期的 Host 已準備完成

task-owned setup 終端機的完整成功畫面，同框顯示 Oysterun Host is running、Managed Tunnel is ready、Managed Endpoint 與 local Host URL。
Ready checkpoint：同一次 setup 顯示 task-owned Host 已成功執行、Managed Tunnel 與 Managed Endpoint 已 ready，並在同一個 terminal frame 保留 Direct／local fallback URL。
  1. Managed start 成功後，找到 Managed Tunnel is ready 與印出的 Managed Endpoint。Setup 也會印出 local 或 Direct Host URL。
  2. Managed Endpoint ready 時開啟它。Managed provisioning pending 時，Direct Host URL 是同一個可信網路上的有界 fallback。
  3. 輸入 Host password，再選擇 Open Oysterun。
  4. 等待 Sessions，並確認顯示 Connected。
  5. 開啟 Oysterun 選單、選擇 Host Preferences，再找到 Host Identity And Browse Root。確認 Host Display Name 與 Default Browse Root 符合 setup 輸入。

如果你在步驟 7 刻意選擇不要啟動，支援的明確啟動命令是 oysterun service:start。只有獲准啟動該已設定的 Host 時才能執行。

5. 分開理解五種可見 identity

已連線 task-owned Direct Host 的完整 Host Preferences identity 畫面，顯示 Host Display Name、完整短 Default Browse Root、Active Config File 與 Claude Code default runtime。
Host identity checkpoint：Host Preferences 識別 P131 A-P05 Host、保留 Connected 與 Direct Host context，並完整顯示 macOS 解析後的 task root /private/tmp/p131-a5、folder control 與 default runtime。

Host

在一台電腦上執行的 Oysterun service。從 Host Preferences 讀取 Host Display Name、Default Browse Root 與連線位址。Endpoint 會開啟這個 Host；它不是 Session 或公開的 Website link。

Session

該 Host 上的一段對話與 provider runtime。使用者可讀的 Session Name 會顯示在 Sessions 與 Chat。不可變的確切 Session ID 則顯示在 Session Profile。

AgentFolder

選為 Start Folder，之後顯示為 Working Directory 的確切工作資料夾。它擁有 Session 的檔案。同一個資料夾可供多個 Session 使用，但這不會合併那些 Session。

Agent ID

在 Session Setup 輸入、並顯示在 Session Profile 的 grouping 與 attribution label。它不會選擇資料夾、不會取代 Session ID、不會識別 Host，也不會形成 Website URL。

使用 Website 的 Copy link 或 Website browser 的 Copy browser link 所複製的 URL。其 /sites/…/ route 指向從 project folder 解析出的 Website。不要用 Agent ID、Session Name 或 Session ID 自行編造。

6. 建立一個 Session 並讀回其 identity

已連線 task-owned Direct Host 的完整 Session Setup，顯示 Agent ID p131-a5-agent、Session Name P131 A5 Identity、完整 Start Folder /tmp/p131-a5，以及已選取的 Claude Agent Runtime。
Session Setup checkpoint：新的 P131 A5 Identity Session 顯示 Agent ID p131-a5-agent、完整 Start Folder /tmp/p131-a5 與已選取的 Claude；header 同時確認已連線 Direct Host。
P131 A5 Identity 的完整 Session Profile identity，顯示 Agent ID、獨立 Session ID、macOS 解析後的完整 Working Directory，以及相符的 Workspace Policy Root。
Session Profile checkpoint：同一個 P131 A5 Identity Session 顯示 Agent ID p131-a5-agent、獨立產生的 Session ID，以及 macOS 解析後的完整 Working Directory 與 Workspace Policy Root /private/tmp/p131-a5。
  1. 從 Sessions 選擇 New Session。
  2. 在 Session Setup 輸入容易辨認的 Agent ID 與唯一的 Session Name。
  3. 選擇預期的 Start Folder，不要假設它就是整個 Default Browse Root。
  4. 檢查可用的 provider settings，再選擇 Start Session。
  5. Chat 開啟後，選擇該 live Session top bar 上的 Open Session Profile 控制項。
  6. 比對 Agent ID 與先前輸入、Working Directory 與選擇的 Start Folder，並確認 Session ID 是另一個由系統產生的值。

畫面檢查點：Chat top bar 只會為目前的 live Session 提供 Open Session Profile；開啟後，profile 會顯示供本次比對使用的 Agent ID、Working Directory 與另一個 Session ID。

檢查點：Host 包含 Session；Session 使用 AgentFolder；Agent ID 標記 attribution；Session ID 仍識別確切 Session。文字相同也不會讓它們變成同一種 authority。

task-owned p128-website-folder 的完整 Website row，顯示 Ready、Available、/sites/p128-website-folder/ route、copy control 與可見的 copied-link result。
Shared-link checkpoint：task-owned p128-website-folder row 在 /sites/p128-website-folder/ 顯示 Ready 與 Available；copy control 已產生可見的「Copied link for p128-website-folder」結果。
  1. 只有預期資料夾已啟用 Website，而且出現在 Website surface 時才繼續。
  2. 確認 Website row 顯示預期資料夾與可見的 /sites/…/ entry path。
  3. 選擇 Copy link，或開啟 Website 後選擇 Copy browser link。
  4. 以預期 audience 開啟複製的 URL，確認它顯示該資料夾所屬的 Website。

Website row 不存在、unavailable 或屬於另一個資料夾時，請停止。不要改用 Host endpoint、Agent ID、Session Name、Session ID 或本機檔案路徑當作 shared link。

安全恢復與停止條件

安全停止：只有預期 Host 顯示 Connected、Host Preferences 符合 setup、Session Profile 符合選擇的 AgentFolder 與 Agent ID，而且每個 shared link 都指向預期 folder-owned Website 後，才開始一般工作。