Mit Background Agents spawnst du asynchrone Agents, die Code in einer Remote-Umgebung bearbeiten und ausführen. Sieh dir ihren Status an, schick Follow-ups oder übernimm jederzeit selbst.

​
So verwendest du es

Du kannst auf Hintergrundagenten auf zwei Arten zugreifen:
  1. Hintergrundagenten-Seitenleiste: Nutze den Tab für Hintergrundagenten in der nativen Cursor-Seitenleiste, um alle mit deinem Konto verknüpften Hintergrundagenten anzuzeigen, bestehende Agenten zu durchsuchen und neue zu starten.
  2. Hintergrundagentenmodus: Drück , um den Hintergrundagentenmodus im UI zu aktivieren.
Nachdem du eine Eingabe abgeschickt hast, wähl deinen Agenten aus der Liste aus, um den Status anzuzeigen und in die Maschine zu wechseln.

Hintergrundagenten erfordern eine Datenspeicherung über mehrere Tage.

​
Setup

Background-Agents laufen standardmäßig auf 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. Sie pushen ihre Änderungen in dein Repo, damit die Übergabe leicht klappt. Gewähre Lese- und Schreibrechte für dein Repo (und alle abhängigen Repos oder Submodule). In Zukunft unterstützen wir weitere Anbieter (GitLab, Bitbucket usw.).
Konfiguration der IP-Allowlist
Wenn deine Organisation die IP-Allowlist-Funktion von GitHub verwendet, musst du den Zugriff für Hintergrund-Agents konfigurieren. Sieh dir die Dokumentation zur GitHub-Integration für vollständige Einrichtungsanleitungen inklusive Kontaktinformationen und IP-Adressen an.

​
Basis-Umgebung 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 anschließend einen Snapshot. Konfiguriere die Runtime-Einstellungen:
  • Der Installationsbefehl läuft, bevor ein Agent startet, und installiert Runtime-Abhä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 anspruchsvollsten Fälle verwendest du ein Dockerfile für das Maschinensetup. Das Dockerfile ermöglicht dir, Systemabhängigkeiten einzurichten: bestimmte Compiler-Versionen installieren, Debugger hinzufügen oder das Basis-OS-Image wechseln. COPY nicht das gesamte Projekt – wir verwalten den Workspace und checken den richtigen Commit aus. Die Installation von Abhängigkeiten gehört weiterhin ins Installationsskript. Gib alle benötigten Secrets für deine Dev-Umgebung ein – sie werden verschlüsselt-at-rest (mit KMS) in unserer Datenbank gespeichert und der Hintergrund-Agent-Umgebung bereitgestellt. Das Maschinensetup liegt in .cursor/environment.json; die Datei kannst du in deinem Repo committen (empfohlen) oder privat speichern. Der Setup-Flow führt dich durch das Erstellen von environment.json.

​
Wartungsbefehle

Wenn du eine neue Maschine einrichtest, startest du mit der Basisumgebung und führst dann den install-Befehl aus deiner environment.json aus. Das ist der Befehl, den ein Developer beim Wechseln von Branches ausführen würde – um neue Dependencies zu installieren. Für die meisten ist der install-Befehl npm install oder bazel build. Damit die Maschine schnell startet, cachen wir den Disk-Status, nachdem der install-Befehl gelaufen ist. Gestalte ihn so, dass er mehrfach ausgeführt werden kann. Nur der Disk-Status aus dem install-Befehl bleibt erhalten – Prozesse, die hier gestartet werden, laufen nicht mehr, wenn der Agent startet.

​
Startup-Befehle

Nachdem install ausgeführt wurde, startet die Maschine, und wir führen den Befehl start aus, gefolgt vom Starten aller terminals. Dadurch werden Prozesse gestartet, die laufen sollen, wenn der Agent aktiv ist. Den Befehl start kannst du oft weglassen. Nutze ihn, wenn deine Dev-Umgebung auf Docker setzt – 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 hinterlegen zum Beispiel 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"
    }
  ]
}
Die Spezifikation ist hier formal definiert.

​
Modelle

Für Hintergrund-Agents sind nur Modelle verfügbar, die mit dem Max Mode kompatibel sind.

​
Preise

Erfahre mehr über die Preise des Background Agents.

​
Sicherheit

Background Agents sind im Privacy Mode verfügbar. Wir trainieren niemals auf deinem Code und behalten Code nur, um den Agenten 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‑Speichern abgelegt, solange der Agent zugänglich ist.
  3. Der Agent hat Internetzugang.
  4. Der Agent führt alle Terminalbefehle automatisch aus, damit er Tests iterieren kann. Das unterscheidet sich vom Foreground Agent, der für jeden Befehl deine Freigabe benötigt. Das automatische Ausführen bringt ein Risiko der Datenexfiltration mit sich: 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 für 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 Start eines Background Agents deaktivierst und ihn dann während der Laufzeit aktivierst, läuft der Agent bis zum Abschluss weiterhin mit deaktiviertem Privacy Mode.

​
Dashboard-Einstellungen

Workspace-Admins können zusätzliche Einstellungen auf dem Tab „Background Agents“ im Dashboard konfigurieren.

​
Standard-Einstellungen

  • Standardmodell – das Modell, das verwendet wird, wenn ein Run keines angibt. Wähle ein beliebiges Modell, das Max Mode unterstützt.
  • Standard-Repository – wenn leer, fragen Agents dich nach einem Repo. Gib hier ein Repo an, um diesen Schritt zu überspringen.
  • Basis-Branch – der Branch, von dem Agents beim Erstellen von Pull Requests forken. Leer lassen, um den Standard-Branch des Repos zu verwenden.

​
Sicherheitseinstellungen

Alle Sicherheitsoptionen erfordern Admin-Rechte.
  • Nutzerbeschränkungen – wähle Keine (alle Mitglieder können Hintergrund-Agents starten) oder Allowlist. Bei Allowlist legst du genau fest, welche Teammitglieder Agents erstellen dürfen.
  • Team-Follow-ups – wenn aktiviert, kann jeder im Workspace Follow-up-Nachrichten zu einem von jemand anderem gestarteten Agent hinzufügen. Deaktiviere das, um Follow-ups auf den Agent-Owner und Admins zu beschränken.
  • Agent-Zusammenfassung anzeigen – steuert, ob Cursor die Datei-Diff-Bilder und Code-Snippets des Agents anzeigt. Deaktiviere das, wenn du Dateipfade oder Code in der Seitenleiste nicht anzeigen möchtest.
  • Agent-Zusammenfassung in externen Kanälen anzeigen – erweitert den vorherigen Schalter auf Slack oder jeden verbundenen externen Kanal.
Änderungen werden sofort gespeichert und gelten umgehend für neue Agents.