Langsung ke konten utama
Dengan background agents, spawn agen asinkron yang mengedit dan menjalankan kode di lingkungan remote. Lihat status mereka, kirim tindak lanjut, atau ambil alih kapan saja.

Cara Menggunakan

Lo bisa akses background agent dengan dua cara:
  1. Background Agent Sidebar: Pakai tab background agent di sidebar native Cursor buat lihat semua background agent yang terhubung ke akun lo, cari agent yang udah ada, dan mulai yang baru.
  2. Background Agent Mode: Pencet buat ngaktifin background agent mode di UI.
Abis submit prompt, pilih agent lo dari daftar buat lihat status dan masuk ke mesin.

Background agent butuh retensi data selama beberapa hari.

Setup

Background agent berjalan di mesin Ubuntu terisolasi secara default. Agent punya akses internet dan bisa memasang paket.

Koneksi GitHub

Agen latar belakang nge-clone repo lo dari GitHub dan kerja di branch terpisah, terus nge-push ke repo lo biar gampang dioper. Kasih hak akses read-write ke repo lo (dan repo atau submodule yang jadi dependensi). Kita bakal dukung penyedia lain (GitLab, Bitbucket, dll.) ke depannya.
Konfigurasi Daftar Izin IP
Kalau organisasi lo pakai fitur daftar izin IP GitHub, lo perlu ngatur akses buat agen background. Lihat dokumentasi integrasi GitHub buat petunjuk setup lengkap, termasuk info kontak dan alamat IP.

Penyiapan Lingkungan Dasar

Untuk kasus yang lebih advanced, atur sendiri lingkungannya. Dapatkan instance IDE yang terhubung ke mesin remote. Siapkan mesin kamu, instal tools dan paket, lalu ambil snapshot. Konfigurasikan pengaturan runtime:
  • Perintah install berjalan sebelum agent mulai dan memasang dependensi runtime. Ini bisa berarti menjalankan npm install atau bazel build.
  • Terminal menjalankan proses background saat agent bekerja—misalnya menjalankan server web atau mengompilasi file protobuf.
Untuk kasus paling advanced, gunakan Dockerfile untuk penyiapan mesin. Dockerfile memungkinkan kamu menyiapkan dependensi tingkat sistem: memasang versi compiler tertentu, debugger, atau mengganti base OS image. Jangan COPY seluruh proyek—kami yang mengelola workspace dan checkout commit yang tepat. Tetap lakukan instalasi dependensi di install script. Masukkan secrets yang diperlukan untuk lingkungan dev kamu—secrets disimpan terenkripsi at rest (menggunakan KMS) di database kami dan disediakan ke environment agent di background. Penyiapan mesin ada di .cursor/environment.json, yang bisa kamu commit ke repo (direkomendasikan) atau simpan privat. Alur penyiapan akan memandu kamu membuat environment.json.

Perintah Maintenance

Saat nyiapin mesin baru, kita mulai dari base environment, lalu jalanin perintah install dari environment.json lo. Perintah ini yang biasa dijalanin developer saat pindah branch—buat install dependency baru. Buat kebanyakan orang, perintah install itu npm install atau bazel build. Biar startup mesin cepet, kita nge-cache state disk setelah perintah install jalan. Rancang biar bisa dijalanin berkali-kali. Cuma state disk yang ke-persist dari perintah install—proses yang dimulai di sini nggak bakal hidup waktu agent mulai.

Perintah Startup

Setelah menjalankan install, mesin akan menyala dan kita menjalankan perintah start, lalu menyalakan semua terminals. Ini memulai proses yang harus tetap berjalan saat agen aktif. Perintah start sering bisa dilewati. Pakai ini kalau environment dev kamu bergantung pada Docker—taruh sudo service docker start di perintah start. terminals dipakai untuk kode aplikasi. Terminal-terminal ini berjalan dalam sesi tmux yang bisa diakses kamu dan agen. Misalnya, banyak repo website menaruh npm run watch sebagai sebuah terminal.

Spesifikasi environment.json

File environment.json bisa berbentuk seperti:
{
  "snapshot": "POPULATED_FROM_SETTINGS",
  "install": "npm install",
  "terminals": [
    {
      "name": "Menjalankan Next.js",
      "command": "npm run dev"
    }
  ]
}
Secara formal, spesifikasinya didefinisikan di sini.

Model

Hanya model yang kompatibel dengan Max Mode yang tersedia untuk agen background.

Harga

Pelajari lebih lanjut tentang penetapan harga Background Agent.

Keamanan

Background Agents tersedia dalam Privacy Mode. Kami nggak pernah melatih model pakai kode lo dan cuma nyimpen kode buat ngejalanin agent. Pelajari lebih lanjut tentang Privacy Mode. Hal yang perlu lo tahu:
  1. Kasih hak akses read-write ke app GitHub kami untuk repo yang mau lo edit. Ini dipakai buat nge-clone repo dan nge-apply perubahan.
  2. Kode lo jalan di infrastruktur AWS kami dalam VM yang terisolasi dan disimpan di disk VM selama agent masih aktif.
  3. Agent punya akses internet.
  4. Agent otomatis ngejalanin semua perintah terminal, biar bisa iterasi di pengujian. Ini beda dari foreground agent, yang butuh persetujuan user untuk setiap perintah. Auto-run bisa memperkenalkan risiko kebocoran data: penyerang bisa ngejalanin prompt injection, ngejebak agent buat mengunggah kode ke situs berbahaya. Lihat penjelasan OpenAI tentang risiko prompt injection untuk background agents.
  5. Kalau Privacy Mode dimatikan, kami ngumpulin prompt dan environment dev buat ningkatin produk.
  6. Kalau lo matiin Privacy Mode saat mulai background agent, lalu lo nyalain lagi di tengah jalan, agent bakal lanjut dengan Privacy Mode nonaktif sampai selesai.

Pengaturan dashboard

Admin workspace bisa mengonfigurasi pengaturan tambahan lewat tab Background Agents di dashboard.

Pengaturan Default

  • Model default – model yang dipakai saat sebuah run nggak nentuin model. Pilih model apa pun yang mendukung Max Mode.
  • Repositori default – kalau kosong, agen bakal minta pengguna milih repo. Ngisi repo di sini bikin pengguna bisa lewatin langkah itu.
  • Branch dasar – branch yang jadi asal fork agen saat bikin pull request. Biarkan kosong untuk pakai branch default repositori.

Pengaturan Keamanan

Semua opsi keamanan butuh privilese admin.
  • Pembatasan pengguna – pilih Tidak ada (semua member bisa mulai agen latar belakang) atau Allow list. Kalau diset ke Allow list, lo nentuin persis siapa aja rekan tim yang boleh bikin agen.
  • Tindak lanjut tim – kalau aktif, siapa pun di workspace bisa nambah pesan tindak lanjut ke agen yang dimulai orang lain. Matikan untuk ngebates tindak lanjut cuma ke pemilik agen dan admin.
  • Tampilkan ringkasan agen – ngatur apakah Cursor nampilin gambar file-diff dan potongan kode agen. Nonaktifkan ini kalau lo nggak mau nge-ekspose path file atau kode di sidebar.
  • Tampilkan ringkasan agen di kanal eksternal – memperluas toggle sebelumnya ke Slack atau kanal eksternal apa pun yang udah lo sambungin.
Perubahan kesimpen instan dan langsung ngefek ke agen baru.