# 設定並理解你的 Oysterun Host

完成目前支援的 Host 設定流程，再從畫面區分 Host、Session、AgentFolder、Agent ID 與 Website shared link。

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

成功結果：

設定流程抵達預期 Host 的

Sessions

畫面，而且顯示

Connected

；Host Preferences 能識別該 Host 與 browse root；Session Setup 與 Session Profile 對第一個 Session 的資料夾與 Agent ID 顯示一致；而且任何複製的 Website link 只開啟預期資料夾所屬的 Website。

## 1. 準備電腦與執行權限

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

- 一台支援的 macOS 或 Linux 電腦，使用 Host 時可持續開機；
- Node.js 20 或更新版本，以及與它相符的 `npm` 命令；
- 如果要立刻啟動 Session，請為同一位使用者安裝並登入 Claude Code 或 Codex；
- 一個已存在、要作為 **Default Browse Root** 的資料夾；
- 一組可輸入兩次的新 Host password；以及
- 一般 Managed connectivity 所需的 outbound HTTPS 連線。

生命週期界線：

先取得在這台電腦安裝並啟動 Oysterun 的許可。如果 setup 找到已在執行的 Host，並把步驟 7 改成 restart，只有在取得同時指明該確切 Host 與本次 restart 動作的即時許可後才能繼續。一般 setup 或 settings 權限不等於 restart 許可。

## 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 步驟

![task-owned 終端機的完整 setup checkpoint，同框顯示 oysterun setup 命令、編號 Host name 與 Project folders context、provider preflight，以及 Start Oysterun Host now 問題，沒有 password input 或 shell history。](../assets/publication/host-setup-seven-steps.png)

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。](../assets/publication/host-setup-managed-ready.png)

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。
1. Managed Endpoint ready 時開啟它。Managed provisioning pending 時，Direct Host URL 是同一個可信網路上的有界 fallback。
1. 輸入 Host password，再選擇 **Open Oysterun**。
1. 等待 **Sessions**，並確認顯示 **Connected**。
1. 開啟 Oysterun 選單、選擇 **Host Preferences**，再找到 **Host Identity And Browse Root**。確認 **Host Display Name** 與 **Default Browse Root** 符合 setup 輸入。

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

Managed pending：

不要只因 Managed Endpoint 尚未 ready 就 reset setup 或建立第二個 Host identity。先在同一個網路使用印出的 Direct Host URL，修正 outbound network prerequisite，再執行

oysterun setup

。Retry 會重用原本的 Host identity。

## 5. 分開理解五種可見 identity

![已連線 task-owned Direct Host 的完整 Host Preferences identity 畫面，顯示 Host Display Name、完整短 Default Browse Root、Active Config File 與 Claude Code default runtime。](../assets/publication/host-identity-browse-root.png)

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。

### 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

![已連線 task-owned Direct Host 的完整 Session Setup，顯示 Agent ID p131-a5-agent、Session Name P131 A5 Identity、完整 Start Folder /tmp/p131-a5，以及已選取的 Claude Agent Runtime。](../assets/publication/session-setup-identity.png)

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。](../assets/publication/session-profile-identity.png)

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**。
1. 在 **Session Setup** 輸入容易辨認的 **Agent ID** 與唯一的 **Session Name**。
1. 選擇預期的 **Start Folder**，不要假設它就是整個 **Default Browse Root**。
1. 檢查可用的 provider settings，再選擇 **Start Session**。
1. Chat 開啟後，選擇該 live Session top bar 上的 **Open Session Profile** 控制項。
1. 比對 **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

![task-owned p128-website-folder 的完整 Website row，顯示 Ready、Available、/sites/p128-website-folder/ route、copy control 與可見的 copied-link result。](../assets/publication/website-link.png)

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 時才繼續。
1. 確認 Website row 顯示預期資料夾與可見的 `/sites/…/` entry path。
1. 選擇 **Copy link**，或開啟 Website 後選擇 **Copy browser link**。
1. 以預期 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 後，才開始一般工作。