Erste Schritte

Lokales Projekt (Coding)

Ein Chat kann statt der Bibliothek einen lokalen Ordner als Ablage nutzen. Der Agent liest und ändert dann Dateien direkt in diesem Projekt, führt Tests aus, startet Dev-Server und arbeitet mit Git.

Der Ordner liegt auf dem Rechner, auf dem Uella Desktop läuft und mit deinem Konto angemeldet ist. Das ist keine Fernsteuerung eines anderen Geräts (dafür gibt es Andere Geräte).

Desktop und Browser

Situation	Was du siehst
Uella Desktop (dieser Rechner)	Kein Host-Chip; Terminal, Sandbox und lokaler Ordner normal
Browser mit verbundenem Desktop	Chip «arbeitet auf ‹Gerätename›»; dieselben Funktionen, aber auf dem anderen Rechner
Browser ohne Desktop	Lokaler Ordner, Terminal und Sandbox ausgeblendet bzw. mit Hinweis zum Verbinden/Download

Im Browser braucht das Zielgerät Profil → Andere Geräte → Diesen Rechner remote erlauben. In der Desktop-App auf demselben Gerät gilt das nicht.

Ordner öffnen

1. Im Composer auf den Ablage-Chip (Bibliothek) klicken.
2. Lokaler Ordner → Lokalen Ordner öffnen … wählen. Die Desktop-App zeigt den Ordnerdialog.
3. Der Chip zeigt danach Ordnername und, bei einem Git-Repository, den Branch (* = ungespeicherte Änderungen).

Im selben Menü wechselst du den Ordner, schliesst ihn (Lokalen Ordner schliessen führt zurück zur Bibliothek) oder überträgst Dateien per SFTP / FTP.

Voraussetzung: Profil → Dieser Computer → Terminal ist an. Die Einstellung legt fest, was Uella auf diesem Rechner ausführen darf.

Was der Agent kann

Tool	Zweck
read_file / list_files / search	Codebase lesen und durchsuchen
apply_patch / str_replace	Gezielte Dateiänderungen, sofort angewendet; danach Keep oder Undo in der Änderungsleiste
host_run_command	Shell im Projekt (Timeout bis 10 Min, Ausgabe live im Chat)
process_start / process_output / process_stop / process_list	Dev-Server, Watcher und lange Builds im Hintergrund; der Agent liest die Ausgabe nach und erkennt lokale URLs
git_status / git_diff	Git-Kurzinfos (ohne Shell, nur lesend)
git_commit / git_branch / git_push / git_pull_request	Git schreibend, jeweils mit Vorschau und Freigabe im Chat

Projekt-Regeln aus AGENTS.md oder .uella/rules.md werden beim Coding-Workspace automatisch geladen (abschaltbar am Agent Loop unter Projektanweisungen). Zusätzlich kannst du dort eigene AGENTS.md-Texte pro Agent anhängen — sie landen vor der Agent-Instruktion im Systemkontext.

Unter Skills am Agent Loop importierst du SKILL.md nach dem offenen Agent-Skills-Standard. Der Loop sieht zuerst nur Name und Beschreibung; den vollen Inhalt lädt er bei Bedarf mit load_skill. Modus Fragen / Plan / Agent wählst du am Composer.

Änderungen prüfen und rückgängig machen

Vor jeder Änderung legt der Desktop einen Checkpoint unter ~/.uella/coding-checkpoints an. Undo in der Änderungsleiste stellt den Stand vor der ersten Änderung dieser Datei wieder her; neu angelegte Dateien werden entfernt.

Runde rückgängig: Am Ende jeder Agent-Runde mit Dateiänderungen steht im Chat die Karte «Änderungen dieser Runde» mit allen Dateien. Ein Klick setzt alle Dateien dieser Runde auf den Stand davor zurück, auch spätere Änderungen an denselben Dateien. Der Agent erfährt in der nächsten Runde, dass die Änderungen zurückgenommen wurden.

Hintergrundprozesse

Laufende Prozesse erscheinen als Leiste unter den Nachrichten, mit Status und erkannten Adressen wie localhost:5173. Pro Projekt laufen höchstens vier gleichzeitig. Sie laufen weiter, bis der Agent sie stoppt oder die Desktop-App beendet wird; beim Ende wird die ganze Prozessgruppe beendet. Starten braucht dieselbe Freigabe wie ein Befehl.

Git

• Commit und Branch zeigen vorher Nachricht, Dateien und git status. Du gibst einmal oder für Commits und Branches in diesem Projekt frei.
• Push fragt immer einzeln und zeigt die Commits, die hochgeladen werden. Er braucht eine vorhandene Anmeldung (SSH-Schlüssel oder Credential-Helper); Uella fragt keine Passwörter ab.
• Pull Request: Der Branch muss gepusht sein. Mit einer GitHub-Verbindung (Profil → Verbindungen → GitHub) öffnet Uella den Pull Request nach deiner Freigabe direkt. Bei GitLab gilt dasselbe für Merge Requests, wenn unter Profil → API-Keys → GitLab ein Personal Access Token mit Scope api hinterlegt ist. Für selbst gehostetes GitLab trägst du dort zusätzlich die GitLab-URL ein. Ohne Token und bei Bitbucket bekommst du einen fertig ausgefüllten Link und legst ihn im Browser an.
• Eigener Arbeitsordner pro Branch (Worktree): Sag dem Agenten zum Beispiel «arbeite in einem eigenen Ordner auf Branch feature/login». Uella legt nach deiner Freigabe einen Git-Worktree unter ~/.uella/worktrees/ an, und der Chat arbeitet ab dann dort. Dein bisheriger Ordner bleibt unberührt, du kannst also parallel weiterarbeiten. Im Ablage-Menü siehst du alle Arbeitsordner des Repositorys und wechselst per Klick. Abhängigkeiten wie node_modules müssen im neuen Ordner neu installiert werden. Entfernen kann der Agent nur Ordner, die Uella angelegt hat, und nur ohne ungespeicherte Änderungen; der Branch bleibt erhalten. Braucht Uella Desktop ab 0.0.9.
• Erlaubt sind nur add, commit -m, switch / switch -c, push (optional -u) und worktree add / worktree remove unter ~/.uella/worktrees/. Kein Force-Push, kein Löschen von Branches, kein Amend, kein Reset. Git läuft ohne Shell in der Projekt-Sandbox, damit Repository-Hooks nichts ausserhalb des Projekts schreiben können. Worktrees liegen ausserhalb des Projekts; dort läuft git deshalb ohne Sandbox, aber mit abgeschalteten Hooks.
• In «Nur lesen» und im Modus «Fragen» ist Git schreibend gesperrt.

Sandbox

Der Chip am Composer wechselt die Stufe:

• Nur lesen: Nur lesende Befehle, keine Verkettungen oder Umleitungen. Auf macOS und Linux verhindert die Sandbox zusätzlich jedes Schreiben ausser in Temp-Ordnern.
• Projekt (Standard): Schreiben nur im Projektordner, in Temp-Ordnern und in den Caches der Paketmanager (npm, pnpm, yarn, Cargo, Gradle, Maven, Go …). Befehle kannst du einmal oder für dieses Projekt freigeben.
• Voll: Keine Sandbox. Jeder Befehl wird einzeln bestätigt.

Die Sandbox nutzt auf macOS sandbox-exec und auf Linux bubblewrap (bwrap, z. B. sudo apt install bubblewrap). Ohne bwrap lehnt Linux Befehle in «Nur lesen» und «Projekt» ab, statt sie ungeschützt auszuführen; dann bleibt «Voll». Netzwerk bleibt in allen Stufen erlaubt. Unter Windows gibt es noch keine Sandbox: Dort schützen nur der Befehlsfilter bei «Nur lesen» und die Freigabe jedes Befehls.

Terminal

Der Chip Terminal öffnet über dem Eingabefeld eine echte Shell im Projektordner (ohne Ordner im Home-Verzeichnis), mit Farben, interaktiven Programmen und Tastenkürzeln. Nur du tippst dort; der Agent nutzt host_run_command und process_start.

SFTP / FTP

Zugänge legst du unter Profil → Andere Geräte → SSH an, testest und löschst sie. Übertragen kannst du über den Ablage-Chip → SFTP / FTP … (kein Live-Mount):

• Herunterladen: Ordner auf dem Server durchsuchen, Datei wählen, ins geöffnete Projekt oder in die Bibliothek speichern. Gleichnamige Dateien in der Bibliothek erhalten eine Nummer.
• Hochladen: Quelle ist eine Projektdatei, eine Bibliotheksdatei oder eine Datei vom Computer. Fehlende Ordner auf dem Server werden angelegt.
• Binärdateien werden byte-genau übertragen. Grenzen: 12 MB mit dem Projekt, 7 MB vom Computer, 50 MB zwischen Server und Bibliothek.
• Interne Adressen (localhost, 10.x, 192.168.x …) gehen nur im Personal-Betrieb oder wenn der Admin REMOTE_TRANSFER_ALLOW_PRIVATE=1 setzt.

Voraussetzung für lokale Bilder in 0.0.31

Die gebündelte MLX-Laufzeit für Uella Images benötigt einen Mac mit Apple Silicon und macOS 26.2 oder neuer. Die Mindestversion der Desktop-App bleibt macOS 14; die optionale lokale Bildengine hat die höhere Voraussetzung.