Sesuaikan sesi di lingkungan yang di-host sendiri

​

Skrip wrapper

claude self-hosted-runner --environment-secret-file /etc/claude/environment-secret --exec-path /etc/claude/session-wrapper.sh

​

Berikan nilai default untuk variabel yang dapat tidak diatur

​

Beri tanda kutip pada argumen dan variabel yang diekspansi skrip Anda

• Argumen: teruskan sebagai "$@"
• Variabel: beri tanda kutip pada masing-masing, seperti dalam "${CLAUDE_CODE_REMOTE_SLACK_THREAD_URL:-}". Tautan thread Slack, misalnya, dapat berisi ? dan &.
• String eval dan sh -c: jangan substitusikan nilai ke dalam string yang dijalankan eval atau sh -c, bahkan di dalam tanda kutip. Buat string tersebut mereferensikan variabelnya sebagai gantinya.

​

Jaga stdin dan file descriptor 3 terlampir

exec 9<&0   # the runner uses 3, and from v2.1.309 reserves 4 and 5
"$CLAUDE_RUNNER_CLAUDE_BIN" "$@" <&9 9<&- &
CHILD=$!
trap 'teardown' EXIT
wait "$CHILD"

• File descriptor 3: membawa sinyal aktivitas anak ke runner. Jangan tutup atau gunakan kembali di wrapper.
• File descriptor 4 dan 5: runner pada Claude Code v2.1.309 atau lebih baru mencadangkannya untuk anak. Jangan tutup atau gunakan kembali di wrapper. Jika wrapper Anda menggunakan salah satunya, misalnya untuk menyimpan stdin, pindahkan penggunaan tersebut ke descriptor 6 hingga 9, yang juga dibiarkan bebas oleh versi sebelumnya.
• stderr: ketika wrapper atau anak keluar dengan kode bukan nol, runner mengirimkan baris-baris terakhir stderr ke sesi dan mencetaknya di log-nya sendiri. Pengguna sesi melihat baris-baris tersebut, jadi jangan cetak rahasia ke stderr, dan hapus set -x sebelum Anda men-deploy wrapper. Jika Anda mengalihkan stderr, sesi tetap berjalan, tetapi runner melaporkan kegagalan hanya dengan exit code.

​

Teruskan flag system prompt

• Teruskan flag tersebut: akhiri wrapper dengan exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@", yang meneruskan flag file bersama setiap argumen lainnya. Jangan hapus atau tulis ulang flag tersebut. Jika sebuah sesi kehilangan flag file prompt, sesi berjalan tanpa instruksi yang dikirim bidang kontrol untuknya.
• Pada runner v2.1.281 atau lebih baru, flag file yang Anda tambahkan menggantikan milik server, tidak pernah menambahinya: setiap flag file prompt hanya menerima satu nilai dan Claude Code mempertahankan kemunculan terakhir, jadi jika Anda menambahkan --append-system-prompt-file <path> setelah "$@", isi file Anda menggantikan instruksi tambahan dari server. Untuk menambahkan instruksi di atas instruksi server, letakkan di CLAUDE.md pada image runner, yang disemai runner ke konfigurasi tingkat pengguna setiap sesi.

​

Perbaiki Argument list too long saat awal sesi

Session <id> finished: failed — reason: child exited 126: /opt/wrapper.sh: line 9: /usr/local/bin/claude: Argument list too long

exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --append-system-prompt "$(cat /opt/team-instructions.md)"

​

Sediakan kredensial yang dibatasi untuk pembuat sesi

#!/bin/bash
# Key on the stable Anthropic user ID and require a human creator.
CREATOR_SUB=$("$CLAUDE_RUNNER_CLAUDE_BIN" self-hosted-runner decode-token \
  | jq -re '.act.sub // "" | select(startswith("user:"))') \
  || { echo "decode-token: verification failed or no human creator" >&2; exit 1; }

creds=$(your-sts-helper assume-role --subject "$CREATOR_SUB") \
  || { echo "credential exchange failed" >&2; exit 1; }
eval "$creds"

exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"

​

Lifecycle hooks

​

checkout

​

Mendapatkan kredensial git di dalam hook

• Kredensial clone per-sesi: verifikasi CLAUDE_CODE_SESSION_ACCESS_TOKEN dengan library JWT standar terhadap endpoint JWKS di bawah CLAUDE_RUNNER_API_BASE_URL, seperti yang dijelaskan dalam Verify the token from your service. Kemudian minta layanan kredensial Anda menerbitkan kredensial clone berumur pendek untuk identitas dalam klaim act token. Kaitkan kredensial tersebut dengan act.sub, dan jangan mewajibkan act.email.
• Autentikasi git host: gunakan autentikasi git apa pun yang sudah dimiliki host, seperti SSH agent, credential helper, atau .netrc.

​

Ketika hook gagal

• Repositori tempat sesi melakukan push hasil: runner menggagalkan sesi, dan pada keluar dengan kode bukan nol menampilkan bagian akhir stderr skrip kepada pengguna. Tulis alasannya ke stderr sebagai satu baris singkat, tulis di bagian paling akhir, lalu keluar dengan kode bukan nol. Jangan mencetak rahasia ke stderr, dan hapus set -x sebelum Anda men-deploy hook. Jika couldn't find remote ref dari git muncul dalam kira-kira 4 KB terakhir stderr hook, runner melaporkan branch yang telah dihapus sebagai gantinya. Pesan error sesi kemudian menyatakan bahwa branch tersebut tidak lagi ada di remote dan meminta pengguna untuk memulihkannya. Jika branch tersebut ada, lihat Sesi gagal dengan no longer exists on the remote atau couldn't find remote ref.
• Repositori yang hanya dibaca sesi, seperti repositori yang ditambahkan ke sesi yang sedang berjalan: runner melewatinya dan melanjutkan dengan repositori yang tersisa. Runner memposting langkah Skipped ke sesi dan menghapus apa pun yang ditinggalkan hook di jalur checkout. Ketika langkah Skipped menyebutkan checkout hook, temukan detail kegagalan pada baris [runner:warn] checkout hook failed di log runner. Ketika langkah tersebut menyatakan bahwa ref sumber no longer exists on remote, lihat Sesi gagal dengan no longer exists on the remote atau couldn't find remote ref. Jika proses melewati ini membuat sesi tidak memiliki repositori sama sekali, runner tetap menggagalkan sesi.

​

post-session

• completed: sesi berakhir dengan bersih. Proses Claude Code keluar secara normal, atau keluar dengan sendirinya setelah sesi diarsipkan atau dihapus.
• failed: proses Claude Code mogok, atau setup gagal setelah dimulai.
• interrupted: runner menghentikan sesi, dalam salah satu kasus berikut:
  • Runner melepaskan sesi untuk membebaskan slot.
  • Sesi mengalami timeout saat startup.
  • Server memindahkan sesi dari runner ini.
  • Polling runner mendeteksi pengarsipan atau penghapusan sebelum proses keluar.
  • Runner sedang melakukan drain.
  • Sesi melampaui batas --kill-session-after-min miliknya.
• abandoned: dicadangkan untuk sesi yang diklaim runner lain. Hook saat ini tidak menyala dalam kasus itu.

#!/usr/bin/env bash
set -u
export GIT_ALLOW_PROTOCOL=${GIT_ALLOW_PROTOCOL:-https:http:ssh}
IFS=':'
# -c overrides beat repo-local settings, blocking session-written fsmonitor,
# hook-path, and gpg-program config from executing code with the hook's
# privileges. -c commit.gpgsign=false also leaves these rescue commits
# unsigned under --configure-git.
# Repo-local credential.helper and pushurl still apply, and on a runner
# before v2.1.280 so does core.sshCommand; see the note below the script
# before you give this push a credential.
g() { git -c core.fsmonitor=false -c core.hooksPath=/dev/null \
        -c commit.gpgsign=false "$@"; }
for ws in $CLAUDE_RUNNER_WORKSPACE_PATHS; do
  cd "$ws" 2>/dev/null || continue
  [ -z "$(g status --porcelain 2>/dev/null)" ] && continue
  g add -A
  g commit -q -m "runner snapshot: $CLAUDE_RUNNER_SESSION_ID ($CLAUDE_RUNNER_EXIT_REASON)" || continue
  g push -q origin "HEAD:refs/heads/rescue/$CLAUDE_RUNNER_SESSION_ID" || true
done

​

Hook timing when the runner releases a session

• Idle setelah giliran, atau timeout saat startup: runner menghentikan anak dan menjalankan hook ini hingga selesai. Hanya kemudian itu merilis sesi. Pesan pengguna yang dikirim saat hook berjalan tidak dapat melanjutkan sesi di runner lain sebelum hook selesai.
• Menunggu pengguna menjawab prompt, seperti prompt izin: runner merilis sesi terlebih dahulu, kemudian menjalankan hook ini. Pesan pengguna yang dikirim saat hook berjalan dapat melanjutkan sesi di runner lain sebelum hook selesai.

​

Konfigurasi Git di dalam lifecycle hooks

• Git hook: kecuali Anda menyediakan nilai, core.hooksPath adalah /dev/null, sehingga git melewati hook di .git/hooks repositori dan direktori hook apa pun yang disebutkan ~/.gitconfig. Untuk menyediakan nilai, ekspor core.hooksPath sebagai pasangan GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n di lingkungan runner. Runner juga membaca core.hooksPath dari konfigurasi git sistem, dan menggunakannya hanya ketika pengguna runner tidak dapat menulis file tersebut, direktori yang disebutkannya, atau file hook di dalamnya. Ketika runner mengabaikan suatu nilai, baris [runner:warn] saat startup menyebutkan nilai tersebut dan alasannya.
• Monitor sistem file: core.fsmonitor kosong, sehingga git di hook Anda tidak menjalankan program monitor yang disebutkan oleh file konfigurasi.
• Protokol remote: GIT_ALLOW_PROTOCOL adalah https:http:ssh. Clone, fetch, atau push yang menggunakan jalur lokal, URL file://, atau URL git:// gagal dengan fatal: transport 'file' not allowed atau fatal: transport 'git' not allowed.
• Perintah SSH dan prompt kredensial: git di hook Anda mengabaikan core.sshCommand dan core.askPass dari file konfigurasi. Untuk menggunakan perintah SSH Anda sendiri, atur GIT_SSH_COMMAND di lingkungan runner. Untuk menggunakan program prompt kredensial, atur GIT_ASKPASS di sana. Sesi mewarisi lingkungan runner, sehingga kedua variabel juga mencapai git milik sesi itu sendiri. Jangan letakkan kredensial di salah satunya.
• Program gpg: gpg.program, gpg.openpgp.program, gpg.x509.program, dan gpg.ssh.program adalah jalur yang ditetapkan runner, tidak pernah nilai dari file konfigurasi.
• Penandatanganan commit: dengan --configure-git, commit yang Anda buat dari hook ditandatangani sebagai sesi. Tanpa flag tersebut, commit.gpgsign dan tag.gpgsign bernilai false.

• Pasangan konfigurasi: pasangan GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n yang Anda ekspor di lingkungan runner menggantikan nilai runner untuk kunci yang sama. Beri nomor pasangan Anda mulai dari 0 dan atur GIT_CONFIG_COUNT ke jumlah pasangan tersebut. Ketika pasangan terakhir yang diumumkan oleh hitungan tidak ada, runner mengabaikan semua pasangan Anda dan mencatat baris [runner:warn] saat startup.
• Environment variable git: runner membiarkan GIT_ALLOW_PROTOCOL, GIT_SSH_COMMAND, dan GIT_ASKPASS sebagaimana Anda mengaturnya di lingkungannya.
• Opsi git -c: opsi git -c di dalam hook menimpa pasangan GIT_CONFIG_KEY_n, baik milik runner maupun milik Anda. Opsi ini tidak mengubah GIT_ALLOW_PROTOCOL, GIT_SSH_COMMAND, atau GIT_ASKPASS, yang dibaca git sebelum konfigurasi apa pun.

​

command

​

Runner on-demand

claude self-hosted-runner orchestrator \
  --environment-secret-file /etc/claude/environment-secret \
  --hooks-dir /etc/claude/hooks

​

Hook spawn-runner

• Mulai dengan pesanan kerja: arahkan --environment-secret-file ke file yang berisi JWT pesanan kerja, atau atur SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET ke nilai JWT.
• Salin JWT sebelum hook keluar: orchestrator menghapus file pesanan kerja setelah hook keluar, jadi salin JWT ke dalam beban kerja yang Anda kirimkan, seperti Kubernetes Secret di Job yang dipijahkan, daripada melewatkan jalur file.
• Gunakan --capacity 1 di runner yang dipijahkan: pesanan kerja yang terikat sesi mendaftarkan tepat satu runner yang terikat ke sesi itu, jadi kapasitas lebih tinggi menambah slot yang tidak pernah menerima pekerjaan, dan runner mencatat peringatan saat startup.
• Pesanan kerja pre-warming mendaftarkan tidak terikat: runner standby tidak terikat ke sesi dan mengklaim pekerjaan antri seperti runner fleet tetap.

1. Jadilah idempoten pada CLAUDE_RUNNER_ORDER_ID. Pengiriman ulang permintaan yang sama harus memijahkan paling banyak satu runner. Turunkan nama sumber daya deterministik dari order ID dan biarkan platform Anda menolak duplikat. Jangan kunci pada CLAUDE_RUNNER_SESSION_ID sebagai gantinya. Setiap permintaan ulang untuk sesi membawa ID sesi yang sama dengan order ID baru. Beban kerja yang dinamai atau dideduplikasi oleh ID sesi tidak dibuat lagi selama beban kerja pertama masih ada.
2. Jangan coba ulang beban kerja. Satu ID pesanan berarti paling banyak satu beban kerja yang dibuat. Jika runner tidak pernah mendaftar, Anthropic meminta ulang dengan ID pesanan segar setelah --expected-spawn-seconds.
3. Gunakan kontrak exit code. Keluar dengan status yang sesuai dengan hasilnya:
   • Keluar 0: dikirimkan.
   • Keluar 1, atau masih berjalan saat --hook-timeout berakhir: kegagalan yang dapat dicoba ulang. Sesi mundur dan ditawarkan kembali. Setelah 10 permintaan gagal berturut-turut, sesi diblokir seperti setelah keluar 2 atau lebih tinggi.
   • Keluar 2 atau lebih tinggi: kegagalan yang tidak dapat dicoba ulang. Sesi diblokir dari pemijahan lagi sampai pengguna mengirimkan pesan baru ke sesi tersebut atau Owner memilih Retry di atasnya di tab Activity lingkungan.
   Selama sesi mundur, sesi tersebut menampilkan Queued di tab Activity tanpa kesalahan pemijahan, jadi baca output hook di log orchestrator. Setelah diblokir, sesi menampilkan Failed. Perluas sesi tersebut untuk membaca kesalahan pemijahan, yang diambil dari 512 karakter terakhir stderr hook. Tulis kesalahan yang dapat ditindaklanjuti ke stderr, dan jangan sertakan rahasia. Dalam hook shell, pertahankan kegagalan sementara agar dapat dicoba ulang. Permintaan pre-warming tidak memiliki sesi untuk gagal: orchestrator mencatat keluar bukan nol secara lokal saja, dan server meminta ulang pemijahan setelah sewa --expected-spawn-seconds kedaluwarsa.
4. Atur --expected-spawn-seconds ke setidaknya waktu p99 Anda dari permintaan pemijahan hingga pendaftaran runner. Ukur sejak orchestrator menerima permintaan pemijahan, dan sertakan waktu tunggu untuk kapasitas di platform Anda serta waktu boot. Nilai ini adalah sewa server-side, dan pesanan kerja kedaluwarsa bersamanya, sehingga runner yang beban kerjanya membutuhkan waktu lebih lama tidak dapat mendaftar. Semua replika orchestrator harus menggunakan nilai yang sama.

​

Perbaiki sesi yang dibuka kembali yang tetap Queued atau menampilkan Failed

name="runner-${CLAUDE_RUNNER_SESSION_ID}"

1. Pada permintaan pemijahan pertama sesi, hook membuat beban kerja dengan nama tersebut, dan sebuah runner dimulai
2. Runner keluar, misalnya setelah --release-idle-session-min, dan pengguna kemudian membuka kembali sesi tersebut
3. Permintaan pemijahan berikutnya untuk sesi tersebut membawa ID sesi yang sama dan order ID baru, sehingga hook membangun nama yang sama
4. Jika platform Anda masih memiliki beban kerja dari permintaan pertama, karena tidak ada yang menghapusnya ketika runner-nya keluar, hook tidak membuat beban kerja baru dan tidak ada runner yang dimulai
5. Setiap permintaan pemijahan berikutnya untuk sesi tersebut berakhir dengan cara yang sama

name="runner-${CLAUDE_RUNNER_ORDER_ID}"

• Queued: sesi mendapatkan permintaan pemijahan berikutnya dengan sendirinya
• Failed: pilih Retry pada sesi tersebut sebagai Owner, atau minta penggunanya mengirim pesan baru

​

Buat runner on-demand keluar saat idle

​

Kirim output proses latar belakang ke file

your-background-command >> "$HOME/claude-runner.log" 2>&1 &

• Sekitar satu detik setelah hook keluar, orchestrator mencatat exited, but a process it started still has the hook's stdout or stderr open. Sejak baris tersebut, orchestrator mencatat hingga 64 KB tambahan dari output tersebut di bawah [runner:hook:spawn-runner:after-exit jti=<order id>] lalu membuang sisanya.
• Setelah orchestrator keluar, penulisan proses ke sana akan gagal.

• Tab Activity, dalam kesalahan pemijahan sesi yang gagal: spawn-runner hook timed out after 60000ms, atau baris-baris terakhir di stderr hook.
• Log orchestrator: timed out after 60000ms, sending SIGTERM to process tree.

​

Keluar dari hook tanpa menunggu runner

• Untuk mengonfirmasi bahwa timeout-lah yang menghentikan runner Anda: cari timed out after 60000ms, sending SIGTERM to process tree di log orchestrator pada setiap permintaan pemijahan. 60000 adalah --hook-timeout Anda dalam milidetik.
• Untuk memperbaikinya: minta hook mengirimkan runner ke platform Anda dan keluar dengan 0. Jika Anda menaikkan --hook-timeout sebagai gantinya, runner hanya berhenti lebih lambat.

​

Pertahankan kegagalan sementara agar dapat dicoba ulang dalam hook shell

set -e
PERMANENT=; permanent() { printf '%s\n' "$*" >&2; PERMANENT=1; exit 2; }
trap 'rc=$?; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT

• exit 2 atau lebih tinggi secara langsung: dengan trap terpasang, ini menjadi keluar 1. Untuk kesalahan yang tidak dapat diperbaiki oleh retry apa pun, panggil permanent dengan alasannya sebagai gantinya, seperti permanent "namespace claude-runners does not exist". Panggil di shell utama, bukan di dalam $( ), ( ), atau pipe.
• exec: jangan memulai perintah terakhir hook dengan exec, karena exec menggantikan shell dan trap tidak berjalan.
• Trap EXIT kedua: trap ... EXIT kedua menggantikan yang pertama, jadi gabungkan keduanya menjadi satu trap. Letakkan perintah pembersihan Anda tepat setelah rc=$?; dan akhiri masing-masing dengan || true;. Pembersihan kemudian berjalan saat gagal maupun saat berhasil, dan perintah pembersihan yang gagal tidak menetapkan status keluar hook. Trap gabungan ini menunjukkan bentuknya, dengan your-cleanup-command sebagai pengganti perintah Anda sendiri:
  trap 'rc=$?; your-cleanup-command || true; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT
  
• Perintah yang boleh gagal: jika hook sebelumnya tidak menggunakan set -e, kini hook berhenti pada perintah pertama yang mengembalikan nilai bukan nol, seperti pencarian yang tidak menemukan apa pun. Jika hook bertindak berdasarkan hasilnya, jadikan perintah tersebut kondisi dari sebuah if. Jika hook mengabaikan hasilnya, tambahkan || true setelah perintah tersebut.
• Perintah yang mengirimkan beban kerja: jangan tambahkan || true setelahnya. Dengan || true, hook keluar dengan 0 bahkan ketika platform Anda menolak pengiriman, misalnya karena melebihi kuota, dan sesi menunggu runner yang tidak pernah dimulai. Beri nama beban kerja berdasarkan CLAUDE_RUNNER_ORDER_ID, seperti yang dinyatakan aturan pertama hook. Jawaban already-exists kemudian merupakan pengiriman ulang permintaan yang sama, jadi perlakukan hanya jawaban tersebut sebagai keberhasilan. Untuk jawaban lainnya, cetak jawaban tersebut ke stderr dan keluar dengan 1, atau panggil permanent jika tidak ada retry yang dapat memperbaikinya. Contoh ini melakukan hal tersebut untuk kubectl create, dengan job.yaml yang hanya berisi beban kerja:
  if ! out=$(kubectl create -f job.yaml 2>&1); then
    case "$out" in
      *AlreadyExists*) ;;
      *) printf '%s\n' "${out:-kubectl create failed}" >&2; exit 1 ;;
    esac
  fi
  
  Log orchestrator kemudian menampilkan pesan tersebut. Jika hook membuat objek lain, beri nama masing-masing berdasarkan order ID, berikan perintahnya sendiri, dan perlakukan jawaban already-exists-nya sebagai keberhasilan dengan cara yang sama. Untuk objek yang menyimpan rahasia, cetak pesan tetap sebagai pengganti output perintah.

​

Mengirim permintaan model ke Bedrock atau Agent Platform

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

env | grep -E 'CLAUDE_CODE_USE_(BEDROCK|VERTEX)'

​

Perbedaan dari sesi di Anthropic API

• Kebijakan dari claude.ai: pengaturan yang dikelola server tidak sampai ke sesi ini. Begitu pula kebijakan organisasi yang ditetapkan Owner di pengaturan admin Claude Code, sehingga Claude Code tidak memberlakukannya di dalam sesi. Letakkan aturan yang Anda andalkan di file pengaturan terkelola pada image runner.
• Skill akun: sesi ini tidak mengunduh skill yang diaktifkan untuk akun claude.ai seseorang. Lihat Bagaimana konfigurasi setiap sesi disusun.
• File: file yang dilampirkan orang ke sesi di claude.ai atau aplikasi seluler atau desktop tidak sampai ke sesi tersebut, dan Claude tidak dapat mengirim file kembali dengan tool SendUserFile. Sebagai gantinya, letakkan file input di repositori atau di runner.
• Pemilihan model: control plane Anthropic mengirimkan model setiap sesi, dan ketika sesi dimulai tanpa model, Claude Code menggunakan model default untuk penyedia tersebut. Anda tidak dapat memilih model dengan ANTHROPIC_MODEL atau ANTHROPIC_DEFAULT_MODEL di environment runner, tetapi Anda dapat menyematkan ke mana sebuah alias diarahkan:
  • ANTHROPIC_MODEL dan ANTHROPIC_DEFAULT_MODEL: runner menghapus keduanya dari environment yang diteruskannya ke sesi, meskipun contoh di halaman penyedia menetapkan ANTHROPIC_MODEL.
  • Variabel penyematan per keluarga model: variabel di Menyematkan versi model untuk Amazon Bedrock dan Agent Platform memang sampai ke sesi. Variabel tersebut menentukan ke mana alias seperti opus diarahkan, bukan ke mana ID model lengkap diarahkan.
• Model yang tidak dilayani akun Anda: sebuah sesi dapat gagal pada suatu pesan dengan error yang menyebutkan nama model. Aktifkan model yang dapat dipilih developer Anda, model latar belakang yang dijelaskan dalam Menyematkan versi model, dan model pengklasifikasi yang digunakan auto mode. Di Amazon Bedrock, izinkan masing-masing model tersebut dalam kebijakan Anda.
• Pencarian web dan fast mode: pencarian web tidak tersedia di Amazon Bedrock, dan fast mode tidak tersedia di kedua penyedia. Untuk kemampuan lain yang berbeda menurut penyedia, lihat Kemampuan CLI yang bervariasi menurut penyedia.

​

Server MCP

RUN claude mcp add --scope user sidecar -- /usr/local/bin/mcp-sidecar
RUN claude mcp add --scope user --transport http internal http://mcp-gateway.svc.cluster.local:8080

• File MCP terkelola cakupan enterprise pada jalur sistem standarnya: /etc/claude-code/managed-mcp.json pada host runner Linux, /Library/Application Support/ClaudeCode/managed-mcp.json pada host macOS. Gunakan file ini untuk armada yang dikunci ketat di mana hanya server yang didaftarkan administrator yang boleh dimuat. Lihat kontrol eksklusif dengan managed-mcp.json untuk aturan prioritas. Ketika file ini ada di host runner, Claude Code melewati server MCP yang dikirimkan control plane Anthropic ke sesi, termasuk konektor claude.ai, dan menyebutkan namanya dalam peringatan di stderr proses anak sesi, yang dicatat runner pada level log debug. Sebelum v2.1.229, sesi tersebut keluar saat startup dengan You cannot dynamically configure MCP servers when an enterprise MCP config is present.
• Kunci managedMcpServers dalam pengaturan terkelola pada host runner: menyediakan server HTTP dan SSE tanpa mengambil kontrol eksklusif, sehingga server dari sumber lain tetap dimuat. Memerlukan Claude Code v2.1.259 atau yang lebih baru.
• <repo>/.mcp.json: cakupan project. Di luar thread project, lakukan commit file ini ke repositori, dan server-servernya disetujui secara otomatis di sesi cloud. Dalam sesi dengan beberapa repositori, paling banyak file dari satu repositori yang dimuat.
• File --mcp-config dari skrip wrapper Anda: tambahkan flag tersebut setelah "$@", seperti pada exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --mcp-config /etc/claude/mcp.json. Agar server dari file tersebut tetap berjalan ketika server yang dikirimkan ke sesi diperbarui di tengah sesi, pastikan wrapper Anda meneruskan environment lengkap ke proses anak, seperti yang dilakukan exec. Sebelum v2.1.299, server stdio, HTTP, dan SSE dalam file tersebut berhenti pada pembaruan pertama semacam itu yang tidak menyebutkan namanya.

​

Menunggu server MCP sebelum giliran pertama

• Startup sesi: sebelum daftar tool pertama kali diambil, sesi menunggu hingga 5 detik secara default untuk server HTTP atau SSE yang entrinya mengatur alwaysLoad: true, atau untuk semua server ketika Anda mengatur MCP_CONNECTION_NONBLOCKING=0 di environment runner. Jika tidak, server HTTP dan SSE terhubung di latar belakang. Selama sesi menunggu di sini, inisialisasinya menjadi lebih lambat. MCP_CONNECT_TIMEOUT_MS mengubah default 5 detik tersebut.
• Giliran pertama: setelah pesan tiba, giliran pertama menunggu hingga 2 detik untuk server stdio yang masih dalam proses terhubung. Selama sesi menunggu di sini, balasan pertama menjadi lebih lambat. Untuk mengubah berapa lama penantian ini berlangsung, atur CLAUDE_CODE_MCP_STARTUP_WAIT_MS di environment runner. Variabel ini tidak mengubah server mana yang dicakup oleh penantian tersebut. Memerlukan Claude Code v2.1.274 atau yang lebih baru.

RUN claude mcp add-json core '{"type":"http","url":"https://mcp.example.com/mcp","alwaysLoad":true}' --scope user

​

Matikan tool sesi bawaan

{
  "permissions": {
    "deny": [
      "mcp__Claude_Code_Remote",
      "mcp__claude-code-remote",
      "mcp__bf7c680d-5fdc-5ef4-b4a0-abadb619bf0a"
    ]
  }
}

​

Prompt sesi untuk mendorong pekerjaan mereka

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "timeout": 10,
            "command": "\"$CLAUDE_CONFIG_DIR/hooks/stop-hook-nudge.sh\""
          }
        ]
      }
    ]
  }
}

#!/bin/sh
# Implementasi referensi Stop-hook untuk runner yang di-host sendiri.
#
# Mendorong Claude sekali per giliran jika direktori proyek memiliki perubahan
# yang belum di-commit ATAU commit yang belum di-push, sehingga pekerjaan tidak
# hilang ketika sesi idle dilepaskan dan sehingga tombol "Create PR" di claude.ai/code
# menyala.
#
# Tingkat runner (tidak ada perubahan repo): letakkan file ini di ~/.claude/hooks/
# di host runner dan gabungkan blok pengaturan Stop-hook yang menyertainya ke
# ~/.claude/settings.json — runner menanam keduanya ke dalam setiap sesi.
# Alternatif tingkat repo: commit ke <repo>/.claude/hooks/ dan ubah jalur perintah
# settings.json ke $CLAUDE_PROJECT_DIR/.claude/hooks/.
#
# stdin: payload JSON hook (lihat https://code.claude.com/docs/en/hooks)
# stdout: {"decision":"block","reason":"..."} untuk mendorong, atau tidak ada untuk memungkinkan stop.

# Penjaga re-entry: harness menetapkan stop_hook_active=true ketika menginvokasi
# ulang hook Stop setelah blok. Keluar sehingga kami hanya mendorong sekali per
# giliran. Harness memancarkan JSON kompak (tidak ada spasi setelah titik dua),
# yang diandalkan pola ini; gunakan jq jika Anda memerlukan pemeriksaan yang toleran
# terhadap spasi.
in=$(cat)
case "$in" in *'"stop_hook_active":true'*) exit 0 ;; esac

d="$CLAUDE_PROJECT_DIR"

# Pengerasan: skrip ini berjalan di luar sandbox Bash Claude Code, sehingga panggilan
# git-nya melewati beberapa fitur yang dapat memulai program yang disebutkan dalam
# pengaturan git checkout. Panggilan tersebut tidak melewati semuanya, jadi jangan
# hanya mengandalkan sandbox.
GIT_OPTIONAL_LOCKS=0
export GIT_OPTIONAL_LOCKS
git() { command git -c core.fsmonitor= -c core.hooksPath=/dev/null "$@"; }

# Bukan repo git → tidak ada yang perlu didorong.
git -C "$d" rev-parse --git-dir >/dev/null 2>&1 || exit 0

# Tidak ada remote → "push ke remote" tidak dapat dipenuhi; keluar.
[ -z "$(git -C "$d" remote 2>/dev/null)" ] && exit 0

# Perubahan yang belum di-commit (staged, unstaged, atau untracked). Kecualikan
# .claude/ sepenuhnya — pengaturan yang ditanam operator dan status runtime
# yang ditulis CLI (kunci penjadwal, worktree, status routine) tinggal di sana
# dan tidak ada yang merupakan "pekerjaan yang belum di-commit" yang perlu di-push
# model.
s=$(git -C "$d" status --porcelain --ignore-submodules=dirty -- . ':(exclude).claude/' 2>/dev/null)
if [ -n "$s" ]; then
  printf '{"decision":"block","reason":"There are uncommitted changes in the repository. Please commit and push these changes to the remote branch."}'
  exit 0
fi

# Commit yang belum di-push. Hitung commit di HEAD yang tidak dapat dijangkau dari
# ref pelacakan remote apa pun atau FETCH_HEAD. Ini bekerja secara seragam untuk:
#   - checkout init+fetch (default runner: hanya FETCH_HEAD yang ada)
#   - checkout berbasis clone (origin/* ada)
#   - default runner: anak dimulai di branch hasil sesi, yang dibuat runner
#     setelah checkout
#   - detached HEAD, ketika setup kustom melewati pembuatan branch itu
# Tanpa titik referensi sama sekali (tidak pernah di-fetch), tetap diam daripada
# false-positive pada giliran read-only.
base=""
git -C "$d" rev-parse --verify -q FETCH_HEAD >/dev/null && base="FETCH_HEAD"
if [ -z "$base" ] && [ -z "$(git -C "$d" for-each-ref --count=1 refs/remotes/origin 2>/dev/null)" ]; then
  exit 0
fi
# shellcheck disable=SC2086  # $base adalah "" atau "FETCH_HEAD", pemisahan kata yang disengaja
unpushed=$(git -C "$d" rev-list HEAD --not $base --remotes=origin --count 2>/dev/null) || unpushed=0
if [ "$unpushed" -gt 0 ]; then
  branch=$(git -C "$d" symbolic-ref --short -q HEAD)
  if [ -n "$branch" ]; then
    # $branch dapat dipengaruhi penyerang — git-check-ref-format(1) mengizinkan `"`
    # dalam nama ref. `\` dilarang (aturan 10) tetapi tetap di-escape sebagai
    # pertahanan berlapis yang murah.
    # Escape karakter meta JSON sebelum interpolasi ke payload yang dibuat manual
    # sehingga branch seperti x","continue":false tidak dapat menyuntikkan kunci ke
    # JSON output-hook yang diurai harness. $unpushed aman — penjaga -gt di atas
    # menolak apa pun yang bukan integer biasa.
    branch_esc=$(printf '%s' "$branch" | sed 's/\\/\\\\/g; s/"/\\"/g')
    printf '{"decision":"block","reason":"There are %s unpushed commit(s) on branch '\''%s'\''. Please push these changes to the remote repository."}' "$unpushed" "$branch_esc"
  else
    printf '{"decision":"block","reason":"There are %s unpushed commit(s) on a detached HEAD. Please create a branch and push it to the remote repository."}' "$unpushed"
  fi
  exit 0
fi

exit 0

• Identitas git: tetapkan user.name dan user.email di image runner Anda, atau mulai runner dengan --configure-git
• Kredensial push: gunakan git yang dikelola Anthropic, atau sediakan kredensial seperti yang dijelaskan di Sertakan konfigurasi git di image Anda
• Untuk sesi yang dilanjutkan: tetapkan --push-outcome-on-release pada setiap runner di environment. Sesi yang dilanjutkan kemudian dimulai dari commit yang di-push Claude ke branch sesi. Untuk batasan flag ini, lihat Sesi yang dilanjutkan kehilangan pekerjaan yang belum di-push.

​

Submodule dan hook Stop

• Commit baru di submodule: Claude diminta sampai repositori induk mencatatnya, bahkan jika .gitmodules menetapkan ignore = all untuk submodule tersebut
• File yang belum di-commit di submodule: Claude tidak diminta, sehingga pekerjaan itu hanya tersimpan di disk runner
• Commit yang belum di-push di submodule: hook Stop tidak memeriksa apakah commit tersebut sudah di-push, sehingga induk dapat menunjuk ke commit yang tidak dapat di-fetch oleh orang lain

​

Ganti salinan lama skrip hook Stop

• Kapan: jika sesi Anda berjalan dengan sandbox Bash aktif, ganti sekarang. Jika tidak, ganti pada build image atau mulai ulang runner berikutnya.
• Apa yang berubah: file yang belum di-commit di submodule tidak lagi meminta Claude. Commit baru di submodule yang ditandai ignore = all oleh .gitmodules kini meminta Claude.

​

Izin dan persetujuan alat

#!/bin/bash
exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --permission-mode auto

​

Bagaimana konfigurasi setiap sesi dirakit

• Pengaturan proyek: di luar thread proyek, .claude/settings.json yang di-commit ke repositori diterapkan di atas baseline tingkat pengguna. Dalam sesi dengan beberapa repositori, paling banyak hanya file dari satu repositori yang berlaku.
• Pengaturan terkelola: sesi membaca managed-settings.json dari jalur sistem standar di image runner Anda. Untuk mengetahui apakah kuncinya berlaku bersama pengaturan terkelola server, lihat bagaimana Claude Code menggabungkan sumber terkelola.

• Di mana mereka mendarat: runner menulis setiap skrip hook yang disediakan ke subdirektori hooks/.ccr-launcher/ yang dicadangkan dari direktori konfigurasi sesi dan mendaftarkan skrip dalam file pengaturan terpisah yang dilewatkan ke sesi dengan --settings, meninggalkan settings.json yang ditanam dan skrip Anda sendiri di hooks/<name> tidak tersentuh. Runner membuat ulang subdirektori yang dicadangkan untuk setiap sesi dan tidak menabur konten host di ~/.claude/hooks/.ccr-launcher/ ke dalam sesi.
• Siapa yang menulisnya: bidang kontrol mengisinya dari konstanta tetap dalam deployment-nya sendiri, tidak pernah dari input per-sesi atau pihak ketiga.
• Apa yang masih mengaturnya: hook yang dikirimkan melalui --settings memasuki konfigurasi hook yang digabungkan biasa, bukan tingkat yang dikelola, jadi pengaturan yang dikelola Anda masih berlaku. disableAllHooks menonaktifkannya, dan mereka bukan di antara kategori yang allowManagedHooksOnly tetap dimuat.

​

Hentikan sesi yang gagal mengambil pengaturan terkelola server

• Sesi channel Claude Tag: jangan sertakan kunci tersebut pada runner di lingkungan yang dijadikan tujuan channel Claude Tag oleh Owner. API Anthropic menolak permintaan pengaturan terkelola server dari sesi ini, sehingga jika kunci tersebut diatur, sesi tersebut gagal dimulai. Letakkan aturan untuk sesi tersebut di managed-settings.json image runner, yang tetap dibacanya. Untuk menggunakan kunci tersebut bagi sesi Anda yang lain, jalankan sesi tersebut di lingkungan terpisah.
• Bedrock atau Agent Platform: sesi pada penyedia ini tidak mengambil pengaturan terkelola server, sehingga sesi tersebut tetap dimulai terlepas dari apakah Anda mengatur kunci tersebut. Terapkan aturan Anda dari managed-settings.json yang sama sebagai gantinya.

{
  "forceRemoteSettingsRefresh": true
}

​

Pengaturan repositori dalam sesi dengan beberapa repositori

• --capacity 1, default, dengan checkout bawaan: sesi dimulai di repositori pertama dalam daftar repositorinya. .claude/settings.json repositori tersebut berlaku sebagai pengaturan proyek dan .mcp.json-nya dimuat, sedangkan milik repositori lain tidak.
• --capacity lebih dari satu, atau hook checkout: sesi dimulai di direktori per sesi yang berisi hasil checkout. Tidak ada .claude/settings.json repositori mana pun yang berlaku sebagai pengaturan proyek, tidak ada .mcp.json repositori mana pun yang dimuat, dan $CLAUDE_PROJECT_DIR dalam perintah hook adalah direktori tersebut, bukan hasil checkout.

​

Aturan izin yang dikomit repositori

​

Apa selanjutnya

• Reference: setiap flag CLI, variabel lingkungan, dan metrik
• Verify session identity: validasi token sesi dari layanan di luar runner