KiroCrew sa VPS: Always-On Agent Setup

Bakit i-self-host ang KiroCrew sa isang VPS sa halip na laptop

Sulit lang ang self-hosting ng KiroCrew sa isang machine na hindi kailanman natutulog, kaya VPS ang tamang paglagyan nito at hindi laptop. Iniimbak ng KiroCrew sa disk ang session history, semantic memory, scheduled jobs, at approval queue, at nire-reload nito ang lahat kapag nag-restart ang process. Walang silbi ang mga ito kung hindi tumatakbo ang process sa 03:00 kapag due na ang isang scheduled job, at hindi ito tumatakbo kapag nakasara ang laptop.

Ang KiroCrew ay isang open source agent workspace mula sa Kiro team at lisensyado sa ilalim ng Apache 2.0. Ang mga unang public release nito ay inilabas noong unang bahagi ng August 2026. Isang process, na tinatawag na gateway, ang namamahala sa state at nagse-serve ng web dashboard sa port 5476. Ina-access mo ang gateway na ito mula sa dashboard, sa kirocrew CLI, o sa isang chat channel gaya ng Slack. Ang gateway lamang ang iyong bina-host sa sarili mong server, kaya nakatuon ang gabay na ito sa pagpapanatili nitong tumatakbo, pagpigil na maging accessible ito mula sa public internet, at pagbabalik nito kapag nagdulot ng problema ang isang upgrade.

May dalawang bagay na kailangan mong malaman bago magsimula. Ginagamit ng KiroCrew ang kiro-cli, na nangangailangan ng isang beses na pag-sign in gamit ang Kiro account, at sinisingil ang agent inference sa isang Kiro plan. Kaya, noong August 2026, hindi ito offline setup. Ilang linggo pa lamang ang project. Ipagpalagay na kakailanganin mong mag-rollback sa hinaharap, at i-install ito sa paraang magpapahintulot sa iyo na gawin iyon. Kung hindi ka pa nagpapatakbo ng agent sa isang server, ipinapaliwanag ng pagpapatakbo ng coding agent sa isang VPS ang mga pangunahing tuntunin na pinagbabatayan ng gabay na ito.

Mga kailangan ng KiroCrew, at kung saan naka-store ang state nito

Ang native install ay nangangailangan ng Python 3.10 o mas bago (inirerekomenda ng project ang 3.12), Node.js 18 o mas bago kung bina-build mo ang dashboard mula sa source, at kiro-cli, na ini-install at sina-sign in para sa iyo sa unang launch. Walang ganito ang kailangan sa host para sa container install. Docker ang kailangan nito. Ito ang pangunahing dahilan para piliin ito.

Naka-store ang state sa ~/.kiro/crew, at inililipat ito ng KIROCREW_HOME environment variable sa ibang lokasyon. Narito ang laman nito:

• config.json: mga setting ng gateway at credentials ng chat channel.
• .env: mga secret.
• workspace/memory/: mga preference, project note, at history ng chat.
• memory.db at memory_index.db: mga semantic at full-text index.
• models/: ang embedding model na dina-download sa unang run.
• gateway.log at security_events.jsonl: ang runtime log at security event log.

Ang directory na iyon ang buong install. Kopyahin ito sa bagong VPS at nailipat mo na ang agent mo. Kaya mas mahalaga ang backup section sa ibaba kaysa sa install section.

Maglaan ng disk space sa halip na RAM. Python process ang gateway. Ang aktuwal na naglo-load sa server ay ang anumang pinapatakbo ng agent, gaya ng build o test suite. Lumalaki ang state directory kasabay ng chat history, at dina-download ang embedding model sa unang start. Kaya sukatin ito sa sarili mong server gamit ang du -sh ~/.kiro/crew makalipas ang ilang linggo, sa halip na umasa sa anumang numerong inilathala noong unang buwan ng project.

Alin sa tatlong install path ang dapat mong gamitin

Tatlo ang inilalabas ng project. Kinukuha ng one-line installer ang isang wheel at inilalagay ang kirocrew sa iyong PATH:

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

Tumatanggap ito ng channel flag at 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.1.3

Naka-publish ang container image sa ghcr.io/kirodotdev/kirocrew para sa linux/amd64 at linux/arm64 sa bawat tag. Ang source build ay git clone kasama ang make build. Para ito sa mga nagbabago ng code, hindi sa mga nagpapatakbo nito.

Gamitin ang container. Sa native install, inilalagay ang Python packages, Node, at kiro-cli sa parehong host na nagpapatakbo ng iba mong serbisyo. Kapag nagkaproblema ang upgrade, kailangan mong ayusin nang mano-mano ang mga pagbabagong ito. Pinananatili ng container ang runtime sa isang image at ang state sa isang volume. Dahil dito, ang rollback ay pagpapalit lang ng tag at pag-restart.

I-pin ang image sa release tag, hindi sa stable

Ginagamit ng sariling halimbawa ng project ang stable tag:

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

Moving tag ang stable. Itinuturo nito ang pinakabagong stable release, kaya maaaring magbago ang version na pinapatakbo mo sa susunod na pull nang hindi mo ito pinipili. Wala ring itinatala ang tag tungkol sa eksaktong version na iyon. Immutable ang version tags, kaya mag-pin ng isa. Ang pinakabagong release noong 6 August 2026 ay 0.1.3, na inilabas noong 5 August 2026. May nightly tag din, pero sa isang project na ganito kabago, nangangahulugan ito na nagbago ang code ngayong umaga.

Isulat ang /opt/kirocrew/compose.yaml:

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

volumes:
  kirocrew-home:

I-start ito, pagkatapos ay i-check ang health endpoint na ginagamit din ng image para sa sarili nitong HEALTHCHECK:

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

Dapat i-report ng docker compose ps na healthy ang container sa loob ng humigit-kumulang isang minuto, at sumasagot ang /api/health nang walang token. Ganoon din ang /api/live at /api/ready, kaya magagamit ang mga ito bilang probes. Kung mananatili ang state sa starting, basahin ang docker logs kirocrew bago magbago ng anuman. Sa unang run, dina-download ang embedding model, kaya maaaring magtagal ang unang start kapag mabagal ang link.

Panatilihing tumatakbo ito gamit ang systemd

restart: unless-stopped ibinabalik ang container kapag nag-crash ito at pagkatapos ng reboot, basta awtomatikong nagsisimula ang Docker sa boot. Ginagawang malinaw ng unit file ang dependency na ito at binibigyan ka nito ng isang command para ihinto ang buong stack bago ang backup. Sinasaklaw ng Pagsisimula ng Docker Compose stack sa boot ang pangkalahatang pattern. Ganito ang anyo nito para sa KiroCrew, sa /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

Dapat magpakita ang systemctl status kirocrew ng active (exited), na siyang tamang resulta para sa unit na ito. Tama ang paggamit ng Type=oneshot kasama ng RemainAfterExit=yes dito dahil agad bumabalik ang docker compose up -d kapag nagsimula na ang container: sinusubaybayan ng systemd ang katotohanang aktibo ang stack, hindi ang isang foreground process. Kung Type=simple ang gagamitin mo, makikita ng systemd na agad natapos ang command, mamarkahan nitong dead ang service, at pagkatapos ay maaaring tumigil o paulit-ulit na mag-restart depende sa setting ng Restart=. Para sa native install, may sarili itong katumbas na inilalabas ang project, ang kirocrew service install, na sumusulat ng /etc/systemd/system/kirocrew.service at nagpapatakbo sa gateway bilang iyong user. Huwag patakbuhin ang parehong unit. Makikita ang mas malawak na bersyon ng paksang ito sa mga systemd service at timer sa isang VPS.

Unang pagtakbo: mag-sign in at kumuha ng dashboard token

Sinisimulan ng container ang gateway, pero hindi pa naka-sign in ang agent runtime. Mag-sign in sa loob ng container:

docker exec -it kirocrew kiro-cli login

Magpi-print ito ng device code at URL na bubuksan mo sa sarili mong browser. Pagkatapos, gumawa ng dashboard token:

docker exec kirocrew kirocrew token --ttl 2h

Ang dashboard URL ay http://localhost:5476/?token=<the token>. May expiration ang mga token: default na isang oras ang mga session, at dalawampung oras ang dokumentadong maximum. Karaniwang expired na token ang dahilan kung bakit blangko ang dashboard o agad kang ibinabalik sa sign-in page, kaya gumawa ng panibagong token. Huwag kailanman mag-paste ng token sa ticket o chat message, dahil ang may hawak nito ang may kontrol sa iyong agent.

I-access ang dashboard sa pamamagitan ng SSH, at huwag kailanman i-publish ang port 5476

Tingnan muli ang bind address sa example ng project: -p 127.0.0.1:5476:5476. Sa loob ng container, nakikinig ang gateway sa 0.0.0.0 dahil kailangan itong maabot sa pamamagitan ng port mapping, pero ang mapping mismo ay nagpa-publish lamang sa loopback ng host. Kapag tinanggal ang prefix na 127.0.0.1:, magiging available ang gateway sa public internet para sa sinumang mag-scan sa port na iyon. Hindi ka rin maililigtas ng firewall rule: naglalagay ang Docker ng DNAT rules para i-publish ang mga port, at sinusuri ang mga ito bago ang filtering ng ufw, kaya walang epekto ang ufw deny 5476 sa isang published port. Ipinapaliwanag ng Mga Docker port na lumalampas sa ufw ang mekanismong ito.

I-forward ang port sa pamamagitan ng SSH mula sa iyong laptop:

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

Panatilihing tumatakbo ang command na iyon at buksan ang http://localhost:5476/?token=<the token> nang lokal. Para awtomatikong gawin ang forward sa bawat connection, ilagay ito sa ~/.ssh/config:

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

Kung ginagamit na sa iyong laptop ang port 5476, ang kaliwang numero lamang ang palitan: ssh -N -L 45476:127.0.0.1:5476 you@your-server.example.com, pagkatapos ay pumunta sa http://localhost:45476/?token=....

May isang documented behavior na dapat asahan kapag gumagamit ng tunnel: binabasa ng gateway bilang remote ang mga request na naka-forward, kaya tinatanggihan ng dashboard ang mga config-write at secret-reveal endpoint. Kung hindi ma-save ang isang settings change sa SSH, inaasahan ito at hindi ito bug. Sa halip, direktang i-edit ang config sa host:

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

Para sa access mula sa phone, itinuturo ng project ang tailscale serve ng Tailscale, na nagpapanatili sa dashboard sa loob ng sarili mong tailnet sa halip na ilagay ito sa public hostname. Mas mainam ito kaysa sa public reverse proxy. Kasama ang token sa URL, at naisusulat ang URL sa bawat access log na dinaraanan nito.

Bigyan ang agent ng pinakamaliit na posibleng blast radius

Sa unang pagsisimula, sinusuri ng container kung may suporta para sa sandbox, at ang resulta ang nagtatakda kung maaaring magsagawa ng anuman ang mga agent. Kung available ang namespace isolation, hiwalay na tumatakbo ang mga subprocess ng agent. Kung hindi ito available at hindi nakatakda ang KIROCREW_ALLOW_UNSANDBOXED=1, tinatanggihan ang execution sa halip na patakbuhin ito nang walang isolation. Kaya karaniwang ganito ang dahilan kung bakit mukhang healthy ang gateway habang natitigil ang bawat task. Nasa docker logs kirocrew ang desisyong ito mula sa unang run. Naglalabas din ang project ng seccomp (secure computing mode) profile na maaari mong i-apply:

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

Kung itatakda mo ang KIROCREW_ALLOW_UNSANDBOXED=1, linawin kung ano ang nagbago: ang container na lamang ngayon ang nagsisilbing boundary sa pagitan ng agent at ng server mo. Dapat ulitin nang buo ang babala ng project. Huwag mag-mount ng host path na hindi mo direktang ipagkakatiwala sa agent. Sa praktika, ipinagbabawal nito ang Docker socket, ang anumang bind mount ng /, at ang anumang directory na naglalaman ng data ng ibang serbisyo.

Ang iba pang bahagi ay ang mga panuntunang nalalapat sa bawat agent na pinapayagang magpatakbo ng commands. Limitahan ang credentials nito sa isang repository o isang bucket lamang na kailangan nito. Huwag gumamit ng personal token na may account-wide rights. Patakbuhin ito bilang dedicated user na walang ibang laman ang home directory nito. Ito ang layunin ng least privilege users sa isang VPS. Kapag nagsusulat ng code ang agent at pagkatapos ay pinapatakbo ang code na iyon, bigyan ito ng machine na maaari nitong masira: mas matibay na boundary ang disposable VM para sa coding agents kaysa sa anumang flag sa compose file na ito, dahil ide-delete mo ang VM sa halip na linisin ito. Pareho ang prinsipyong ginagamit sa ligtas na pagpapatakbo ng OpenClaw sa isang VPS at self-hosting ng Hermes agent sa isang VPS. Bahagi rin ng blast radius ang mga tool: kapag binigyan mo ang agent ng web search, nagiging untrusted input ang bawat page na kinukuha nito. Kaya ang pagkonekta nito sa sarili mong SearXNG instance ay desisyon tungkol sa prompt injection, hindi lamang tungkol sa plumbing. Gumagastos din ang scheduled work habang natutulog ka, dahil sinisingil ang inference sa iyong Kiro plan. Itakda muna ang mga limit na inilalarawan sa pagkontrol sa gastos ng AI agent sa isang VPS bago magdagdag ng nightly job.

I-back up ang state volume bago ang bawat upgrade

Hanapin muna ang aktuwal na volume name. Pina-prefix ng Compose ang mga named volume gamit ang project name. Bilang default, directory name ito. Kaya ang volume na dineklara bilang kirocrew-home sa /opt/kirocrew/compose.yaml ay nagiging kirocrew_kirocrew-home:

docker volume ls

I-stop ang gateway bago mag-copy ng kahit ano. Ang memory.db at memory_index.db ay mga SQLite database. Kapag nag-copy ng database habang sinusulatan ito, maaaring makuha ang hindi pa kumpletong transaction. Kapag ni-restore ito, magiging corrupt na file ito. Pareho rin ang sinasabi ng sariling migration instructions ng project: ilipat lamang ang memory kapag naka-stop ang mga gateway.

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

I-copy ang archive palabas ng server. Pareho ang command para sa pag-restore, pero dapat naka-stop ang container at tar xzf ang gamitin sa halip na 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

Ibang gawain ang paglipat sa bagong host kumpara sa pag-restore sa kasalukuyang host, at malinaw ito sa project documentation. Kasama sa paglilipat ang chat history at project notes sa ilalim ng workspace/memory/, pati ang dalawang database file at config.json. Nakadepende sa dating host ang PID files, security event log, at .env. Iwan ang mga ito at ilagay muli ang mga secret sa bagong server.

Paano mag-roll back ng maling upgrade

Maikli ang proseso ng upgrade, at ligtas lamang ito dahil nag-pin ka ng version. Gawin muna ang backup, saka baguhin ang tag:

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

Kino-configure ng docker compose up -d ang image kung wala pa ito sa server, kaya ang pag-edit ng tag ang buong proseso ng upgrade. Pareho ang sequence sa pag-roll back, gamit ang dating number. Makukuha mo ang eksaktong image na ginamit mo dati dahil immutable ang version tags.

Malinis na nagro-roll back ang binary. Ang state ang maaaring magkaroon ng problema. Maaaring i-rewrite ng mas bagong gateway ang config.json o i-migrate ang memory databases sa format na hindi mabasa ng mas lumang gateway. Wala ring documented downgrade path hanggang Agosto 2026. Kaya kung nag-start ang mas lumang image pero kakaiba ang behavior nito, huwag mo itong i-debug. I-stop ito, i-restore ang backup na ginawa mo bago ang upgrade, at magsimula muli. Iyan ang buong dahilan kung bakit nauuna ang backup. Kaya rin hindi gumagana sa ganitong kabagong project ang nakasanayang mag-upgrade muna at mag-backup pagkatapos.

Ano ang hindi pa napatutunayan dito

Maging tapat sa edad ng software na ito. Ilang araw pa lamang ang Version 0.1.3 noong isinulat ito. Ang release notes nito ay mga automated changelog link, hindi migration notes. Wala pa itong track record ng mga upgrade. Walang pangmatagalang resulta sa gabay na ito. Kaya sukatin mismo sa server mo ang memory growth, database size, at pagiging maaasahan ng scheduler sa halip na ipagpalagay ang mga ito.

May dalawang behavior na dapat mong subukan bago mo ito asahan sa production. Una, tingnan kung nababasa ng downgrade ang state na isinulat ng mas bagong version. Subukan ito sa kopya ng volume habang hindi pa kritikal ang resulta, hindi habang may outage. Ikalawa, tingnan kung ano ang ginagawa ng gateway kapag nag-expire ang Kiro sign-in habang due na ang isang scheduled job. Mga ganitong edge case ang karaniwang tahimik na inaayos ng batang project sa pagitan ng mga release. Pareho rin itong madaling i-check ngayon.

FAQ

Bakit hindi bumubukas ang KiroCrew dashboard sa public IP ng server ko?

Dahil ang inilathalang halimbawa ay nagbi-bind ng port sa loopback. Ang -p 127.0.0.1:5476:5476 ay nagma-map ng port ng container sa loopback address lamang ng host, at sinadya ito. I-access ito sa pamamagitan ng pag-forward ng port sa SSH gamit ang ssh -N -L 5476:127.0.0.1:5476 you@your-server, pagkatapos ay buksan ang http://localhost:5476/?token=<token> sa iyong laptop. Kapag inalis ang prefix na 127.0.0.1: upang maging reachable ito, malalagay ang gateway sa public internet. Hindi ito makokontrol ng firewall rule dahil sinusuri ang Docker published-port DNAT rules bago i-filter ng ufw ang traffic.

Saan ini-store ng KiroCrew ang data nito, at ano ang dapat kong i-back up?

Nasa ilalim ng ~/.kiro/crew ang lahat. Ito ay /home/kirocrew/.kiro/crew sa loob ng container image, at inililipat ito ng KIROCREW_HOME. I-back up ang buong directory o ang buong Docker volume habang nakahinto ang gateway. Mga SQLite database ang memory.db at memory_index.db, kaya maaaring maging inconsistent ang kopyang ginawa habang nagsusulat ang gateway. Kapag lumilipat sa bagong host, kasama sa paglipat ang workspace/memory/, ang dalawang database file, at config.json. Ang PID files, security event log, at .env ay para sa lumang host.

Dapat ko bang gamitin ang stable tag o version tag?

Gumamit ng version tag. Nagbabago ang stable sa tuwing may nire-release, kaya maaaring magbago ang bersyong pinapatakbo mo sa susunod na pull, at walang ipinapahiwatig ang tag mismo tungkol sa kasalukuyang tumatakbo. Immutable ang mga version tag gaya ng 0.1.3. Ito mismo ang dahilan kung bakit gumagana ang rollback: ibinabalik mo ang dating number at nakukuha ang kaparehong image. Noong 6 August 2026, ang pinakabagong release ay 0.1.3.

Bakit ayaw magpatakbo ng anumang command ng agent ko?

Sinusuri ng container ang suporta para sa sandbox sa unang pagsisimula nito. Kung hindi nito maihihiwalay ang mga subprocess ng agent at hindi nakatakda ang KIROCREW_ALLOW_UNSANDBOXED=1, tumatanggi itong patakbuhin ang mga ito sa halip na patakbuhin nang walang isolation. Dahil dito, mukhang healthy ang gateway habang natitigil ang bawat task. Ipinapakita ng docker logs kirocrew ang naging desisyon tungkol sa sandbox sa unang pagtakbo. Kapag itinakda mo ang variable, ang container lamang ang nagsisilbing boundary sa pagitan ng agent at host. Kung itatakda mo ito, huwag mag-mount ng anumang file o directory na hindi mo direktang ipagkakatiwala sa agent.

Kailangan ko ba ng Kiro account para mag-self-host ng KiroCrew?

Oo, ayon sa estado noong August 2026. Free software ang KiroCrew sa ilalim ng Apache 2.0, ngunit ginagamit nito ang kiro-cli, na nangangailangan ng one-time sign-in, at sinisingil sa Kiro plan ang inference ng agent. Sa loob ng container, patakbuhin ang docker exec -it kirocrew kiro-cli login at aprubahan ang device code sa iyong browser. Hangga't hindi kumpleto ang sign-in, nagsisimula ang gateway at naglo-load ang dashboard, ngunit walang model na makakausap ang agent.