Mit Hintergrund-Agents startest du asynchrone Agents, die Code in einer Remote-Umgebung bearbeiten und ausführen. Schau dir ihren Status an, sende Follow-ups oder übernimm jederzeit.

​
So verwendest du es

Du kannst auf Background Agents auf zwei Arten zugreifen:
  1. Background Agent Sidebar: Nutze den Background-Agent-Tab in der nativen Cursor-Sidebar, um alle Background Agents zu sehen, die mit deinem Account verknüpft sind, bestehende Agents zu durchsuchen und neue zu starten.
  2. Background Agent Mode: Drücke , um den Background-Agent-Mode in der UI zu aktivieren.
Nachdem du eine Prompt abgeschickt hast, wähle deinen Agent aus der Liste aus, um den Status zu sehen und in die Maschine zu wechseln.

Background Agents erfordern eine Datenaufbewahrung über einige Tage.

​
Feedback

Schick dein Feedback an unseren Discord-Kanal #background-agent oder an background-agent-feedback@cursor.com. Schick uns bitte Bugs, Feature-Requests oder Ideen.

​
Setup

Background Agents laufen standardmäßig in einer isolierten, Ubuntu-basierten Maschine. Agents haben Internetzugang und können Pakete installieren.

​
GitHub-Verbindung

Background Agents klonen dein Repo von GitHub und arbeiten auf einem separaten Branch, pushen in dein Repo für einen einfachen Handoff. Gib deinem Repo (und allen abhängigen Repos oder Submodulen) Lese- und Schreibrechte. Wir werden in Zukunft andere Provider (GitLab, Bitbucket, etc.) unterstützen.
IP-Allowlist-Konfiguration
Wenn deine Organisation GitHubs IP-Allowlist-Feature nutzt, musst du den Zugriff für Background Agents konfigurieren. Sieh dir die GitHub-Integrationsdokumentation für vollständige Setup-Anweisungen inklusive Kontaktinformationen und IP-Adressen an.

​
Basisumgebung einrichten

Für fortgeschrittene Fälle richtest du die Umgebung selbst ein. Hol dir eine IDE-Instanz, die mit der Remote-Maschine verbunden ist. Richte deine Maschine ein, installiere Tools und Pakete und mach dann einen Snapshot. Konfiguriere Laufzeiteinstellungen:
  • Der Install-Befehl läuft, bevor ein Agent startet, und installiert Laufzeitabhängigkeiten. Das kann bedeuten, npm install oder bazel build auszuführen.
  • Terminals starten Hintergrundprozesse, während der Agent arbeitet – z. B. einen Webserver starten oder Protobuf-Dateien kompilieren.
Für die fortgeschrittensten Fälle nutz ein Dockerfile für das Machine-Setup. Das Dockerfile lässt dich Systemabhängigkeiten einrichten: spezifische Compiler-Versionen installieren, Debugger, oder das Basis-OS-Image wechseln. Nicht das gesamte Projekt mit COPY übernehmen – wir verwalten den Workspace und checken den richtigen Commit aus. Die Installation von Abhängigkeiten gehört weiterhin ins Install-Skript. Gib alle erforderlichen Secrets für deine Dev-Umgebung ein – sie werden im Ruhezustand verschlüsselt (mit KMS) in unserer Datenbank gespeichert und der Background-Agent-Umgebung bereitgestellt. Das Machine-Setup liegt in .cursor/environment.json, was in deinem Repo committed werden kann (empfohlen) oder privat gespeichert wird. Der Setup-Flow führt dich durch das Erstellen von environment.json.

​
Maintenance-Befehle

Beim Einrichten einer neuen Maschine starten wir von der Basisumgebung und führen dann den install-Befehl aus deiner environment.json aus. Dies ist der Befehl, den ein Developer beim Branch-Wechsel ausführen würde – neue Abhängigkeiten installieren. Für die meisten ist der install-Befehl npm install oder bazel build. Um einen schnellen Maschinenstart sicherzustellen, cachen wir den Disk-State, nachdem der install-Befehl gelaufen ist. Gestalte ihn so, dass er mehrfach laufen kann. Nur der Disk-State aus dem install-Befehl bleibt bestehen – hier gestartete Prozesse laufen nicht weiter, wenn der Agent startet.

​
Startup-Befehle

Nach dem Ausführen von install startet die Maschine und wir führen den start-Befehl aus, gefolgt vom Starten aller terminals. Das startet Prozesse, die aktiv sein sollen, wenn der Agent läuft. Der start-Befehl kann oft entfallen. Nutz ihn, wenn deine Dev-Umgebung auf Docker basiert – pack sudo service docker start in den start-Befehl. terminals sind für App-Code. Diese Terminals laufen in einer tmux-Session, die dir und dem Agent zur Verfügung steht. Viele Website-Repos setzen z. B. npm run watch als Terminal.

​
Die environment.json-Spezifikation

Die Datei environment.json kann so aussehen: 
{
  "snapshot": "POPULATED_FROM_SETTINGS",
  "install": "npm install",
  "terminals": [
    {
      "name": "Run Next.js",
      "command": "npm run dev"
    }
  ]
}
Formal ist die Spezifikation hier definiert.

​
Modelle

Für Hintergrund-Agents sind nur Max Mode-kompatible Modelle verfügbar.

​
Preise

Erfahre mehr über die Preise für den Background Agent.

​
Sicherheit

Background Agents sind im Privacy Mode verfügbar. Wir trainieren niemals mit deinem Code und behalten Code nur, um den Agent auszuführen. Erfahre mehr über den Privacy Mode. Was du wissen solltest:
  1. Gewähre unserer GitHub-App Lese- und Schreibrechte für Repos, die du bearbeiten willst. Wir nutzen das, um das Repo zu klonen und Änderungen vorzunehmen.
  2. Dein Code läuft in unserer AWS-Infrastruktur in isolierten VMs und wird auf VM-Disks gespeichert, solange der Agent aktiv ist.
  3. Der Agent hat Internetzugang.
  4. Der Agent führt alle Terminalbefehle automatisch aus und kann so Tests iterieren. Das unterscheidet sich vom Foreground Agent, der für jeden Befehl deine Bestätigung braucht. Automatisches Ausführen erhöht das Risiko von Data Exfiltration: Angreifer könnten Prompt-Injection-Angriffe durchführen und den Agenten dazu bringen, Code auf bösartige Websites hochzuladen. Siehe OpenAIs Erklärung zu Risiken von Prompt Injection bei Background Agents.
  5. Wenn der Privacy Mode deaktiviert ist, sammeln wir Prompts und Dev-Umgebungen, um das Produkt zu verbessern.
  6. Wenn du den Privacy Mode beim Starten eines Background Agents deaktivierst und ihn während der Laufzeit wieder aktivierst, läuft der Agent weiterhin mit deaktiviertem Privacy Mode, bis er fertig ist.