SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

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

在 Linux VPS 固定安裝 Agentlas OS v1.2.0,了解 Hephaestus 狀態檔位置、如何連接 Ollama,以及閒置 agent hub 實際消耗的磁碟與成本。

Agentlas OS 的實際定位

Agentlas OS 是開放原始碼的 agent runtime,會將專業 agent 以套件形式儲存在磁碟上,並為每項工作建立暫時的 orchestrator。您可以將它安裝到 Linux VPS 上的自有使用者帳號,自行代管。以下固定使用 v1.2.0 的命令列安裝方式,並不是服務:安裝程式不會啟用 daemon,也不會開啟 listening port。目前的專案也另有說明獨立的 desktop app。

這項區分會決定本頁其餘所有內容。多數 multi-agent 系統會執行持續運作的 supervisor process,並由它持有各個 agent。Agentlas 則採取相反的架構:專業 agent 是靜態檔案,orchestrator 只在工作執行期間存在。實際結果是,閒置的 hub 只會占用磁碟空間,不會占用記憶體。

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

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

截至 2026 年 10 月 13 日,這個 repository 約有 4 個月的歷史,約有 1,580 顆 stars 和 110 個 forks。對於要用來處理實際工作的工具而言,這仍處於早期階段。

相較於專案年齡,release cadence 更重要。v1.1.103 於 2026 年 8 月 8 日發布,v1.2.0 則於 2026 年 8 月 12 日發布。1.1 系列已有超過 100 個 tagged releases,有些日子甚至發布數個,並由 automation 執行發布。1.2 系列也維持相同速度:截至 2026 年 10 月 10 日,已達到 v1.2.62。變更速度如此快的專案,可能在星期二和星期四之間就改變行為。

因此,請固定 release 版本。installer 會讀取用於此目的的 environment variable,以下整份指南都會使用它。對於發布如此頻繁的專案,若不固定版本,安裝程式可能會安裝 script 上次編輯時最近標記的版本。

VPS 所需條件

需求不多,因為閒置的 specialists 是檔案,不是程序。

  • Linux VPS。Ubuntu 24.04 可作為合適的基準。安裝程式會使用 uname -s 偵測作業系統,並在 Linux 上採用非 macOS 分支,因此支援無頭伺服器。
  • 伺服器上需有 curl、tar 和 git,以及 Python 3.9 或更新版本。固定版本的安裝程式會使用 Python 驗證隨附的 embedding model。
  • 正常安裝需要對 raw.githubusercontent.com 和 github.com 具備對外 HTTPS 連線。安裝程式會下載 release archive,並驗證其 SHA-256。現行獨立安裝程式會透過 standalone_local_source_unverified 拒絕 HEPHAESTUS_SOURCE_DIR;目前不再支援透過該變數進行離線安裝。
  • Host harness,也就是實際與 model 通訊的 coding agent。Claude Code、Codex、opencode、goose 和 Hermes 都有支援的 adapter。

不需要 root。安裝程式只會在家目錄下寫入檔案,包括 ~/.local/bin。步驟失敗時,例如路徑無法寫入,安裝程式會發出警告並繼續執行其餘步驟;如果有任何步驟失敗,最後會以非零狀態碼結束。如果你尚未決定伺服器本身,在 VPS 上執行 coding agent 說明了此設定所依據的基礎映像檔與存取設定。

安裝固定版本

上游 README 提供單行指令,會將來自 main 的腳本直接傳送給 bash 執行。請先下載 v1.2.0 安裝程式並閱讀內容。它會寫入找到的每個 agent harness,因此值得花十秒確認。

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

HEPHAESTUS_REF 是固定版本。截至 8 November 2026,main 上的腳本使用 release_ref="${HEPHAESTUS_REF:-os-v1.2.89}";發布頁面則將今天透過 os-v1.2.89 發布的 Agentlas OS 1.2.89 標示為 Latest。目前的安裝程式要求使用 os-v 標籤,並會以 standalone_channel_tag_invalid 拒絕 HEPHAESTUS_REF=v1.2.0。上方的歷史安裝程式接受該固定版本。

上方的腳本 URL 同時將安裝程式與 runtime payload 固定在 v1.2.0。目前的獨立安裝使用 ~/.agentlas/os-runtime 與 ~/.agentlas/os-bin/agentlas-os launcher,預設不再安裝 global wrapper,也不再永久註冊 host plugin 與 MCP。這些預設值與下方說明的歷史安裝方式不同。

固定版本只涵蓋安裝程序,不涵蓋後續行為。在 v1.2.0 中,hephaestus 指令會啟動背景更新檢查。若有較新的版本,系統會在未詢問的情況下安裝該版本,並重新指向 ~/.agentlas/runtime/current。安裝程式會使用 HEPHAESTUS_AUTO_UPDATE=0 停用本次執行的更新檢查;要維持這個歷史固定版本,也必須使用相同變數。下一步會將它加入 shell profile。目前的獨立安裝預設關閉自動更新。

成功執行後,系統會列出寫入的路徑。當 ~/.local/bin 不在 PATH 中時,會包含以下幾行:

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)

PATH 警告就是最容易被略過的訊息。在全新的 Ubuntu 主機上,~/.local/bin 通常不在 PATH 中,因此每個 hep-* 指令都會以 command not found 失敗,即使安裝已成功。將它加入 ~/.bashrc,同時關閉歷史背景更新程式,然後確認:

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

hep-global 是 hephaestus global 的原始拼寫;status 則會顯示每個 harness instruction file 是否包含受管理的 router 區塊。該 router 預設為關閉,因此預期結果為 none。只要指令能執行,代表你的 PATH 正確。

狀態的儲存位置

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

  • ~/.agentlas/runtime/1.2.0/ 儲存執行環境本身(安裝程式會從標籤中移除開頭的 v),而 ~/.agentlas/runtime/current/ 是指向目前啟用版本的符號連結。兩個固定版本可以並存。
  • ~/.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 使用不同路徑,安裝程式會透過 uname 選擇該分支。

v1.2.0 的記憶文件明確規定,任何記憶範圍都不得存放 secrets、原始憑證或完整 transcript。憑證值應保留在已加入 gitignore 的本機檔案中,記憶只記錄名稱與路徑。備份 ~/.agentlas 和專案的 .agentlas 目錄後,就能在新的 VPS 上重建環境。

有一項資料會離開主機:在固定的 v1.2.0 release 中,hep-build 預設會傳送匿名的 build counter,不包含提示內容、路徑或 agent 內容。設定 AGENTLAS_TELEMETRY=0 或 DO_NOT_TRACK=1,或在 ~/.agentlas/networking/config.json 中加入 "telemetry": false 和 "telemetrySetBy": "user",即可停用此功能。目前 standalone telemetry 預設為關閉。

可指向的模型後端

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

架構文件說明,runtime adapter 會將單一核心轉換為各個 harness 可使用的形式;README 則指出,adapter 負責其 provider 的驗證,而呼叫端需提供自己的模型與 API 存取權限。Agentlas 提供兩個可由 harness 取用的介面:AgentSkills 檔案,以及透過 stdio 通訊的 MCP(model context protocol)伺服器。因此,「Agentlas 支援哪些模型」實際上等同於「你的 harness 支援哪些模型」,答案是 Claude Code、Codex、opencode、goose 或 Hermes 能夠存取的任何模型。

在 Codex 風格的 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 端點

由於 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。接著,透過本機執行環境路由請求:

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

成功路由後會回傳 JSON 決策,指出所選取的 agent 或 team,並包含 receipt_id。如果回傳內容沒有作用,請檢查 context length。v1.2.0 的 local-models 文件要求路由密集的工作階段使用至少 64k context 的模型,並以 qwen3-coder、gemma3 及 deepseek-r1 為例。Ollama 對 coding tools 的建議也相同,最低要求為 64k。路由決策會將 agent inventory 放入 prompt,因此 8k 或 32k context 的模型會截斷 inventory,導致選擇錯誤。

有一項標語不會告訴你的限制。Ollama、Gemma 與 DeepSeek 本身沒有 plugin 或 command system,因此其中不存在 /agentlas slash commands。使用 Ollama 啟動的 harness 仍會提供自己的 commands、skills 與 plugins;但原始 Ollama API loop 則改用 MCP server 或 hephaestus route command。對原始 API loop 而言,這確實會縮小可用功能範圍。

閒置專家中心需要多少 RAM

完全不需要。這就是完整答案,而且你可以自行驗證,不必直接相信。

借用的中心專家是套件成品,不是常駐程序。專家由一個 agent.md 和一個包含 JSON 的 .agentlas/ 目錄組成:routing-card.json 定義觸發條件與功能,memory-map.json 定義寫入範圍,mode-map.json 定義以單獨模式或團隊模式執行。Hephaestus Network 文件說明,runner 會為工作啟動 worker;其中沒有任何內容會開啟 listening port,也不會要求你啟用服務。在工作之間,請自行檢查:

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

由命令觸發的 worker 結束後,前兩個命令在閒置主機上不會輸出任何內容,因為專家不是常駐程序。固定使用的 v1.2.0 可能在命令返回後,留下短暫執行且已脫離的更新與建置遙測 worker。HEPHAESTUS_AUTO_UPDATE=0 可停用其 updater;遙測則需要使用上文所述的個別退出設定。目前,獨立更新檢查與遙測預設均已停用。第三個命令只會列出閒置中心占用的成本,也就是磁碟空間。成本會隨你保留的專家數量增加,也會包含 runtime 隨附的 embedding model。

因此,記憶體問題完全取決於 burst,而 burst 取決於你的 harness 與 model backend。如果 harness 使用 hosted API,常駐成本就是 harness 程序,其記憶體使用量取決於 harness 與工作負載。如果你自行託管權重,權重就是主要成本:

圖表Model weights resident on the VPS, published Ollama download sizes, November 2026
此圖表背後的資料
[
  {
    "label": "Hosted API model",
    "weights_gb": 0
  },
  {
    "label": "gemma3:4b",
    "weights_gb": 3.4
  },
  {
    "label": "gemma3:12b",
    "weights_gb": 8.2
  },
  {
    "label": "gemma3:27b",
    "weights_gb": 17
  },
  {
    "label": "qwen3-coder:30b",
    "weights_gb": 19
  }
]

以上是 Ollama model library 公布的下載大小,不是 benchmark 執行結果;此外,64k context 的 KV cache 會額外占用記憶體,因此所有大於零的數值都還要加上這項成本。Agentlas 文件首先列出的 model qwen3-coder:30b,在計入 context 前就需要 19 GB 的權重;即使是 27B Gemma variant,也需要 17 GB。與這些數值相比,Agentlas layer 本身不會出現在記憶體預算中。

與執行單一 harness 的比較

對託管 API 執行單一 harness 時,VPS 只需承載一個程序。加入 Agentlas 後,除了相同的 harness,還會承載檔案與任務範圍內的執行階段程序。orchestrator 並不是額外的常駐程式,而是由磁碟上的套件組合成較大的提示,使用後即丟棄。

實際增加的是 context,而不是記憶體。orchestrator 載入多個 specialist cards 及其 routing metadata 時,每項任務使用的 token 會比單純的 harness 更多。對託管 API 而言,這代表成本增加,而不是 RAM 增加。使用本機 weights 時,增加的是處理時間,因為較長的提示會讓 CPU 的 prefill 時間變長,或讓 GPU 承受更高負載。

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

失敗模式與您將看到的字串

剛完成安裝後出現 hep-build: command not found。 固定版本的安裝程式寫入 ~/.local/bin,但部分新開啟的 shell 之 PATH 沒有此路徑。安裝程式已在輸出接近結尾處說明這點,但警告訊息可能已經向上捲過。將上方顯示的 export 加入 ~/.bashrc。

重建主機後行為改變。 您未設定 HEPHAESTUS_REF,因此安裝程式採用其腳本當天指定的 tag。將版本固定,並在其他版本號旁記錄此固定值。

未重建主機但行為改變。 在固定版本 v1.2.0 中,背景更新程式可能安裝較新的 release,並將 ~/.agentlas/runtime/current 移至該版本。檢查 current 目前指向的位置,並在 harness 執行所使用的環境中設定 HEPHAESTUS_AUTO_UPDATE=0,不要只在互動式 shell 中設定。現行獨立安裝的自動更新預設為停用。

本機模型的路由選錯專用模型。 檢查模型的 context window 是否太小,無法容納 agent 清單。改用 64k 以上的模型,並將 Ollama 的 context length 設為相同值。當 VRAM 小於 24 GiB 時,Ollama 預設為 4k;從 24 GiB 至小於 48 GiB 時預設為 32k;達到 48 GiB 以上時預設為 256k。因此,較小的配置需要明確提高此值。

無法辨識 ollama launch。 此子命令是在 Ollama v0.15 中加入的。distribution repository 中的舊套件早於此功能,因此請安裝目前版本的 Ollama。

安裝程式寫入了您未預期的 harness。 固定版本的腳本會偵測並設定找到的每個 harness,寫入 ~/.claude/、~/.codex/、~/.gemini/、~/.cursor/ 等路徑,也會編輯已存在的設定檔,例如 ~/.codex/config.toml,並在原檔旁保留備份。在共用的建置主機上,執行前請先閱讀腳本,並確認您需要管理其中哪些目錄。

現在是否適合執行

這個專案仍很新,且會自動發布版本,有時一天會發布數次,因此不適合承載正式環境的工作負載。其架構確實很有意思,授權條款是 Apache-2.0,所有狀態都儲存在可備份的檔案中。但實際移除時並不如上述描述般簡單:v1.2.0 的 README 未提供解除安裝方式,固定版本的安裝程式會在家目錄中的多個位置寫入檔案,並修改現有的 harness 設定,而 hephaestus global remove 只會移除選用的 router 區塊。這些情況表示,在可丟棄的主機上試用成本很低,但要依賴它的成本很高。

目前較合理的做法是使用其標記版本的安裝程式固定在 v1.2.0,設定 HEPHAESTUS_AUTO_UPDATE=0 以維持這個歷史版本固定值,在可重新建置的主機上執行,將 ~/.agentlas 納入備份,並在移動版本固定值前重新閱讀變更日誌。若要更廣泛了解這個領域還有哪些選項,以及各選項的成熟度,自架 AI agent 的整理 是較好的起點;而 在 VPS 上自架 Hermes agent 則介紹 Agentlas 所適配的其中一個 harness。

FAQ

Agentlas OS 會在我的 VPS 上以伺服器身分執行嗎?

固定使用 v1.2.0 的命令列安裝不會啟用 daemon,也不會開啟監聽連接埠。安裝程式會將 runtime 寫入 ~/.agentlas/runtime/,並將命令包裝程式寫入 ~/.local/bin。Hephaestus Network 會在工作啟動時執行,而不是以背景服務執行。由命令觸發的 worker 結束後,在閒置的主機上執行 pgrep -af hephaestus 不會輸出任何內容。固定版本可以啟動短暫執行的更新與建置遙測 worker:HEPHAESTUS_AUTO_UPDATE=0 會停用更新程式,而 AGENTLAS_TELEMETRY=0 或 DO_NOT_TRACK=1 會停用遙測。現在的獨立更新檢查與遙測預設為關閉。在此處,自行託管是指程式碼與狀態位於你的機器上,不代表有服務正在監聽。

閒置 specialist 的 hub 會使用多少 RAM?

不會使用,因為閒置的 specialist 不是程序。specialist 是一個 agent.md 檔案,以及一個存放 routing-card.json、memory-map.json 和類似中繼資料的 .agentlas/ 目錄。因此,停放的 hub 只會占用磁碟空間。使用 du -sh ~/.agentlas 測量其大小。工作與短暫執行的背景 worker 會消耗記憶體;停放的 specialist 不會。

我可以使用哪些模型?可以指定自己的 Ollama 嗎?

Agentlas 不會自行呼叫模型 API。主機上的 harness 負責憑證與連線,因此支援的模型取決於你的 harness 所支援的模型。若要使用本機權重,請執行 ollama launch opencode,並替換 claude、codex 或 droid。此命令會將 harness 設定為連線至你的 Ollama server,不需要環境變數。請使用至少具備 64k context 的模型,例如 qwen3-coder 或 gemma3,因為路由提示會包含 agent 清單,在較小的 context window 中很容易遭到截斷。

我應該安裝哪個版本?為什麼在此處固定版本很重要?

請依照上方說明,從 v1.2.0 tag 取得安裝程式,並設定 HEPHAESTUS_REF=v1.2.0,以安裝 v1.2.0。這是 12 August 2026 當時最新的標記版本。截至 8 November 2026,main 上的 script 預設值為 release_ref="${HEPHAESTUS_REF:-os-v1.2.89}",而 Agentlas OS 1.2.89 是最新版本,已於今天以 os-v1.2.89 發布。目前的安裝程式只接受 os-v 版本 tag,並拒絕舊的 v1.2.0 pin。固定版本在此特別重要,因為專案在 1.1 系列發布了超過一百個版本,有些日子甚至發布多個版本。因此,數週後進行未固定版本的重建時,取得的系統可能不是你測試過的系統。此外,歷史上的 v1.2.0 runtime 也應設定 HEPHAESTUS_AUTO_UPDATE=0,否則其更新程式會在背景安裝較新的版本,使版本固定設定在未察覺的情況下失效。目前獨立的自動更新預設為關閉。

這篇文章對您有幫助嗎?