在將要執行工作的電腦上設定一個 Oysterun Host、開啟其 dashboard，再從各自擁有該值的畫面讀取每個可見 identity。Host、Session、AgentFolder、Agent ID 與 shared Website link 即使含有相似文字，也不能互換。
1. 準備電腦與執行權限
請在一般終端機中，以之後要執行 Oysterun 的同一位作業系統使用者操作。安裝前，準備：
- 一台支援的 macOS 或 Linux 電腦，使用 Host 時可持續開機；
- Node.js 20 或更新版本，以及與它相符的
npm命令； - 如果要立刻啟動 Session，請為同一位使用者安裝並登入 Claude Code 或 Codex；
- 一個已存在、要作為 Default Browse Root 的資料夾；
- 一組可輸入兩次的新 Host password；以及
- 一般 Managed connectivity 所需的 outbound HTTPS 連線。
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?
- 選擇 No，或按 Enter 採用預設的 No，即可安全停止。終端機應以 Installation cancelled; no changes were made. 結束。
- 只有你刻意要先設定 Host、之後才安裝 provider 時，才選擇 Yes。Host 可以完成設定，但同一位作業系統使用者仍須安裝 Claude Code 或 Codex，才能建立新的 Session。
3. 完成畫面實際顯示的 setup 步驟
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 已準備完成
檢視完整尺寸截圖
- Managed start 成功後，找到 Managed Tunnel is ready 與印出的 Managed Endpoint。Setup 也會印出 local 或 Direct Host URL。
- Managed Endpoint ready 時開啟它。Managed provisioning pending 時，Direct Host URL 是同一個可信網路上的有界 fallback。
- 輸入 Host password，再選擇 Open Oysterun。
- 等待 Sessions，並確認顯示 Connected。
- 開啟 Oysterun 選單、選擇 Host Preferences，再找到 Host Identity And Browse Root。確認 Host Display Name 與 Default Browse Root 符合 setup 輸入。
如果你在步驟 7 刻意選擇不要啟動，支援的明確啟動命令是 oysterun service:start。只有獲准啟動該已設定的 Host 時才能執行。
5. 分開理解五種可見 identity
/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。
Shared Website link
使用 Website 的 Copy link 或 Website browser 的 Copy browser link 所複製的 URL。其 /sites/…/ route 指向從 project folder 解析出的 Website。不要用 Agent ID、Session Name 或 Session ID 自行編造。
6. 建立一個 Session 並讀回其 identity
p131-a5-agent、完整 Start Folder /tmp/p131-a5 與已選取的 Claude；header 同時確認已連線 Direct Host。檢視完整尺寸截圖
p131-a5-agent、獨立產生的 Session ID，以及 macOS 解析後的完整 Working Directory 與 Workspace Policy Root /private/tmp/p131-a5。檢視完整尺寸截圖
- 從 Sessions 選擇 New Session。
- 在 Session Setup 輸入容易辨認的 Agent ID 與唯一的 Session Name。
- 選擇預期的 Start Folder，不要假設它就是整個 Default Browse Root。
- 檢查可用的 provider settings，再選擇 Start Session。
- Chat 開啟後，選擇該 live Session top bar 上的 Open Session Profile 控制項。
- 比對 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。
7. 不靠猜測，驗證 shared Website link
p128-website-folder row 在 /sites/p128-website-folder/ 顯示 Ready 與 Available；copy control 已產生可見的「Copied link for p128-website-folder」結果。檢視完整尺寸截圖
- 只有預期資料夾已啟用 Website，而且出現在 Website surface 時才繼續。
- 確認 Website row 顯示預期資料夾與可見的
/sites/…/entry path。 - 選擇 Copy link，或開啟 Website 後選擇 Copy browser link。
- 以預期 audience 開啟複製的 URL，確認它顯示該資料夾所屬的 Website。
Website row 不存在、unavailable 或屬於另一個資料夾時，請停止。不要改用 Host endpoint、Agent ID、Session Name、Session ID 或本機檔案路徑當作 shared link。
安全恢復與停止條件
- 未偵測到 provider：採用預設 No 取消，以得到不變更的結果；或在明知限制的情況下繼續，並在建立 Session 前，為 Host 的作業系統使用者安裝並登入 Claude Code 或 Codex。
- Managed connectivity 持續 pending：只在同一個可信網路使用 Direct access；修正 network prerequisite 後重新執行 setup。不要 reset Host identity。
- Setup 要求重新啟動既有 Host：沒有該確切 Host 與動作的即時許可就停止。不要因本指南改用 service 或 terminal restart。
- Host Display Name 或 Default Browse Root 錯誤：建立 Session 前停止。修正 Host Preferences 的可見值並選擇 Save；需要放棄或重新讀取 draft 時，請在儲存前使用 Reset/Reload。不要編輯隱藏設定。
- Agent ID 或 Working Directory 錯誤：在使用該 Session 進行 attribution 或檔案工作前停止。回到 Sessions，透過 Session Setup 建立預期 Session；不要改寫 Website route 或 private record 來掩飾不一致。
- 畫面沒有有效 Website link：尚未證明 shared Website identity。回到預期 Website row，解決畫面上的 availability，不要自行組合 link。
安全停止：只有預期 Host 顯示 Connected、Host Preferences 符合 setup、Session Profile 符合選擇的 AgentFolder 與 Agent ID，而且每個 shared link 都指向預期 folder-owned Website 後，才開始一般工作。