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

在 VPS 自架 KiroCrew,打造全天候代理程式

了解如何以固定版本的 Docker 容器在 VPS 執行 KiroCrew,透過 systemd、SSH、備份與回復,讓記憶和排程在重新啟動後仍然保留。

為何應在 VPS 上而不是筆記型電腦上自架 KiroCrew

只有在永不休眠的機器上自架 KiroCrew 才有實際效益,因此 VPS 適合作為執行環境,筆記型電腦則不適合。KiroCrew 會將工作階段歷程、語意記憶、排程工作與核准佇列儲存在磁碟上,並在程序重新啟動時重新載入這些資料。如果排程工作在 03:00 到期時程序並未執行,這些資料就沒有作用;而筆記型電腦關機時,程序也不會執行。

KiroCrew 是 Kiro 團隊推出的開放原始碼代理工作區,採用 Apache 2.0 授權,並於 22 July 2026 發布 0.1.0。其中一個稱為 gateway 的程序負責管理狀態,並在 port 5476 提供 Web 儀表板。您可以從儀表板、kirocrew CLI,或 Slack 等聊天頻道連線至該 gateway。您實際自架的只有 gateway,因此本指南著重於讓它持續執行、避免暴露在公開網際網路上,以及在升級失敗後能夠還原。

開始前需要知道兩件事。自 0.11.0 起,沒有儲存 harness 選擇的新 KiroCrew 安裝會預設使用 KAS,無須 kiro-cli;既有的明確 Kiro CLI 選擇則會保留。Kiro 後端上的推論會使用您的 Kiro 方案,因此截至 1 November 2026,此預設設定並非離線執行。此專案仍處於早期階段,更新速度也很快:穩定版本已從 5 August 2026 的 0.1.3 進展至 25 October 2026 的 0.10.0,期間還發布了 9 October 的 0.8.0 與 16 October 的 0.9.0;此外,0.11.0 release candidate 已於 25 October 以 pre-release 形式發布。請預期日後可能需要回復到舊版本,並採用允許回復的安裝方式。如果您過去未曾在伺服器上執行代理,在 VPS 上執行 coding agent 會說明本指南所依據的基本原則。如果您對代理端的熟悉程度低於伺服器端,請先了解代理迴圈、工具與記憶的實際運作方式,這樣下文的選擇會更像明確的決策,而不是需要照做的咒語。

KiroCrew 的需求與狀態儲存位置

原生安裝需要 Python 3.12 或更新版本。如果要從原始碼建置儀表板,還需要 Node.js 22.12.0 或更新版本(專案建議使用 Node 24 LTS)。Kiro CLI 後端需要 kiro-cli,並以 kiro-cli login 完成驗證;若要自動化使用,也可以使用 API key。自 0.10.0 起,內建的 KAS 引擎不需要安裝 kiro-cli 即可執行;0.11.0 讓它成為新安裝的預設引擎,前提是尚未儲存 harness 選擇。容器安裝不需要在主機上準備上述元件,只需要 Docker。這是優先選擇容器安裝的主要原因。

狀態儲存在 ~/.kiro/crew,也可以透過 KIROCREW_HOME 環境變數將其移到其他位置。其內容包括:

  • config.json:gateway 設定與聊天頻道憑證。
  • .env:secret。
  • workspace/memory/:偏好設定、專案備註與聊天記錄。
  • memory.db 與 memory_index.db:語意索引與全文索引。
  • models/:首次執行時下載的 embedding model。
  • security_events.jsonl:安全事件日誌。

該目錄就是整個安裝內容。將它複製到新的 VPS,即可搬移你的 agent。因此,下方的備份章節比安裝章節更重要。

請優先規劃磁碟空間,而不是 RAM。gateway 是 Python 程序;真正消耗主機資源的是 agent 執行的工作、建置程序或測試套件。狀態目錄會隨聊天記錄增加,而 embedding model 會在首次啟動時下載。因此,執行數週後,請使用 du -sh ~/.kiro/crew 在自己的主機上測量實際用量,不要直接採信專案初期發布的任何數據。相較之下,另一種執行環境會為每個 worker 提供獨立的容器與瀏覽器;在這種情況下,自行託管 OpenBot 的 AI 協作者 時,應先將規模估算視為 RAM 問題,而不是磁碟空間問題。

應使用哪一種安裝方式

此專案提供 4 種安裝方式:桌面應用程式、單行 wheel、原始碼與 Docker。單行安裝程式會下載 wheel,並建立 kirocrew 啟動程式。若其所在目錄不在 PATH 中,安裝程式會顯示加入該目錄的操作說明:

curl -fsSL https://download.crew.kiro.dev/cli.sh | sh

此安裝程式接受 channel flag 與 version flag:

curl -fsSL https://download.crew.kiro.dev/cli.sh | sh -s -- --channel insider
curl -fsSL https://download.crew.kiro.dev/cli.sh | sh -s -- --version 0.8.0

容器映像檔發布於 ghcr.io/kirodotdev/kirocrew,每個 tag 都包含 linux/amd64 與 linux/arm64。原始碼建置需要 git clone 及 make build,適合修改程式碼的人員,不適合只要執行程式的人員。

請使用容器。原生原始碼安裝會將 Python 套件與 Node 放在執行其他服務的同一台主機上;使用 Kiro CLI backend 時,還會加入 kiro-cli。因此,升級失敗後,您必須手動清理這些變更。容器會將執行環境固定在單一映像檔中,並將狀態集中在單一 volume。回復版本時,只需變更 tag 並重新啟動即可。

將映像固定至版本標籤,而不是固定至 stable

專案本身的範例使用 stable 標籤:

docker run -d --name kirocrew \
  -p 127.0.0.1:5476:5476 \
  -v kirocrew-home:/home/kirocrew \
  ghcr.io/kirodotdev/kirocrew:stable

stable 是會變動的標籤,latest 也是如此;它指向相同的版本。它會指向當時最新的穩定版本,因此下一次 pull 可能在未經你選擇的情況下變更執行中的版本,而且標籤不會記錄實際使用的是哪個版本。版本標籤不可變更,因此請固定使用版本標籤。截至 1 November 2026,最新的穩定版本是 0.11.1,於 31 October 2026 發布,用於修補 0.11.0 中的記憶體完整性與 KAS 問題。下方的 0.8.0 範例使用 Kiro CLI。此外還有 insider 與 nightly 標籤;nightly 會跟隨 main 的建置版本。

寫入 /opt/kirocrew/compose.yaml:

services:
  kirocrew:
    image: ghcr.io/kirodotdev/kirocrew:0.8.0
    container_name: kirocrew
    restart: unless-stopped
    ports:
      - "127.0.0.1:5476:5476"
    volumes:
      - kirocrew-home:/home/kirocrew

volumes:
  kirocrew-home:

啟動後,檢查該映像也用於自身 HEALTHCHECK 的 health endpoint:

cd /opt/kirocrew
docker compose up -d
docker compose ps
curl -s http://127.0.0.1:5476/api/health

docker compose ps 應在約 1 分鐘內回報容器為 healthy,而 /api/health 不需要 token 即可回應(/api/live 與 /api/ready 也是如此,因此可用作探針)。若狀態維持在 starting,請先讀取 docker logs kirocrew,再進行任何變更。第一次執行會在背景下載 embedding model;模型完成下載前,記憶體搜尋會使用關鍵字比對。

使用 systemd 讓服務持續運作

restart: unless-stopped 會在容器當機及系統重新開機後重新啟動容器,前提是 Docker 本身會在開機時啟動。unit 檔案可明確宣告這項相依性,並提供單一指令,在備份前停止整個服務堆疊。在開機時啟動 Docker Compose 堆疊說明了一般作法。KiroCrew 的設定方式如下,位於 /etc/systemd/system/kirocrew.service:

[Unit]
Description=KiroCrew gateway
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/kirocrew
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now kirocrew
systemctl status kirocrew

systemctl status kirocrew 應顯示 active (exited),這是此 unit 的正常結果。這裡使用 Type=oneshot 搭配 RemainAfterExit=yes 是正確的,因為容器啟動後 docker compose up -d 就會立即返回:systemd 追蹤的是服務堆疊已啟動這項狀態,而不是前景程序。若改寫為 Type=simple,systemd 會看到指令立即結束,將服務標記為已停止,接著依 Restart= 設定決定放棄或持續重新啟動。原生安裝則由專案提供對應的 kirocrew service install,它會寫入 /etc/systemd/system/kirocrew.service,並以你的使用者身分執行 gateway。不要同時執行這兩個 unit。VPS 上的 systemd 服務與計時器介紹了這個主題的完整內容。unit 若無法重新啟動,除非你讓它發出通知,否則不會有人察覺。因此,請加入 OnFailure= 處理常式,將警示推送到你自己的 ntfy 伺服器。這樣你可以透過手機得知 gateway 已停止,而不是等到排程工作未執行時才發現。

首次執行:登入並取得儀表板 token

容器會啟動 gateway,但固定使用的 0.8.0 image 中,預設的 Kiro CLI runtime 仍需要驗證。請在容器內登入,或透過容器環境傳入 KIRO_API_KEY 以供自動化使用:

docker exec -it kirocrew kiro-cli login

此命令會輸出 device code 與 URL,請在自己的瀏覽器中開啟該 URL。接著建立儀表板 token:

docker exec kirocrew kirocrew token --ttl 2h

儀表板 URL 為 http://localhost:5476/?token=<the token>。Token 會過期:產生的連結必須在建立後五分鐘內開啟。此命令會要求有效時間為兩小時的存取 cookie;文件記載的上限為二十小時。瀏覽器也會收到具有 30 天滑動閒置期限的 refresh cookie,因此活動中的工作階段可自動續期,不必再次開啟連結。儀表板載入空白,或開啟後立即將你導回登入頁面,通常表示 token 已過期。請重新建立 token,並立即開啟連結。切勿將 token 貼到工單或聊天訊息中,因為持有 token 的人即可控制你的 agent。

透過 SSH 存取儀表板,絕不要發布連接埠 5476

再次查看專案範例中的繫結位址:-p 127.0.0.1:5476:5476。在容器內,gateway 監聽 0.0.0.0,因為必須透過連接埠對映讓外部連入;但該對映只會在主機的 loopback 上發布。刪除 127.0.0.1: 前綴後,任何掃描該連接埠的人都能從公用網際網路連入 gateway。ufw 規則也無法保護你:Docker 會建立 DNAT 規則,在流量套用 ufw 規則前先進行轉送,因此 ufw deny 5476 對已發布的連接埠不起作用。使用 Docker 預設的 iptables backend 時,Docker 的做法是在其 DOCKER-USER chain 中加入過濾規則。這種方式可行,但除非搭配 conntrack extension 進行比對,否則這些規則看到的是容器的內部位址與連接埠。因此,繫結 loopback 仍是較簡單、也較不容易設定錯誤的控制方式。Docker 的 nftables backend 則使用獨立的 nftables tables 與 base chains 進行自訂過濾。Docker 連接埠繞過 ufw 詳細說明了這套機制。

改為從筆記型電腦透過 SSH 轉送連接埠:

ssh -N -L 5476:127.0.0.1:5476 you@your-server.example.com

讓這個連線持續執行,然後在本機開啟 http://localhost:5476/?token=<the token>。若要在每次連線時自動建立轉送,請將它加入 ~/.ssh/config:

Host your-server.example.com
    LocalForward 5476 127.0.0.1:5476

如果筆記型電腦上的連接埠 5476 已在使用中,只修改左側的數字:ssh -N -L 45476:127.0.0.1:5476 you@your-server.example.com,然後瀏覽 http://localhost:45476/?token=...。不需要額外設定 loopback 連接埠,也不需要重新建立容器:loopback Origin 會符合請求本身的 Host,因此 CSRF 檢查會接受該請求。只要第二個 agent 共用這台主機,你就會開始像這樣疊加多個轉送,因為自行代管 open-kritt 進行安全掃描會在同一台伺服器的 5173 連接埠上,再提供一個僅限 loopback 的儀表板。

兩項已記錄的行為會決定你能從儀表板變更哪些設定。第一,gateway 會將任何帶有轉送標頭(Forwarded、X-Forwarded-* 或 X-Real-IP)的請求視為遠端請求,其設定寫入與 secret 顯示端點會拒絕這些請求。反向代理會加入這些標頭;一般的 ssh -L 轉送不會加入任何標頭,因此不會因這項條件被拒絕。第二,在容器映像中,對於非直接本機的瀏覽器,channel credential 頁面與 secret 顯示檢視畫面都是唯讀,而且映像中沒有文字編輯器。若 channel credential 無法從儀表板儲存,原因就是這項限制,不是程式錯誤。請改在主機上編輯設定:

docker cp kirocrew:/home/kirocrew/.kiro/crew/config.json .
# edit config.json here
docker cp config.json kirocrew:/home/kirocrew/.kiro/crew/config.json
docker exec -u 0 kirocrew chown kirocrew:kirocrew /home/kirocrew/.kiro/crew/config.json
docker restart kirocrew

若要透過手機存取,專案建議使用 Tailscale 的 tailscale serve,讓儀表板留在你自己的 tailnet 內,而不是使用公開 hostname。這比公開反向代理更合適。token 會出現在 URL 中,而該 URL 會寫入沿途每個 access log。這項原則取決於連接埠後方提供的是什麼服務,而不是連接埠本身:例如 Halcyon 可將 Jellyfin 媒體庫重建為可瀏覽的 90s 影片商店是供其他人開啟的服務,適合使用反向代理;但能在伺服器上執行命令的 gateway 則不適合。

將代理程式的影響範圍縮小到最低

容器首次啟動時會探測是否支援 sandbox,並根據結果決定代理程式是否能執行任何操作。如果可用 namespace 隔離,代理程式的子程序會在隔離環境中執行。如果不可用且未設定 KIROCREW_ALLOW_UNSANDBOXED=1,系統會拒絕執行,而不是讓程序在未受限制的環境中執行。因此,閘道看似正常,但所有工作都停滯不前時,通常就是這個原因。該決定會記錄在首次執行產生的 docker logs kirocrew 中。專案也提供可套用的 seccomp(secure computing mode)設定檔:

curl -fsSL https://raw.githubusercontent.com/kirodotdev/KiroCrew/main/docker/seccomp/kirocrew-seccomp.json \
  -o /opt/kirocrew/kirocrew-seccomp.json
    security_opt:
      - seccomp:./kirocrew-seccomp.json

在啟用 AppArmor 的主機上,專案的 Docker 指南指出,seccomp 設定檔只是變更的一半,因為 Docker 也會附加其 docker-default AppArmor 設定檔,並搭配 apparmor=unconfined。這個選項只會解除 AppArmor 對單一容器套用的規則;seccomp 設定檔、已移除的 capabilities,以及非 root 使用者仍然有效。

如果確實設定 KIROCREW_ALLOW_UNSANDBOXED=1,請明確了解變更內容:此時容器成為代理程式與伺服器之間唯一的隔離邊界。專案的警告值得完整重申。不要掛載你不會直接交給代理程式的主機路徑。實務上,這表示不能掛載 Docker socket、任何對 / 的 bind mount,以及存放其他服務資料的任何目錄。

其餘設定構成所有獲准執行命令之代理程式都適用的基本防護。將其憑證權限限制在單一儲存庫或單一 bucket 所需的範圍內,絕不要使用具備整個帳戶權限的個人 token。使用專用使用者執行代理程式,並確保其 home 目錄不存放其他內容;這正是 VPS 上的最小權限使用者 所要處理的問題。代理程式寫入程式碼後又會執行該程式碼,因此應提供一台即使被破壞也不會造成影響的機器:供程式碼代理程式使用的一次性 VM 比 compose 檔案中的任何 flag 都能提供更強的隔離邊界,因為你可以直接刪除它,而不必逐項清理。相同的原則也適用於 在 VPS 上安全執行 OpenClaw 和 在 VPS 上自行託管 Hermes agent。工具同樣會擴大影響範圍:讓代理程式進行網頁搜尋,等於將它擷取的每個頁面都視為不受信任輸入,因此 將代理程式指向自己的 SearXNG instance 不只是連線設定問題,也涉及 prompt injection。排程工作也會在你睡覺時持續產生成本,因為 Kiro backends 的推論會使用你的 Kiro plan;在加入每晚執行的工作前,先依照 控制 VPS 上 AI 代理程式的成本 中所述設定限制。

每次升級前備份狀態磁碟區

先找出實際的磁碟區名稱。Compose 會在具名磁碟區前加上專案名稱。專案名稱預設為目錄名稱。因此,kirocrew-home 中宣告為 /opt/kirocrew/compose.yaml 的磁碟區,會建立為 kirocrew_kirocrew-home:

docker volume ls

複製任何資料前,先停止 gateway。memory.db 和 memory_index.db 是 SQLite 資料庫。資料庫正在寫入時複製,可能會取得尚未完成的交易,還原後會變成損毀的檔案。專案本身的遷移指示也採用相同原則:只有在 gateway 停止時,才能搬移記憶資料。這項先停止服務的規則不限於 KiroCrew。如果同一台主機還共用 photo server,PhotoPrism 與 Immich 的比較提供這兩者各自需要的完整備份指令。

sudo systemctl stop kirocrew
docker run --rm -v kirocrew_kirocrew-home:/data:ro -v "$PWD":/backup \
  alpine tar czf /backup/kirocrew-2026-08-06.tgz -C /data .
sudo systemctl start kirocrew

將封存檔複製到主機外部。還原時使用相同的指令,但必須先停止容器,並以 tar xzf 取代 tar czf:

sudo systemctl stop kirocrew
docker run --rm -v kirocrew_kirocrew-home:/data -v "$PWD":/backup \
  alpine tar xzf /backup/kirocrew-2026-08-06.tgz -C /data
sudo systemctl start kirocrew

搬遷到新主機與就地還原是不同的工作,專案對此有明確說明。workspace/memory/ 下的聊天記錄與專案筆記會一併保留,兩個資料庫檔案和 config.json 也會保留。PID 檔案、安全事件日誌及 .env 都與舊主機綁定,因此不要搬移;改在新主機上重新輸入 secrets。

不良升級後如何回復

升級所需時間很短,之所以安全,是因為你已固定版本。先建立備份,再修改標籤:

sudo systemctl stop kirocrew
# take the backup here, as above
sudo nano /opt/kirocrew/compose.yaml   # set the new image tag
sudo systemctl start kirocrew
docker compose -f /opt/kirocrew/compose.yaml ps
curl -s http://127.0.0.1:5476/api/health

如果映像尚未存在於主機上,docker compose up -d 會先拉取映像,因此修改標籤就是完整的升級流程。回復時使用相同流程,但改用舊版本號。由於版本標籤不可變更,這會取得升級前使用的確切映像。

二進位檔可以順利回復,但狀態資料不一定。較新的 gateway 可能會改寫 config.json,或將記憶體資料庫遷移成舊版 gateway 無法讀取的格式。截至 2026 年 10 月 12 日,沒有文件說明狀態資料的降級流程。安裝指南明確指出一種情況:從舊版 ~/.kirocrew 主目錄移出的資料無法回復,而早於 ~/.kiro/crew 的版本啟動時會使用空白資料。因此,如果舊映像能啟動但行為異常,不要進行除錯。停止服務,還原升級前建立的備份,然後重新啟動。這就是備份必須先於升級的完整原因,也說明了在這個仍很新的專案中,先升級、之後才備份的做法為何不可行。

此處尚未證實的內容

請正視此軟體的開發時間。版本 0.1.3 於 2026 年 8 月 5 日發布;截至 2026 年 10 月 12 日,穩定版本線已達 0.8.0。大多數發行說明仍是自動產生的變更日誌;0.8.0 的說明雖由人工撰寫,但沒有移轉章節,而公開的版本歷程約只有 3 個月。此指南中的內容都不是長期觀察結果,因此記憶體增長、資料庫大小與排程器可靠性,應在你自己的伺服器上測量,不應直接假設。

在依賴以下兩項行為前,建議先自行測試。第一,確認降級版本是否能讀取較新版本寫入的狀態:趁問題尚不影響服務時,在磁碟區副本上測試,不要等到服務中斷時才測試。第二,確認排程工作即將執行時,Kiro 登入工作階段過期後 gateway 的處理方式。這兩項都是新專案可能在版本之間逐步修正的邊界問題,現在檢查的成本很低。

FAQ

為什麼 KiroCrew 儀表板無法透過伺服器的公開 IP 開啟?

因為發布的範例會將連接埠繫結至 loopback。-p 127.0.0.1:5476:5476 只會將容器的連接埠對應至主機的 loopback 位址,這是刻意的設計。請使用 ssh -N -L 5476:127.0.0.1:5476 you@your-server 透過 SSH 轉送連接埠,然後在筆電上開啟 http://localhost:5476/?token=<token>。移除 127.0.0.1: 前綴即可讓服務可連線,但這會將 gateway 暴露在公用網際網路上;ufw 無法限制這些流量,因為 Docker 的已發布連接埠 DNAT 規則會在 ufw 規則套用前先轉送流量。請搭配 iptables backend 使用 Docker 的 DOCKER-USER chain,或搭配 nftables backend 使用獨立的 nftables base chain,以篩選已發布的連接埠;維持 loopback 繫結較為簡單。

KiroCrew 將資料儲存在哪裡?應備份哪些內容?

所有資料都位於 ~/.kiro/crew 下;在容器映像檔中,該路徑是 /home/kirocrew/.kiro/crew,而 KIROCREW_HOME 可將其搬移至其他位置。停止 gateway 後,請備份整個目錄或整個 Docker volume。memory.db 與 memory_index.db 是 SQLite 資料庫,因此在 gateway 寫入期間建立的副本可能不一致。移轉至新主機時,workspace/memory/、兩個資料庫檔案及 config.json 都會一併移轉;PID 檔案、安全事件日誌與 .env 則屬於舊主機。

應使用 stable tag 還是版本 tag?

請使用版本 tag。stable 每次發布新版本時都會變更,因此下次 pull 時,實際執行的版本可能在未明確操作的情況下改變,而且 tag 本身無法告訴你目前執行的是哪個版本。0.8.0 等版本 tag 不可變更,這正是 rollback 能夠運作的原因:還原舊版本號即可取得完全相同的映像檔。截至 1 November 2026,最新的穩定版本是 0.11.1。

為什麼我的 agent 拒絕執行任何命令?

容器會在第一次啟動時檢查 sandbox 支援。如果無法隔離 agent 的 subprocess,且未設定 KIROCREW_ALLOW_UNSANDBOXED=1,容器會拒絕執行這些 subprocess,而不是在未受限制的環境中執行。因此 gateway 看似正常,但每項工作都會停滯。docker logs kirocrew 會顯示第一次執行時作出的 sandbox 判定。設定此變數後,容器就會成為 agent 與主機之間唯一的隔離邊界。因此若要設定該變數,請勿掛載任何你不會直接交給 agent 的內容。

自行託管 KiroCrew 是否需要 Kiro 帳戶?

對 Kiro backend 而言,截至 1 November 2026,需要。KiroCrew 是採用 Apache 2.0 授權的自由軟體,但這些 backend 的推論功能會使用你的 Kiro 方案。固定版本的 0.8.0 容器使用 Kiro CLI:執行 docker exec -it kirocrew kiro-cli login,並在瀏覽器中核准 device code;若要自動化使用,也可以透過容器環境傳入 KIRO_API_KEY。在完成驗證前,gateway 仍會啟動,儀表板也會載入,但其預設 harness 沒有可供連線的模型。自 0.10.0 起,系統也內建不需要安裝 kiro-cli 的 KAS engine;0.11.0 讓 KAS 成為沒有已儲存 harness 選擇之新安裝的預設值,同時保留明確指定的 Kiro CLI 選擇。KAS 使用 Crew 自有的登入機制,而非 kiro-cli login。專案的自訂 backend 指南允許 claude harness 將主要模型回合傳送至你選擇的 Anthropic-compatible endpoint,但 Kiro 的 kiro-cli 登入仍是 Kiro 專屬功能所需。

這篇文章對您有幫助嗎?