Agentlas OS v1.2.0 VPS 自架安裝指南

Agentlas OS 的實際定位

Agentlas OS 是開放原始碼的 agent runtime。它會將專用 agent 以套件形式儲存在磁碟上，並為每項任務建立暫時的 orchestrator。您可以將它安裝到 Linux VPS 上自己的使用者帳號中，以自行代管。它不是服務。沒有 daemon、監聽中的連接埠、Web 介面，也沒有儲存庫中的 container image。

上一段最後一句話決定了本頁其餘內容。多數 multi-agent 系統會執行持續運作的 supervisor process，並由該 process 持有各個 agent。Agentlas 則採用相反方式：專用 agent 以檔案形式儲存，而 orchestrator 只在執行任務期間存在。實際結果是，閒置的 hub 消耗的是磁碟空間，而不是記憶體。

此專案將其 open core 稱為 Hephaestus。您會在命令、路徑與環境變數中看到這個名稱。儲存庫為 agentlas-ai/Agentlas-OS，採用 Apache-2.0 授權，主要以 Python 撰寫。

這個專案目前究竟有多早期

此 repository 建立於 4 June 2026。截至 12 August 2026，專案約有十週歷史，約有 1,150 顆 stars 和 112 個 forks。對於要用來處理實際工作的工具而言，這仍屬早期階段。

版本發布頻率比專案年齡更值得注意。v1.1.103 於 8 August 2026 發布，v1.2.0 則於 12 August 2026 推出。1.1 系列已有超過 100 個標記版本，有些日子甚至發布數個版本，且由自動化流程發布。變更速度如此之快，代表工具的行為可能在週二與週四之間就發生變化。

因此，請固定版本。安裝程式會讀取對應的環境變數，以下整份指南都會使用該設定。未固定版本的安裝方式，會取得該小時 main 上恰好存在的版本，而這個專案每天會發布數次。

VPS 的需求

需求不多，因為沒有任何程式在背景執行。

• Linux VPS。Ubuntu 24.04 可作為合適的基準環境。安裝程式會使用 uname -s 偵測作業系統，並在 Linux 上採用非 macOS 分支，因此支援無頭主機。
• 主機上的 curl、tar 和 git，以及可正常運作的 Python 直譯器。
• 對 raw.githubusercontent.com 和 github.com 的對外 HTTPS 連線。安裝程式會下載 release archive 並驗證其 SHA-256，因此無法對外連線的主機無法完成安裝。
• Host harness，也就是實際與模型通訊的 coding agent。Claude Code、Codex、opencode、goose 和 Hermes 都有支援的 adapter。

不需要 root。安裝程式只會寫入你的家目錄和 ~/.local/bin；路徑不可寫入時，程式會發出警告而不會中止。如果你仍在選擇主機本身，在 VPS 上執行 coding agent 說明了此環境所依賴的基礎映像檔與存取設定。

安裝固定版本

上游 README 會提供一行指令，將來自 main 的 script 直接 pipe 至 bash。請先下載並閱讀該 script。它會寫入 shell 設定，以及找到的每個 agent harness，因此值得花十秒確認內容。

curl -fsSL -o install-all-runtimes.sh \
  https://raw.githubusercontent.com/agentlas-ai/Agentlas-OS/main/scripts/install-all-runtimes.sh
less install-all-runtimes.sh
HEPHAESTUS_REF=v1.2.0 bash install-all-runtimes.sh

HEPHAESTUS_REF 是固定版本。在 script 中，該行是 version="${HEPHAESTUS_REF:-v1.2.0}"。如果不明確設定，今天可能會取得 v1.2.0，下週則可能取得其他版本。明確設定後，您在 10 月重新建置時，安裝的就是 8 月測試過的版本。

有一項限制需要注意：上方的 script URL 會追蹤 main，而 HEPHAESTUS_REF 則固定 script 下載的 runtime payload。兩者並不相同。若要同時固定兩者，請從 tag 取得 script，而不要使用 main；將該 URL 中的 main 替換為 v1.2.0。

執行成功後，畫面會列出寫入的路徑，包括以下兩行：

Installed runner: /home/you/.agentlas/runtime/current/bin/hephaestus
Installed shell commands in /home/you/.local/bin (add ~/.local/bin to PATH to use them)

第二行最容易被忽略。在全新的 Ubuntu 主機上，~/.local/bin 通常不在 PATH 中，因此每個 hep-* 指令都會因 command not found 而失敗，即使安裝本身已成功。請修正後確認：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
hep-global status

hep-global status 會顯示全域 router 安裝的內容，以及偵測到的 harness。如果它能正常執行，表示您的 PATH 設定正確。

狀態儲存位置

主目錄下的所有內容都是檔案，因此備份與遷移都很簡單。

• ~/.agentlas/runtime/v1.2.0/ 儲存 runtime 本身，~/.agentlas/runtime/current/ 是指向使用中版本的 symbolic link。兩個固定版本可以並存。
• ~/.local/bin/ 儲存 shell wrapper：hephaestus、hep-build、hep-network、hep-search、hep-storm、hep-cloud 和 hep-upload。
• ~/.agentlas/networking/memory/ 儲存持久記憶：playbook-registry.json、playbook-candidates.jsonl 和 memory-events.jsonl。
• ~/.agentlas/networking/hub-agents/<slug>/memory/experience.sqlite 儲存個別 agent 的經驗，並依擁有者設定範圍。
• <project>/.agentlas/ontology-runtime.sqlite 儲存個別專案的狀態，因此狀態會隨 repository 移動，而不是綁定在伺服器上。
• ~/.cache/agentlas/python 在 Linux 上儲存 Python cache。macOS 使用不同路徑；installer 會透過 uname 選擇對應分支。

記憶文件明確規定，任何記憶範圍都不得存放 secrets、原始 credentials 或完整 transcripts。Credential 值應保存在 gitignored 的本機檔案中，記憶記錄只保留名稱與路徑。備份 ~/.agentlas 和專案的 .agentlas 目錄後，即可在新的 VPS 上重建環境。

可連接的模型後端

這裡有一項會重新界定整體設定方式的細節：Agentlas 不會呼叫模型 API，而是由主機 harness 呼叫。

架構文件描述了將核心元件轉換為各個 harness 的執行階段介接器，並指出模型認證資訊由主機執行階段管理。Agentlas 提供兩個由 harness 取用的介面：AgentSkills 檔案，以及透過 stdio 通訊的 MCP (model context protocol) 伺服器。因此，「Agentlas 支援哪些模型」實際上等同於「你的 harness 支援哪些模型」；答案是 Claude Code、Codex、opencode、goose 或 Hermes 能夠連線的任何模型。

在 Codex-style TOML 設定中，MCP 伺服器的註冊方式如下：

[mcp_servers.hephaestus-network]
command = "~/.agentlas/runtime/current/bin/hephaestus"
args = ["mcp", "serve"]

安裝期間，同一部伺服器也會自動註冊至 ~/.cursor/mcp.json、~/.config/goose/config.yaml 及其他 harness 設定。如果你要在同一台機器上配置多個這類伺服器，在 VPS 上執行 MCP 伺服器會更深入說明 stdio 與程序模型。

指向自架的 Ollama endpoint

由於 harness 負責管理模型連線，若要讓 Agentlas 使用本機模型，就必須將 harness 指向 Ollama。Ollama 在 v0.15 新增了 launch 子命令，正是用於此用途；截至 11 August 2026，v0.32.9 仍提供此功能。它可以設定現有 harness 使用本機模型，無須設定環境變數：

ollama pull qwen3-coder:30b
ollama launch opencode

請依安裝的 harness，將 opencode 替換為 claude、codex 或 droid。接著透過本機 runtime 傳送請求：

~/.agentlas/runtime/current/bin/hephaestus route "summarise the failing tests" --runtime ollama

成功路由時，會回傳一個 JSON 決策，指出所選用的 agent 或 team，並包含 receipt_id。如果沒有回傳可用結果，通常是 context length 不足。Agentlas 文件要求用於路由密集工作階段的模型至少具備 64k context，並以 qwen3-coder、gemma3 和 deepseek-r1 為例。Ollama 對 coding tools 的建議也是最低 64k。路由決策會將 agent inventory 放入 prompt，因此使用 8k 或 32k context 的模型會截斷 inventory，導致選擇錯誤。

有一點 tagline 不會告訴你。Ollama、Gemma 和 DeepSeek 本身沒有 plugin 或 command system，因此不存在 /agentlas slash commands。在本機模型設定中，應透過 MCP server 和 hephaestus route command 操作系統。這確實會縮減可用介面，但若要將模型權重保留在自己的主機上，這就是必須接受的取捨。

閒置專家中樞的 RAM 成本

完全沒有。這就是完整答案，而且你可以自行驗證，不必只相信這個說法。

借用的中樞專家會以套件成品的形式載入，而不是以程序形式執行。每個專家都是一個 agent.md，加上一個包含 JSON 的 .agentlas/ 目錄：routing-card.json 定義觸發條件與能力，memory-map.json 定義寫入邊界，mode-map.json 定義以單獨模式或團隊模式執行。Hephaestus Network 被描述為程序內排程器，不會執行背景服務。在工作之間，你可以自行檢查：

pgrep -af hephaestus
systemctl --user list-units --type=service | grep -i agentlas
du -sh ~/.agentlas

前兩個指令在閒置主機上不會輸出任何內容，因為沒有任何元件常駐。第三個指令會顯示閒置中樞施加的唯一成本，也就是磁碟空間。這項成本會隨你保留的專家數量增加，也會包含執行環境隨附的嵌入模型。

因此，記憶體問題完全取決於突發工作，而突發工作取決於你的 harness 與模型後端。如果 harness 連線至代管 API，常駐成本就是一個數百 MB 的程序。如果自行代管模型權重，主要成本就是模型權重：

[
  {
    "label": "Hosted API model",
    "weights_gb": 0
  },
  {
    "label": "gemma3:4b",
    "weights_gb": 3.3
  },
  {
    "label": "gemma3:12b",
    "weights_gb": 8.1
  },
  {
    "label": "gemma3:27b",
    "weights_gb": 17
  },
  {
    "label": "qwen3-coder:30b",
    "weights_gb": 19
  }
]

這些是 Ollama 模型庫公布的下載大小，不是基準測試執行結果；此外，64k context 的 KV cache 會在上述每個非零數值之上額外占用記憶體。Agentlas 文件首先列出的模型 qwen3-coder:30b，在計入 context 前就需要 19 GB 的模型權重；即使是 27B Gemma 變體，也需要 17 GB。與這些數值相比，Agentlas 層本身不會出現在資源預算中。

與執行單一 harness 的比較

對託管 API 執行單一 harness 時，VPS 只需承載一個程序。加入 Agentlas 後，仍是同一個程序，但會多出檔案。orchestrator 不是額外長時間執行的程式，而是根據磁碟上的套件組合較大的提示，完成後即捨棄。

會增加的是內容長度，而不是記憶體。orchestrator 載入多個專業卡片及其路由中繼資料後，每項工作消耗的 token 會比精簡 harness 更多。對託管 API 而言，增加的是費用，不是 RAM。使用本機模型權重時，增加的是處理時間，因為較長的提示會讓 CPU 的 prefill 時間更長，或讓 GPU 更繁忙。

因此，這類主機的規模建議取決於模型選擇，而不是 agent framework。為 coding agent VPS 配置 RAM 與 CPU 詳細說明了這一點，結論在此同樣適用：先依預計執行的 backend 選擇方案，再為 harness 預留幾 GB 的餘裕。如果要改用常駐 supervisor 設計進行比較，Omnigent multi-agent harness 會讓 coordinator 常駐記憶體，這是相反的取捨，也會直接反映在閒置記憶體用量上。

失敗情況與您會看到的訊息

安裝完成後立即出現 hep-build: command not found。 安裝程式將內容寫入 ~/.local/bin，但預設的 Ubuntu 映像檔不包含 PATH。安裝程式已在最後一行顯示這項資訊，但該行已向上捲動而看不到。請加入上方所示的 export。

重建伺服器後行為發生變化。 您未設定 HEPHAESTUS_REF，因此安裝程式採用當天最新的 tag。請固定該 tag，並將固定值記錄在其他版本號碼旁。

本機模型的路由選錯專用模型。 該模型的 context window 太小，無法容納 agent 清單。請改用 64k 以上的模型，並將 Ollama 的 context length 設為相同值，因為預設值低於 coding tools 的需求。

無法辨識 ollama launch。 此 subcommand 在 Ollama v0.15 才加入。distribution repository 中的舊套件早於此版本，因此請安裝目前版本的 Ollama。

安裝程式寫入了您未預期的 harness。 此 script 會偵測並設定找到的每個 harness，並寫入 ~/.claude/、~/.codex/、~/.gemini/、~/.cursor/ 及其他目錄。在共用的 build box 上，執行前請先閱讀該 script，確認需要管理哪些目錄。

是否現在就應該執行

一個只有十週歷史、每天自動發布數次的專案，不適合承載 production workload。它的架構確實很有趣，授權條款是 Apache-2.0，而且檔案型設計表示解除安裝時只需刪除兩個目錄。這些特性讓它容易試用，卻不適合作為相依服務。

目前較穩妥的做法是固定使用 v1.2.0，將它執行在可重建的主機上，將 ~/.agentlas 納入備份，並在變更版本固定前重新閱讀 changelog。若要更全面了解這個領域中的其他選項及各自的成熟度，自架 AI agents 的整理 是較好的起點；在 VPS 上自架 Hermes agent 則介紹 Agentlas 所調整的其中一種 harness。

FAQ

Agentlas OS 會在我的 VPS 上以伺服器形式執行嗎？

不會。儲存庫中沒有 daemon、監聽中的連接埠，也沒有 container image。安裝程式會將 runtime 寫入 ~/.agentlas/runtime/，並將 command wrapper 寫入 ~/.local/bin；Hephaestus Network 是程序內的 scheduler，不是背景服務。您可以在閒置的主機上確認這點：pgrep -af hephaestus 不會輸出任何內容，而且沒有可啟用的 systemd unit。這裡所說的 self-hosting，是指程式碼與狀態位於您的主機上，而不是有服務正在監聽。

閒置 specialist 組成的 hub 會使用多少 RAM？

不會使用 RAM，因為閒置的 specialist 不是程序。每個 specialist 都是 agent.md 檔案，加上存放 routing-card.json、memory-map.json 及其他類似 metadata 的 .agentlas/ 目錄。因此，停止工作的 hub 只會占用磁碟空間。使用 du -sh ~/.agentlas 進行測量。只有執行 task 時才會使用記憶體，而且消耗記憶體的是您的 harness process 與 model backend，不是 Agentlas layer。

我可以使用哪些 model？可以指定自己的 Ollama 嗎？

Agentlas 不會自行呼叫 model API。憑證與連線由 host harness 管理，因此支援的 model 取決於您的 harness 支援哪些 model。若要使用 local weight，請執行 ollama launch opencode，將 claude、codex 或 droid 替換為相應值。這會設定 harness 連線至您的 Ollama server，且不需要環境變數。請使用至少支援 64k context 的 model，例如 qwen3-coder 或 gemma3，因為 routing prompt 會包含 agent inventory，在較小的 context window 中容易遭到截斷。

我應該安裝哪個版本？為什麼這裡需要 pinning？

請在執行安裝程式前設定 HEPHAESTUS_REF=v1.2.0，以安裝 v1.2.0；這是截至 12 August 2026 最新的 tagged release。該 script 自身的預設值為 version="${HEPHAESTUS_REF:-v1.2.0}"，會跟隨 maintainers 下一次標記的版本。這裡比一般情況更需要 pinning，因為專案在 1.1 series 中發布了超過 100 個 release，有些日子甚至發布數個。因此，數週後未指定版本便重新建置，取得的系統可能與您測試過的系統不同。