Cara Menjadwalkan Agen AI Berjalan Semalaman di VPS

Pukul 2 dini hari, sebuah tugas terjadwal berjalan di VPS yang tidak pernah tidur. Sebuah proses headless claude -p menyelesaikan tugas dalam antrean di repo hasil kloning tanpa bertanya apa pun kepada siapa pun, lalu keluar. Saat Anda memeriksanya pagi hari, sudah ada commit yang menunggu, atau laporan, atau log yang menunjukkan persis di mana proses berhenti dan mengapa. Tidak ada yang menungguinya.

Itu berbeda dari membiarkan terminal terbuka semalaman dan berharap koneksi SSH bertahan. Titik kegagalan yang umum pada proses agen semalaman adalah host-nya: laptop tertidur, tutupnya ditutup, jaringan putus, atau pembaruan OS me-reboot mesin di tengah tugas. Kegagalan autentikasi, galat API, dan macet menunggu izin tetap bisa mematikan pekerjaan, tetapi host yang selalu menyala menghilangkan mode kegagalan yang paling mudah.

Panduan ini membahas mekanismenya secara nyata: flag headless yang disediakan setiap CLI agen coding besar, dua cara memicu proses terjadwal dan mana yang sebaiknya dipilih, apa yang dibutuhkan host di bawahnya, serta pengaman yang mencegah proses tanpa pengawasan menghabiskan biaya atau merusak lebih banyak daripada yang ingin Anda jelaskan nanti.

Versi Singkat

• Setiap CLI agen coding besar menyediakan mode non-interaktif yang terdokumentasi, yang menjalankan satu prompt sampai selesai lalu keluar. Claude Code punya claude -p, Codex CLI punya codex exec, dan Gemini CLI punya gemini -p. Ini bukan akal-akalan, melainkan fitur resmi.
• Claude Code juga punya penjadwalan sendiri: Routines, tugas terjadwal Desktop, dan /loop. Bagi sebagian pembaca itu sudah benar-benar cukup, dan lebih sedikit yang perlu dirawat dibanding VPS.
• Cron sudah cukup untuk pekerjaan harian malam. Timer systemd adalah pilihan default yang lebih baik di mesin yang mungkin reboot, karena Persistent=true menangkap proses yang akan dilewati cron tanpa suara.
• CLI-nya sendiri ringan karena inferensi berjalan di API penyedia. Tentukan ukuran VPS berdasarkan perintah yang akan dijalankannya (tes, build, kontainer, pekerjaan paralel), bukan berdasarkan modelnya.
• Yang membuat jadwal aman ditinggal adalah pengamannya: alat yang dibatasi, batas jumlah giliran, dan percabangan berdasarkan exit code. Jadwal itu sendiri bukan mekanisme keamanan.

Apa yang Akan Anda Butuhkan

Siapkan lima hal ini sebelum menulis satu baris crontab atau file unit pun:

• VPS yang bisa Anda akses lewat SSH, menjalankan distribusi Linux berbasis systemd.
• CLI agen terpasang di VPS tersebut: Claude Code, Codex CLI, atau Gemini CLI.
• Kredensial non-interaktif untuk CLI yang Anda pilih. Mode bare di Claude Code tidak membaca login akun, jadi ia butuh ANTHROPIC_API_KEY di environment, atau sebuah apiKeyHelper di pengaturannya. Proses print-mode biasa, Codex, dan Gemini juga bisa memakai kredensial login akun yang terdokumentasi.
• Repo atau direktori tugas tempat agen akan bekerja.
• Akses shell dengan izin mengedit crontab atau menulis file unit systemd.

Menjalankan Agen Tanpa Sesi yang Terhubung

Setiap CLI agen coding besar menyediakan mode non-interaktif yang dibuat persis untuk ini. Claude Code menerima -p, yang juga ditulis --print. Codex CLI menerima codex exec. Gemini CLI menerima -p, yang juga ditulis --prompt. Masing-masing menerima sebuah prompt, menjalankannya sampai selesai, lalu keluar. Tanpa loop obrolan, tanpa terminal yang harus dibiarkan terbuka, tanpa apa pun untuk disambungkan kembali.

Bisakah Claude Code berjalan tanpa sesi aktif? Bisa. Memberikan -p menjalankan prompt dalam mode non-interaktif: Claude Code mengeksekusinya sampai selesai, mencetak hasilnya, lalu keluar. Tidak ada loop obrolan dan tidak ada yang perlu dijaga tetap hidup, dan semuanya berjalan di Agent SDK yang sama dengan CLI interaktif, menurut dokumentasi mode headless resmi dari Anthropic.

Di sini yang paling penting adalah flag milik Claude Code sendiri, karena itulah yang benar-benar akan Anda skripkan. Dua di antaranya membuat proses tetap berjalan tanpa berhenti meminta izin yang tidak ada orang terjaga untuk memberikannya: --allowedTools, yang menyetujui alat tertentu di muka, dan --permission-mode, yang menetapkan dasar untuk seluruh proses. --max-turns membatasi berapa banyak giliran agen yang boleh diambil sebuah proses sebelum keluar dengan galat.

--bare melewati hook, skill, plugin, server MCP, dan instruksi proyek seperti CLAUDE.md, demi proses skrip yang lebih cepat dan lebih deterministik. Itu juga berarti setiap instruksi yang dibutuhkan pekerjaan harus ada di prompt atau di perintahnya. Mode bare juga tidak membaca login akun Anda, jadi dokumentasi Anthropic menyarankan menyetel kunci API di environment sebelum menjalankannya. Claude Code menolak --bg secara langsung ketika digabungkan dengan -p, dan menolak --cloud dengan cara yang sama ketika Anda memberinya deskripsi tugas. Ia menyebutkan konfliknya lalu berhenti, alih-alih melakukan sesuatu yang ambigu.

Contoh pemanggilan lengkap, sesuaikan prompt dan daftar alat dengan tugas Anda:

claude --bare -p "Review open PRs in this repo and summarize any blockers in NOTES.md" \
  --allowedTools "Bash(gh pr list *),Bash(gh pr view *),Bash(gh pr diff *),Read,Edit" \
  --permission-mode dontAsk \
  --max-turns 8 \
  --max-budget-usd 5.00 \
  --output-format json

Sesuaikan anggaran dan pola perintah dengan tugasnya; contoh ini juga mengasumsikan autentikasi GitHub CLI sudah dikonfigurasi untuk akun yang menjalankannya.

Jika Anda menyiapkan Claude Code di VPS baru dan ingin panduan mengautentikasinya di mesin tanpa browser, hal itu dibahas terpisah di cara mengautentikasi Claude Code di server headless; versi singkat di atas sudah cukup untuk membuat proses terjadwal berjalan.

Mode exec pada Codex CLI, yang dijelaskan di dokumentasi mode non-interaktif dari OpenAI, menerima --sandbox untuk memilih kebijakan. read-only adalah nilai bawaan, workspace-write memungkinkan agen menulis di dalam workspace-nya, dan --json mengubah stdout menjadi aliran event yang bisa diurai mesin, bukan teks biasa. Hindari danger-full-access untuk pekerjaan tanpa pengawasan kecuali prosesnya terisolasi dan risiko itu memang disengaja.

Mode headless Gemini CLI, yang didokumentasikan di dokumentasi headless milik proyek itu sendiri, aktif otomatis di lingkungan non-TTY, atau secara eksplisit dengan -p. Ia keluar dengan kode non-nol yang berbeda untuk galat umum, galat input, atau tercapainya batas giliran, bukan satu kode kegagalan generik.

Di Mana Jadwal Sebaiknya Ditempatkan

Sebelum semua pekerjaan penyiapan ini: penyedia agen mungkin sudah menjadwalkannya untuk Anda. Claude Code menawarkan tiga opsi bawaan, dan salah satunya bisa jadi memang lebih cocok daripada VPS yang Anda kelola sendiri.

Dokumentasi tugas terjadwal resmi dari Anthropic menyajikan ini sebagai pilihan tiga arah yang sungguhan, bukan hierarki dengan VPS di puncaknya. Jika tugas Anda tidak butuh state lokal, sanggup menerima batas bawah satu jam, dan Anda hanya memakai Claude Code, Routines lebih sedikit perawatannya dibanding yang dibahas berikutnya: Anthropic menjalankannya di cloud dari kloning baru saat mesin Anda mati.

/loop memang layak diketahui, tetapi tidak cocok untuk kasus ini, karena ia butuh sesi yang terbuka dan menganggur, yaitu persis kendala yang ingin Anda hilangkan. Dokumentasi yang sama juga menyebut GitHub Actions sebagai opsi keempat, untuk tim yang pemicunya sudah berada di CI alih-alih pada jadwal yang terikat ke satu mesin tertentu.

VPS yang Anda kelola sendiri layak dipilih ketika pekerjaannya butuh akses penuh ke sistem berkas lokal dan perkakas, ketika Anda ingin mekanisme yang sama bekerja identik di Claude Code, Codex CLI, dan Gemini CLI, atau ketika interval yang diizinkan Routines terlalu kasar. Fungsi serverless konvensional biasanya kurang pas di sini karena harus memulihkan kredensial, mengkloning repo, dan selesai dalam batas waktu jalan platform. Runner CI sekali pakai seperti GitHub Actions tetap jalur ketiga yang sah bila checkout baru setiap kali dijalankan masih bisa diterima. Kalau Anda sudah punya perangkat keras yang selalu menyala dan menganggur, mesin homelab juga bisa; imbalannya adalah keandalan jaringan rumah dan akses jarak jauh Anda, bukan milik penyedia.

Cron atau Timer systemd?

Kedua alat bisa menjalankan perintah yang sama pada jadwal yang sama, tetapi berbeda dalam hal apa yang terjadi saat mesin reboot dan seberapa banyak penyiapan yang dibutuhkan masing-masing:

Cron biasa sudah cukup untuk pekerjaan malam di mesin yang jarang reboot. Jebakannya ada di environment: cron mulai dengan PATHPATH minimal, tidak masuk ke repo Anda untuk Anda, dan dengan senang hati memulai salinan kedua saat yang pertama masih berjalan. Taruh path repo, perintah agen yang sempit, dan pemuatan kredensial di skrip pembungkus yang terlindungi, lalu gunakan flock untuk mencegah proses yang tumpang tindih.

# /usr/local/bin/agent-nightly
#!/usr/bin/env bash
set -euo pipefail
export PATH=/usr/local/bin:/usr/bin:/bin
export ANTHROPIC_API_KEY="$(
  cat "$HOME/.config/agent-nightly/anthropic_api_key"
)"
cd /srv/myrepo
exec /usr/local/bin/claude --bare -p \
  "Run the nightly dependency audit and write the findings to NOTES.md" \
  --allowedTools "Bash(npm audit *),Read,Edit" \
  --permission-mode dontAsk \
  --max-turns 8 \
  --max-budget-usd 5.00 \
  --output-format json

# crontab -e
0 2 * * * /usr/bin/flock -n "$HOME/.local/state/agent-runs/nightly.lock" /usr/local/bin/agent-nightly >> "$HOME/.local/state/agent-runs/nightly.log" 2>&1

Buat direktori kredensial dan log sekali saja, lalu jadikan skrip pembungkus dapat dieksekusi:

install -d -m 700 \
  "$HOME/.config/agent-nightly" \
  "$HOME/.local/state/agent-runs"
touch "$HOME/.config/agent-nightly/anthropic_api_key"
chmod 600 "$HOME/.config/agent-nightly/anthropic_api_key"
"${EDITOR:-nano}" \
  "$HOME/.config/agent-nightly/anthropic_api_key"
sudo chmod 755 /usr/local/bin/agent-nightly

Tempelkan hanya kunci API ke dalam file kredensial. Jangan menaruhnya langsung di crontab.

Timer systemd butuh lebih banyak penyiapan dan memberi Anda dua hal yang tidak ada di cron: pencatatan lewat journald tanpa pengalihan buatan tangan, dan Persistent=true. Contoh di bawah mengasumsikan akun khusus agent-runner memiliki /srv/myrepo. Simpan kunci API di file kredensial yang hanya bisa dibaca root, bukan menanamkannya di dalam unit.

Menurut manual systemd.timer, menyetel Persistent=true berarti "unit layanan langsung dipicu jika seharusnya terpicu setidaknya sekali selama waktu timer tidak aktif." Jadi proses yang seharusnya berjalan saat VPS Anda sedang reboot untuk pembaruan kernel akan berjalan begitu mesin kembali, alih-alih lenyap diam-diam sampai slot berikutnya.

Buat file kredensial khusus root yang dipakai oleh layanan ini:

sudo install -d -m 700 /etc/agent-nightly
sudo touch /etc/agent-nightly/anthropic_api_key
sudo chmod 600 /etc/agent-nightly/anthropic_api_key
sudoedit /etc/agent-nightly/anthropic_api_key

Tempelkan hanya kunci API ke dalam file itu.

# /etc/systemd/system/agent-nightly.service
[Unit]
Description=Nightly scoped agent run
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
User=agent-runner
Group=agent-runner
WorkingDirectory=/srv/myrepo
Environment=HOME=/home/agent-runner
Environment=PATH=/usr/local/bin:/usr/bin:/bin
LoadCredential=anthropic_api_key:/etc/agent-nightly/anthropic_api_key
ExecStart=/bin/sh -c 'export ANTHROPIC_API_KEY="$(cat "$CREDENTIALS_DIRECTORY/anthropic_api_key")"; exec /usr/local/bin/claude --bare -p "Run the nightly dependency audit and write the findings to NOTES.md" --allowedTools "Bash(npm audit *),Read,Edit" --permission-mode dontAsk --max-turns 8 --max-budget-usd 5.00 --output-format json'
StandardOutput=journal
StandardError=journal
UMask=0077

# /etc/systemd/system/agent-nightly.timer
[Unit]
Description=Run agent-nightly.service at 2am daily, catching up missed runs

[Timer]
# Uses the VPS's configured local timezone
OnCalendar=*-*-* 02:00:00
Persistent=true
Unit=agent-nightly.service

[Install]
WantedBy=timers.target

Muat ulang systemd, aktifkan timer-nya, lalu jalankan layanan sekali langsung, supaya masalah kredensial, izin, dan path muncul sekarang, bukan pukul 2 dini hari:

sudo systemctl daemon-reload
sudo systemctl enable --now agent-nightly.timer
sudo systemctl start agent-nightly.service
systemctl list-timers agent-nightly.timer
sudo journalctl \
  -u agent-nightly.service \
  -n 100 \
  --no-pager

Persistent=true adalah perbedaan yang menentukan: timer mengingat proses kalender yang terlewat, bukan membuangnya diam-diam.

Apa yang Sebenarnya Dibutuhkan VPS

Inilah bagian yang mengejutkan orang yang baru pertama kali menentukan ukurannya: CLI-nya sendiri ringan karena inferensi berjalan di API penyedia. Namun agen tetap bisa menjalankan build, tes, package manager, language server, dan kontainer secara lokal, jadi beban kerja repo-lah yang menentukan batas bawah sebenarnya.

Jadikan 1-2 vCPU dan 2-4 GB RAM dengan penyimpanan NVMe sebagai titik awal untuk satu pekerjaan terjadwal yang ringan. Repo besar, kompiler, build Docker, rangkaian tes, atau proses bersamaan bisa butuh jauh lebih banyak. Yang mendorong Anda menaikkan ukuran adalah perintah lokal terberat yang akan dijalankan agen, bukan model di balik API. Jika Anda sudah menjalankan beban kerja Docker di VPS ini dan ingin gambaran anggaran yang lebih utuh, menentukan ukuran dan mengamankan mesin build membahas trade-off yang sama untuk beban kerja tanpa pengawasan yang berbeda.

Satu hal lagi yang perlu direncanakan: proses tanpa pengawasan menghasilkan log setiap malam, ada masalah atau tidak. Tambahkan logrotate jika cron menulis ke sebuah file, dan periksa batas retensi journald alih-alih berasumsi nilai bawaannya cocok dengan disk VPS.

Seluruh pendekatan ini bergantung pada host yang terjaga pukul 2 dini hari dan tetap begitu, apa pun yang dilakukan laptop Anda. Itulah tugas yang tepat untuk sebuah Linux VPS dengan akses root. Tidak ada yang membuatnya tidur, dan Anda tidak berbagi dengan cron job orang lain.

Bangun di VPS Linux dengan akses root, NVMe, dan tenaga AMD EPYC.

Lihat Paket Linux

Mencegah Proses Tanpa Pengawasan Berjalan Kacau

Perbedaan terbesar antara proses terjadwal yang berhasil dan yang tidak adalah apakah tugasnya cukup sempit untuk selesai tanpa manusia yang menjawab pertanyaan di tengah jalan. Prompt yang ambisius akan mandek menunggu keputusan yang tidak ada orang untuk mengambilnya; tugas yang sempit dan mandiri selesai lalu keluar dengan rapi.

Dua flag izin itu ada supaya proses tidak macet menunggu permintaan izin pukul 2 dini hari, tetapi akses Bash yang telanjang bukan pengaman yang sempit: ia bisa melakukan hampir semua yang bisa dilakukan akun layanan itu. Lebih baik pakai aturan spesifik per perintah seperti Bash(git status *), pasangkan dengan --permission-mode dontAsk, dan jalankan layanannya di bawah akun khusus non-root. Jumlah giliran dan pengeluaran punya plafonnya masing-masing: --max-turns membatasi seberapa lama agen boleh berkeliaran, dan --max-budget-usd membatasi berapa banyak yang boleh dihabiskan satu proses untuk panggilan API.

Tips: jalankan dengan --output-format json dan catat kolom total_cost_usd dari setiap pemanggilan. Ini kait paling bersih untuk melacak berapa sebenarnya biaya proses terjadwal per malam, dan untuk memberi peringatan saat satu proses jelas lebih mahal daripada yang lain. Lima menit untuk memasangnya sepadan, karena yang dilacak adalah tagihan Anda, bukan sesuatu yang abstrak.

Pembengkakan biaya pada proses tanpa pengawasan bukan hal hipotetis. Dalam sebuah unggahan di Hacker News, seorang pengguna melaporkan tagihan kotor AWS Bedrock sebesar $37.901,73 dari alur kerja agen coding harian di mana caching prompt hanya sebagian efektif, sehingga sekitar 6,47 miliar token input tidak tercache. Itu terjadi di stack yang berbeda, bukan di mode headless Claude Code, tetapi menunjukkan mengapa pencatatan biaya dan anggaran ketat per proses layak masuk ke dalam jadwal.

Tips: Claude Code keluar dengan kode 0 saat berhasil dan kode bukan nol saat gagal. Skrip pembungkus yang memeriksa status keluar bisa mengirimi Anda notifikasi saat gagal, sehingga malam yang bermasalah ketahuan keesokan paginya, bukan tiga hari kemudian saat Anda kebetulan melihat.

Minimal, jalankan setiap pekerjaan di branch khusus atau worktree sekali pakai, dan wajibkan tinjauan manusia sebelum merge. Kredensial berlingkup sempit, isolasi sistem berkas, dan kendali radius dampak di tingkat server adalah topik lebih besar yang layak dibahas tersendiri, bukan satu paragraf yang ditempel di ujung panduan penjadwalan.

Yang membuat jadwal aman ditinggal adalah pengamannya: jadwal itu sendiri bukan mekanisme keamanan.

Ketika Cron Tidak Lagi Cukup

Satu prompt di atas timer tidak butuh apa pun selain yang sudah dibahas di sini. Tiga langkah berantai dengan kondisi, percobaan ulang, dan notifikasi Slack butuh sesuatu yang lain.

Ada tiga opsi yang layak diketahui, masing-masing naik satu tingkat karena alasan berbeda:

• Dagu adalah langkah naik paling ringan: pekerjaan mandiri yang didefinisikan dengan YAML, lengkap dengan dependensi DAG, percobaan ulang, dan UI web untuk melihat apa saja yang sudah berjalan.
• n8n paling cocok ketika proses agen hanyalah satu simpul di antara beberapa integrasi dan notifikasi, bukan keseluruhan alur kerja.
• Kestra adalah yang paling berat di antara ketiganya, dibuat untuk mengorkestrasi pipeline data dan infrastruktur, dan menjadi jawaban yang tepat ketika penjadwalan agen adalah bagian dari pipeline yang lebih besar, bukan tujuannya.

Bagi pembaca yang menjalankan satu prompt tiap malam, ketiganya berlebihan, dan itu layak dikatakan terus terang alih-alih membujuk Anda memakai penyiapan yang lebih berat dari kebutuhan. Kalau suatu saat rangkaian langkah memang membenarkan salah satunya, Dagu, n8n, dan Kestra semuanya bisa di-deploy sekali klik, dan itu kemudahan yang nyata tepat pada saat Anda menimbang apakah biaya penyiapannya sepadan.

Framework orkestrasi multi-agen seperti LangChain atau CrewAI adalah topik yang sama sekali berbeda: membangun sistem agen, bukan menjadwalkan CLI yang sudah ada.

Pertanyaan yang Sering Diajukan