Cara Self-Host KiroCrew di VPS agar Selalu Aktif

Mengapa melakukan self-host KiroCrew di VPS, bukan di laptop

Self-host KiroCrew hanya bermanfaat pada mesin yang tidak pernah masuk mode tidur. Karena itu, VPS adalah tempat yang tepat, sedangkan laptop bukan. KiroCrew menyimpan riwayat sesi, memori semantik, pekerjaan terjadwal, dan antrean persetujuan di disk. Semua data tersebut dimuat kembali saat proses dimulai ulang. Data itu tidak akan membantu jika proses tidak berjalan pada pukul 03:00 ketika pekerjaan terjadwal harus dijalankan. Laptop yang ditutup tidak menjalankan proses tersebut.

KiroCrew adalah ruang kerja agen open source dari tim Kiro dan berlisensi Apache 2.0. Rilis publik pertamanya tersedia pada awal August 2026. Satu proses yang disebut gateway mengelola status dan menyediakan dashboard web pada port 5476. Anda dapat mengakses gateway tersebut dari dashboard, dari CLI kirocrew, atau dari channel chat seperti Slack. Gateway adalah satu-satunya komponen yang Anda self-host. Karena itu, panduan ini membahas cara menjaganya tetap berjalan, mencegah aksesnya dari Internet publik, dan memulihkannya setelah upgrade yang bermasalah.

Ada dua hal yang perlu diketahui sebelum memulai. KiroCrew menjalankan kiro-cli, yang memerlukan sign-in satu kali dengan akun Kiro. Inferensi agen dibebankan ke paket Kiro. Jadi, per August 2026, ini bukan setup offline. Proyek ini juga baru berusia beberapa minggu. Anggaplah Anda akan perlu melakukan rollback pada suatu saat, lalu instal dengan cara yang memungkinkan hal tersebut. Jika Anda belum pernah menjalankan agen di server, menjalankan coding agent di VPS membahas dasar-dasar yang menjadi landasan panduan ini.

Kebutuhan KiroCrew dan lokasi penyimpanan state

Instalasi native memerlukan Python 3.10 atau yang lebih baru (proyek ini merekomendasikan 3.12), Node.js 18 atau yang lebih baru jika Anda membangun dashboard dari source, serta kiro-cli, yang akan diinstal dan digunakan untuk login oleh peluncuran pertama. Instalasi container tidak memerlukan semua itu pada host. Instalasi tersebut hanya memerlukan Docker. Inilah alasan utama untuk memilihnya.

State disimpan di ~/.kiro/crew, dan variabel lingkungan KIROCREW_HOME memindahkannya ke lokasi lain. Isi direktori tersebut:

• config.json: pengaturan gateway dan kredensial channel chat.
• .env: secret.
• workspace/memory/: preferensi, catatan proyek, dan riwayat chat.
• memory.db dan memory_index.db: indeks semantik dan indeks full-text.
• models/: model embedding yang diunduh saat proses pertama kali dijalankan.
• gateway.log dan security_events.jsonl: log runtime dan log peristiwa keamanan.

Direktori tersebut adalah instalasinya. Salin direktori itu ke VPS baru untuk memindahkan agent Anda. Karena itu, bagian pencadangan di bawah lebih penting daripada bagian instalasi.

Prioritaskan kapasitas disk, bukan RAM. Gateway merupakan proses Python. Beban yang sebenarnya menggunakan resource server berasal dari apa pun yang dijalankan agent, seperti proses build atau test suite. Direktori state bertambah seiring riwayat chat. Model embedding juga diunduh saat pertama kali dijalankan. Karena itu, ukur ukurannya di server Anda sendiri dengan du -sh ~/.kiro/crew setelah beberapa minggu, bukan berdasarkan angka yang dipublikasikan pada bulan pertama proyek.

Gunakan jalur instalasi yang mana dari ketiganya

Proyek ini menyediakan tiga jalur instalasi. Installer satu baris mengambil sebuah wheel dan menempatkan kirocrew pada PATH Anda:

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

Installer ini menerima flag channel dan flag version:

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

Container image tersedia di ghcr.io/kirodotdev/kirocrew, untuk linux/amd64 dan linux/arm64 pada setiap tag. Build dari source memerlukan git clone serta make build, dan ditujukan bagi orang yang mengubah kode, bukan bagi orang yang menjalankannya.

Gunakan container. Instalasi native menempatkan package Python, Node, dan kiro-cli pada host yang sama dengan service lain, sehingga upgrade yang bermasalah membuat Anda harus memulihkan konfigurasi tersebut secara manual. Container menyimpan runtime dalam satu image dan state dalam satu volume. Dengan demikian, rollback cukup dilakukan dengan mengganti tag dan me-restart container.

Tetapkan image ke tag rilis, bukan ke stable

Contoh dari proyek itu sendiri menggunakan tag stable:

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

stable adalah tag yang dapat berubah. Tag ini menunjuk ke rilis stabil terbaru, sehingga pull berikutnya dapat mengubah versi yang Anda jalankan tanpa pilihan Anda, dan tag tersebut tidak mencatat versi yang digunakan. Tag versi bersifat immutable, jadi gunakan salah satunya. Rilis terbaru per 6 August 2026 adalah 0.1.3, yang dipublikasikan pada 5 August 2026. Ada juga tag nightly. Pada proyek yang masih sangat baru, tag ini berarti kode berubah pagi ini.

Tulis /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:

Jalankan, lalu periksa endpoint health yang juga digunakan image tersebut untuk HEALTHCHECK miliknya:

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

docker compose ps seharusnya melaporkan container sebagai healthy dalam waktu sekitar satu menit, dan /api/health memberikan respons tanpa token. Hal yang sama berlaku untuk /api/live dan /api/ready, sehingga semuanya dapat digunakan sebagai probe. Jika status tetap starting, baca docker logs kirocrew sebelum mengubah apa pun. Proses pertama mengunduh model embedding, sehingga koneksi yang lambat membuat start pertama berlangsung lama.

Menjaga layanan tetap berjalan dengan systemd

restart: unless-stopped menghidupkan kembali container setelah crash dan reboot, selama Docker sendiri dijalankan saat boot. Unit file memperjelas dependensi tersebut dan menyediakan satu perintah untuk menghentikan seluruh stack sebelum pencadangan. Menjalankan stack Docker Compose saat boot membahas pola umumnya. Berikut bentuk khusus KiroCrew dalam /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 seharusnya menampilkan active (exited). Ini adalah hasil yang menunjukkan unit tersebut berjalan normal. Type=oneshot bersama RemainAfterExit=yes tepat digunakan di sini karena docker compose up -d segera selesai setelah container dijalankan: systemd melacak bahwa stack sudah aktif, bukan proses yang berjalan di foreground. Jika Anda menulis Type=simple, systemd menganggap perintah tersebut langsung selesai, menandai service sebagai mati, lalu menyerah atau masuk ke loop restart, bergantung pada pengaturan Restart=. Untuk instalasi native, project ini menyediakan padanannya sendiri, yaitu kirocrew service install, yang menulis /etc/systemd/system/kirocrew.service dan menjalankan gateway sebagai user Anda. Jangan jalankan kedua unit tersebut. Pembahasan yang lebih luas mengenai topik ini tersedia di service dan timer systemd pada VPS.

First run: masuk dan dapatkan token dashboard

Container menjalankan gateway, tetapi runtime agent belum masuk. Masuk dari dalam container:

docker exec -it kirocrew kiro-cli login

Perintah tersebut menampilkan kode perangkat dan URL yang harus dibuka di browser Anda. Kemudian, buat token dashboard:

docker exec kirocrew kirocrew token --ttl 2h

URL dashboard adalah http://localhost:5476/?token=<the token>. Token memiliki masa berlaku: sesi secara default berlaku selama satu jam, dan maksimum yang didokumentasikan adalah dua puluh jam. Jika dashboard tampil kosong atau langsung mengarahkan Anda kembali ke halaman sebelumnya, biasanya token sudah kedaluwarsa. Buat token baru. Jangan pernah menempelkan token ke tiket atau pesan chat, karena siapa pun yang memegangnya dapat mengendalikan agent Anda.

Akses dashboard melalui SSH, dan jangan pernah memublikasikan port 5476

Periksa kembali alamat bind pada contoh dari proyek: -p 127.0.0.1:5476:5476. Di dalam container, gateway mendengarkan pada 0.0.0.0 karena harus dapat dijangkau melalui pemetaan port. Namun, pemetaan tersebut hanya memublikasikan port ke loopback pada host. Hapus awalan 127.0.0.1:, lalu gateway dapat diakses dari Internet oleh siapa pun yang memindai port tersebut. Aturan firewall juga tidak akan melindungi Anda. Docker memublikasikan port dengan menulis aturan DNAT yang dievaluasi sebelum pemfilteran ufw, sehingga ufw deny 5476 tidak berpengaruh pada port yang telah dipublikasikan. Port Docker melewati ufw menjelaskan mekanisme tersebut.

Teruskan port melalui SSH dari laptop Anda:

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

Biarkan proses tersebut tetap berjalan, lalu buka http://localhost:5476/?token=<the token> secara lokal. Agar penerusan ini berjalan otomatis pada setiap koneksi, masukkan konfigurasi tersebut ke ~/.ssh/config:

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

Jika port 5476 sudah digunakan pada laptop, ubah hanya angka di sisi kiri: ssh -N -L 45476:127.0.0.1:5476 you@your-server.example.com, lalu buka http://localhost:45476/?token=... di browser.

Ada satu perilaku yang perlu diketahui saat menggunakan tunnel: gateway membaca request yang diteruskan sebagai request jarak jauh. Karena itu, endpoint untuk menulis konfigurasi dan menampilkan secret pada dashboard akan menolaknya. Jika perubahan pengaturan tidak dapat disimpan melalui SSH, itu adalah perilaku yang diharapkan, bukan bug. Edit konfigurasi langsung pada 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

Untuk akses dari ponsel, proyek ini mengarahkan pengguna ke tailscale serve milik Tailscale. Dengan demikian, dashboard tetap berada di dalam tailnet Anda sendiri, bukan pada hostname publik. Pilih cara ini daripada menggunakan reverse proxy publik. Token dikirim di dalam URL, dan URL tersebut ditulis ke setiap access log pada jalurnya.

Berikan ruang dampak sekecil mungkin kepada agent

Container memeriksa dukungan sandbox saat pertama kali dijalankan. Hasilnya menentukan apakah agent dapat mengeksekusi sesuatu. Jika isolasi namespace tersedia, subprocess agent berjalan secara terisolasi. Jika tidak tersedia dan KIROCREW_ALLOW_UNSANDBOXED=1 tidak ditetapkan, eksekusi ditolak daripada dijalankan tanpa pembatasan. Karena itu, gateway yang terlihat sehat sementara semua tugas macet biasanya mengalami masalah ini. Keputusan tersebut dicatat dalam docker logs kirocrew sejak proses pertama dijalankan. Project ini juga menyediakan profil seccomp (secure computing mode) yang dapat Anda terapkan:

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

Jika Anda menetapkan KIROCREW_ALLOW_UNSANDBOXED=1, pahami dengan jelas perubahan yang terjadi: container kini menjadi satu-satunya batas antara agent dan server Anda. Peringatan dari project ini perlu diulangi secara lengkap. Jangan mount path host yang tidak akan Anda berikan langsung kepada agent. Dalam praktiknya, ini berarti jangan mount Docker socket, bind mount /, atau direktori apa pun yang menyimpan data service lain.

Bagian lainnya adalah kerangka yang berlaku untuk setiap agent yang diizinkan menjalankan perintah. Batasi kredensialnya hanya ke satu repository atau satu bucket yang diperlukan. Jangan gunakan personal token dengan hak akses ke seluruh akun. Jalankan agent sebagai dedicated user yang home directory-nya tidak berisi apa pun selain yang diperlukan. Inilah tujuan user dengan hak akses minimum pada VPS. Saat agent menulis kode lalu menjalankan kode tersebut, berikan machine yang boleh rusak: VM sekali pakai untuk coding agent memberikan batas yang lebih kuat daripada flag apa pun dalam compose file ini, karena Anda dapat menghapusnya, bukan membersihkannya. Pertimbangan yang sama berlaku untuk menjalankan OpenClaw dengan aman pada VPS dan self-hosting agent Hermes pada VPS. Tools juga menentukan ruang dampak: jika Anda memberikan akses web search kepada agent, setiap halaman yang diambilnya menjadi input yang tidak tepercaya. Karena itu, mengarahkan agent ke instance SearXNG milik Anda sendiri merupakan keputusan terkait prompt injection sekaligus keputusan konfigurasi jaringan. Pekerjaan terjadwal juga dapat menghabiskan biaya saat Anda tidur karena inference dibebankan ke Kiro plan Anda. Oleh sebab itu, tetapkan batas yang dijelaskan dalam mengendalikan biaya AI agent pada VPS sebelum menambahkan nightly job.

Cadangkan volume state sebelum setiap upgrade

Cari nama volume yang sebenarnya terlebih dahulu. Compose menambahkan nama project ke named volume. Secara default, nama project adalah nama direktori. Jadi, volume yang dideklarasikan sebagai kirocrew-home dalam /opt/kirocrew/compose.yaml dibuat sebagai kirocrew_kirocrew-home:

docker volume ls

Hentikan gateway sebelum menyalin apa pun. memory.db dan memory_index.db adalah database SQLite. Menyalin database saat sedang ditulis dapat menangkap transaksi yang belum selesai, sehingga file akan dipulihkan dalam keadaan rusak. Petunjuk migrasi project juga menyatakan hal yang sama: pindahkan memory hanya saat gateway dihentikan.

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

Salin arsip ke luar server. Pemulihan menggunakan perintah yang sama saat container dihentikan, dengan tar xzf sebagai pengganti 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

Memindahkan layanan ke host baru berbeda dari memulihkannya pada host yang sama. Project memberikan instruksi khusus untuk proses ini. Riwayat chat dan catatan project di bawah workspace/memory/ ikut dipindahkan. Dua file database dan config.json juga ikut dipindahkan. File PID, log peristiwa keamanan, dan .env terkait dengan host lama. Jangan pindahkan file-file tersebut, lalu masukkan kembali secret pada host baru.

Cara mengembalikan upgrade yang bermasalah

Proses upgrade berlangsung singkat dan aman hanya karena Anda menetapkan versi tertentu. Buat backup terlebih dahulu, lalu ubah 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

docker compose up -d mengunduh image jika image tersebut belum tersedia di server, sehingga mengubah tag sudah mencakup seluruh proses upgrade. Rollback dilakukan dengan urutan yang sama menggunakan nomor versi lama. Dengan cara ini, Anda mendapatkan image yang sama persis seperti sebelum upgrade karena tag versi bersifat immutable.

Binary dapat di-rollback dengan bersih. Namun, state belum tentu dapat dipulihkan dengan cara yang sama. Gateway yang lebih baru dapat menulis ulang config.json atau memigrasikan database memori ke struktur yang tidak dapat dibaca gateway versi lama. Hingga August 2026, tidak ada jalur downgrade yang didokumentasikan. Jadi, jika image lama berhasil start tetapi kemudian berperilaku tidak semestinya, jangan lakukan debugging. Hentikan image tersebut, pulihkan backup yang dibuat sebelum upgrade, lalu jalankan kembali. Itulah alasan backup harus dibuat terlebih dahulu. Karena itu pula, kebiasaan melakukan upgrade sekarang dan membuat backup nanti tidak cocok untuk project yang masih sangat baru.

Hal yang belum terbukti di sini

Bersikaplah jujur mengenai usia software ini. Versi 0.1.3 baru berusia beberapa hari saat panduan ini ditulis. Catatan rilisnya berupa tautan changelog otomatis, bukan catatan migrasi. Belum ada rekam jejak upgrade. Tidak ada bagian dari panduan ini yang merupakan hasil jangka panjang. Karena itu, anggap pertumbuhan penggunaan memori, ukuran database, dan keandalan scheduler sebagai hal yang perlu Anda ukur pada server sendiri, bukan sebagai hal yang dapat diasumsikan.

Ada dua perilaku yang sebaiknya Anda uji sendiri sebelum mengandalkannya. Pertama, apakah downgrade dapat membaca state yang ditulis oleh versi yang lebih baru. Uji pada salinan volume saat tidak ada dampak jika terjadi masalah, bukan ketika sedang terjadi outage. Kedua, apa yang dilakukan gateway ketika sign-in Kiro kedaluwarsa saat scheduled job harus dijalankan. Keduanya merupakan potensi masalah pada proyek yang masih baru. Masalah seperti ini biasanya diperbaiki secara bertahap di antara rilis. Keduanya juga mudah diperiksa sekarang.

FAQ

Mengapa dasbor KiroCrew tidak terbuka pada IP publik server saya?

Karena contoh yang dipublikasikan mengikat port ke loopback. -p 127.0.0.1:5476:5476 hanya memetakan port container ke alamat loopback host, dan hal ini memang disengaja. Akses melalui penerusan port dengan SSH menggunakan ssh -N -L 5476:127.0.0.1:5476 you@your-server, lalu buka http://localhost:5476/?token=<token> di laptop Anda. Menghapus awalan 127.0.0.1: agar layanan dapat diakses akan menempatkan gateway di Internet publik. Aturan firewall tidak akan membatasi akses tersebut karena aturan DNAT untuk port yang dipublikasikan Docker dievaluasi sebelum ufw memfilter trafik.

Di mana KiroCrew menyimpan datanya, dan apa yang harus saya cadangkan?

Semua data berada di bawah ~/.kiro/crew, yang merupakan /home/kirocrew/.kiro/crew di dalam image container, dan KIROCREW_HOME memindahkannya. Cadangkan seluruh direktori atau seluruh volume Docker saat gateway dihentikan. memory.db dan memory_index.db adalah database SQLite, sehingga salinan yang dibuat saat gateway sedang menulis data dapat menjadi tidak konsisten. Saat memindahkan layanan ke host baru, workspace/memory/, kedua file database, dan config.json dapat ikut dipindahkan, sedangkan file PID, log peristiwa keamanan, dan .env terkait dengan host lama.

Sebaiknya saya menggunakan tag stable atau tag versi?

Gunakan tag versi. stable berubah setiap kali rilis baru tersedia, sehingga versi yang Anda jalankan dapat berubah pada pull berikutnya tanpa Anda sadari, dan tag tersebut tidak memberi informasi tentang versi yang sedang berjalan. Tag versi seperti 0.1.3 bersifat immutable. Inilah yang membuat rollback berfungsi: masukkan kembali nomor versi lama untuk mendapatkan image yang identik. Per 6 Agustus 2026, rilis terbaru adalah 0.1.3.

Mengapa agent saya menolak menjalankan perintah apa pun?

Container memeriksa dukungan sandbox saat pertama kali dijalankan. Jika container tidak dapat mengisolasi subprocess agent dan KIROCREW_ALLOW_UNSANDBOXED=1 tidak ditetapkan, container menolak menjalankannya daripada menjalankannya tanpa isolasi. Akibatnya, gateway terlihat sehat, tetapi setiap tugas berhenti. docker logs kirocrew menampilkan keputusan sandbox dari proses pertama tersebut. Menetapkan variabel ini menjadikan container satu-satunya batas antara agent dan host. Jika Anda menetapkannya, jangan mount apa pun yang tidak akan Anda berikan langsung kepada agent.

Apakah saya memerlukan akun Kiro untuk melakukan self-hosting KiroCrew?

Ya, per Agustus 2026. KiroCrew adalah perangkat lunak gratis berdasarkan Apache 2.0, tetapi perangkat lunak ini menggunakan kiro-cli, yang memerlukan sign-in satu kali, dan inferensi agent dibebankan ke paket Kiro. Di dalam container, jalankan docker exec -it kirocrew kiro-cli login dan setujui kode perangkat di browser Anda. Sebelum sign-in selesai, gateway dapat berjalan dan dasbor dapat dimuat, tetapi agent tidak memiliki model untuk diajak berkomunikasi.