Claude Code Docker: Menjalankan Agen AI di Container

Agen pengodean AI otonom sangatlah kuat. Mereka menavigasi filesystem Anda, mengeksekusi perintah shell, membuat commit, dan memodifikasi file—semuanya tanpa Anda mengetik satu baris kode pun. Namun, kekuatan itu memunculkan pertanyaan nyata: apa yang terjadi jika sesuatu berjalan salah? Bagaimana jika agen memodifikasi file konfigurasi yang seharusnya tidak disentuh, atau memasang paket yang bertentangan dengan sistem Anda?

Jawaban yang biasanya dipilih para developer berorientasi produksi adalah Docker, dan itu juga jawaban yang terus saya kembali setelah satu sesi ketika Claude Code dengan “membantu” "membersihkan" file .env proyek saya karena tampak tidak digunakan. (Sebenarnya digunakan.) 

Container memberi batas tegas antara agen dan mesin host Anda, dan batas itulah yang membuat menjalankan agen tanpa pengawasan terasa aman, bukan membuat cemas. 

Dalam tutorial ini, saya akan memandu Anda menjalankan Claude Code di dalam Docker: mulai dari membangun image baseline minimal hingga mengorkestrasi aplikasi multi-layanan dengan Docker Compose. Pada akhirnya, Anda akan memiliki alur kerja yang berulang dan aman yang bisa digunakan di proyek apa pun.

Bagi Anda yang tertarik dengan model Anthropic terbaru, saya sarankan membaca panduan kami tentang Claude Opus 4.6 dan Claude Sonnet 4.6.

Cara Integrasi Claude Code dengan Docker

Untuk memahami mengapa Docker sangat cocok untuk Claude Code, ada baiknya memahami secara singkat apa yang sebenarnya dilakukan masing-masing alat.

Claude Code adalah alat pengodean beragen berbasis command line dari Anthropic, dirilis untuk ketersediaan umum pada Mei 2025. Ia berjalan di terminal Anda, membaca codebase, dan menjalankan tugas (refactor kode, menulis tes, mengelola alur kerja git) melalui prompt berbasis bahasa natural. Tutorial Claude Code 2.1 komprehensif kami mencakup semua yang perlu Anda ketahui.

Docker adalah platform untuk mengemas dan menjalankan aplikasi dalam container ringan dan terisolasi yang berbagi kernel OS host namun menjaga batas proses dan filesystem yang ketat. Jika Anda benar-benar baru dengan Docker, saya sarankan melihat panduan kami tentang platform gratis Play with Docker dan bereksperimen di sana.

Claude Code membutuhkan lingkungan untuk berjalan. Docker menyediakan lingkungan yang dapat direproduksi dan dapat dibuang. Kombinasi ini kuat, tetapi untuk memaksimalkannya Anda perlu memahami model eksekusi, default keamanan, dan pendekatan deployment yang sesuai dengan situasi Anda.

Arsitektur container dan alur eksekusi

Mari mulai dengan cara sesi Claude Code ter-container benar-benar bekerja pada level permintaan.

1. Anda mengirim prompt dari terminal host Anda. 
2. Docker memulai container dengan CLI Claude Code yang sudah terpasang dan workspace Anda di-mount sebagai volume. 
3. Claude Code membaca file dari mount tersebut, menalar tentang codebase, mengeksekusi perintah di ruang proses terisolasi container, dan menulis output kembali ke volume yang di-mount. 
4. Saat sesi berakhir, filesystem ephemeral container (semua di luar mount) dibuang.

Pembedaan kunci di sini adalah antara state ephemeral dan state persisten. Apa pun yang ditulis ke container tetapi di luar volume yang di-mount akan dihapus saat pembersihan. Workspace Anda, yang berada di host dan di-mount masuk, tetap ada. 

Artinya dependensi sementara, artefak build, dan instalasi alat akan lenyap, tetapi file proyek Anda yang sebenarnya tetap persis seperti yang ditinggalkan Claude. Pemisahan ini benar-benar menenangkan bagi saya: sebelum memahaminya, saya dulu tegang mengawasi sesi agen. Sekarang saya memulai tugas lalu membuat kopi.

Model keamanan dan default aman

Dengan alur eksekusi dalam pikiran, ada baiknya memperjelas apa yang benar-benar dilindungi oleh isolasi Docker, dan apa yang tidak.

Isolasi filesystem adalah keuntungan keamanan utama. Claude Code hanya dapat membaca dan menulis file di path yang Anda mount secara eksplisit. Jika Anda tidak me-mount-nya ke container, kunci SSH, kredensial ~/.aws, variabel lingkungan host, dan file konfigurasi sistem tidak terlihat oleh agen kecuali Anda sengaja mengeksposnya. Namun, perlindungan itu hanya berlaku jika Anda mengonfigurasi mount dengan hati-hati.

Satu aturan kritis: jangan pernah mount socket Docker host (/var/run/docker.sock) ke dalam container Claude Code. Jika agen dapat berbicara dengan daemon Docker pada host Anda, ia berpotensi menjalankan container berprivilege, keluar dari sandbox sepenuhnya, dan memperoleh akses level root ke mesin Anda. 

Ini adalah jalur eskalasi privilege yang sudah dikenal tanpa pembenaran yang baik. Saya telah melihat ini disarankan di beberapa Dockerfile komunitas sebagai cara agar agen dapat "mengelola container," dan setiap kali melihatnya, saya ingin mengirim pesan tegas kepada penulisnya.

Memilih jalur deployment yang tepat

Selain default keamanan, ada satu keputusan lagi sebelum menulis kode apa pun: model deployment mana yang sesuai dengan use case Anda? Ada tiga opsi utama, dan ketiganya tidak dapat dipertukarkan.

Untuk sebagian besar tugas (menjalankan agen pada satu repo, debug skrip, refactor modul), sandbox Docker biasa adalah default paling aman. 

Docker Compose masuk akal ketika Claude Code perlu berinteraksi dengan database, API, atau layanan frontend yang sedang berjalan. 

Devcontainer tepat untuk lingkungan standar di tingkat tim dengan ekstensi IDE yang sudah dikonfigurasi. Perlu dicatat, devcontainer referensi resmi Anthropic menyertakan firewall bawaan yang membatasi koneksi keluar ke daftar tepercaya, dan isolasi itulah yang membuat aman menjalankan Claude Code dengan --dangerously-skip-permissions untuk operasi sepenuhnya tanpa pengawasan. 

Untuk tutorial ini, kita akan membahas baik sandbox single-container maupun setup Compose.

Menyiapkan Container Docker untuk Claude Code

Setelah arsitektur dan opsi deployment jelas, mari pastikan lingkungannya dikonfigurasi dengan benar sebelum menulis kode. Saya sering melihat langkah ini dilewati, dan ini adalah alasan paling umum mengapa tutorial seperti ini gagal di tengah jalan.

Persyaratan sistem dan perangkat lunak

Berikut semua yang Anda butuhkan sebelum docker build pertama:

• Docker Desktop (macOS atau Windows) atau Docker Engine (Linux), dengan daemon aktif berjalan. Di macOS dan Windows, virtualisasi harus diaktifkan di pengaturan BIOS/firmware Anda. Di Linux, tambahkan pengguna Anda ke grup docker dengan sudo usermod -aG docker $USER, atau awali setiap perintah Docker dengan sudo.

• Node.js v18 atau lebih baru di mesin host Anda, karena CLI Claude Code adalah paket npm. Konfirmasi dengan node --version.

• Kunci API Anthropic, yang dapat Anda buat di Claude Console.

Verifikasi Docker sehat dengan uji cepat sebelum melangkah lebih jauh:

docker run --rm hello-world

Jika Anda melihat Hello from Docker!, daemon Anda merespons dengan benar, dan Anda siap lanjut.

Autentikasi dan variabel lingkungan

Dengan daemon dipastikan sehat, hal berikutnya adalah kredensial. Menyuntikkan kunci API Anthropic Anda sebagai variabel lingkungan saat runtime jauh lebih aman daripada login interaktif di dalam container. 

Saya belajar ini dengan cara sulit: login interaktif dapat memanggang kredensial ke layer container atau file riwayat shell yang bertahan di disk jauh setelah Anda melupakannya.

Pola yang benar adalah meneruskan kunci saat runtime menggunakan -e:

docker run --rm -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" my-claude-image

Perhatikan saya mereferensikan $ANTHROPIC_API_KEY dari shell host saya. Kunci tersebut tidak pernah ditulis ke Dockerfile, tidak pernah dikomit ke version control, dan tidak pernah muncul di layer image mana pun. Setel sekali di profil shell Anda (~/.zshrc atau ~/.bashrc), dan kunci itu akan mengalir mulus ke setiap run container selanjutnya.

Inisialisasi workspace

Dengan autentikasi beres, langkah setup terakhir adalah membuat workspace bersih. Saya selalu membuat direktori khusus untuk setiap sesi agen alih-alih mengarahkan Claude ke proyek yang sudah ada, karena ini menghilangkan risiko agen berkeliaran ke kode lain yang tidak Anda maksud untuk disentuh.

mkdir ~/claude-docker-tutorial
cd ~/claude-docker-tutorial
echo "# My Project" > README.md
echo "def hello(): return 'world'" > app.py

Jaga direktori ini tetap bersih. Jangan menyalin file .env asli atau kredensial apa pun ke dalamnya. Workspace hanya boleh berisi kode yang ingin Anda kerjakan dengan agen, dan tidak ada yang lain. Dengan itu, kita siap membangun.

Menjalankan Claude Code di Docker

Dengan lingkungan terkonfigurasi dan konsepnya jelas, saatnya membangun. Bagian ini memandu langkah-langkahnya: pertama, image single-container minimal, lalu sesi sandbox yang berfungsi, dan akhirnya stack Compose multi-layanan lengkap. Setiap langkah membangun di atas sebelumnya, jadi saya sarankan mengikutinya berurutan alih-alih melompat-lompat.

1. Membangun image container baseline

Semua di bagian ini bertumpu pada prinsip keamanan yang kita bahas sebelumnya. Berikut Dockerfile minimal yang menerapkan prinsip tersebut, memasang CLI Claude Code di atas image dasar Node.js yang ramping:

FROM node:20-slim

# Create a non-root user for safer execution
RUN useradd -m -u 1001 claude

# Install Claude Code CLI globally
RUN npm install -g @anthropic-ai/claude-code

# Set the working directory
WORKDIR /workspace

# Switch to non-root user
USER claude

ENTRYPOINT ["claude"]

Beberapa keputusan desain perlu dijelaskan. Saya menggunakan node:20-slim bukan node:20-alpine karena Alpine menggunakan pustaka libc musl, yang sesekali menyebabkan masalah kompatibilitas dengan paket npm native. 

Saya menemui masalah ini tepatnya pada percobaan pertama dengan Alpine: CLI Claude Code terpasang dengan baik, tetapi crash saat pertama kali dijalankan dengan error linker samar yang memakan waktu satu jam untuk saya telusuri ke musl. 

Varian slim berbasis Debian: ringan dan andal, tanpa drama itu. Selain itu, saya membuat pengguna khusus claude dan beralih ke sana sebelum entrypoint, yang berarti proses agen berjalan tanpa hak root dan membatasi apa yang dapat dilakukannya bahkan di dalam container.

Bangun image dengan:

docker build -t claude-code:latest .

Pada build pertama, Docker menarik image dasar dan memasang CLI. Pada build selanjutnya tanpa perubahan Dockerfile, Anda akan melihat “CACHED” di setiap layer, membuat rebuild hampir seketika setelah basisnya terbentuk.

2. Menjalankan sesi sandbox terisolasi

Dengan image siap, saatnya menjalankan sesi pertama yang nyata. 

Operasi read-only

Untuk tugas baca-saja seperti membuat daftar atau meringkas file, perintah dasar sudah cukup:

docker run --rm \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -v $(pwd):/workspace \
  claude-code:latest \
  "List the files in this workspace and describe what each one does."

Opsi -v $(pwd):/workspace me-mount direktori saat ini ke dalam container, sehingga perintah ini bekerja dari direktori proyek mana pun. Flag --rm menghapus container secara otomatis setelah keluar.

Operasi write

Operasi tulis memerlukan dua flag tambahan. 

Flag -u $(id -u):$(id -g) meneruskan UID dan GID pengguna host Anda ke container, memberikan proses claude izin untuk menulis ke file yang di-mount. Tanpanya, Anda akan mendapat error filesystem read-only karena pengguna claude di container tidak cocok dengan kepemilikan file host Anda. 

Flag --dangerously-skip-permissions melewati prompt persetujuan interaktif Claude Code, yang diperlukan saat berjalan non-interaktif di dalam container. Batas Docker itulah yang membuat ini aman.

docker run --rm \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -v $(pwd):/workspace \
  -u $(id -u):$(id -g) \
  claude-code:latest \
  --dangerously-skip-permissions \
  "Add a docstring to the hello function in app.py."

Operasi tulis Claude Code di Docker

Lalu periksa file lokal Anda: cat app.py. Jika Anda melihat docstring, volume mount berfungsi dua arah, dan Anda siap menskalakan ke setup multi-layanan.

3. Mengorkestrasi aplikasi multi-layanan

Sandbox single-container bekerja baik untuk tugas terisolasi, tetapi pengembangan nyata sering melibatkan banyak layanan yang berjalan bersamaan. Di sinilah Docker Compose membuktikan kegunaannya.

Konfigurasi di bawah ini menautkan agen Claude Code dengan layanan web dan database PostgreSQL—setup yang representatif untuk banyak proyek backend:

services:
  claude:
    build: .
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ./workspace:/workspace
    depends_on:
      db:
        condition: service_healthy
    networks:
      - app-network

  web:
    image: python:3.12-slim
    working_dir: /app
    volumes:
      - ./workspace:/app
    command: python -m http.server 8080
    ports:
      - "8080:8080"
    networks:
      - app-network

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: appdb
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d appdb"]
      interval: 5s
      timeout: 3s
      retries: 5
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

Perhatikan bahwa version dihilangkan, karena sudah usang di Docker Compose modern dan akan memicu peringatan jika disertakan. 

Dua detail lain patut disorot:

Pertama, layanan claude me-mount .:/workspace (direktori saat ini) alih-alih subdirektori. Menggunakan ./workspace akan membutuhkan subfolder terpisah untuk ada, dan agen akan melihat workspace kosong. 

Kedua, DATABASE_URL diteruskan secara eksplisit agar agen tahu cara menjangkau Postgres. Tanpanya, Claude tidak punya connection string dan akan meminta Anda memberikannya.

Baris user: "${UID}:${GID}" menerapkan override UID/GID host yang sama seperti pada perintah docker run mandiri, sehingga penulisan file berfungsi dengan benar. Ekspor keduanya sebelum menjalankan:

export UID=$(id -u) GID=$(id -g)

Layanan claude tidak memiliki command persisten, jadi berbeda dengan web dan db, ia tidak dimaksudkan untuk berjalan terus-menerus. Mulai layanan pendukung terlebih dahulu, lalu panggil Claude sesuai kebutuhan dengan docker compose run:

# Mulai database dan layanan web
docker compose up -d web db

# Jalankan tugas sekali jalan dengan Claude
docker compose run --rm \
  claude \
  --dangerously-skip-permissions \
  "Check the database connection and summarize the schema in README.md."

Claude Code dengan Docker Compose

Mulai layanan pendukung terlebih dahulu dengan docker compose up -d web db, lalu pantau log mereka dengan docker compose logs -f. Perhatikan depends_on dengan condition: service_healthy. 

Saya melewatkan ini pada proyek awal dan menghabiskan 20 menit mengejar error koneksi database sebelum menyadari Claude sudah mulai sebelum Postgres siap. Health check ini nyaris tanpa biaya dan mencegah sakit kepala yang sama.

4. Mengelola pembersihan sesi

Setelah sesi selesai, pembersihan sama pentingnya dengan setup. Container yatim piatu mengonsumsi memori dan mengganggu run berikutnya, dan menurut pengalaman saya, ini adalah langkah yang paling sering diabaikan developer sampai ada perilaku aneh.

Berikut perintah yang paling sering Anda gunakan, dan kapan harus menggunakannya:

Thag -v pada docker compose down adalah yang harus diwaspadai. Ini menghapus named volume, artinya data database apa pun yang telah Anda kumpulkan di Postgres akan hilang. Saya hanya menggunakannya saat benar-benar menginginkan kondisi bersih. Selain itu, docker compose down saja sudah cukup.

Integrasi dan Pemecahan Masalah Claude Code Docker

Dengan alur kerja inti berjalan mulus, mari lihat cara memperluasnya dan cara men-debug saat terjadi masalah.

Mengintegrasikan model lokal dan ekstensi

Claude Code mendukung pengalihan inferensi ke endpoint lokal yang kompatibel dengan Anthropic melalui ANTHROPIC_BASE_URL. Docker Model Runner, yang tersemat di Docker Desktop, mengekspos API semacam itu, membuat integrasinya terasa native di ekosistem Docker.

Tarik model dan arahkan Claude Code ke endpoint lokal:

docker model pull ai/smollm2
ANTHROPIC_BASE_URL=http://localhost:12434 claude --model ai/smollm2 "List the files of the repository."

Ini adalah pola berbeda dari pendekatan container sandbox yang dibahas sebelumnya. Di sini, Claude Code berjalan di host Anda, dan inferensi tetap lokal melalui Docker Model Runner, sehingga tidak ada panggilan API yang meninggalkan mesin Anda.

Selain model lokal, Anda dapat memperluas jangkauan Claude Code melalui server MCP (Model Context Protocol). Jika Anda belum familiar, Panduan MCP kami adalah sumber yang bagus untuk memulai.

Docker's MCP Toolkit menyediakan lebih dari 200 server MCP terkemas dalam container yang sudah dibangun, mencakup GitHub, Jira, Supabase, dan banyak lagi, memberi Claude Code akses dengan izin ke alat-alat tersebut tanpa mengekspos kredensial API mentah. 

Bersama-sama, dua titik ekstensi ini memberi Anda kendali bermakna atas di mana inferensi terjadi dan layanan eksternal apa yang dapat dijangkau agen.

Mengoptimalkan performa build

Seiring Dockerfile Anda tumbuh, waktu build bisa menjadi hambatan. Build multi-tahap mengatasinya dengan memisahkan instalasi dari image runtime:

# Build stage
FROM node:20-slim AS builder
RUN npm install -g @anthropic-ai/claude-code

# Runtime stage
FROM node:20-slim
COPY --from=builder /usr/local/lib/node_modules /usr/local/lib/node_modules
COPY --from=builder /usr/local/bin/claude /usr/local/bin/claude
RUN useradd -m -u 1001 claude
USER claude
WORKDIR /workspace
ENTRYPOINT ["claude"]

Urutan layer sama pentingnya dengan strukturnya, dan ini sesuatu yang cukup lama saya salah pahami. 

Instruksi yang jarang berubah (seperti memasang paket sistem) letakkan di bagian atas. Yang sering berubah (seperti menyalin source code) di bagian bawah. Ini memaksimalkan cache hit dan mengubah rebuild 30 detik menjadi nyaris instan.

Men-debug kegagalan integrasi umum

Bahkan dengan setup yang tertata baik, masalah bisa muncul. Berikut loop debugging berulang untuk isu yang paling sering saya temui. Gejala dulu, lalu perintah yang dijalankan:

• Network egress terblokir: Claude Code tidak bisa menjangkau API Anthropic. Jalankan docker run --rm alpine wget -qO- https://api.anthropic.com untuk verifikasi akses keluar. Jika gagal, periksa docker network inspect bridge untuk setelan proxy.

• Volume mount salah: Claude Code melaporkan tidak dapat menemukan file. Jalankan docker run --rm -v $(pwd):/workspace alpine ls /workspace. Daftar kosong berarti path Anda salah. Pastikan direktori ada sebelum hal lain.

• Cache build usang: Anda memperbarui Dockerfile, tetapi perilaku tidak berubah. Paksa rebuild penuh dengan docker build --no-cache -t claude-code:latest ..

• Kegagalan koneksi antar layanan di Compose: Satu layanan tidak bisa menjangkau yang lain. Layanan berkomunikasi melalui nama layanan mereka (db, web), bukan localhost. Jalankan docker compose exec web ping db untuk menguji keterjangkauan. Ping gagal berarti layanan tidak berada di network yang sama.

Kesimpulan

Menjalankan Claude Code di dalam Docker memberi Anda sesuatu yang benar-benar berharga: kebebasan untuk membiarkan agen otonom bekerja dengan leluasa, dengan kepastian bahwa apa yang dapat disentuhnya dibatasi dengan ketat. 

Dalam tutorial ini, saya membahas pembuatan image container minimal tanpa root, pengelolaan volume workspace, orkestrasi aplikasi multi-layanan dengan Docker Compose, dan diagnosis kegagalan integrasi yang paling umum. 

Setup ini memakan waktu sekitar satu sore untuk saya rapikan, dan benar-benar mengubah cara saya mendekati pengembangan berbantuan agen. Saya mendelegasikan seluruh tugas alih-alih mengawasi setiap langkah, dan batas Dockerlah yang membuat itu mungkin.

Dari sini, ada dua arah yang layak dieksplorasi:

Pertama, look into template devcontainer untuk tim Anda. Devcontainer referensi Claude Code di GitHub menyertakan firewall yang telah dikonfigurasi untuk membatasi koneksi keluar ke domain tepercaya. Kedua, bereksperimenlah dengan Docker MCP Toolkit untuk memberi Claude Code akses terstruktur ke alat Anda yang sudah ada: GitHub, database, sistem manajemen proyek, dan lainnya.

Terakhir, pasang pengingat untuk memperbarui image dasar Anda secara berkala. Image Docker menumpuk kerentanan seiring waktu, dan docker pull node:20-slim cepat diikuti rebuild hanya butuh menit.

Jika Anda tertarik mengembangkan aplikasi AI, saya sangat merekomendasikan mendaftar di skill track AI Engineering with LangChain kami. Kursus-kursusnya bersifat AI-native, sehingga Anda akan mendapatkan pengajar pribadi yang menyesuaikan dengan tingkat Anda dan membantu mencapai tujuan sesuai ritme Anda.