SpyBara
Go Premium

self-hosted-environments.md 2026-10-22 22:58 UTC to 2026-10-23 22:59 UTC

This page contains 31 additions and 31 deletions.

2026
Thu 1 23:59 Fri 2 22:59 Tue 6 23:59 Sat 10 23:01 Wed 14 22:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Sat 24 22:59 Thu 29 23:57 Fri 30 23:01

Lingkungan yang di-host sendiri

Jalankan sesi cloud Claude Code pada infrastruktur yang Anda kontrol: siapkan lingkungan yang di-host sendiri, deploy runner, dan arahkan sesi ke komputasi Anda sendiri.

[!NOTE]

Lingkungan yang di-host sendiri berada dalam beta publik pada paket Team dan Enterprise dan dinonaktifkan secara default. Lihat Ketersediaan dan batasan untuk jalur pengaktifan dan apa yang dikecualikan.

Lingkungan yang di-host sendiri menjalankan sesi cloud Claude Code pada infrastruktur yang dioperasikan organisasi Anda. Sesi cloud adalah sesi apa pun yang berjalan di tempat selain mesin pengembang. Pengembang memulainya dari claude.ai, aplikasi mobile dan desktop, terminal dengan claude --cloud, dan tugas terjadwal cloud. Secara default, sesi cloud dijalankan pada infrastruktur Anthropic.

Dalam lingkungan yang di-host sendiri, sesi yang sama tersebut dijalankan di dalam jaringan Anda. Selebihnya, pengalaman pengembang sama, kecuali perbedaan dalam Ketersediaan dan batasan dan masalah yang diketahui halaman deploy.

Jika tim Anda tidak menggunakan sesi cloud, tidak ada yang perlu dikonfigurasi di sini: sesi di terminal atau IDE selalu berjalan di mesin pengembang sendiri. Jika Anda ingin menjalankan Claude Code pada mesin yang selalu aktif milik Anda dan menggerakkannya dari perangkat lain, gunakan Remote Control, yang juga tersedia pada paket Pro dan Max. Ketika Anda siap untuk menyiapkan, langsung ke quickstart; untuk meninjau postur keamanan terlebih dahulu, mulai dengan Deploy ke produksi. Sisa halaman ini menjelaskan cara kerja self-hosting dan kapan memilihnya.

Cara kerja lingkungan yang di-host sendiri

Self-hosting memiliki tiga bagian:

  • Environment: tujuan bernama yang dapat dikirim sesi cloud. Organisasi Anda membuat environment di pengaturan admin claude.ai, dan masing-masing mengelompokkan serangkaian runner.
  • Runner: program yang berjalan pada host di dalam jaringan Anda. Runner menjalankan sesi; idenya sama dengan runner CI yang di-host sendiri.
  • Session: satu tugas Claude Code yang dimulai pengembang.

Ketika pengembang memulai sesi cloud, UI awal sesi menampilkan pemilih environment yang mencantumkan environment yang di-host Anthropic bersama dengan yang telah dibuat organisasi Anda. Jika mereka memilih milik Anda, control plane Anthropic menempatkan sesi pada antrian environment Anda, di mana runner mengklaimnya, mengkloning repositori yang dipilih pengembang, dan memulai proses Claude Code pada host Anda untuk menjalankannya. Runner mengautentikasi ke host git Anda dengan kredensial yang Anda konfigurasi; Konfigurasi git mencakup opsinya. Sesi menjangkau layanan internal Anda dari dalam jaringan Anda, dan host git Anda dengan cara yang sama ketika itu internal; lalu lintas ke Anthropic, polling antrian, aliran peristiwa sesi, dan secara default inferensi model, adalah HTTPS keluar ke api.anthropic.com, dengan daftar singkat host lebih lanjut yang dapat dijangkau sesi dalam Persyaratan jaringan. Anthropic tidak pernah terhubung ke jaringan Anda.

Diagram arsitektur lingkungan yang di-host sendiri: batas jaringan Anda berisi runner, dua proses sesi Claude Code di dalamnya, dan host git Anda, dengan api.anthropic.com di luar yang menyimpan antrian, aliran sesi, dan inferensi. Runner polling antrian dan menjangkau host git, setiap proses sesi membuka aliran, inferensi, dan koneksi git miliknya sendiri, dan setiap koneksi keluar dari jaringan Anda, tanpa yang masuk.

Dua kotak Claude Code dalam diagram adalah proses sesi: satu runner menjalankan dua sesi sekaligus, hingga kapasitas yang dikonfigurasi. Runner melayani satu owner pada satu waktu dan terkunci ke owner itu ketika mengklaim sesi pertamanya, jadi kode yang diperiksa tidak pernah bercampur antara owner; Runner lifecycle mencakup aturannya.

Anda dapat memulai runner sendiri dan membiarkannya berjalan, atau menjalankan orchestrator autoscaling, proses kedua yang Anda host, yang memulai runner saat sesi antri; setiap runner keluar dengan sendirinya ketika pekerjaannya selesai. Bagaimanapun, Anda menyiapkan environment sekali, dan itu muncul di pemilih pada setiap permukaan yang didukung.

Ketersediaan dan batasan

Periksa ini sebelum merencanakan peluncuran:

Mengapa self-host

Sebagian besar tim dilayani dengan lebih baik oleh lingkungan yang di-host Anthropic, yang tidak memerlukan infrastruktur untuk dijalankan atau dipertahankan. Self-hosting adalah untuk tim yang persyaratan jaringan, tooling, atau kepatuhan mereka memerlukan menjaga eksekusi sesi pada infrastruktur yang mereka kontrol. Jika itu Anda, rencanakan kepemilikan operasional yang dibawanya: Anda membangun dan mempertahankan citra runner, mengoperasikan fleet, dan mengontrol jaringannya.

Sebagai gantinya, self-hosting memberi Anda akses jaringan, tooling kustom, dan kontrol kepatuhan:

  • Network access: sesi berjalan di dalam jaringan Anda dan dapat menjangkau layanan internal, database, dan registri tanpa mengeksposnya ke internet publik
  • Custom tooling: pra-instal compiler, SDK, dan CLI internal dalam citra runner Anda sehingga setiap sesi dimulai siap untuk membangun
  • Compliance: checkout repositori dan artefak build tetap pada infrastruktur yang Anda kontrol. Konten sesi masih dikirim ke api.anthropic.com.

Environment, runner, dan sesi

Environment dikelola pada halaman Cloud environments di pengaturan admin claude.ai; runner adalah proses yang Anda mulai dan kelola pada infrastruktur Anda sendiri.

Konsep kunci

Istilah-istilah ini muncul di seluruh halaman self-hosted:

Istilah Apa itu
Environment Grup bernama runner Anda, dibuat di pengaturan claude.ai. Sesi dirutekan ke environment, bukan ke runner individual.
Environment secret Kredensial bersama tunggal yang digunakan runner untuk mengautentikasi dan mendaftar dengan environment. Ditampilkan sekali saat pembuatan environment, berlabel environment key di UI admin.
Runner Proses jangka panjang yang Anda deploy. Runner mendaftar dengan environment, menerima token runner, dan polling untuk sesi.
Session Satu tugas Claude Code, dimulai dari claude.ai, aplikasi mobile, atau surface Anthropic lain seperti tugas terjadwal atau agent. Setiap sesi berjalan sebagai proses Claude Code anak yang dimulai runner.

Di bidang API, klaim token, dan nama metrik, environment muncul sebagai pool, dan ID environment adalah pool_id. Referensi memetakan dua ejaan, termasuk nama flag pool yang sudah usang.

Runner melayani satu owner pada satu waktu. Sesi pertama yang diambil runner mengunci runner ke owner sesi itu, dan runner kemudian menjalankan sesi hanya untuk owner itu, hingga kapasitas yang dikonfigurasi. Siapa owner tergantung pada bagaimana sesi dimulai:

  • Sesi yang dimulai pengguna: owner adalah akun pengguna itu.
  • Sesi saluran Claude Tag: Claude menjalankannya tanpa akun pengguna yang terlampir, jadi owner adalah agen Claude Tag yang memulai sesi. Setiap sesi saluran yang dimulai agen itu memiliki owner yang sama, siapa pun yang mengirim pesan Slack, jadi runner yang terkunci ke itu melayani sesi yang dimulai orang berbeda ketika Anda menjalankannya pada --capacity di atas satu atau dengan --drain-grace-sec positif.

Ukuran fleet minimum adalah oleh karena itu jumlah owner yang Anda harapkan aktif sekaligus, menghitung pengguna dan agen Claude Tag.

Siklus hidup sesi

Ketika pengembang memulai sesi dan memilih environment Anda, control plane Anthropic menempatkan sesi pada antrian environment. Dari sana:

  1. Runner dengan kapasitas gratis mengklaim sesi dan memegang sewa padanya.
  2. Runner mengkloning repositori ke direktori kerjanya dan memulai proses Claude Code anak.
  3. Anak streaming peristiwa kembali melalui HTTPS sementara runner terus polling; setiap poll menyegarkan sewa dan berfungsi ganda sebagai detak jantung.
  4. Jika runner berhenti polling, sewanya berakhir setelah sekitar 60 detik. Server kemudian dapat memerlukan beberapa menit dan terkadang lebih lama untuk memasukkan kembali sesi ke antrian untuk runner lain.

Runner memberikan setiap permintaan poll 10 detik. Ketika permintaan habis waktu, hilang, atau mendapat respons yang tidak dapat diurai runner, runner terus melayani sesi aktifnya dan mencoba lagi setelah satu atau dua detik daripada menunggu poll terjadwal berikutnya. Misalnya, proxy intersepsi yang menjawab poll dengan halaman miliknya sendiri menghasilkan respons yang tidak dapat diurai runner. Setiap kali permintaan lain gagal dengan salah satu cara itu, runner menggandakan celah sebelum percobaan ulang berikutnya, hingga 20 detik, dan mempersingkat celah kapan pun sewa hampir kedaluwarsa.

Siklus hidup runner

Sesi pertama yang diambil runner mengunci runner ke owner sesi itu, dan runner menjalankan hingga --capacity sesi bersamaan untuk owner itu. Sementara runner memiliki sesi aktif dan belum menerima sinyal shutdown atau mencapai waktu pensiun, runner terus mengklaim pekerjaan antri owner yang terkunci. Apa yang terjadi setelah mereka selesai tergantung pada --drain-grace-sec:

  • Pada default 0: runner keluar segera setelah sesi aktifnya selesai, tanpa polling untuk lebih banyak, jadi orchestrator yang Anda deploy di bawahnya, seperti Kubernetes, dapat memulainya ulang dengan disk segar, siap melayani owner apa pun.
  • Pada nilai positif: runner terus polling antrian owner yang terkunci selama banyak detik itu sebelum keluar.

Siklus hidup ini mengisolasi kode yang diperiksa setiap owner tanpa memerlukan runner untuk menghapus status disk antara owner.

Bagaimana infrastruktur Anda menghentikan runner menentukan apakah Anda memerlukan --retire-at. Pembunuhan yang mengirimkan SIGTERM tidak memerlukan flag: runner mengalirkan seperti Shutdown timing menjelaskan, atau terus melayani sesi yang sudah dipegang ketika Anda menetapkan --defer-shutdown-max-min. Jika infrastruktur Anda malah menghancurkan host pada waktu dinding jam yang diketahui tanpa sinyal, atau dengan periode grace terlalu pendek untuk mengalirkan, seperti batas seumur hidup sandbox atau penarikan spot-instance, teruskan --retire-at <epoch-seconds> diatur ke beberapa menit sebelum waktu itu. Pada waktu pensiun:

  1. Runner berhenti mengambil pekerjaan baru.
  2. Runner melepaskan setiap sesi aktif melalui jalur pelepasan yang sama yang digunakan flag --release-idle-session-min, jadi sesi dilanjutkan pada runner segar ketika pengguna mengirim pesan berikutnya. Kapan runner melepaskan setiap sesi tergantung pada statusnya:
    • Runner melepaskan sesi yang sedang berada di tengah giliran setelah giliran itu selesai. Runner terlebih dahulu menunggu proses sesi melaporkan akhir giliran ke Anthropic, tidak lebih lama dari SELF_HOSTED_RUNNER_POST_TURN_SETTLE_MS. Sebelum v2.1.280, runner melepaskan sesi segera setelah giliran selesai.
    • Ketika giliran selesai dan meninggalkan tugas latar belakang berjalan, runner menunggu hingga 60 detik untuk mereka, kemudian melepaskan sesi bahkan jika mereka masih berjalan. Jika tugas telah selesai tetapi giliran tindak lanjut yang membaca hasilnya belum berjalan, runner menyimpan sesi sampai giliran itu selesai, dan menunggu tidak lebih lama dari SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS untuk giliran itu dimulai.
  3. Runner keluar 0 setelah semua sesinya dilepaskan.

Giliran yang bertahan lebih lama dari pembunuhan masih hilang; Shutdown timing mencakup ukuran margin. Tanpa --retire-at, pembunuhan host tanpa sinyal tidak dapat dibedakan dari crash: control plane mencatat pekerja yang hilang daripada pelepasan bersih, dan sesi memasukkan kembali ke runner lain.

Jalur jaringan

Runner dan sesinya membuat beberapa jenis koneksi keluar, dan tidak ada konektivitas masuk dari Anthropic yang diperlukan:

  • Control plane: runner polling api.anthropic.com untuk pekerjaan dan posting peristiwa kemajuan setup dan kegagalan, semua HTTPS keluar. Polling berfungsi ganda sebagai detak jantung runner.
  • Git: runner mengkloning dari dan melakukan push ke host git Anda melalui HTTPS atau SSH, diautentikasi dengan kredensial yang disediakan deployment Anda. Lihat Konfigurasi git untuk opsinya, termasuk kredensial yang dicetak per sesi. Dengan proxy git Anthropic, lalu lintas git untuk repositori di github.com melewati api.anthropic.com sebagai gantinya.
  • Session child: proses Claude Code anak memegang stream peristiwa sesi ke api.anthropic.com, dan membuat panggilan keluarnya sendiri untuk inferensi model dan untuk perintah git yang dijalankan selama sesi. Dalam sesi yang menggunakan git yang dikelola Anthropic, proses anak mengirim lalu lintas git dan gh untuk github.com melalui koneksi WebSocket yang dibukanya ke api.anthropic.com.
  • SCM connector: SCM connector orchestrator yang opsional tidak tersedia, sehingga tunnel-nya tidak terbuka. Tunnel tersebut adalah koneksi WebSocket ke api.anthropic.com.

Lihat Persyaratan jaringan untuk daftar egress lengkap. Diagram di atas menunjukkan jalur-jalur ini, kecuali SCM connector opsional dan koneksi git yang dikelola Anthropic.

Secara default, inferensi model menggunakan Anthropic API. Control plane mengirimkan endpoint API ke setiap sesi, dan sesi mengautentikasi dengan token OAuth yang diterbitkan Anthropic dan berlingkup sesi. Untuk mengirim permintaan model ke akun cloud Anda sendiri sebagai gantinya, lihat Kirim permintaan model ke Bedrock atau Agent Platform.

Proxy egress korporat didukung. Runner dan orchestrator autoscaling opsional menghormati proxy dan variabel mTLS yang dijelaskan dalam Konfigurasi jaringan, seperti HTTPS_PROXY dan NO_PROXY; atur mereka di lingkungan setiap proses. Variabel mencakup panggilan control-plane, SCM connector WebSocket orchestrator, dan klon bawaan untuk remote HTTPS, dan sesi mewarisinya dari runner. Streaming sesi menggunakan server-sent events melalui HTTPS, jadi proxy dalam jalur tidak boleh membuffer respons.

Jika proxy Anda juga memerlukan header Proxy-Authorization, runner dapat menambahkannya ke setiap koneksi yang dibukanya ke proxy; lihat Autentikasi ke proxy egress.

Apa yang tetap pada infrastruktur Anda

Checkout repositori, artefak build, rahasia, dan file apa pun yang dibuat atau dimodifikasi sesi tetap pada mesin yang Anda sediakan. Percakapan itu sendiri, termasuk prompt, respons, dan hasil tool, dikirim ke api.anthropic.com, dan Anthropic menyimpan transkrip sesi sehingga Anda dapat melanjutkan sesi dari surface yang didukung lain. Ketika runner mengirim permintaan model ke Amazon Bedrock atau Agent Platform Google Cloud, percakapan tetap dikirim ke api.anthropic.com dalam aliran event sesi.

Lingkungan yang di-host sendiri memindahkan eksekusi sesi ke dalam jaringan Anda. Control plane tetap di-host Anthropic: orkestrasi sesi, antrian, dan antarmuka claude.ai terus berjalan pada infrastruktur Anthropic.

Memulai

Halaman lingkungan yang di-host sendiri diatur oleh apa yang Anda lakukan:

  • Quickstart: instal Claude Code, buat environment, mulai runner, dan arahkan sesi pertama Anda
  • Deploy ke produksi: pengerasan keamanan, egress jaringan, kredensial git, resep Kubernetes dan Compose, masalah yang diketahui, dan troubleshooting
  • Sesuaikan sesi: skrip wrapper untuk kredensial per-sesi, hook siklus hidup, runner on-demand, server MCP, dan izin
  • Uji end to end: uji smoke CI yang memverifikasi citra runner sebelum Anda mempromosikannya
  • Referensi: setiap flag CLI, variabel lingkungan, metrik, dan endpoint kesehatan
  • Verifikasi identitas sesi: validasi token sesi dari layanan Anda sendiri sebelum memberikan akses