Einrichtung der Cloud-Umgebung

Cloud Agents werden auf isolierten Ubuntu-Maschinen ausgeführt. Konfiguriere die Umgebung so, dass der Agent dieselben Repos, Tools, Abhängigkeiten, Secrets und denselben Netzwerkzugriff hat, die auch ein Entwickler nutzen würde.

Erstelle eine neue Umgebung in deinem Cloud-Agents-Dashboard.

Was ist eine Cloud-Agent-Umgebung?

Die Entwicklungsumgebung für einen Cloud-Agent ähnelt dem Setup auf einem Laptop: geklonte Repos, installierte Abhängigkeiten, Secrets, Startbefehle und Netzwerkzugriff.

Effektive Entwicklungsumgebungen geben Agenten den vollständigen Kontext zu deiner Codebasis und Organisation, damit sie ihre Arbeit testen und überprüfen können.

Warum ist die Umgebungskonfiguration wichtig?

Agenten sind nur so leistungsfähig wie die Umgebungen, in denen sie laufen. Ein Agent, der Code schreiben, aber keine Tests ausführen, Dienste abfragen oder APIs erreichen kann, kann seinen Arbeitsablauf nicht vollständig abschließen.

Damit Engineering-Aufgaben von Anfang bis Ende erledigt werden können, brauchen Cloud Agents eine konfigurierte Entwicklungsumgebung mit allen Repositories, Tools, Abhängigkeiten und dem nötigen Kontext, um autonom und produktiv zu bleiben.

Entwicklungsumgebungen machen Agent-Sessions außerdem schneller. Builds bereiten Repositories, Tools und Abhängigkeiten im Hintergrund vor, sodass Agenten mit einer einsatzbereiten Maschine starten.

Das Einrichten der Umgebung ist der wichtigste Schritt, um die Effektivität deiner Cloud Agents zu verbessern.

Optionen für die Einrichtung der Umgebung

Es gibt zwei Hauptmöglichkeiten, die Umgebung für deinen Cloud-Agent zu konfigurieren:

1. Lass den Cursor-Agent seine eigene Umgebung über das Cloud-Agents-Dashboard einrichten. Der Agent installiert Abhängigkeiten, überprüft die Umgebung und erstellt seinen ersten Build.
2. Konfiguriere die Umgebung manuell mit einem Dockerfile. Wenn du diese Option wählst, kannst du das Dockerfile in einer Datei .cursor/environment.json angeben.

Beide Optionen ermöglichen dir, ein Installationsskript anzugeben. Cursor führt es beim Erstellen eines Builds aus, sodass die Abhängigkeiten bereitstehen, bevor ein Agent startet.

Multi-Repo-Umgebungen

Verwende eine Multi-Repo-Umgebung, wenn ein Agent über mehr als ein Repository hinweg arbeiten muss. Wähle mehrere Repositories aus, wenn du eine Umgebung erstellst. Cursor klont jedes Repo auf die Maschine des Agenten und verwendet die Umgebung für künftige Agent-Ausführungen und Automatisierungen wieder, die dieselbe Repo-Gruppe nutzen.

Multi-Repo-Umgebungen sind nützlich, wenn dein Frontend, Backend, deine Infrastruktur oder gemeinsam genutzte Bibliotheken in separaten Repos liegen. Der Agent kann den gesamten Workspace einsehen, koordinierte Änderungen vornehmen, Tests repoübergreifend ausführen und Pull Requests in den Repos öffnen, die er geändert hat.

Du kannst auf der Konfigurationsseite der Umgebung im Cloud-Agents-Dashboard sehen, welche Umgebung aktiv ist, zusammen mit allen zuvor aktiven Versionen.

Reihenfolge bei der Umgebungsauflösung

Cursor ermittelt die Umgebungskonfiguration nach Repository oder Repo-Gruppe und verwendet dabei den ersten Treffer:

1. .cursor/environment.json im Repository
2. Eine persönlich gespeicherte Umgebung
3. Eine vom Team gespeicherte Umgebung

So erhältst du auf Team-Ebene vorhersehbare Standardeinstellungen, während einzelne Nutzer sie weiterhin mit einer persönlichen Umgebung überschreiben können, wenn keine .cursor/environment.json auf Repo-Ebene vorhanden ist. Solche Nutzer-Overrides sind auch nützlich, um eine neue Umgebungskonfiguration zu testen, bevor sie für das gesamte Team ausgerollt wird.

Agentengestützte Einrichtung (empfohlen)

Cursor kann deine Entwicklungsumgebung in weniger als 10 Minuten in der Cloud einrichten. Starte die geführte Einrichtung über das Cloud-Agents-Dashboard oder über das Agents Window in der Cursor-Desktop-App.

Du wirst aufgefordert, dein GitHub-, GitLab-, Azure-DevOps- oder Bitbucket-Konto zu verbinden und ein oder mehrere Repositories auszuwählen.

Anschließend stellst du Cursor die Umgebungsvariablen und Secrets bereit, die zum Installieren von Abhängigkeiten und zum Ausführen des Codes benötigt werden.

Während der Agent arbeitet, kannst du seinen Fortschritt in einer geteilten Terminal-Session verfolgen, während er Einrichtungsaufgaben wie das Installieren von Abhängigkeiten übernimmt. Cursor speichert die Umgebung, nachdem es den Code überprüft und einen erfolgreichen Build abgeschlossen hat.

Künftige Cloud Agents starten mit dem aktiven Build und können Änderungen durch Ausführen deiner Software testen. Committe die Konfiguration in .cursor/environment.json, damit dein ganzes Team davon profitiert.

Manuelle Einrichtung mit Dockerfile (fortgeschritten)

Für fortgeschrittene Anwendungsfälle konfigurieren Sie die Umgebung mit einem Dockerfile:

• Erstellen Sie ein Dockerfile, um Abhängigkeiten auf Systemebene zu installieren, bestimmte Compilerversionen zu verwenden, Debugger zu installieren oder das Basis-OS-Image zu wechseln
• Verwenden Sie nicht COPY für das gesamte Projekt; Cursor verwaltet den Workspace und checkt das richtige Commit aus
• Bearbeiten Sie .cursor/environment.json direkt, um Laufzeiteinstellungen zu konfigurieren
• Verwenden Sie Build-Secrets für private Paket-Registries oder Anmeldedaten für den Build

Hier ist ein Beispiel für .cursor/environment.json, das auf eine .cursor/Dockerfile (relativer Pfad) und ein custom_script.sh-Installationsskript verweist:

{  "build": {    "dockerfile": "Dockerfile",    "context": ".."  },  "install": "pnpm install && ./custom_script.sh"}

Wenn dein Repo Docker, Tailscale oder Cloudflare Tunnel benötigt, siehe unten Docker ausführen, Tailscale ausführen und Cloudflare Tunnel verwenden.

Die Umgebung konfigurierst du mit einem Dockerfile; du erhältst keinen direkten Zugriff auf die Remote-Maschine.

Dockerfile-Builds nutzen Layer-Caching. Wenn du ein Dockerfile änderst, erstellt Cursor nur die geänderten Layer neu, statt jeden Layer von Grund auf neu zu erstellen.

Von Cursor konfigurierte Dockerfiles (private Beta)

Für Teams, die kein Dockerfile von Grund auf neu schreiben möchten, kann Cursor eines für Sie konfigurieren. Während des Setups analysiert Cursor Ihre Repos, identifiziert Tools und Abhängigkeiten und erstellt eine Dockerfile-basierte Umgebungskonfiguration, die Sie bearbeiten und versionieren können.

Dieser Ablauf ist als private Beta für Enterprise-Teams verfügbar. Um Zugriff anzufordern, wenden Sie sich an Ihren Ansprechpartner für Ihr Cursor-Konto oder senden Sie von Ihrem Team-Admin-Konto aus eine E-Mail an hi@cursor.com.

Ressourcenlimits

Jeder Cloud Agent läuft mit einem Standard-VM-Profil mit begrenztem Arbeitsspeicher und CPU. Wenn du den Enterprise-Plan nutzt und dein Repo mehr Ressourcen benötigt, kannst du den Support kontaktieren, und wir können die Limits für deinen Workspace erhöhen.

Self-Service für benutzerdefinierte Ressourcenkonfigurationen wird in Kürze verfügbar sein.

Installationsskript

Das Installationsskript hieß im Dashboard und in der Dokumentation zuvor Aktualisierungsskript.

Cursor führt das Installationsskript (install in environment.json) aus, wenn es einen Build erstellt. Das Skript wird im Hintergrund ausgeführt, sodass sich der Start der einzelnen Agenten nicht verzögert.

Verwenden Sie install für Aufgaben, die Cursor im Voraus vorbereiten kann. Dazu gehören das Installieren von Abhängigkeiten, das Generieren von Code, das Kompilieren von Artefakten und das Vorwärmen von Festplatten-Caches.

Wie Builds das Installationsskript verwenden

Cursor verwendet das Basis-Image der Umgebung, klont die Repositories und führt install vollständig aus. Ein erfolgreicher Build speichert den resultierenden Zustand des Dateisystems und wird aktiv. Neue Agenten starten mit dem aktiven Build.

Stellen Sie sicher, dass das Skript vollständig durchläuft. Aufwendige Einrichtung gehört in install, da es vor einer Agentenanfrage und nicht beim Start ausgeführt wird. Befehle wie pnpm install können weiterhin vorbereitete Zustände wiederverwenden und nur geänderte Abhängigkeiten aktualisieren.

Builds speichern nur den Zustand des Dateisystems. Laufende Prozesse, exportierte Shell-Variablen und In-Memory-Caches werden nicht in eine Agent-Ausführung übernommen. Starten Sie Dienste mit start oder terminals.

Wiederherstellung der Umgebungskonfiguration

Ein fehlgeschlagener Build ersetzt den aktiven Build nicht. Agents starten weiterhin in der zuletzt erfolgreichen Umgebung, während du den Fehler prüfst und einen Ersatz-Build erstellst.

Öffne den Tab Builds der Umgebung, um Logs zu prüfen, einen Agent aus dem fehlgeschlagenen Build zu starten oder einen anderen erfolgreichen Build auszuwählen. Informationen zu Build-Steuerelementen und zum Debugging findest du unter Cloud Agent Builds.

Was in dein Installationsskript gehört

Füge alle wiederholbaren Vorbereitungsschritte zu install hinzu. Dazu gehören die vollständige Installation von Abhängigkeiten, die Codegenerierung, die Kompilierung von Artefakten und andere Arbeiten, die wiederverwendbare Ergebnisse auf dem Datenträger speichern.

Halte lang laufende Prozesse aus install heraus. Füge Docker, Datenbanken, Tunnel und Entwicklungsserver zu Startbefehlen hinzu. Du kannst auch Anweisungen in AGENTS.md hinzufügen für Dienste, die ein Agent nur für bestimmte Aufgaben benötigt.

Startbefehle

Nachdem ein Agent aus einem Build gestartet wurde, führt Cursor den Befehl start und anschließend alle konfigurierten terminals aus. Verwende diese für Prozesse, die aktiv bleiben sollen, während der Agent läuft.

Du kannst start in vielen Repositories weglassen. Wenn deine Umgebung von Docker abhängt, füge sudo service docker start in start ein.

terminals sind für App-Code-Prozesse. Diese Terminals laufen in einer tmux-Sitzung, die von dir und dem Agenten gemeinsam genutzt wird.

Fügen Sie cloudspezifische Anweisungen zu AGENTS.md hinzu

Cloud Agents lesen AGENTS.md-Dateien. Wir empfehlen, einen eigenen Abschnitt nur für Cloud-Setup und Tests hinzuzufügen, zum Beispiel mit dem Titel Cursor Cloud specific instructions.

Wenn dieser Abschnitt sehr umfangreich wird, empfehlen wir, auf andere Dateien zu verweisen, die detaillierte Anweisungen für bestimmte Aufgaben enthalten können.

Weitere Informationen finden Sie in unserer AGENTS.md-Dokumentation.

Umgebungsvariablen und Secrets

Damit Cloud Agents Code wie menschliche Entwickler vollständig ausführen und testen können, benötigen sie oft Umgebungsvariablen und Secrets wie API keys und Datenbank-Anmeldedaten.

Empfohlen: den Secrets-Tab in den Cursor-Einstellungen nutzen

Am einfachsten lassen sich Secrets über cursor.com verwalten. Sie werden dem Cloud-Agent als Umgebungsvariablen zur Verfügung gestellt.

Weitere Informationen zu den verschiedenen Arten von Secrets finden Sie in unserer Secrets-Dokumentation. Informationen dazu, wie Sie Cloud-Rollen Zugriff ohne langlebige Schlüssel gewähren, finden Sie unter OIDC-Tokens.

Umgebungsbezogene Secrets

Verwenden Sie umgebungsbezogene Secrets, wenn Zugangsdaten nur für Agenten verfügbar sein sollen, die eine Umgebung nutzen. Dies ist nützlich für Multi-Repo-Umgebungen, Staging-Zugangsdaten oder Repository-Gruppen mit unterschiedlichen Zugriffsanforderungen.

Umgebungsbezogene Secrets gelten für jedes Repo in dieser Umgebung. Sie sind in anderen Umgebungen nicht verfügbar.

Anmeldedaten und 2FA

Wenn Ihre App eine Anmeldung erfordert, fügen Sie dieselben Anmeldedaten, die Sie lokal verwenden, als Secrets hinzu, wie z. B. Benutzername, E-Mail-Adresse und Passwort.

Wenn Ihr Anmeldeablauf TOTP-basierte 2FA verwendet, fügen Sie auch das TOTP-Secret, das manchmal als Shared Secret oder Root Secret bezeichnet wird, als Secret hinzu. Der Agent kann mit oathtool --totp -b "$TOTP_SECRET" den aktuellen 6-stelligen Code generieren.

Monorepos mit mehreren .env-Dateien

Wenn dein Monorepo mehrere .env.local-Dateien hat:

• Füge Werte aus allen .env.local-Dateien im selben Secrets-Tab hinzu
• Verwende eindeutige Variablennamen, wenn sich Keys überschneiden, z. B. NEXTJS_* und CONVEX_*
• Verweise bei Bedarf aus jeder App auf diese Variablen

Wenn du .env.local-Dateien beim Erstellen eines Snapshots einbeziehst, können sie gespeichert und für Cloud Agents verfügbar werden. Der Secrets-Tab bleibt der empfohlene Ansatz für Sicherheit und Verwaltung.

AWS-IAM-Rollen verwenden

Cursor unterstützt das Annehmen kundenseitig bereitgestellter IAM-Rollen für eine tiefere Integration mit AWS. So kannst du Cloud Agents bestimmte AWS-Berechtigungen erteilen, ohne langlebige Anmeldedaten weiterzugeben.

1. IAM-Rolle erstellen: Erstelle in deinem AWS-Konto die IAM-Rolle, die der Cloud-Agent annehmen soll, und notiere dir ihre ARN (z. B. arn:aws:iam::123456789012:role/acmeRole).

2. IAM-Rollen-Secret konfigurieren: Wechsle zu Cursor Dashboard → Cloud Agents und füge ein Nutzer- oder Team-Secret mit dem Namen CURSOR_AWS_ASSUME_IAM_ROLE_ARN hinzu, das auf die ARN der von dir erstellten IAM-Rolle gesetzt ist.

3. Eine External ID generieren: Das muss ein Team-Admin im Abschnitt Advanced der Team-Einstellungen tun. Wechsle zu Cursor Dashboard → Settings → Advanced und suche die Einstellungen für die External ID. Wenn keine External ID angezeigt wird, gib einen Platzhalterwert in das Feld "AWS IAM Role ARN" ein, klicke auf "Validate & Save" und lade die Seite neu. Dadurch wird eine External ID für dein Team generiert (z. B. cursor-xxx-yyy-zzz).

4. Trust-Policy der IAM-Rolle konfigurieren: Aktualisiere in deinem AWS-Konto die Trust-Policy der IAM-Rolle so, dass sie dem Role Assumer von Cursor vertraut. Die Trust-Policy sollte wie folgt aussehen:

{  "Version": "2012-10-17",  "Statement": [    {      "Sid": "AllowCursorAssume",      "Effect": "Allow",      "Principal": {        "AWS": "arn:aws:iam::289469326074:role/roleAssumer"      },      "Action": "sts:AssumeRole",      "Condition": {        "StringEquals": {          "sts:ExternalId": "cursor-xxx-yyy-zzz"        }      }    }  ]}

Ersetze cursor-xxx-yyy-zzz durch die für dein Team generierte External ID.

Umgebungsvariablen:

Wenn Cursor entsprechend konfiguriert ist, setzt es diese Umgebungsvariablen, damit AWS-Tools das Profil cursor-cloud-agent verwenden:

• AWS_CONFIG_FILE verweist auf eine von Cursor verwaltete AWS-Konfigurationsdatei
• AWS_PROFILE wird auf cursor-cloud-agent gesetzt
• AWS_SDK_LOAD_CONFIG wird auf 1 gesetzt

Die AWS CLI und AWS SDKs, die die Standard-Anmeldedatenkette verwenden, übernehmen dieses Profil bei Setup-Befehlen und während der Agent läuft automatisch. Du musst AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY oder AWS_SESSION_TOKEN nicht selbst exportieren.

Um dich über AWS STS AssumeRoleWithWebIdentity, GCP, Azure oder einen anderen OIDC-Verifizierer zu föderieren, präge OIDC-Token auf der Agent-VM, anstatt langlebige Cloud-Schlüssel zu speichern.

Konfiguration im Code mit environment.json

Wenn du deine Umgebungskonfiguration lieber im Code definiert halten möchtest, kannst du eine .cursor/environment.json in dein Repository committen.

Builds verwenden die Konfiguration aus dem Standard-Branch der Umgebung. Bei Änderungen in Feature-Branches committe und pushe die Konfiguration und starte dann einen Agent im Branch. Cursor checkt den angeforderten Branch über dem aktiven Build aus, und der Agent kann den Installationsbefehl erneut ausführen, wenn der Branch Abhängigkeiten ändert.

Beispiel für eine environment.json mit einer snapshotbasierten Konfiguration (du findest die Snapshot-ID auf der Environments-Seite im Dashboard):

{  "snapshot": "snapshot-20260212-00000000-0000-0000-0000-000000000000",  "install": "npm install"}

Hier ist ein Beispiel für eine .cursor/environment.json, die auf ein .cursor/Dockerfile (relativer Pfad) und ein custom_script.sh-Installationsskript verweist:

{  "build": {    "dockerfile": "Dockerfile",    "context": ".."  },  "install": "pnpm install && ./custom_script.sh"}

Das vollständige Schema ist hier definiert.

Docker ausführen

Cloud Agents unterstützen Docker-Workflows. Wir verwenden das intern für Full-Stack-Repos, die viele Services ausführen.

Für einfache Setups reicht es oft aus, Docker zu installieren. Befehle wie docker run hello-world funktionieren normalerweise, sobald Docker installiert ist und der Daemon läuft.

Docker läuft innerhalb einer weiteren Container-Schicht, daher gibt es bei Cloud Agents einige Randfälle. Einfache Workflows funktionieren normalerweise. Komplexere Setups sollten mit der unten stehenden Konfiguration für fuse-overlayfs und iptables-legacy beginnen.

Für komplexere Docker-Setups verwenden Sie fuse-overlayfs, iptables-legacy und stellen Sie sicher, dass Ihr Cloud-Agent-Benutzer Docker ausführen kann.

######################################################### DOCKER INSTALLATION######################################################### Docker installierenRUN install -m 0755 -d /etc/apt/keyrings && \    curl --retry 3 --retry-delay 5 -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg && \    chmod a+r /etc/apt/keyrings/docker.gpg && \    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \    $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null && \    apt-get update && \    apt-get install -y \    docker-ce=5:28.5.2-1~ubuntu.24.04~noble \    docker-ce-cli=5:28.5.2-1~ubuntu.24.04~noble \    containerd.io \    docker-buildx-plugin \    docker-compose-plugin \    && rm -rf /var/lib/apt/lists/*RUN apt-get update && apt-get install -y fuse-overlayfs && rm -rf /var/lib/apt/lists/*RUN mkdir -p /etc/docker && \    printf '%s\n' '{' \    '  "storage-driver": "fuse-overlayfs"' \    '}' > /etc/docker/daemon.jsonRUN apt-get update && apt-get install -y iptables && rm -rf /var/lib/apt/lists/*RUN update-alternatives --set iptables /usr/sbin/iptables-legacy && \    update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy######################################################### CONFIG UBUNTU USER######################################################### keine Passwort-Authentifizierung sicherstellenRUN echo 'PasswordAuthentication no\nChallengeResponseAuthentication no\nUsePAM no' > /etc/ssh/sshd_config.d/disable_password_auth.conf# Nicht-Root-Benutzer erstellen (nur wenn er nicht existiert)RUN id -u ubuntu &>/dev/null || useradd -m -s /bin/bash ubuntu# Docker-Gruppe erstellen, falls sie nicht existiert, und ubuntu-Benutzer hinzufügenRUN groupadd -f docker && usermod -aG docker ubuntuRUN usermod -aG sudo ubuntu# Passwortloses sudo für ubuntu-Benutzer konfigurierenRUN echo "ubuntu ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/ubuntu# Passwort für ubuntu-Benutzer festlegenRUN echo "ubuntu:ubuntu" | chpasswd

Tailscale ausführen

Tailscale funktioniert in Cloud-Agent-VMs nicht im Standard-Netzwerkmodus. Verwenden Sie stattdessen den Userspace-Networking-Modus.

Dadurch kann der Agent über dein Tailnet auf private Dienste und Datenspeicher zugreifen, ohne diese Dienste dem öffentlichen Internet zugänglich zu machen.

Starten Sie tailscaled mit:

tailscaled --tun=userspace-networking \  --outbound-http-proxy-listen=localhost:1054 \  --socks5-server=localhost:1055

Exportiere dann diese Proxy-Variablen in der Shell, in der der Datenverkehr über Tailscale laufen soll:

export ALL_PROXY=socks5h://localhost:1055/export HTTP_PROXY=http://localhost:1054/export HTTPS_PROXY=http://localhost:1054/

Führe danach wie gewohnt tailscale up ... aus.

Wenn du eine funktionierende Referenz möchtest: Einige Kunden haben tailscale-orb erfolgreich verwendet, da der Docker-Modus diesem Muster folgt.

Cloudflare Tunnel ausführen

Cloudflare Tunnel funktioniert in Cloud-Agent-VMs, weil cloudflared im Userspace ausgeführt wird.

Verwenden Sie dieses Muster, wenn ein Cloud-Agent einen privaten HTTP-Dienst in einer VPC oder einem Intranet erreichen muss:

• Installieren Sie cloudflared in Ihrem Umgebungs-Dockerfile oder Installationsskript.
• Führen Sie einen cloudflared-Connector in Ihrem privaten Netzwerk aus.
• Leiten Sie einen authentifizierten Hostnamen wie vpc.example.com über den Tunnel an den privaten Origin weiter.
• Fügen Sie diesen Hostnamen zur Netzwerk-Allowlist des Cloud-Agenten hinzu, wenn Ihre Umgebung eingeschränkten Egress verwendet.
• Speichern Sie die Werte des Cloudflare-Access-Servicetokens als Cursor Secrets. Verwenden Sie zum Beispiel CF_ACCESS_CLIENT_ID und CF_ACCESS_CLIENT_SECRET.

Der Cloud-Agent kann den privaten Dienst dann über normales HTTPS mit den Headern CF-Access-Client-Id und CF-Access-Client-Secret aufrufen. Der Connector stellt die Outbound-Verbindung zu Cloudflare her und leitet die Anfrage an Ihren privaten Origin weiter. Ihre Dienste und Datenspeicher bleiben in Ihrem privaten Netzwerk, und der Connector benötigt keine offenen Inbound-Ports.

Für private TCP-Dienste wie Datenbanken konfigurieren Sie eine Cloudflare-TCP-Access-App und führen cloudflared access tcp in Ihrem Startbefehl aus. Richten Sie Ihre App oder Ihren Testbefehl auf den lokalen Listener aus, den cloudflared erstellt.