SpyBara
Go Premium

self-hosted-environments-quickstart.md 2026-10-09 23:02 UTC to 2026-10-10 20:02 UTC

This page contains 45 additions and 7 deletions.

2026
Sun 4 23:58 Sat 10 21:01

Panduan cepat lingkungan yang di-host sendiri

Siapkan lingkungan yang di-host sendiri pertama Anda: instal Claude Code, buat lingkungan, mulai runner, dan arahkan sesi ke sana.

Sebuah lingkungan yang di-host sendiri menjalankan Claude Code sesi cloud pada infrastruktur yang dioperasikan organisasi Anda, dijalankan oleh proses runner yang Anda terapkan. Panduan cepat ini menyiapkan yang pertama, yang terkecil yang berfungsi: satu runner pada satu host, menjalankan satu sesi uji. Ada dua langkah: buat lingkungan, mulai runner, dan arahkan sesi ke sana, kemudian kirim pesan ke sesi itu dari terminal Anda. Anda akan berpindah antara dua permukaan: claude.ai untuk membuat lingkungan, memeriksa statusnya, dan mengarahkan sesi, dan terminal pada host untuk semua yang dilakukan runner.

Pada akhirnya Anda akan memiliki lingkungan pada halaman admin Cloud environments, runner yang menunggu pekerjaan, dan sesi yang berjalan pada host Anda. Sebelum Anda menghubungkan repositori nyata atau sistem internal, kerjakan Terapkan ke produksi, yang mencakup postur keamanan, kontrol egress, kredensial git, dan orkestrasi.

Prasyarat

Organisasi dan peran

Sisi claude.ai memerlukan:

  • Izinkan lingkungan yang di-host sendiri diaktifkan oleh Pemilik pada halaman admin Cloud environments; tombol New tidak muncul sampai diaktifkan. Jika Anda tidak memiliki peran tersebut, seseorang yang memilikinya dapat membuat lingkungan dan memberikan rahasia kepada Anda; langkah runner dan terminal pada halaman ini tidak memerlukan peran claude.ai, dan di mana langkah memeriksa status di UI admin, baris log runner sendiri memberikan sinyal yang sama.
  • Sebuah koneksi GitHub untuk organisasi Anda, sehingga pengembang dapat memilih repositori saat mereka memulai sesi.

Host dan jaringan

Host runner memerlukan:

  • Host atau kontainer Linux atau macOS dengan HTTPS keluar ke api.anthropic.com, ke claude.ai dan host unduhan yang dialihkan untuk langkah instalasi di bawah, dan ke host git Anda untuk klon; tabel persyaratan jaringan memiliki daftar lengkap. Windows tidak didukung sebagai host runner; jalankan runner dalam kontainer Linux sebagai gantinya. Workstation pengembang tidak terpengaruh, karena sesi dimulai dari claude.ai di browser.
  • Sebuah repositori untuk sesi uji: repositori publik, atau repositori yang sudah dapat diklon oleh host ini melalui URL HTTPS-nya tanpa diminta kredensial.
  • Jam yang disinkronkan dengan waktu nyata, misalnya dengan NTP. Autentikasi gagal ketika jam lebih dari lima menit mati; lihat Troubleshooting.

Perangkat lunak pada host runner

Instal pada host sebelum Anda memulai:

  • Claude Code v2.1.224 atau lebih baru, dengan salah satu dari metode instalasi standar. Runner adalah bagian dari biner claude standar, dan versi sebelumnya tidak mengenali subperintah self-hosted-runner. Saluran latest penginstal asli membawa setiap rilis segera setelah dipublikasikan; saluran stable, cask Homebrew claude-code, dan repositori apt, dnf, dan apk yang stabil tertinggal sekitar seminggu. Untuk menyematkan versi yang tepat yang dijalankan armada Anda, lihat Instal versi tertentu. Untuk gambar kontainer, lihat Dockerfile di Terapkan ke produksi.
  • Git 2.24 atau lebih baru. Beberapa opsi git pada halaman terapkan memerlukan versi yang lebih baru; Konfigurasi git menyatakan setiap lantai.

Konfirmasi host siap:

claude self-hosted-runner --help

Host yang siap mencetak teks penggunaan runner, mencantumkan bendera seperti --environment-secret-file. Pada versi yang lebih lama dari 2.1.224, perintah mencetak output claude --help umum sebagai gantinya; tingkatkan dengan claude update atau instal ulang dari saluran latest.

Siapkan lingkungan dan runner

Gunakan pengaturan terpandu atau langkah manual. Pengaturan terpandu adalah satu perintah yang memulai sesi Claude Code interaktif dan memandu Anda melalui sisanya. Gunakan langkah manual sebagai gantinya pada host di mana sesi interaktif tidak mungkin. Gunakan juga langkah manual ketika seseorang yang memiliki peran Owner telah membuat lingkungan dan menyerahkan rahasianya kepada Anda, karena pengaturan terpandu memerlukan masuk sebagai Owner.

Jalankan pengaturan terpandu

Pengaturan terpandu memandu Anda melalui pembuatan lingkungan di UI admin, memulai runner lokal dengan file rahasia yang Anda simpan, mengonfirmasi bahwa runner terdaftar, dan menulis lembar contekan ke ./runner-setup/CHEAT-SHEET.md. Sebelum menjalankannya, konfirmasikan status masuk dan versi Anda:

  • Masuk: jalankan pada mesin di mana Anda telah masuk dengan claude auth login menggunakan akun yang memiliki peran Owner. Dengan hanya kunci API atau penyedia model pihak ketiga, sesi dimulai tetapi pemeriksaan organisasinya gagal.
  • Versi: konfirmasikan bahwa pemeriksaan versi lulus. Pada versi yang lebih lama dari 2.1.224, perintah setup memulai sesi Claude dengan kata-kata tersebut sebagai prompt alih-alih pengaturan terpandu.

Untuk memulai pengaturan terpandu, jalankan subperintah setup di shell Anda dan ikuti petunjuknya:

claude self-hosted-runner setup

Pengaturan tidak memulai sesi uji dengan sendirinya: pengaturan memberi tahu Anda untuk memulainya di claude.ai/code. Langkah terakhir pengaturan menghentikan runner yang dimulainya. Jika Anda meninggalkan pengaturan sebelum langkah tersebut, runner tetap berjalan. Untuk melanjutkan setelah langkah terakhir, mulai runner lagi di shell Anda dengan perintah di ./runner-setup/CHEAT-SHEET.md, kemudian arahkan sesi ke lingkungan.

Siapkan secara manual

Buat lingkungan di claude.ai, mulai runner dari terminal di host, kemudian kembali ke claude.ai untuk mengonfirmasi bahwa runner muncul dan arahkan sesi ke sana. Jika seseorang yang memiliki peran Owner sudah membuat lingkungan dan menyerahkan rahasianya kepada Anda, mulailah dari langkah 2.

1

Buat lingkungan

Buka halaman Cloud environments di pengaturan admin. Di bawah Self-hosted environments, pilih New, beri nama lingkungan, dan pilih Create. Pada langkah kedua wizard, pilih Copy environment key untuk menyalin rahasia lingkungan, yang UI admin beri label kunci lingkungan. claude.ai menampilkan rahasia sekali, dan Anda tidak dapat mengambilnya nanti; itu kedaluwarsa 365 hari setelah pembuatan. ID ccpool_... lingkungan tetap terlihat dalam dialog detailnya; Anda akan membutuhkannya untuk pemeriksaan aud dalam verifikasi token dan untuk mengirim sesi uji dari CI.

Jika Anda kehilangan rahasia atau perlu memutar ulang, buat rahasia baru dari tab Configuration lingkungan, gulirkan rahasia baru ke runner Anda, kemudian cabut yang lama. Runner yang memegang rahasia yang dicabut gagal polling terautentikasi berikutnya dan keluar, mencatat poll auth failed, dan orkestrator Anda memulai ulang dengan rahasia baru.

2

Mulai runner

Buat direktori rahasia. Perintah ini dan berikutnya menggunakan /etc/claude, yang memerlukan root, dan file rahasia yang dibuatnya hanya dapat dibaca oleh pengguna yang menjalankannya. Jika runner akan berjalan sebagai pengguna lain, runner keluar dengan error: Failed to read environment secret file <path> (EACCES: permission denied, open '<path>'). Dalam hal ini, jalankan kedua perintah sebagai pengguna runner dengan direktori yang dapat ditulis oleh pengguna tersebut sebagai pengganti /etc/claude, dan berikan jalur yang sama ke --environment-secret-file. Jalur apa pun yang dapat dibaca proses runner berfungsi.

mkdir -p /etc/claude

Tulis rahasia lingkungan ke file. Perintah di bawah membaca dari terminal Anda sehingga rahasia tetap keluar dari riwayat shell: tempel nilai yang Anda salin, tekan Enter, kemudian Ctrl-D, dan umask subshell membuat file dapat dibaca hanya oleh pemiliknya.

(umask 077 && cat > /etc/claude/environment-secret)

Pilih direktori dasar, mengganti <writable-dir> dalam perintah runner di bawah dengan jalur absolut yang dapat ditulis atau dibuat oleh runner. Runner membuat direktori saat startup, kemudian memeriksa repositori dan membuat direktori per-sesi di bawahnya. Tanpa --base-dir itu menggunakan /workspace, yang hanya berfungsi jika direktori itu sudah ada dan dapat ditulis atau Anda memulai runner sebagai root.

Jika runner tidak dapat membuat atau menulis ke jalur, itu keluar saat startup dengan kesalahan yang menamai direktori alih-alih mendaftar. Lihat Troubleshooting.

Kemudian mulai runner dengan --environment-secret-file dan --base-dir:

claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>'

Runner mencatat Registered: runner_id=<runner-id> setelah terdaftar dengan lingkungan Anda, kemudian mulai melakukan polling untuk pekerjaan. Jika runner keluar kemudian, mulai ulang sendiri. Lihat Jika runner keluar untuk mengetahui kapan hal itu terjadi.

3

Verifikasi runner muncul

Kembali ke halaman Cloud environments. Status lingkungan Anda berubah dari No runners deployed menjadi Healthy dalam beberapa detik setelah runner dimulai; buka lingkungan dan pilih Activity untuk melihat runner itu sendiri. Jika Anda tidak memiliki akses ke halaman admin, baris Registered: runner_id=<runner-id> di log runner dari langkah sebelumnya memberi Anda sinyal yang sama.

4

Arahkan sesi ke lingkungan

Mulai sesi di claude.ai/code dan pilih lingkungan Anda dari pemilih lingkungan, di mana lingkungan yang di-host sendiri muncul bersama yang di-host Anthropic. Untuk repositori, pilih repositori dari prasyarat: repositori publik, atau repositori yang sudah dapat diklon host ini. Runner mengklon dengan kredensial git apa pun yang sudah dimiliki host.

Runner yang tersedia berikutnya mengambil sesi yang antri dan mencatat Picked up session <session-id> bersama dengan hitungan aktif dan kapasitasnya, sehingga Anda dapat mengonfirmasi dari output runner sendiri host mana yang mengambil sesi. Tonton sesi bekerja dan baca balasan Claude di claude.ai/code.

Jika sesi tidak mulai bekerja, cocokkan dengan apa yang Anda lihat:

  • Sesi tetap dalam antrean: lihat Troubleshooting.
  • Sesi gagal dimulai dengan kesalahan git: kesalahan muncul di sesi dan di log runner. Jika kesalahan tersebut menyertakan could not read Username for dari git diikuti URL host git Anda, runner tidak memiliki kredensial HTTPS untuk host tersebut. Lihat Konfigurasi git, yang juga mencakup opsi kredensial untuk repositori pribadi dalam produksi.

Jika runner keluar

Jika runner keluar selama mulai cepat ini, mulai lagi dengan perintah yang sama. Runner dapat keluar dengan sendirinya:

  • Sesi selesai: log menampilkan [runner:exit] account workload drained — exiting. Runner keluar sesuai desain setelah sesi aktifnya selesai. Lihat Runner lifecycle.
  • Kehilangan kontak: log menampilkan baris [runner:fatal] dengan runner record gone server-side atau dengan poll auth failed. Jika runner kehilangan kontak dengan Anthropic untuk sementara waktu, misalnya karena host tertidur, runner dapat keluar saat berikutnya terhubung ke Anthropic.

Giliran yang selesai tidak mengakhiri sesi uji Anda. Setelah giliran pertama, sesi masih terpasang dan runner masih berjalan, sehingga Anda dapat mengirim pesan lanjutan ke sesi tanpa memulai ulang runner terlebih dahulu.

Untuk produksi, terapkan runner di bawah orkestrator yang memulai ulang saat keluar dan menunggu lebih lama antara restart ketika runner terus keluar tepat setelah dimulai. Lihat Terapkan ke produksi dan Ketika runner keluar.

Mengirim pesan lanjutan ke sesi yang sedang berjalan

Setelah sesi berjalan di lingkungan Anda, kirimkan pesan lanjutan ke sesi tersebut dari CLI claude di mesin mana pun tempat Anda masuk dengan claude auth login; perintah tidak perlu dijalankan dari mesin yang memulai sesi. Perintah ini mengirimkan satu pesan:

claude -p "your message" --cloud <session-id>

Untuk <session-id>, berikan ID session_... atau cse_... tanpa tambahan apa pun atau URL claude.ai/code milik sesi tersebut. Pengiriman yang berhasil akan mencetak Sent to cloud session. beserta ID sesi dan tautan untuk melihatnya. Bentuk ID yang diterima, output JSON, serta persyaratan akun dan kebijakan tercantum di Mengirim pesan lanjutan dari CLI, karena perintah ini bekerja dengan cara yang sama terhadap sesi yang di-host oleh Anthropic.

Apa selanjutnya

  • Terapkan ke produksi: keraskan penerapan, kontrol egress, konfigurasi kredensial git, dan jalankan armada di bawah Kubernetes atau Compose
  • Sesuaikan sesi: skrip wrapper, hook siklus hidup, runner sesuai permintaan, server MCP, dan izin
  • Uji end to end: uji asap CI yang mengirim sesi dan membaca balasan Claude