Skip to main content
Lingkungan yang di-host sendiri berada dalam beta publik pada paket Team dan Enterprise; Ketersediaan dan batasan mencakup jalur pengaktifan. Halaman ini menjalankan sesi pertama Anda; lihat Lingkungan yang di-host sendiri untuk mengetahui apa itu dan Terapkan ke produksi untuk pengerasan dan resep armada.
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.
  • Konektor GitHub diaktifkan oleh Owner, serta koneksi GitHub milik masing-masing pengembang, sehingga mereka dapat memilih repositori github.com saat 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. Kunci SSH saja tidak cukup, karena runner mengklon URL https:// repositori. Untuk mengklon melalui SSH sebagai gantinya, lihat Tulis ulang URL git untuk jaringan privat.
  • 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. Runner yang melayani sesi Claude Tag memerlukan v2.1.229 atau lebih baru serta python3 pada PATH-nya, karena hook yang disediakan oleh control plane untuk sesi tersebut menjalankan python3. 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:
Host yang siap mencetak teks penggunaan runner, mencantumkan flag seperti --environment-secret-file. Pada versi yang lebih lama dari 2.1.224, perintah mencetak output claude --help umum sebagai gantinya. Jika Anda melihat output tersebut, perbarui Claude Code. Jika Anda menjalankan claude dari gambar kontainer, bangun ulang gambar dengan versi 2.1.224 atau lebih baru.

​
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:
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.
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.
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.
Gunakan direktori yang dikhususkan untuk runner, bukan direktori home Anda atau direktori berisi klon milik Anda sendiri. Runner memperlakukan apa pun yang ditemukannya di <writable-dir>/<repo-owner>/<repo> sebagai klonnya sendiri, dan dapat mengatur ulang serta menimpa atau menghapus file di dalamnya.
Jika runner tidak dapat membuat atau menulis ke direktori dasar, runner keluar saat startup dengan kesalahan yang menyebutkan nama direktori tersebut alih-alih mendaftar. Lihat Troubleshooting.Kemudian mulai runner dengan --environment-secret-file dan --base-dir:
Runner mencatat Registered: runner_id=<runner-id> setelah terdaftar dengan lingkungan Anda, kemudian mulai melakukan polling untuk pekerjaan. Jika dimulai dengan perintah ini, runner keluar sesuai desain setelah melayani satu sesi, bukan setelah setiap giliran. Untuk melayani lebih banyak sesi, mulai runner lagi setiap kali runner keluar. Lihat Jika runner keluar untuk mengetahui kapan hal itu terjadi dan apa yang dicatat runner di log.
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 melalui URL HTTPS-nya tanpa diminta kredensial.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: jika kesalahan tersebut menyertakan could not read Username for dari git diikuti URL host git Anda, runner tidak memiliki kredensial HTTPS untuk host tersebut.
    • Sediakan kredensial HTTPS: lihat Konfigurasi git
    • Klon melalui SSH sebagai gantinya: jika host runner sudah memiliki kunci SSH, lihat Tulis ulang URL git untuk jaringan pribadi
    • Setelah salah satu perbaikan: mulai runner lagi dan pantau sesi yang gagal alih-alih memulai sesi baru. Jika sesi tersebut telah gagal beberapa kali, tunggu beberapa menit hingga runner mencatat Picked up session.
    • Untuk menggunakan repositori lain sebagai gantinya: arsipkan atau hapus sesi yang gagal, kemudian mulai runner lagi dan mulai sesi baru. Jika tidak, runner dapat mengambil sesi yang gagal alih-alih sesi yang baru.

​
Jika runner keluar

Jika runner keluar selama mulai cepat ini, mulai lagi. Runner dapat keluar dengan sendirinya:
  • Tidak ada lagi yang berjalan: log menampilkan [runner:exit] account workload drained — exiting. Runner keluar sesuai desain setelah tidak lagi menjalankan sesi apa pun, misalnya:
    • Anda mengarsipkan atau menghapus sesi: mulai runner lagi
    • Sesi gagal dimulai: perbaiki penyebabnya, kemudian mulai runner lagi
  • 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:
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